win

/* Copyright 1996 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/****************************************************************************
 * 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.                         *
 *                                                                          *
 ***************************************************************************/

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

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


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


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

void win_settitle(wimp_w w, char *newtitle);

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

BOOL win_init(void);

#endif

/* end win.h */