(* Title:   win.h
 * Purpose: central management of RISC OS windows
 *
 *)

# ifndef __win_h
# define __win_h

# ifndef __wimp_h
# include "wimp.h"
# endif

(* This module constructs a very simple idea of "window class" within RISCOS.
 * RISCOS window class implementations register the existence of each window
 * with this module. 
 *)

(* This structure allows event-processing loops to be constructed that
 * have no knowledge of what other modules are present in the program.
 * For instance, the dialogue box module can contain an event-processing loop
 * without reference to what other window types are present in the program.
 *)
type win_event_handler = ^procedure event_handler(e : wimp_eventstr_ptr;
                                                  handle : pointer);

(* ************************** Claiming Events. *************************** *)


(* ------------------------- win_register_event_handler --------------------
 * Description:   Install an event handler function for a given window.
 *
 * Parameters:    wimp_w -- the window's handle
 *                win_event_handler -- the event handler function
 *                void *handle -- caller-defined handle 
 * Returns:       void.
 * Other Info:    This call has no effect on the window itself -- it just
 *                informs the win module that the supplied function should
 *                be called when events are delivered to the window.
 *                To remove a handler, call with a null function pointer,
 *                ie.  win_register_event_handler(w,(win_event_handler)0,0)
 *                To catch key events for an icon on the icon bar register
 *                a handler for win_ICONBAR,
 *                   ie. win_event_handler(win_ICONBAR, handler_func, handle)
 *                To catch load event for an icon on the icon bar register
 *                a handler for win_ICONBARLOAD,
 *                 ie. win_event_handler(win_ICONBARLOAD, load_func, handle).
 *
 *)
const   win_ICONBAR = -3;
        win_ICONBARLOAD = -99;

procedure win_register_event_handler(w : wimp_w;
                p : win_event_handler;
                handle : pointer); extern;


(* ------------------------- win_read_event_handler ------------------------
 * Description:   Read current event handler for a given window, and the
 *                handle which it is passed.
 *
 * Parameters:    wimp_w w -- the window's handle
 *                win_event_handler *p -- the handler function
 *                void **handle -- the handle passed to the handler function
 * Returns:       TRUE if given window is registered, FALSE otherwise
 * Other Info:    This is useful for registering an alternative event handler
 *                which can vet events, before passing them on to the original
 *                handler.
 *
 *)
function win_read_eventhandler(w : wimp_w;
                var p : win_event_handler;
                var handle : pointer) : boolean; extern;


(* ------------------------- win_claim_idle_events -------------------------
 * Description:   Cause "idle" events to be delivered to a given window.
 *
 * Parameters:    wimp_w -- the window's handle
 * Returns:       void.
 * Other Info:    To cancel this, call with window handle (wimp_w)-1.
 *
 *)
procedure win_claim_idle_events(w : wimp_w); extern;


type win_unknown_event_processor = ^function handler(e : wimp_eventstr_ptr;
                                        handle : pointer) : boolean;
(* You can ask to vet unknown events, before they are passed to the default
 * unknown event handler. These procs return TRUE if they have dealt with the
 * event.
 *)


(* --------------------- win_add_unknown_event_processor -------------------
 * Description:   Add a handler for unknown events onto the front of the
 *                queue of such handlers.
 *
 * Parameters:    win_unknown_event_processor -- handler function
 *                void *handle -- passed to handler on call
 * Returns:       void.
 * Other Info:    The win module maintains a list of unknown event handlers.
 *                An unknown event results in the "head of the list" function
 *                being called; if this function doesn't deal with the event
 *                it is passed on to the next in the list, and so on.
 *                Handler functios should return a Boolean result to show
 *                if they dealt with the event, or if it should be passed on.
 *                "Known" events are as follows:
 *                         ENULL, EREDRAW, ECLOSE, EOPEN, EPTRLEAVE, 
 *                         EPTRENTER, EKEY, ESCROLL, EBUT
 *                         and ESEND/ESENDWANTACK for the following msg types
 *                             MCLOSEDOWN, MDATASAVE, MDATALOAD, MHELPREQUEST
 *                All other events are considered "unknown"
 *                Note: if none of the unknown event handlers deals with the
 *                event, then it is passed on to the unknown event claiming
 *                window (registered by win_claim_unknown_events()). If 
 *                there is no such claimer, then the unknown event is 
 *                ignored. 
 *
 *)
procedure win_add_unknown_event_processor(p : win_unknown_event_processor;
                handle : pointer); extern;


(* ------------------ win_remove_unknown_event_processor -------------------
 * Description:   Removes the given unknown event handler with the given
 *                handle from the stack of handlers.
 *
 * Parameters:    win_unknown_event_processor -- the handler to be removed
 *                void *handle -- its handle
 * Returns:       void.
 * Other Info:    The handler to be removed can be anyway in the stack
 *                (not necessarily at the top).
 *
 *)
procedure win_remove_unknown_event_processor(p : win_unknown_event_processor;
                handle : pointer); extern;


(* ---------------------- win_idle_event_claimer ---------------------------
 * Description:   Informs caller of which window is claiming idle events.
 *
 * Parameters:    void
 * Returns:       Handle of window claiming idle events.
 * Other Info:    Returns (wimp_w)-1, if no window is claiming idle events.
 *
 *)
function win_idle_event_claimer : wimp_w; extern;


