/**************************************************************************** * This source file was written by Acorn Computers Limited. It is part of * * the RISCOS library for writing applications in C for RISC OS. It may be * * used freely in the creation of programs for Archimedes. It should be * * used with Acorn's C Compiler Release 3 or later. * * * ***************************************************************************/ /*----- Licensing note ----------------------------------------------------* * * This file is part of Straylight's Steel library. * * Steel is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2, or (at your option) * any later version. * * Steel is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with Steel. If not, write to the Free Software Foundation, * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /* Title: win.h * Purpose: central management of RISC OS windows * */ # ifndef __win_h # define __win_h # ifndef __wimp_h # include "wimp.h" # endif #ifndef BOOL #define BOOL int #define TRUE 1 #define FALSE 0 #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. */ typedef void (*win_event_handler)(wimp_eventstr*, void *handle); typedef void (*win_idle_claimer)(void *handle); /* ************************** 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). * */ #define win_ICONBAR (-3) #define win_ICONBARLOAD (-99) void win_register_event_handler(wimp_w, win_event_handler, void *handle); /* ------------------------- 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. * */ BOOL win_read_eventhandler(wimp_w w, win_event_handler *p, void **handle); /* * void win_idleTime(int time) * * Use * Sets the approximate time requested between calls of idle claimer * routines. The actual time may be more (e.g. if other tasks are busy) or * less (if idle claimers with a lower time are specified). * * Parameters * int time == approximate time in centiseconds between idle claimer calls */ void win_idleTime(int time); /* * void win_addIdleClaimer(win_idle_claimer proc,void *handle) * * Use * Allows a list of idle event claimers to be set up, as opposed to just * one. * * Parameters * win_idle_claimer proc == the procedure to add * int speed == requested number centiseconds between calls, or * win_DONTCARE * void *handle == the jolly old handle (again!) */ #define win_DONTCARE (-1) void win_addIdleClaimer(win_idle_claimer proc,int speed,void *handle); /* * BOOL win_any_idles(void) * * Use * Returns TRUE if there are any routines using the idle claimer system */ BOOL win_any_idles(void); /* * void win_removeIdleClaimer(win_idle_claimer proc,void *handle) * * Use * Removes a procedure from the list. * * Parameters * win_idle_claimer proc == the procedure to remove * void *handle == the procedure's handle */ void win_removeIdleClaimer(win_idle_claimer proc,void *handle); /* --- Macros for the old versions --- */ #define win_add_idle_claimer(p,h) win_addIdleClaimer(p,win_DONTCARE,h) #define win_remove_idle_claimer(p,h) win_removeIdleClaimer(p,h) /* ------------------------- 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. * */ void win_claim_idle_events(wimp_w); typedef BOOL (*win_unknown_event_processor)(wimp_eventstr*, void *handle); /* 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. * */ void win_add_unknown_event_processor(win_unknown_event_processor, void *handle) ; /* ------------------ 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). * */ void win_remove_unknown_event_processor(win_unknown_event_processor, void *handle) ; /* ---------------------- 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. * */ wimp_w win_idle_event_claimer(void); /* ---------------------- 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". * */ void win_claim_unknown_events(wimp_w); /* ------------------------- 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. * */ wimp_w win_unknown_event_claimer(void); /* ********************************* 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()). * */ void win_setmenuh(wimp_w, void *handle); /* --------------------------- 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()). * */ void *win_getmenuh(wimp_w); /* ************************** Event Processing. ************************** */ /* * void win_broadcast(wimp_eventstr *e) * * Use * Broadcasts the given event to ALL windows currently active. Note: this * works in a similar way to module service calls - a broadcast can be * 'claimed' by changing it to a null event. This is most useful for * informing other windows about events (such as a parent window being * closed), and thus message broadcasts should be used. * * Parameters * wimp_eventstr *e == the event to broadcast. */ void win_broadcast(wimp_eventstr *e); /* -------------------------- 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. * */ BOOL win_processevent(wimp_eventstr*); /* ****************************** 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. * */ void win_activeinc(void); /* ---------------------------- 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. * */ void win_activedec(void); /* ---------------------------- 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(). * */ int win_activeno(void); /* -------------------------- 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(); * */ void win_give_away_caret(void); /* ------------------------------ win_settitle ----------------------------- * Description: changes the title displayed in a given window * * Parameters: wimp_w w -- given window's handle * char *newtitle -- null-terminated printf-type string * giving new title for window * ... -- more parameters * * 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); * */ void win_settitle(wimp_w w, char *newtitle,...); /* * void win_gadgetWidths(wimp_wflags f,wimp_box *b) * * Use * Returns a box giving the width of the system area around a window with * window flags f. */ void win_gadgetWidths(wimp_wflags f,wimp_box *b); /* * void win_adjustBox(wimp_openstr *o) * * Use * Adjusts a window so that it fits on the screen. * * Parameters * wimp_openstr *o == pointer to the block to fiddle */ void win_adjustBox(wimp_openstr *o); /* * BOOL win_anyWindows(void) * * Use * Informs the caller if there are any windows left. * * Returns * TRUE if there are */ BOOL win_anyWindows(void); #endif /* end win.h */