Initial revision

[ssr] / StraySrc / Libraries / Steel / h / win

/****************************************************************************
 * 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 */