(* ---------------------- win_claim_unknown_events -------------------------
 * Description:   Cause any unknown, or non-window-specific events to be
 *                delivered to a given window.
 *
 * Parameters:    wimp_w -- handle of window to which unknown events should
 *                          be delivered
 * Returns:       void.
 * Other Info:    Calling with (wimp_w)-1 cancels this
 *                See win_add_unknown_event_processor() for details of which
 *                events are "known".
 *
 *)
procedure win_claim_unknown_events(w : wimp_w); extern;


(* ------------------------- win_unknown_event_claimer ---------------------
 * Description:   Informs caller of which window is claiming unknown events.
 *
 * Parameters:    void
 * Returns:       Handle of window claiming unknown events.
 * Other Info:    Return of (wimp_w)-1 means no claimer registered.
 *
 *)
function win_unknown_event_claimer : wimp_w; extern;



(* ********************************* Menus. ****************************** *)


(* ---------------------------- win_setmenuh -------------------------------
 * Description:   Attaches the given menu structure to the given window
 *
 * Parameters:    wimp_w -- handle of window
 *                void *handle -- pointer to menu structure
 * Returns:       void.
 * Other Info:    Mainly used by higher level RISC_OSlib routines to attach
 *                menus to windows (eg. event_attachmenu()).
 *
 *)
procedure win_setmenuh(w : wimp_w; handle : pointer); extern;


(* --------------------------- win_getmenuh --------------------------------
 * Description:   Returns a pointer to the menu structure attached to given
 *                window.
 *
 * Parameters:    wimp_w -- handle of window
 * Returns:       pointer to the attached menu (0 if no menu attached).
 * Other Info:    As for win_setmenuh(), this is used mainly by higher level
 *                RISC_OSlib routines (eg. event_attachmenu()).
 *
 *)
function win_getmenuh(w : wimp_w) : pointer; extern;


(* ************************** Event Processing. ************************** *)


(* -------------------------- win_processevent -----------------------------
 * Description:   Delivers an event to its relevant window, if such a window
 *                has been registered with this module (via
 *                win_register_event_handler()).
 *
 * Parameters:    wimp_eventstr* -- pointer to the event which has occurred
 * Returns:       true if an event handler (registered with this module)
 *                has dealt with the event, false otherwise.
 * Other Info:    the main client for this routine is event_process(), which
 *                uses it to deliver an event to its appropriate window.
 *                Keyboard events are delivered to the current owner of the
 *                caret.
 *
 *)
function win_processevent(e : wimp_eventstr_ptr) : boolean; extern;


(* ****************************** Termination. *************************** *)


(* --------------------------- win_activeinc -------------------------------
 * Description:   Increment by one the win module's idea of the number of
 *                active windows owned by a program.
 *
 * Parameters:    void
 * Returns:       void.
 * Other Info:    Note: event_process() calls exit() on behalf of the program
 *                when the number of active windows reaches zero
 *                Programs which wish to remain running even when they have
 *                no active windows, should ensure that win_activeinc() is
 *                called once before creating any windows, so that the no.
 *                of active windows is always >= 1. This is done for you
 *                if you use baricon() to install your program's icon on the
 *                iconbar.
 *
 *)
procedure win_activeinc; extern;


(* ---------------------------- win_activedec ------------------------------
 * Description:   Decrements by one the win module's idea of the number of
 *                active windows owned by a program.
 *
 * Parameters:    void
 * Returns:       void.
 * Other Info:    See note in win_activeinc() regarding program termination.
 *
 *)
procedure win_activedec; extern;


(* ---------------------------- win_activeno -------------------------------
 * Description:   Informs the caller of the number of active windows owned
 *                by your program.
 *
 * Parameters:    void
 * Returns:       no. of active windows owned by program.
 * Other Info:    This is given by (no. of calls to win_activeinc()) minus
 *                (no. of calls to win_activedec())
 *                Note that modules in RISCOSlib itself may have made calls
 *                to win_activeinc() and win_activedec().
 *
 *)
function win_activeno : integer; extern;


(* -------------------------- win_give_away_caret --------------------------
 * Description:   gives the caret away to the open window at the top of the
 *                WIMP's window stack (if that window is owned by your
 *                program).
 * 
 * Parameters:    void
 * Returns:       void.
 * Other Info:    If the top window is interested it will take the caret
 *                If not then nothing happens.
 *                Note: only works if polling is done using the wimpt module,
 *                which is the case if your main inner loop goes something
 *                like:   while (TRUE)
 *                            event_process();
 *
 *)
procedure win_give_away_caret; extern;

(* ------------------------------ win_settitle -----------------------------
 * Description:   changes the title displayed in a given window
 *
 * Parameters:    wimp_w w      -- given window's handle
 *                char *newtitle -- null-terminated string giving new
 *                                  title for window
 *
 * Returns:       void.
 * Other Info:    The title icon of the given window must be indirected text
 *                This will change the title used by all windows created
 *                from the given window's template if you have used the
 *                template module (since the Window manager uses your address
 *                space to hold indirected text icons). To avoid this the 
 *                window can be created from a copy of the template, ie.
 *                    template *t = template_copy(template_find("name"));
 *                    wimp_create_wind(t->window, &w);
 *
 *)
procedure win_settitle(w : wimp_w; newtitle : string); extern;

(* ------------------------------ win_init ---------------------------------
 * Description:   initialise the centralised window event system
 *
 * Parameters:    void
 * Returns:       TRUE if initialisation went OK.
 * Other Info:    If you use wimpt_init(), to start your application, then
 *                this call is made for you.
 *
 *)
function win_init : boolean; extern;

#endif

(* end win.h *)
