/*
 * 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: PGwin.h                                      */
/* Author: Paul Gardiner.                             */
/* Function:                                          */
/*   This is one of two alternative modules for       */
/* manipulating windows under control of the Wimp -   */
/* the other being PGscn. This module provides a      */
/* library of functions for directly manipulating     */
/* windows, leaving the responsibility of redrawing   */
/* the window to the application. Use of this module  */
/* must begin with a call to WinInit. Calls to this   */
/* and the PGscn 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 _PGwin_
#define _PGwin_

#include "kernel.h"
#include "PGspr.h"

#ifndef NULL
#define NULL 0
#endif

typedef struct win_template_s *win_template;

typedef struct win_window_s   *win_window;

typedef void (*win_draw)(void);

typedef void (*win_closing)(void);

typedef void (*win_new_mode)(void);

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

typedef int (*win_use_char)(int);

typedef void (*win_caret)(int);

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

typedef void (*win_load)(char *);

typedef void (*win_save)(char *);

typedef int (*win_data_open)(int, char *);

typedef void (*win_callback)(void *);

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

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

char *WinTaskName(void);

void WinCoOp(void);
    /* Allow the Wimp to operate. This function  */
    /* must not be called while output is redirected */
    /* away from the terminal.                   */

void WinSleep(int t);
/*
  Like WinCoOp but friendlier to other applications.
  Wont come back for at least t cs.  t = -1 means
  don't come back at all.
*/

win_template WinStdTplt(void);
    /* Returns the standard template for         */
    /* creating graphic-display windows.         */

win_template WinLdTplt(char *, char *);
    /* Load a template. The first argument       */
    /* specifies the file name - the second the  */
    /* template name.                            */

void WinSprites(win_template, spr_sprite *);
/*
  Attaches a group of sprites to a window template.
  The sprite pointer should be one returned by SprLoadN.
*/

win_window WinIconBar(void);
/*
  Allow the icon bar to be viewed as a window.
*/

win_window WinCreate(win_template);
    /* Create a window.                          */

void WinTitle(win_window, char *);
    /* Change the window title.                  */

void WinKill(win_window);

void WinOpen(win_window);
    /* Open the specified window.                */

void WinClose(win_window);
    /* Close the specified window.               */

void WinExtent(win_window, int *, int *, int *, int *);
/*
 * Return the working area of the specified window as
 * xmin, ymin, xmax, ymax.
 */

void WinSetExtent(win_window, int, int, int, int);
    /* Set working area of specified window,     */
    /* specified as xmin, ymin, xmax, ymax       */

void WinGetPlace(win_window, int *, int *);
/*
 * Returns top left coordinate of specified window.
 */

void WinPlace(win_window, int, int);
/*
 * Open specified window so that top left corner coinsides with
 * specified coordinate.
 */

void WinNudge(win_window, int, int);
/*
 * Move window by specified amount
 */

void WinFullSize(win_window);
/*
 * Open window to full size.
 */

void WinShowBottom(win_window);
/*
 * Scroll window to show bottom of working area.
 */

void WinNewMode(win_new_mode);
/*
 * Registers a handler for mode changes.
 */

void WinContent(win_window, win_draw);
    /* Define the plotting function for           */
    /* redrawing the specified window.            */
    /* The plotting function can be written under */
    /* the assumption that the graphics origin    */
    /* has been positioned at the window's work-  */
    /* space origin.                              */

void WinRedrawArea(int *, int *, int *, int *);
/*
 * This function may be called from within the
 * body of a window's redraw handler; it returns
 * the rectangle to be redrawn in work area
 * coordinates. Often this call can be avoided, because
 * sufficient speed is achieved by the handler redrawing the
 * entire window on every call.
 */

void WinPatch(win_window, int, int, int, int);
    /* Update the specified area of a window,    */
    /* using the draw function that was passed   */
    /* to WinContent. The area is given as       */
    /* xmin, ymin, xmax, ymax.                   */

void WinClickS(win_window, win_action);
    /* Defines the action to be performed, when   */
    /* the SELECT button is clicked over the work */
    /* area of a window. 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). The SELECT button     */
    /* may be deactivated by specifying NULL as   */
    /* the action.                                */

void WinClickM(win_window, win_action);
    /* As above for the MENU button.             */

void WinClickA(win_window, win_action);
    /* As above for the ADJUST button.           */

void WinClickC(win_window, win_closing);
    /* As Above for clicks over the close icon of */
    /* a window, and any other cause of a close   */
    /* request. As a default the window is closed */

int WinDoubled(void);

void WinPress(win_window, win_use_char);
/*
 *  Requests the input focus for the specified window
 *  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 WinFocus(win_window, win_caret);
/*
 * Registers a handler for gaining and losing of the input
 * focus. The handler will be called with 1 as its argument
 * when the window gains the caret, and with 0 when it loses
 * the caret.
 */

void WinDrag(win_window, win_select);
/*
 * Registers the selection handler to be used when the mouse
 * is dragged over the work area of the specified window.
 */

void WinDataOpen(win_data_open);
/*
  Register a handler for data open messages.
*/

void WinLoad(win_window, win_load);
    /* Define the action to be performed when a   */
    /* file icon is dropped in a window.          */

void WinSetData(win_window, void *);
    /* Associates data with a window so that it   */
    /* can be accessed by calling WinData.        */

void *WinGetData(win_window);
    /* Return the data associated with a          */
    /* specific window.                           */

void *WinData(void);
    /* This function may be called within the     */
    /* body of service functions (i.e. those      */
    /* passed as arguments to:                    */
    /*       WinContents                          */
    /*       WinClickS                            */
    /*       WinClickM                            */
    /*       WinClickA                            */
    /*       WinLoad                              */
    /* The function will return the data that     */
    /* has been associated with the window for    */
    /* which the service is being performed.      */

win_window WinSaveAs(char *, win_save);
    /* Creates a save-as window and defines the   */
    /* saving action to be performed.             */

void WinHourGlass(int);
    /* Turns hour glass on and off; non-zero on, zero off*/

void WinHourGlassPercentage(int);
    /* Sets a previously turned on hour glass to percentage in the range 0-99 */
    /* use -1 to turn off */

void WinRedraw(int, int, int, int);
/*
    Instruct WIMP to redraw part of the screen
    at the next opportunity.
*/

void WinError(_kernel_oserror *err);

void WinMessage(_kernel_oserror *err);

int WinCallBack(win_callback, void *);
/*
    Give a routine to callback and some data to call it with. Callbacks are
    all at the next available opportunity and are guaranteed to be outside
    WinCoOp. Returns non-zero for 'unable to queue'.
    */

#endif /* _PGwin */
