/* 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: event.h
* Purpose: system-independent central processing for window sytem events.
*
*/
# ifndef __event_h
# define __event_h
# ifndef __menu_h
# include "menu.h"
# endif
# ifndef __wimp_h
# include "wimp.h"
# endif
#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif
/* ************************** Processing Events ************************* */
/* ---------------------------- event_process ------------------------------
* Description: Process one event.
*
* Parameters: void.
* Returns: void.
* Other Info: If the number of current active windows is 0 then the
* program exits. One event is polled and processed (with
* the exception of some complex menu handling, this really
* means passing the event on to the "win" module). Unless
* an application window is claiming idle events, this
* function waits when processor is idle.
* Typically this should be called in a loop in the main
* function of the application.
*
*/
void event_process(void);
/* ----------------------------- event_anywindows --------------------------
* Description: Informs caller if there are any windows active, that can
* process events.
*
* Parameters: void.
* Returns: TRUE if there are any active windows.
* Other Info: None.
*
*/
BOOL event_anywindows(void);
/* *************************** Attaching menus *************************** */
typedef int event_w;
typedef void (*event_menu_proc)(void *handle, char* hit);
typedef menu (*event_menu_maker)(void *handle);
/* -------------------------- event_attachmenu ----------------------------
* Description: Attach a menu, and its associated handler function, to the
* given window.
*
* Parameters: event_w -- the window to which menu should be attached
* menu -- the menu structure
* event_menu_proc -- the handler for the menu
* void *handle -- caller-defined handle
* Returns: TRUE if able to attach menu.
* Other Info: The menu should have been created by a call to menu_new
* or something similar. When user invokes a menu from the
* given window, this menu will be activated. The handler
* function will be called when the user selects a menu entry
* The handler's parameter "hit" is a string containing a
* character for each level of nesting in a hierarchical menu
* structure, terminated by a 0 character. A call with
* menu == 0 removes the attachment. NOTE: to catch menu
* events on the iconbar attach a menu to win_ICONBAR
* (defined in the win module).
*
*/
BOOL event_attachmenu(event_w, menu, event_menu_proc, void *handle);
/* ------------------------ event_attachmenumaker -------------------------
* Description: Attach to the given window, a function which makes a menu
* when the user invokes a menu
*
* Parameters: event_w -- the window to which the menu maker should be
* attached
* event_menu_maker -- the menu maker function
* event_menu_proc -- handler for the menu
* void *handle -- caller-defined handle
* Returns: TRUE if able to attach menu maker
* Other Info: This works similarly to event_attachmenu, except that it
* allows you to make any last minute changes to flags in the
* menu etc. (eg. ticks/fades), before displaying it. Call
* with event_menu_maker==0 removes attachment
*
*/
BOOL event_attachmenumaker(
event_w, event_menu_maker, event_menu_proc, void *handle);
/* ----------------------- event_clear_current_menu ------------------------
* Description: Clears the current menu tree.
*
* Parameters: void.
* Returns: void.
* Other Info: To be used when you are not sure that all menus have been
* cleared from the screen.
*
*/
void event_clear_current_menu(void);
/* ------------------ event_is_menu_being_recreated ------------------------
* Description: Informs caller if a menu is being recreated.
*
* Parameters: void.
* Returns: void.
* Other Info: Useful for when the RISC OS library is recreating a menu
* due to Adjust click (call it in your menu makers).
*
*/
BOOL event_is_menu_being_recreated(void) ;
/* ***************************** masking off events ********************** */
/* ----------------------------- event_setmask -----------------------------
* Description: Sets the mask used by wimp_poll and wimpt_poll when polling
* the WIMP.
*
* Parameters: wimp_emask mask - the desired mask.
* Returns: void
* Other Info: Bits of the mask are set if you want the corresponding
* events ignored (as in the wimp_poll SWI)
* eg. event_setmask(wimp_EMNULL | wimp_EMPTRENTER);
* will ignore nulls and pointer entering window events.
* NOTE: the default mask is to ignore null events only.
*
*/
void event_setmask(wimp_emask mask);
/* --------------------------- event_getmask -------------------------------
* Description: Inform the caller of the current mask being used to poll
* the WIMP.
*
* Parameters: void.
* Returns: The mask currently used.
* Other Info: none.
*
*/
wimp_emask event_getmask(void);
#endif
/* end event.h */