/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "Licence").
 * You may not use this file except in compliance with the Licence.
 *
 * You can obtain a copy of the licence at RISC OS path @.^.LICENCE
 * or  http://www.riscosdev.com/lanman98/LICENCE.CDDL
 * See the Licence for the specific language governing permissions
 * and limitations under the Licence.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the Licence file. If applicable, add the
 * following below this CDDL HEADER, with the fields enclosed by
 * brackets "[]" replaced with your own identifying information:
 * Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
 
/*
 *   Portions Copyright 1996 Warm Silence Software Ltd.
 */

/******************************************************/
/*                                                    */
/* Name: PGscn.h                                      */
/* Author: Paul Gardiner.                             */
/* Function:                                          */
/*   This is one of two alternative modules for       */
/* manipulating windows under control of the Wimp -   */
/* the other being PGwin. This module provides a      */
/* library of functions for manipulating              */
/* virtual, bit-mapped screens. Use of this module    */
/* must begin with a call to ScnInit. Calls to this   */
/* and the PGwin module can be mixed reasonably       */
/* freely. When they are mixed, only one of the two   */
/* functions ScnInit and WinInit should be called -   */
/* preferably the first.                              */
/*                                                    */
/******************************************************/

#ifndef _PGscn_
#define _PGscn_

typedef struct scn_screen_s *scn_screen;

typedef void (*scn_action)(int, int);

typedef int (*scn_use_char)(int);

typedef void (*scn_caret)(int);

typedef void (*scn_select)(int, int, int, int);

typedef void (*scn_load)(char *);



void ScnInit(char *);
    /* Announces task to the Wimp, using the     */
    /* specified character string as the name of */
    /* the task.                                 */

void ScnFin(void);
    /* Kill the task and exit from the program.  */ 

scn_screen ScnCreate(void);
    /* Create a virtual, mode 12 screen          */

void ScnTitle(scn_screen, char *);
    /* Change the window title.                  */

void ScnOpen(scn_screen);

void ScnKill(scn_screen);

void ScnVDU(scn_screen);
    /* Directs all plot commands to the specified */
    /* virtual screen. If NULL is specified then  */
    /* plotting is directed back to the terminal. */
    /* An application should call this function   */
    /* regularly, since it is only then that the  */
    /* terminal is updated and pending Wimp       */
    /* actions are performed. Calls should be     */
    /* used as brackets around plotting           */
    /* routines. For example:                     */
    /*                                            */
    /*          ScnVDU(screen);                   */
    /*          GrMove(x1, y1);                   */
    /*          GrDraw(x2, y2);                   */
    /*          ScnVDU(NULL);                     */
    /*                                            */
    /* Between such 'brackets', no uses of other  */
    /* graphics redirection functions should      */
    /* appear. (e.g. SprVDU must not be called.)  */
    /* Extra calls to ScnVDU(NULL) can be added   */
    /* to let the Wimp in during long             */
    /* calculations. It is usual to end a program */
    /* with  "while(1) ScnVDU(NULL);"             */

void ScnClickS(scn_screen, scn_action);
    /* Defines the action to be performed, when   */
    /* the SELECT button is clicked over the work */
    /* area of a screen. Such actions are         */
    /* specified as functions with two integer    */
    /* arguments, through which the               */
    /* (window-relative) mouse coordinates are    */
    /* passed. Actions initiated in this way are  */
    /* not performed until a call is made to      */
    /* ScnVDU (or WinCoop).                       */

void ScnClickM(scn_screen, scn_action);
    /* As above, for the MENU button.             */

void ScnClickA(scn_screen, scn_action);
    /* As above, for the ADJUST button.           */

void ScnPress(scn_screen, scn_use_char);
/*
 *  Requests the input focus for the specified screen
 *  and regesters a character handler. The character
 *  handler should return 1 each time it wishes to claim a
 *  character and 0 if it rejects one. To lose the input
 *  focus specify NULL as the character handler.
 */

void ScnFocus(scn_screen, scn_caret);
/*
 * Registers a handler for gaining and losing of the input
 * focus. The handler will be called with 1 as its argument
 * when the screen gains the caret, and with 0 when it loses
 * the caret.
 */
 
void ScnDrag(scn_screen, scn_select);
/*
 * Registers the selection handler to be used when the mouse
 * is dragged over the work area of the specified screen.
 */

void ScnLoad(scn_screen, scn_load);
    /* Define the action to be performed when a   */
    /* file icon is dropped on the work area of a */
    /* screen.                                    */

#endif /* _PGscn */
