ARM Club 3/TheARMClub_PDCD3.iso/hensa/help/dlhelp_1/!DLHelp/DeskLib/HelpData

Text File | 1994-04-25 | 164KB | 4,949 lines

Help on DeskLib
#Sprite 40,0 !desklib
#Indent 9
DeskLib
v 2.04
#Indent 0

DeskLib consists of the following header files:
-----------------------------------------------
#Indent 1
#Table 10 14
<ColourTran>
<Coord>
<Core>
<Dialog>
<Dispatch>
<DragASpr>
<Error>
<Event>
<EventMsg>
<File>
<Filter>
<Font>
<GFX>
<Handler>
<Hourglass>
<Icon>
<Kbd>
<KeyCodes>
<LinkList>
<Mem>
<Menu>
<Msgs>
<PDriver>
<PopUp>
<Resource>
<Screen>
<Sound>
<Sprite>
<StringCR>
<SWI>
<Template>
<TextFile>
<Time>
<Validation>
<Wimp>
<WimpSWIs>
<Window>
#EndTable
#Indent 0
-----------------------------------------------
To link with the DeskLib library, use something
like:
  link $(linkflags) C:o.Stubs C:o.DeskLib

For examples of this, see !TestApp.MakeFile
                      and !TestApp.c.TestApp

Jason Williams May 1993DeskLib:ColourTran.h
These four functions form the C calling
interface to the ColourTrans module:
<ColourTrans_SetGCOL>
<ColourTrans_InvalidateCache>
<ColourTrans_SelectTable>
<ColourTrans_ReturnFontColours>DeskLib:Coord.h
Screen \<---\> Work Area conversion routines.
#Table 5 25
<Coord_PointInRect>
<Coord_RectContained>
<Coord_RectsOverlap>
<Coord_RectsIntersect>
<Coord_WindowOrigin>
<Coord_XToScreen>
<Coord_YToScreen>
<Coord_PointToScreen>
<Coord_RectToScreen>
<Coord_XToWorkArea>
<Coord_YToWorkArea>
<Coord_PointToWorkArea>
<Coord_RectToWorkArea>
#EndTable

NOTE:
  "Screen Coordinates" refers to OS coordinates, with the bottom
    left corner of the screen being placed at the screen origin, (0,0)
  "Work Area Coordinates" refers to Coordinates within the Window's
    work area, where the (0,0) origin is at the TOP left of the work area

Some of these routines have been defined as macros because they are
very elementary, and are common, so efficiency will be improved by
removing the function call overhead.

To keep compatibility with the syntax of Acorn's coords_ calls, these
macros still accept a pointer to a convert_block, which results in
code of the form (&convert)->xxx which would be better as convert.xxx
-I am banking on the compiler being smart enough to notice and generate
good code for this. If not, you can easily modify the macro to accept
the actual variable instead - just remember there's no type checking!DeskLib:Core.h
Core defines the following types and constants
used in other parts of DeskLib:

/* --- Boolean values */
#define BOOL  int

#define FALSE 0
#define TRUE  1

#define ERROR   1
#define NOERROR 0

Operating system errors (== _kernel_oserror)
are reported as type <os_error>DeskLib:Dialog.h
A dialogue is a window that is popped open to get user choices and
then goes away - They can act like menus (go away when you click outside
them) if opened with <Dialog_Show>(), or can be permanent windows if
you open them using <Dialog_ShowStatic>().
This code simplifies popping up such dialogues, as it handles opening,
closing and simple processing of the window for you.

See <Example=>Dialog_Example> for how to use Dialog

#Table 3 23
<Dialog_Create>
<Dialog_Destroy>
<Dialog_Show>
<Dialog_ShowStatic>
<Dialog_WaitForClick>
<Dialog_WindowHandle>
<Dialog_Persist>
<Dialog_LastClicked>
<Dialog_StillOpen>
#EndTableDeskLib:Dispatch
extern int Dispatch(int value, int size, int table[],
                    <dispatch_proc> functions[],
                    int arg0, int arg1, int arg2, int arg3);

Performs a table look up of value in table[size], and
calls the corrseponding procedure in functions[size], with
up to 4 arguments (any excess arguments will be safely ignored, as
these are the arguments that C passes in registers R0-R3)

If the table[] entry contains a -1 then the coresponding procedure in
functions[] is ALWAYS taken - Use this for a default action

defined in Dispatch.hDeskLib:DragASpr.h
These functions are the C calling
interface for the DragASprite module:
<DragASprite_Start>
<DragASprite_Stop>
<DragASprite_DragIcon>DeskLib:Error.h
#Table 4 30
<Error_ReportInternal>
<Error_ReportFatalInternal>
<Error_Report>
<Error_ReportFatal>
<Error_Check>
<Error_CheckFatal>
<Error_OutOfMemory>
#EndTableDeskLib:Event.h
<Notes on the use of Event_ functions=>Event_Note>

These global variables are defined:
#Table 2 23
<event_mask>
<event_taskhandle>
<event_wimpversion>
<event_taskname>
<event_lastevent>
#EndTable

And these functions:
#Table 3 23
<Event_Claim>
<Event_Release>
<Event_ReleaseWindow>
<Event_Process>
<Event_Poll>
<Event_Initialise>
<Event_Initialise3>
<Event_CloseDown>
#EndTableDeskLib:EventMsg.h
EventMsg.h defines these functions:
<EventMsg_Initialise>
<EventMsg_Claim>
<EventMsg_Release>
<EventMsg_ReleaseWindow>
<EventMsg_ReleaseMessage>DeskLib:File.h
<file_lasterror> reports the error status of File_* operations.

#Table 6 20
<File_Delete>
<File_Size>
<File_Exists>
<File_Open>
<File_Close>
<File_EOF>
<File_Seek>
<File_ReturnPos>
<File_WriteBytes>
<File_ReadBytes>
<File_Write8>
<File_Read8>
<File_Write32>
<File_Read32>
<File_Read32R>
<File_Write32R>
#EndTableDeskLib:Filter.h
These functions form a C interface to the
Filter Manager SWIs:
<Filter_RegisterPreFilter>
<Filter_RegisterPostFilter>
<Filter_DeRegisterPreFilter>
<Filter_DeRegisterPostFilter>DeskLib:Font.h
#Table 8 25
<Font_CacheAddr>
<Font_ListFonts>
<Font_ReadDefn>
<Font_ReadInfo>
<Font_ConvertToOS>
<Font_ConvertToPoints>
<Font_FindFont>
<Font_LoseFont>
<Font_LoseAllFonts>
<Font_SetFont>
<Font_CurrentFont>
<Font_FutureFont>
<Font_Paint>
<Font_Caret>
<Font_FindCaret>
<Font_FindCaretJ>
<Font_StringWidth>
<Font_CharBBox>
<Font_StringBBox>
<Font_ReadScaleFactor>
<Font_SetFontColours>
<Font_SetPalette>
<Font_ReadThresholds>
<Font_SetThresholds>
#EndTableDeskLib:GFX.h
GFX.h defines the following Graphics functions:
#Table 6 38
<GFX_Plot>
<GFX_ miscellaneous drawing macros=>GFX_MiscMacro>
<GFX_Rectangle>
<GFX_RectangleFill>
<GFX_Circle>
<GFX_CircleFill>
<GFX_CLG>
<GFX_VDU>
<GFX_Write0>
<GFX_WriteN>
<GFX_Wait>
#EndTableDeskLib:Handler.h
NOTE that these are basically EXAMPLE handlers, and so are
not all designed with peak efficiency in mind.
PLEASE read the information about these handlers *carefully*
before use.
Note that some handlers are for <Event>, some are for <EventMsg>

#Table 2 23
<Handler_CloseWindow>
<Handler_DeleteWindow>
<Handler_OpenWindow>
<Handler_NullRedraw>
<Handler_ClickOK>
<Handler_ModeChange>
#EndTableDeskLib:Hourglass.h
These Functions form the C calling
interface to the Hourglass module:

void Hourglass_On(void);
void Hourglass_Start(int startdelay);
void Hourglass_Percentage(int percent);
void Hourglass_Off(void);
void Hourglass_Smash(void);DeskLib:Icon.h
#Table 7 23
<Icon_BarIcon>
<Icon_GetSelect>
<Icon_GetShade>
<Icon_SetSelect>
<Icon_Select>
<Icon_Deselect>
<Icon_SetShade>
<Icon_Shade>
<Icon_Unshade>
<Icon_ForceWindowRedraw>
<Icon_SetCaret>
<Icon_LoseCaret>
<Icon_SetInteger>
<Icon_SetDouble>
<Icon_SetText>
<Icon_printf>
<Icon_GetDouble>
<Icon_GetInteger>
<Icon_GetText>
<Icon_SetRadios>
<Icon_WhichRadio>
<Icon_ClickWait>
<Icon_StartDrag>
<Icon_StartSolidDrag>
<Icon_DisposeIndData>
#EndTable

Slider icons: See "DeskLib.Libraries.Icon.c.Slider" for details
#Table 1 23
<Icon_SetSlider>
<Icon_UpdateSlider>
<Icon_DragSlider>
<Icon_ReadSlider>
#EndTableDeskLib:Kbd.h
There is one type:
<kbd_neginkey>

And one function:
<Kbd_KeyDown>DeskLib:KeyCodes.h
This header defines constants for key codes.

Some keypresses are returned the same if shift, ctrl are held down, so we
don't want people to think that keycode_SHIFT_X returns a different
value to keycode_X, these get the value <UNDEFINED>

<Keys on their own=>Key_own>
<Keys in combination with SHIFT=>Key_shift>
<Keys in combination with CTRL=>Key_ctrl>
<Keys in combination with SHIFT & CTRL=>Key_shiftctrl>DeskLib:LinkList.h
#Table 4 23
<LinkList_AddToHead>
<LinkList_AddToTail>
<LinkList_InsertBefore>
<LinkList_InsertAfter>
<LinkList_InList>
<LinkList_ListLength>
<LinkList_Unlink>
<LinkList_Init>
<LinkList_InitItem>
<LinkList_NextItem>
<LinkList_PreviousItem>
#EndTableDeskLib:Mem.h
"Flex" is the RISC OS Lib 'flexible' malloc for desktop tasks
"Mem" is DeskLib's equivalent thereof.

<Notes on the Mem library=>Mem_Note>

#Table 3 23
<Mem_Initialise>
<Mem_Alloc>
<Mem_MidExtend>
<Mem_MoveAnchor>
<Mem_Free>
<Mem_Compact>
<Mem_Size>
#EndTableDeskLib:Menu.h
<Notes on the use of Menu_ functions=>Menu_Note>

Functions:
#Table 4 25
<Menu_New>
<Menu_Extend>
<Menu_Show>
<Menu_ShowLast>
<Menu_AddSubMenu>
<Menu_MakeWritable>
<Menu_SetFlags>
<Menu_SetText>
<Menu_CalcHeight>
<Menu_SysHandle>
<Menu_SDispose>
#EndTable

Global variables:
#Table 1 25
<menu_currentpos>
<menu_currentopen>
#EndTableDeskLib:Msgs.h
These functions provide a C calling
interface for the MessageTrans module:
#Table 3 23
<Msgs_Lookup>
<Msgs_printf>
<Msgs_LoadFile>
<Msgs_DropGroup>
<Msgs_Report>
<Msgs_ReportFatal>
#EndTableDeskLib:PDriver.h
#Table 6 25
<PDriver_Info>
<PDriver_PrinterName>
<PDriver_CheckFeatures>
<PDriver_PageSize>
<PDriver_SelectJob>
<PDriver_CurrentJob>
<PDriver_EndJob>
<PDriver_AbortJob>
<PDriver_GiveRectangle>
<PDriver_DrawPage>
<PDriver_GetRectangle>
<PDriver_CancelJob>
<PDriver_ScreenDump>
<PDriver_EnumerateJobs>
<PDriver_CancelJobWithError>
<PDriver_SelectIllustration>
<PDriver_InsertIllustration>
#EndTableDeskLib:PopUp.h
<NOTE on the use of PopUp.h=>PopUp_Note>

<How to use the ProgInfo PopUp=>PopUp_ProgInfoHelp>
<How to use the SaveAs PopUp=>PopUp_SaveAsHelp>

<Constants defined in PopUp.h=>PopUp_Consts>

Type: <message_popuprequest>

Functions:
#Table 2 20
<PopUp_Open>
<PopUp_Close>
<PopUp_ShowMenuLeaf>
<PopUp_ShowPtr>
<PopUp_ShowStandalone>
<PopUp_ShowStatic>
#EndTableDeskLib:Resource.h
One of the following functions:
<Resource_Initialise>
<Resource_InitialisePath>

sets the variable <resource_pathname>. Other
modules use this to find their resources.DeskLib:Screen.h
EXTRA NOTES:
See Handler.c and '!TestApp.c' for examples of mode_change handlers to
automatically keep all these mode variables up-to-date, etc.

These variables can be accessed globally for maximum efficiency.
Note that they are not valid unless screen_mode == the current screen mode
This can be guaranteed if you call <Screen_CacheModeInfo>() every time
you get a mode change message, or before you attempt to use these variables

 Usage should be:
   <Screen_CacheModeInfo>();
   ...
   screenwidth = screen_size.x;   (or whatever)
   ...

extern int        screen_mode;
extern <wimp_point> screen_size;
extern <wimp_point> screen_eig;
extern <wimp_point> screen_delta;
extern int        screen_bpp;DeskLib:Sound.h
Sound_SysBeep()
extern void Sound_SysBeep(void);

Simply writes a character 7 (system beep) to the VDU stream, in order
to sound a system beep. It sorta goes 'beep', really.

defined in <Sound>DeskLib:Sprite.h
Constants:
#Table 1 23
<spritepool_SYSTEM>
<spritepool_WIMP>
#EndTable

Types defined in Sprite.h:
#Table 1 23
<sprite_header>
#EndTable

SpriteOp veneers:
#Table 5 23
<Sprite_ScreenSave>
<Sprite_ScreenLoad>
<Sprite_InitArea>
<Sprite_Load>
<Sprite_Save>
<Sprite_Create>
<Sprite_Delete>
<Sprite_Rename>
<Sprite_Copy>
<Sprite_Get>
<Sprite_Plot>
<Sprite_ReadInfo>
<Sprite_Redirect>
<Sprite_UnRedirect>
<Sprite_ReadSaveAreaSize>
#EndTable

Sprite manipulation functions:
#Table 1 23
<Sprite_MemorySize>
<Sprite_IconMemorySize>
#EndTableDeskLib:StringCR.h
Purpose: Provides functions identical in operation to those defined in
         ANSI \<string.h\>, except that these functions all work with strings
         that have non-zero terminating characters (BASIC and the WIMP
         often use a char 13 instead of a char 0 to terminate their
         strings). ANY char \< 32 will terminate these strings.
         These functions are currently defined in Sublibrary Misc.c.*

#Table 1 15
<strlencr>
<strcmpcr>
<strcatcr>
<strcpycr>
#EndTableDeskLib:SWI
This header defines the function:
<SWI=>SWI_f>DeskLib:Template.h
Template.h defines the following functions:
#Table 3 23
<Template_Initialise>
<Template_Find>
<Template_Clone>
<Template_Free>
<Template_Delete>
<Template_ClearAll>
<Template_LoadFile>
<Template_UseOutlineFonts>
#EndTableDeskLib:TextFile.h
This Header defines the following
TextFile manipulation functions:
<TextFile_Lowercase>
<TextFile_SkipBlanks>
<TextFile_GetToken>
<TextFile_ReadToDelimiter>DeskLib:Time.h
This header defines the function:
<Time_Monotonic>DeskLib:Validation.h
This header defines the function:
<Validation_ScanString>DeskLib:Wimp.h
Wimp.h defines the following constants:
<Wimp colours and palettes =>Wimp_colours>
<Wimp icon data =>Wimp_icons>
<wimp_NUMBEROFEVENTS>

Wimp.h defines the following types:
#Table 3 22
<wimp_coord>
<wimp_colour>
<palette_entry>
<window_colourindices>
<message_action>
<message_header>
#EndTableDeskLib:WimpSWIs.h
Task handling: init, closedown, messages, transfers, etc.
#Table 3 23
<Wimp_Initialise>
<Wimp_CloseDown>
<Wimp_StartTask>
<Wimp_SlotSize>
<Wimp_TransferBlock>
<Wimp_ReportError>
<Wimp_ReportErrorR>
<Wimp_SendMessage>
#EndTable

window handling
#Table 5 23
<Wimp_OpenTemplate>
<Wimp_CloseTemplate>
<Wimp_LoadTemplate>
<Wimp_CreateWindow>
<Wimp_OpenWindow>
<Wimp_CloseWindow>
<Wimp_DeleteWindow>
<Wimp_RedrawWindow>
<Wimp_UpdateWindow>
<Wimp_GetRectangle>
<Wimp_GetWindowState>
<Wimp_GetWindowInfo>
<Wimp_GetWindowOutline>
<Wimp_SetExtent>
<Wimp_ForceRedraw>
#EndTable

Icon handling
#Table 2 23
<Wimp_CreateIcon>
<Wimp_DeleteIcon>
<Wimp_SetIconState>
<Wimp_GetIconState>
<Wimp_WhichIcon>
<Wimp_PlotIcon>
#EndTable

Poll handling
<--- Notes on Poll handling ---=>Wimp_PollNote>
#Table 2 23
<Wimp_Poll>
<Wimp_PollIdle>
<Wimp_Poll3>
<Wimp_PollIdle3>
<Wimp_SaveFPStateOnPoll>
<Wimp_CorruptFPStateOnPoll>
#EndTable

Pointer/Mouse handling
#Table 1 23
<Wimp_GetPointerInfo>
<Wimp_SetPointerShape>
<Wimp_DragBox>
#EndTable

Caret handling
#Table 1 23
<Wimp_SetCaretPosition>
<Wimp_GetCaretPosition>
#EndTable

Menu handling
#Table 1 23
<Wimp_CreateMenu>
<Wimp_CreateSubMenu>
<Wimp_DecodeMenu>
#EndTable

Keyboard handling
<Wimp_ProcessKey>

Graphics/Screen handling
#Table 4 23
<Wimp_SetMode>
<Wimp_SetColour>
<Wimp_ReadPalette>
<Wimp_SetPalette>
<Wimp_ReadPixTrans>
<Wimp_SetFontColours>
<Wimp_SpriteOp>
<Wimp_BaseOfSprites>
<Wimp_BlockCopy>
<Wimp_CommandWindow>
#EndTableDeskLib:Window.h
Window.h defines these functions:
#Table 4 23
<Window_Create>
<Window_Show>
<Window_CreateAndShow>
<Window_Hide>
<Window_Delete>
<Window_GetInfo>
<Window_ParentName>
<Window_AutoHelp>
<Window_HelpHandler>
<Window_ModeChange>
<Window_SetTitle>
#EndTableWimp_Initialise
extern <os_error> *Wimp_Initialise(unsigned int *version,
                                 char         *name,
                                 <task_handle>  *task,
                                 int          *messages);

See also: <SWI Wimp_Initialise=>SWI.Wimp_Initialise>

defined in <WimpSWIs>Wimp_CloseDown
extern <os_error> *Wimp_CloseDown(<task_handle> task);

See also: <SWI Wimp_CloseDown=>SWI.Wimp_CloseDown>

defined in <Wimp_SWIs>Wimp_StartTask
extern <os_error> *Wimp_StartTask(char *command);

See also: <SWI Wimp_StartTask=>SWI.Wimp_StartTask>

defined in <Wimp_SWIs>Wimp_SlotSize
extern <os_error> *Wimp_SlotSize(int *currentslot, int *nextslot, int *freepool);

See also: <SWI Wimp_SlotSize=>SWI.Wimp_SlotSize>

defined in <Wimp_SWIs>Wimp_TransferBlock
extern <os_error> *Wimp_TransferBlock(<task_handle>  sourcetask,
                                    void         *sourcebuffer,
                                    <task_handle>  desttask,
                                    void         *destbuffer,
                                    unsigned int length);
See also: <SWI Wimp_TransferBlock=>SWI.Wimp_TransferBlock>

defined in <Wimp_SWIs>Wimp_ReportError
Reports an error in the standard WIMP non-multitasking error box.
Avoid (by using your own multitasking error box) where possible!
See also <Wimp_ReportErrorR>

extern <os_error> *Wimp_ReportError(<os_error> *error, int <flags=>error_flags>, char *name);

See also: <SWI Wimp_ReportError=>SWI.Wimp_ReportError>

defined in <Wimp_SWIs>Wimp_ReportErrorR
Identical to <Wimp_ReportError>, except this version returns the flags
that are returned by the SWI. That is, the return code from this
function is 1 if OK was pressed or 2 if Cancel was pressed.

extern int Wimp_ReportErrorR(<os_error> *error, int <flags=>error_flags>, char *name);

See also: <SWI Wimp_ReportError=>SWI.Wimp_ReportError>

defined in <Wimp_SWIs>Wimp_SendMessage
extern <os_error> *Wimp_SendMessage (<event_type>       eventtype,
                                   <message_block>    *message,
                                   <message_destinee> destinee,
                                   <icon_handle>      icon);
See also: <SWI Wimp_SendMessage=>SWI.Wimp_SendMessage>

defined in <Wimp_SWIs>Wimp_OpenTemplate
extern <os_error> *Wimp_OpenTemplate(char *name);

See also: <SWI Wimp_OpenTemplate=>SWI.Wimp_OpenTemplate>

defined in <Wimp_SWIs>Wimp_CloseTemplate
extern <os_error> *Wimp_CloseTemplate(void);

See also: <SWI Wimp_CloseTemplate=>SWI.Wimp_CloseTemplate>

defined in <Wimp_SWIs>Wimp_LoadTemplate
extern <os_error> *Wimp_LoadTemplate(<template_block> *template);

See also: <SWI Wimp_LoadTemplate=>SWI.Wimp_LoadTemplate>

defined in <WimpSWIs>Wimp_CreateWindow
extern <os_error> *Wimp_CreateWindow(<window_block> *block, <window_handle> *window);

See also: <SWI Wimp_CreateWindow=>SWI.Wimp_CreateWindow>

defined in <WimpSWIs>Wimp_OpenWindow
extern <os_error> *Wimp_OpenWindow(<window_openblock> *block);

See also: <SWI Wimp_OpenWindow=>SWI.Wimp_OpenWindow>

defined in <WimpSWIs>Wimp_CloseWindow
extern <os_error> *Wimp_CloseWindow(<window_handle> window);

See also: <SWI Wimp_CloseWindow=>SWI.Wimp_CloseWindow>

defined in <WimpSWIs>Wimp_DeleteWindow
extern <os_error> *Wimp_DeleteWindow(<window_handle> window);

See also: <SWI Wimp_DeleteWindow=>SWI.Wimp_DeleteWindow>

defined in <WimpSWIs>Wimp_RedrawWindow
extern <os_error> *Wimp_RedrawWindow(<window_redrawblock> *block, BOOL *more);

See also: <SWI Wimp_RedrawWindow=>SWI.Wimp_RedrawWindow>

defined in <WimpSWIs>Wimp_GetRectangle
extern <os_error> *Wimp_GetRectangle(<window_redrawblock> *block, BOOL *more);

See also: <SWI Wimp_GetRectangle=>SWI.Wimp_GetRectangle>

defined in <WimpSWIs>Wimp_GetWindowState
extern <os_error> *Wimp_GetWindowState(<window_handle> window, <window_state> *state);

See also: <SWI Wimp_GetWindowState=>SWI.Wimp_GetWindowState>

defined in <WimpSWIs>Wimp_GetWindowInfo
extern <os_error> *Wimp_GetWindowInfo(<window_info> *info);

See also: <SWI Wimp_GetWindowInfo=>SWI.Wimp_GetWindowInfo>

defined in <WimpSWIs>Wimp_UpdateWindow
extern <os_error> *Wimp_UpdateWindow(<window_redrawblock> *block, BOOL *more);

See also: <SWI Wimp_UpdateWindow=>SWI.Wimp_UpdateWindow>

defined in <WimpSWIs>Wimp_GetWindowOutline
extern <os_error> *Wimp_GetWindowOutline(<window_outline> *outline);

See also: <SWI Wimp_GetWindowOutline=>SWI.Wimp_GetWindowOutline>

defined in <WimpSWIs>Wimp_SetExtent
extern <os_error> *Wimp_SetExtent(<window_handle> window, <wimp_box> *newextent);

See also: <SWI Wimp_SetExtent=>SWI.Wimp_SetExtent>

defined in <WimpSWIs>Wimp_ForceRedraw
extern <os_error> *Wimp_ForceRedraw(<window_redrawblock> *block);

See also: <SWI Wimp_ForceRedraw=>SWI.Wimp_ForceRedraw>

defined in <WimpSWIs>Wimp_CreateIcon
extern <os_error> *Wimp_CreateIcon(<icon_createblock> *block, <icon_handle> *icon);

See also: <SWI Wimp_CreateIcon=>SWI.Wimp_CreateIcon>

defined in <WimpSWIs>Wimp_DeleteIcon
extern <os_error> *Wimp_DeleteIcon(<window_handle> window, <icon_handle> icon);

See also: <SWI Wimp_DeleteIcon=>SWI.Wimp_DeleteIcon>

defined in <WimpSWIs>Wimp_SetIconState
extern <os_error> *Wimp_SetIconState(<window_handle> window,
                                   <icon_handle>   icon,
                                   int           value,
                                   int           mask);

See also: <SWI Wimp_SetIconState=>SWI.Wimp_SetIconState>

defined in <WimpSWIs>Wimp_GetIconState
extern <os_error> *Wimp_GetIconState(<window_handle> window,
                                   <icon_handle>   icon,
                                   <icon_block>    *iconinfo);

See also: <SWI Wimp_GetIconState=>SWI.Wimp_GetIconState>

defined in <WimpSWIs>Wimp_WhichIcon
extern <os_error> *Wimp_WhichIcon(<window_handle>    window,
                                <icon_handle>      *icons,
                                int              mask,
                                int              settings);

See also: <SWI Wimp_WhichIcon=>SWI.Wimp_WhichIcon>

defined in <WimpSWIs>Wimp_PlotIcon
extern <os_error> *Wimp_PlotIcon(<icon_block> *fakeicon);

See also: <SWI Wimp_PlotIcon=>SWI.Wimp_PlotIcon>

defined in <WimpSWIs>Wimp_Poll
#define Wimp_Poll(mask, evt) <Wimp_Poll3>(mask, evt, 0)

See also: <SWI Wimp_Poll=>SWI.Wimp_Poll>

defined in <WimpSWIs>WimpPollIdle
#define Wimp_PollIdle(mask, evt, time) <Wimp_PollIdle3>(mask, evt, time, 0)

See also: <SWI WimpPollIdle=>SWI.WimpPollIdle>

defined in <WimpSWIs>Wimp_Poll3
extern <os_error> *Wimp_Poll3(<event_pollmask> mask, <event_pollblock> *event,
                            void *pollword);

See also: <SWI Wimp_Poll=>SWI.Wimp_Poll>

defined in <Wimp_SWIs>Wimp_PollIdle3
extern <os_error> *Wimp_PollIdle3(<event_pollmask> mask, <event_pollblock> *block,
                                int earliest, void *pollword);

See also: <SWI Wimp_PollIdle=>SWI.Wimp_PollIdle>

defined in <WimpSWIs>Wimp_SaveFPStateOnPoll
extern <os_error> *Wimp_SaveFPStateOnPoll(void);

See also: <Wimp_CorruptFPStateOnPoll>

See also: <SWI Wimp_SaveFPStateOnPoll=>SWI.Wimp_SaveFPStateOnPoll>

defined in <WimpSWIs>Wimp_CorruptFPStateOnPoll
extern <os_error> *Wimp_CorruptFPStateOnPoll(void);

See also: <Wimp_SaveFPStateOnPoll>

See also: <SWI Wimp_CorruptFPStateOnPoll=>SWI.Wimp_CorruptFPStateOnPoll>

defined in <WimpSWIs>Wimp_GetPointerInfo
extern <os_error> *Wimp_GetPointerInfo(<mouse_block> *ptrinfo);

See also: <SWI Wimp_GetPointerInfo=>SWI.Wimp_GetPointerInfo>

defined in <WimpSWIs>Wimp_SetPointerShape
extern <os_error> *Wimp_SetPointerShape(<pointer_shapeblock> *shape);

See also: <SWI Wimp_SetPointerShape=>SWI.Wimp_SetPointerShape>

defined in <WimpSWIs> Wimp_DragBox
extern <os_error> *Wimp_DragBox(<drag_block> *draginfo);

See also: <SWI Wimp_DragBox=>SWI.Wimp_DragBox>

defined in <WimpSWIs>Wimp_SetCaretPosition
extern <os_error> *Wimp_SetCaretPosition(<caret_block> *caret);

See also: <Wimp_GetCaretPosition>

See also: <SWI Wimp_SetCaretPosition=>SWI.Wimp_SetCaretPosition>

defined in <WimpSWIs>Wimp_GetCaretPosition
extern <os_error> *Wimp_GetCaretPosition(<caret_block> *caret);

See also: <Wimp_SetCaretPosition>

See also: <SWI Wimp_GetCaretPosition=>SWI.Wimp_GetCaretPosition>

defined in <WimpSWIs>Wimp_CreateMenu
extern <os_error> *Wimp_CreateMenu(<menu_block> *menu, int xpos, int ypos);

See also: <SWI Wimp_CreateMenu=>SWI.Wimp_CreateMenu>

defined in <WimpSWIs>Wimp_CreateSubMenu
extern <os_error> *Wimp_CreateSubMenu(<menu_block> *menu, int xpos, int ypos);

See also: <SWI Wimp_CreateSubMenu=>SWI.Wimp_CreateSubMenu>

defined in <WimpSWIs>Wimp_DecodeMenu
extern <os_error> *Wimp_DecodeMenu(<menu_block> *menu,
                                 int        *selections,
                                 char       *result);

See also: <SWI Wimp_DecodeMenu=>SWI.Wimp_DecodeMenu>

defined in <WimpSWIs>Wimp_ProcessKey
extern <os_error> *Wimp_ProcessKey(int character);

See also: <SWI Wimp_ProcessKey=>SWI.Wimp_ProcessKey>

defined in <WimpSWIs>Wimp_SetMode
extern <os_error> *Wimp_SetMode(int mode);

See also: <SWI Wimp_SetMode=>SWI.Wimp_SetMode>

defined in <WimpSWIs>Wimp_SetColour
extern <os_error> *Wimp_SetColour(int colour);

See also: <SWI Wimp_SetColour=>SWI.Wimp_SetColour>

defined in <WimpSWIs>Wimp_ReadPalette
extern <os_error> *Wimp_ReadPalette(<palette_block> *palette);

See also: <Wimp_SetPalette>

See also: <SWI Wimp_ReadPalette=>SWI.Wimp_ReadPalette>

defined in <WimpSWIs>Wimp_SetPalette
extern <os_error> *Wimp_SetPalette(<palette_block> *palette);

See also: <Wimp_ReadPalette>

See also: <SWI Wimp_SetPalette=>SWI.Wimp_SetPalette>

defined in <WimpSWIs>Wimp_ReadPixTrans
extern <os_error> *Wimp_ReadPixTrans(int         areaindex,
                                   void        *area,
                                   void        *sprite,
                                   <scale_block> *scaleblock,
                                   char        *transblock);

See also: <SWI Wimp_ReadPixTrans=>SWI.Wimp_ReadPixTrans>

defined in <WimpSWIs>Wimp_SetFontColours
extern <os_error> *Wimp_SetFontColours(int foreground, int background);

See also: <SWI Wimp_SetFontColours=>SWI.Wimp_SetFontColours>

defined in <WimpSWIs>Wimp_SpriteOp
extern <os_error> *Wimp_SpriteOp(<_kernel_swi_regs> *registers);

See also: <SWI Wimp_SpriteOp=>SWI.Wimp_SpriteOp>

defined in <WimpSWIs>Wimp_BaseOfSprites
extern <os_error> *Wimp_BaseOfSprites(void **rom_base, void **ram_base);

See also: <SWI Wimp_BaseOfSprites=>SWI.Wimp_BaseOfSprites>

defined in <WimpSWIs>Wimp_BlockCopy
extern <os_error> *Wimp_BlockCopy(<window_handle> window, <wimp_box> *source,
                                                      int x, int y);

See also: <SWI Wimp_BlockCopy=>SWI.Wimp_BlockCopy>

defined in <WimpSWIs>Wimp_CommandWindow
extern <os_error> *Wimp_CommandWindow(int);

See also: <SWI Wimp_CommandWindow=>SWI.Wimp_CommandWindow>

defined in <WimpSWIs>type: wimp_point
typedef struct
{
  int x, y;
} wimp_point;

defined in <Wimp>type: wimp_coord
typedef <wimp_point> wimp_coord;

defined in <Wimp>type: wimp_rect
typedef struct
{
  <wimp_point> min;
  <wimp_point> max;
} wimp_rect;

defined in <Wimp>type: wimp_box
typedef <wimp_rect> wimp_box;

defined in <Wimp>type: window_handle
typedef int window_handle;

defined in <Wimp>type: icon_handle
typedef int icon_handle;

defined in <Wimp>type: task_handle
typedef int task_handle;

defined in <Wimp>Const: wimp_MAXNAME
The size of wimp names (icon text fields, sprite names, etc)
#define wimp_MAXNAME 12

defined in <Wimp>Wimp colour constants:
#define colour_WHITE        0
#define colour_GREY0        0
#define colour_GREY1        1
#define colour_GREY2        2
#define colour_GREY3        3
#define colour_GREY4        4
#define colour_GREY5        5
#define colour_GREY6        6
#define colour_GREY7        7
#define colour_BLACK        7
#define colour_DARK_BLUE    8
#define colour_YELLOW       9
#define colour_GREEN       10
#define colour_RED         11
#define colour_CREAM       12
#define colour_ARMY_GREEN  13
#define colour_ORANGE      14
#define colour_LIGHT_BLUE  15

#define colour_TRANSPARENT 255

defined in <Wimp>type: wimp_colour
typedef union
{
  int value;
  struct
  {
    unsigned int wimpcolour : 4;
    unsigned int gcolaction : 3;
    unsigned int foreback   : 1;
    unsigned int padding    : 24;
  } data;
} wimp_colour;

defined in <Wimp>type: palette_entry
typedef union
{
  int value;
  struct
  {
    char gcol;
    char red;
    char green;
    char blue;
  } data;
} palette_entry;

defined in <Wimp>type: palette_block
typedef struct
{
  palette_entry colour[16];
  palette_entry border;
  palette_entry mouse1;
  palette_entry mouse2;
  palette_entry mouse3;
} palette_block;

defined in <Wimp>Wimp icons data constants
#define iconbtype_NEVER            0
#define iconbtype_ALWAYS           1
#define iconbtype_AUTOREPEAT       2
#define iconbtype_CLICK            3
#define iconbtype_RELEASE          4
#define iconbtype_DOUBLECLICK      5
#define iconbtype_CLICKDRAG        6
#define iconbtype_RELEASEDRAG      7
#define iconbtype_DOUBLEDRAG       8
#define iconbtype_MENU             9
#define iconbtype_DOUBLECLICKDRAG 10
#define iconbtype_RADIO           11
#define iconbtype_RESERVED1       12
#define iconbtype_RESERVED2       13
#define iconbtype_WRITECLICKDRAG  14
#define iconbtype_WRITABLE        15


Icon bar icon positions, and the window handle of
the iconbar when returned by the Wimp

#define iconbar_RIGHT -1
#define iconbar_LEFT  -2
#define window_ICONBAR -2

Icon flag bits
#define icon_TEXT        0x00000001   icon contains text
#define icon_SPRITE      0x00000002   icon is a sprite
#define icon_BORDER      0x00000004   icon has a border
#define icon_HCENTRE     0x00000008   text is horizontally centred
#define icon_VCENTRE     0x00000010   text is vertically centred
#define icon_FILLED      0x00000020   icon has a filled background
#define icon_FONT        0x00000040   text is an anti-aliased font
#define icon_NEEDSHELP   0x00000080   redraw needs application's help
#define icon_INDIRECTED  0x00000100   icon data is 'indirected'
#define icon_RJUSTIFY    0x00000200   text right justified in box
#define icon_ALLOWADJUST 0x00000400   Allow multiple select with adjust
#define icon_HALVESPRITE 0x00000800   plot sprites half-size
#define icon_BUTTONTYPE  0x00001000   4-bit field: button type
#define icon_SELECTED    0x00200000   icon selected by user (inverted)
#define icon_SHADED      0x00400000   icon cannot be selected (shaded)
#define icon_DELETED     0x00800000   icon has been deleted

#define icon_FORECOLOUR  0x01000000   4-bit field: foreground colour
#define icon_BACKCOLOUR  0x10000000   4-bit field: background colour

#define iconvalid_ALLOW           'A'
#define iconvalid_BORDERTYPE      'R'
#define iconvalid_DISPLAY         'D'
#define iconvalid_FONTCOLOURS     'F'
#define iconvalid_LINESPACE       'L'
#define iconvalid_SPRITENAME      'S'

#define iconborder_PLINTH          0
#define iconborder_SURROUND        1
#define iconborder_OKBUTTON        2
#define iconborder_INDENT          3

defined in <Wimp>type: icon_flags
typedef union
{
  unsigned int value;

  struct
  {
    unsigned int garbage1      : 6;    /* New struct to allow easy access to */
    unsigned int font          : 1;    /* the font handle of an icon. NOTE   */
    unsigned int garbage2      : 17;   /* that handle is ONLY valid IF       */
    unsigned int handle        : 8;    /* 'font' is TRUE.                    */
  } font;

  struct
  {
    unsigned int text          : 1;
    unsigned int sprite        : 1;
    unsigned int border        : 1;
    unsigned int hcentre       : 1;
    unsigned int vcentre       : 1;
    unsigned int filled        : 1;
    unsigned int font          : 1;
    unsigned int needshelp     : 1;
    unsigned int indirected    : 1;
    unsigned int rightjustify  : 1;
    unsigned int allowadjust   : 1;
    unsigned int halfsize      : 1;
    unsigned int buttontype    : 4;
    unsigned int esg           : 5;
    unsigned int selected      : 1;
    unsigned int shaded        : 1;
    unsigned int deleted       : 1;
    unsigned int foreground    : 4;
    unsigned int background    : 4;
  } data;
} icon_flags;

defined in <Wimp>type: icon_indtext
typedef struct
{
  char         *buffer;
  char         *validstring;
  unsigned int bufflen;
} icon_indtext;

defined in <Wimp>type: icon_indsprite
typedef struct
{
  const char   *name;
  unsigned int *spritearea;
  unsigned int nameisname;
} icon_indsprite;

defined in <Wimp>type: icon_data
typedef union
{
  char           text[<wimp_MAXNAME>];
  <icon_indtext>   indirecttext;
  char           spritename[<wimp_MAXNAME>];
  <icon_indsprite> indirectsprite;
} icon_data;

defined in <Wimp>type: icon_block
typedef struct
{
  <wimp_box>   workarearect;
  <icon_flags> flags;
  <icon_data>  data;
} icon_block;

defined in <Wimp> type: icon_createblock
typedef struct
{
  <window_handle> window;
  <icon_block>    icondata;
} icon_createblock;

defined in <Wimp>type: window_flags
typedef union
{
  struct
  {
    unsigned int hastitle      : 1;  /* these are "old-style" flags  */
    unsigned int moveable      : 1;  /* You should not be using them */
    unsigned int hasvscroll    : 1;  /* " */
    unsigned int hashscroll    : 1;  /* " */
    unsigned int autoredraw    : 1;  /* " */
    unsigned int pane          : 1;  /* " */
    unsigned int nobounds      : 1;  /* " */
    unsigned int nobackclose   : 1;  /* " */

    unsigned int scrollrq      : 1;
    unsigned int scrollrqdebounced : 1;
    unsigned int realcolours   : 1;
    unsigned int backwindow    : 1;
    unsigned int hotkeys       : 1;
    unsigned int dummy13       : 1;
    unsigned int dummy14       : 1;
    unsigned int dummy15       : 1;
    unsigned int open          : 1;
    unsigned int top           : 1;
    unsigned int fullsize      : 1;
    unsigned int istoggling    : 1;
    unsigned int focus         : 1;
    unsigned int dummy21       : 1;
    unsigned int dummy22       : 1;
    unsigned int dummy23       : 1;
    unsigned int backicon      : 1;
    unsigned int closeicon     : 1;
    unsigned int titlebar      : 1;
    unsigned int toggleicon    : 1;
    unsigned int vscroll       : 1;
    unsigned int adjusticon    : 1;
    unsigned int hscroll       : 1;
    unsigned int newflags      : 1;  /* This should always be TRUE */
  } data;
  int value;
} window_flags;

defined in <Wimp>type: window_minsize
typedef struct       /* Minimum width/height of window. Used to be: */
{                    /*   unsigned short minwidth, minheight;       */
  int x : 16;        /* This has been changed for compatability     */
  int y : 16;        /* with compilers other than Desktop C         */
} window_minsize;

defined in <Wimp>type: window_colourindices
typedef enum
{
  windowcol_TITLEFORE = 0,
  windowcol_TITLEBACK,
  windowcol_WORKFORE,
  windowcol_WORKBACK,
  windowcol_SCROLLBACK,
  windowcol_SCROLLFORE,
  windowcol_TITLEHILITE
} window_colourindices;

defined in <Wimp>type: window_block
typedef struct
{
  <wimp_box>       screenrect;
  <wimp_point>     scroll;
  <window_handle>  behind;
  <window_flags>   flags;
  char           colours[8];
  <wimp_box>       workarearect;
  <icon_flags>     titleflags;
  <icon_flags>     workflags;
  void           *spritearea;
  <window_minsize> minsize;
  <icon_data>      title;
  unsigned int   numicons;
  /*
   *  What we really want here is :
  icon_block        icons [0];
   *  but unfortunately 'C' (stupidly) doesn't allow it.  Just think it.
   */
} window_block;

defined in <Wimp>type: window_openblock
typedef struct
{
  <window_handle> window;
  <wimp_box>      screenrect;
  <wimp_point>    scroll;
  <window_handle> behind;
} window_openblock;

defined in <Wimp>type: window_state
typedef struct
{
  <window_openblock> openblock;
  <window_flags>     flags;
} window_state;

defined in <Wimp>type: window_info
typedef struct
{
  <window_handle> window;
  <window_block>  block;
} window_info;

defined in <Wimp>type: window_redrawblock
typedef struct
{
  <window_handle> window;
  <wimp_box>      rect;
  <wimp_point>    scroll;
  <wimp_box>      cliprect;
} window_redrawblock;

defined in <Wimp>type: window_outline
typedef struct
{
  <window_handle> window;
  <wimp_box>      screenrect;
} window_outline;

defined in <Wimp>type: button_state
typedef union
{
  unsigned int value;
  struct
  {
    unsigned int adjust       : 1;
    unsigned int menu         : 1;
    unsigned int select       : 1;
    unsigned int dummy3       : 1;
    unsigned int dragadjust   : 1;
    unsigned int dummy5       : 1;
    unsigned int dragselect   : 1;
    unsigned int dummy7       : 1;
    unsigned int clickadjust  : 1;
    unsigned int dummy9       : 1;
    unsigned int clickselect  : 1;
  } data;
} button_state;

defined in <Wimp.h>type: message_action
Wimp message data:

typedef enum
{
  message_QUIT           = 0,
  message_CLOSEDOWN      = 0,
  message_DATASAVE       = 1,
  message_DATASAVEACK    = 2,
  message_DATASAVEOK     = 2,
  message_DATALOAD       = 3,
  message_DATALOADACK    = 4,
  message_DATALOADOK     = 4,
  message_DATAOPEN,
  message_RAMFETCH,
  message_RAMTRANSMIT,
  message_PREQUIT,
  message_PALETTECHANGE,
  message_SAVEDESK,
  message_DEVICECLAIM,
  message_DEVICEINUSE,
  message_DATASAVED,

  message_FILEROPENDIR   = 0x400,
  message_FILERCLOSEDIR,

  message_HELPREQUEST    = 0x502,
  message_HELPREPLY,

  message_NOTIFY         = 0x40040,
  message_MENUWARNING    = 0x400C0,
  message_MENUWARN       = 0x400C0,
  message_MODECHANGE,
  message_TASKINITIALISE = 0x400C2,
  message_INITTASK       = 0x400C2,
  message_TASKCLOSEDOWN  = 0x400C3,
  message_CLOSETASK      = 0x400C3,
  message_SLOTSIZE       = 0x400C4,
  message_SLOTCHANGE     = 0x400C4,
  message_SETSLOT        = 0x400C5,
  message_TASKNAMERQ,
  message_TASKNAMEIS,
  message_TASKSTARTED,
  message_MENUSDELETED,              /* RO3 Menu closed warning    */
  message_WINDOWINFO     = 0x400CC,  /* RO3 For window iconisation */

  message_POPUPRQ        = 0x46D40,  /* PopUp messages - cf PopUp.h */
  message_POPUPREQUEST   = 0x46D40,
  message_POPUPSTATE,
  message_POPUPCLOSED,

  message_PRINTFILE      = 0x80140,
  message_WILLPRINT,
  message_PRINTTYPEODD   = 0x80145,
  message_PRINTTYPEKNOWN,
  message_PRINTERCHANGE
} message_action;

defined in <Wimp>: scale_block
typedef struct
{
  <wimp_point> mul;
  <wimp_point> div;
} scale_block;

defined in <Wimp>
type: template_block
typedef struct
{
  <window_block>   *buffer;
  char           *workfree;
  char           *workend;
  <font_array>     *font;
  char           *name;
  unsigned int   index;
} template_block;

defined in <Wimp>Font usage array  (font_array)
This array is indexed by the font handle - each entry contains a
count of how many times we have <Font_FindFont>'d this font. This is used
mainly by the template system (<Wimp_LoadTemplate>).
See <Font_LoseAllFonts>

typedef struct
{
  char fonts[256];
} font_array;

For convenience, this is defined in <Wimp>.h (it is mainly used for
template loading)type: event_pollblock
typedef struct
{
  <event_type> type;
  <event_data> data;
} event_pollblock;

defined in <Wimp>type: event_data
typedef union
{
  <caret_block>      caret;
  <key_block>        key;
  <pollword_block>   pollword;
  <window_openblock> openblock;
  <message_block>    message;
  <mouse_block>      mouse;
  <wimp_box>         screenrect;
  int              selection[10];
  <scroll_rq>        scroll;
  char             bytes [256];
  int              words [64];
} event_data;

defined in <Wimp>type: scrolls_rq
typedef struct
{
  <window_openblock> openblock;
  <wimp_point>       direction;
} scroll_rq;

defined in <Wimp>type: event_pollmask
typedef union
{
  unsigned int value;
  struct
  {
    unsigned int null                : 1;
    unsigned int redraw              : 1;
    unsigned int open                : 1;
    unsigned int close               : 1;
    unsigned int ptrleave            : 1;
    unsigned int ptrenter            : 1;
    unsigned int click               : 1;
    unsigned int userdrag            : 1;
    unsigned int key                 : 1;
    unsigned int menu                : 1;
    unsigned int scroll              : 1;
    unsigned int losecaret           : 1;
    unsigned int gaincaret           : 1;
    unsigned int nonzeropollword     : 1;
    unsigned int dummy14             : 1;
    unsigned int dummy15             : 1;
    unsigned int dummy16             : 1;
    unsigned int usermessage         : 1;
    unsigned int usermessagerecorded : 1;
    unsigned int usermessageack      : 1;
    unsigned int dummy20             : 1;
    unsigned int dummy21             : 1;
    unsigned int r3ispollwordptr     : 1;
    unsigned int highprioritypoll    : 1;
    unsigned int keepfpregisters     : 1;
  } data;
} event_pollmask;

defined in <Wimp>type: event_type
typedef enum
{
  event_ANY                 = -99,
     /*  see event.c: this is used to denote
      *  any event type, any window handle,
      *  or any icon handle ... thus -99.
      */
  event_NULL                = 0,
  event_REDRAW,
  event_OPEN,
  event_CLOSE,
  event_PTRLEAVE,
  event_PTRENTER,
  event_CLICK = 6,
  event_BUTTON = 6,
  event_USERDRAG,
  event_KEY,
  event_MENU,
  event_SCROLL,
  event_LOSECARET,
  event_GAINCARET,
  event_NONZEROPOLLWORD,
  event_USERMESSAGE         = 17,
  event_SEND                = 17,
  event_USERMESSAGERECORDED = 18,
  event_SENDWANTACK         = 18,
  event_USERMESSAGEACK      = 19,
  event_ACK                 = 19
} event_type;

defined in <Wimp>Const: wimp_NUMBEROFEVENTS
#define wimp_NUMBEROFEVENTS 20

N.B.  There aren't 20, but you need an array this big to store them
due to the way they are numbered.

defined in <Wimp>
type: message_block
typedef struct
{
  message_header  header;
  union
  {
    char                 bytes [236];
    int                  words [59];
    <message_datasave>     datasave;
    <message_datasaveack>  datasaveack;
    <message_dataload>     dataload;
    <message_dataopen>     dataopen;
    <message_ramfetch>     ramfetch;
    <message_ramtransmit>  ramtransmit;
    <message_helprequest>  helprequest;
    <message_helpreply>    helpreply;
    <message_print>        print;
    <message_menuwarn>     menuwarn;

#if FALSE
    /* If <PopUp> in use, also include */
    /* the relevant PopUp messages    */
    <message_popuprequest> popuprequest;
    <message_popupstate>   popupstate;
#endif

  } data;
} message_block;

defined in <Wimp>type: message_menuwarn
typedef struct
{
  int        id;             /* The number given to Wimp_CreateMenu */
  <wimp_point> openpos;        /* Position to open window/menu at     */
  int        selection[10];  /* -1 terminated list of menu hits     */
} message_menuwarn;

defined in <Wimp>type: message_print
typedef struct
{
  int filler[5];
  int filetype;
  char filename[212];
} message_print;

defined in <Wimp>type: message_helpreply
typedef struct
{
  char text[200];
} message_helpreply;

defined in <Wimp>type: message_helprequest
typedef struct
{
  mouse_block where;  /* Where is help needed for? */
} message_helprequest;

defined in <Wimp>tyep: message_ramtransmit
typedef struct
{
  char *buffer;   /* copied directly from initiating RamFetch */
  int  byteswritten;
} message_ramtransmit;

defined in <Wimp>type: message_ramfetch
typedef struct
{
  char *buffer;
  int  buffsize;
} message_ramfetch;

defined in <Wimp>type: message_dataopen
typedef <message_dataload> message_dataopen;

defined in <Wimp>type: message_dataload
typedef struct
{
  <window_handle> window;
  <icon_handle>   icon;
  <wimp_point>    pos;
  int           size;
  int           filetype;
  char          filename[212];
} message_dataload;

defined in <Wimp>type: message_datasaveack
typedef struct
{
  <window_handle> window;   /* window, icon, pos, estsize, filetype all copied */
  <icon_handle>   icon;     /* from the initiating datasave message            */
  <wimp_point>    pos;
  int           estsize;
  int           filetype;
  char          filename[212];
} message_datasaveack;

defined in <Wimp>type: message_datasave
typedef struct
{
  <window_handle> window;
  <icon_handle>   icon;
  <wimp_point>    pos;
  int           estsize;
  int           filetype;
  char          leafname[12];
} message_datasave;

defined in <Wimp>type: message_header
typedef struct
{
  unsigned int   size;
  <task_handle>    sender;
  unsigned int   myref;
  unsigned int   yourref;
  <message_action> action;
} message_header;

defined in <Wimp>type: message_destinee
Window or Task handle

typedef int message_destinee;

defined in <Wimp>type: pollword_block
typedef struct
{
  int address;
  int contents;
} pollword_block;

defined in <Wimp>type: key_block
typedef struct
{
  <caret_block> caret;
  <key_press>   code;
} key_block;

defined in <Wimp>type: caret_block
typedef struct
{
  <window_handle> window;
  <icon_handle>   icon;
  <wimp_point>    offset;
  int           height;
  int           index;
} caret_block;

defined in <Wimp>type: key_press
typedef int key_press;

defined in <Wimp>type: menu_block
typedef struct menu_block
{
  char     title [wimp_MAXNAME];
  char     titlefore, titleback, workfore, workback;
  unsigned int width;
  unsigned int height;
  unsigned int gap;
  /*  Followed immediately by <menu items=>menu_item> */
} menu_block;

defined in <Wimp>type: menu_item
typedef struct
{
  <menu_flags>   menuflags;
  <menu_submenu> submenu;
  <icon_flags>   iconflags;
  <icon_data>    icondata;
} menu_item;

defined in <Wimp>type: menu_submenu
typedef union
{
  <menu_ptr>      menu;
  <window_handle> window;
  int           value;
} menu_submenu;

defined in <Wimp>type: menu_flags
typedef union
{
  unsigned int value;
  struct
  {
    unsigned int ticked     : 1;
    unsigned int dotted     : 1;
    unsigned int writable   : 1;
    unsigned int notifysub  : 1;
    unsigned int dummy3     : 3;
    unsigned int last       : 1;
    unsigned int dummy14    : 14;
    unsigned int shaded     : 1;
    unsigned int dummy1     : 1;
    unsigned int foreground : 4;
    unsigned int background : 4;
  } data;
} menu_flags;

defined in <Wimp>type: menu_ptr
typedef struct <menu_block> *menu_ptr;

defined in <Wimp>type: error_flags
typedef union
{
  unsigned int value;
  struct
  {
    unsigned int ok               : 1;
    unsigned int cancel           : 1;
    unsigned int highlightcancel  : 1;
    unsigned int noprompt         : 1;
    unsigned int noprefix         : 1;
    unsigned int nowait           : 1;
    unsigned int closebox         : 1;
  } data;
} error_flags;

defined in <Wimp>type: drag_block
typedef struct
{
  <window_handle> window;
  <drag_type>     type;
  <wimp_box>      screenrect;
  <wimp_box>      parent;
} drag_block;

defined in <Wimp>type: drag_type
typedef enum
{
  drag_MOVEWINDOW    = 1,
  drag_RESIZEWINDOW,
  drag_SCROLLX,
  drag_SCROLLY,
  drag_FIXEDBOX,
  drag_RUBBERBOX,
  drag_INVISIBLE,
  drag_USERFIXEDBBOX,
  drag_USERRUBBERBOX,
  drag_USERFIXEDNC,
  drag_USERRUBBERNC
} drag_type;

defined in <Wimp>type: pointer_shapeblock
typedef struct
{
  int           shapenumber;
  char          *shapedata;
  unsigned int  width;
  unsigned int  height;
  <wimp_point>    active;
} pointer_shapeblock;

defined in <Wimp>type: mouse_block
typedef struct
{
  <wimp_point>    pos;
  <button_state>  button;
  <window_handle> window;
  <icon_handle>   icon;
} mouse_block;

defined in <Wimp>type: convert_block
typedef struct
{
  <wimp_rect>  screenrect;
  <wimp_point> scroll;
} convert_block;

defined in <Coord>Coord_PointInRect(point, rectangle)
extern BOOL Coord_PointInRect(<wimp_point> *, <wimp_rect> *);

Tests whether the point is within the rectangle. If it is on the line
its counted as in (just like in tennis).

defined in <Coord> Coord_RectContained(InsideRect, OutsideRect)
extern BOOL Coord_RectContained(<wimp_rect> *, <wimp_rect> *);

Test whether the InsideRect is wholly contained by the OutsideRect.
Shared vertices/edges are considered to be inside.

defined in <Coord>Coord_RectsOverlap(RectangleA, RectangeB)
extern BOOL Coord_RectsOverlap(<wimp_rect> *, <wimp_rect> *);

Returns TRUE if the two rectangles overlap (includes containment)

defined in <Coord>Coord_RectsIntersect(RectangleA, RectangeB)
#define Coord_RectsIntersect(r1, r2) (<Coord_RectsOverlap>(r1, r2) && \\
                                     !<Coord_RectContained>(r1, r2) && \\
                                     !<Coord_RectContained>(r2, r1))

Returns TRUE if the two rectangles intersect but neither is contained
wholly within the other.

defined in <Coord>Coord_WindowOrigin
extern void Coord_WindowOrigin(<wimp_point> *origin, <convert_block> *convert);

Returns the origin (TOP LEFT (0,0) corner) of the window's work-area
in screen coordinates. This can then be used as a redraw-origin
for redraws - any drawing done relative to this origin will appear at
the correct screen position regardless of scroll bar offsets and screen
position of the window.
Remember to call this at the start of each redraw - whenever the window
is moved or scrolled, the position of this origin (in screen coordinates)
will change, so it must be recalculated.

defined in <Coord>Coord_XToScreen
#define Coord_XToScreen(X, C) (((X) - (C)->scroll.x) + (C)->screenrect.min.x)

This takes in an integer x-workarea-coord and a pointer to a convert_block,
and returns the screen-coordinate equivalent

defined in <Coord>Coord_YToScreen
#define Coord_YToScreen(Y, C) ( ((Y) - (C)->scroll.y) + (C)->screenrect.max.y )

This takes in an integer y-workarea-coord and a pointer to a <convert_block>,
and returns the screen-coordinate equivalent

defined in <Coord>Coord_PointToScreen
extern void Coord_PointToScreen(<wimp_point> *point, <convert_block> *convert);

Input:  A point in Work Area coords
Output: The same point in Screen coordinates

defined in <Coord>Coord_RectToScreen
extern void Coord_RectToScreen(<wimp_rect> *rect, <convert_block> *convert);

Input:  A rectangle in Work Area coords
Output: The same rectangle in Screen coordinates

defined in <Coord>Coord_XToWorkArea
#define Coord_XToWorkArea(X, C) (((X)-(C)->screenrect.min.x)+(C)->scroll.x)

This takes in an integer x-screen-coord and a pointer to a <convert_block>,
and returns the workarea-coordinate equivalent

defined in <Coord>Coord_YToWorkArea

#define Coord_YToWorkArea(Y, C) (((Y)-(C)->screenrect.max.y)+(C)->scroll.y)

This takes in an integer y-screen-coord and a pointer to a <convert_block>,
and returns the workarea-coordinate equivalent

defined in <Coord>Coord_PointToWorkArea
extern void Coord_PointToWorkArea(<wimp_point> *point, <convert_block> *convert);

Input:  A point in Screen coords
Output: The same point in Work Area coordinates

defined in <Coord>Coord_RectToWorkArea
extern void Coord_RectToWorkArea(<wimp_rect> *rect, <convert_block> *convert);

Input:  A rectangle in Screen coords
Output: The same rectangle in Work Area coordinates

defined in <Coord>Menu_New()
extern <menu_ptr> Menu_New(char *title, char *description);

Creates a new menu. "title" should be no more than 12 characters long
(including the terminator). "description" is a RISC OS Lib style
menu_new() string (Desktop C manual, page 240, but note their syntax
AND their example are both WRONG!), i.e.
    opt   :- " "  no special options (i.e. leading spaces are skipped)
             "!"  ticked
             "~"  shaded
             ">"  has submenu/subwindow
             "-"  dotted
    name  :- any character except "," and "|"
    entry :- {opt}* name
    sep   :- ","  to separate normal items
             "|"  to separate items and place a dotted line between them
    descr :- entry {sep entry}*

    EXAMPLES:
      "!Ticked,~Disabled,>Sub-menu,!~Ticked and disabled, Normal"
      ">Info, Create| Quit"         ; info with sublink arrow
                                    ; then create, dotted line, quit.

NOTES:
  Menu_New needs <Screen>_() functions. It assumes you have called
  <Screen_CacheModeInfo>() in this screen mode (to get screen_delta.x)
  If this call fails (out of malloc memory) then it will call
  <Error_OutOfMemory>() and then return NULL.

defined in <Menu>Menu_Extend()
extern <menu_ptr> Menu_Extend(<menu_ptr> menu, char *description);

Extends (if possible) the menu by appending the items in "description"
onto the menu structure "menu". If the memory reallocation fails, it
returns the pointer to the old, UNCHANGED menu structure.
"description" is the same as for <Menu_New>().

defined in <Menu>Menu_Show()
extern void Menu_Show(<menu_ptr> menu, int x, int y);
Shows the given menu on screen, at the given x and y position.
Set (y = -1) to place the menu at the correct position above the
icon bar.

defined in <Menu>Menu_ShowLast()
extern void Menu_ShowLast(void);
Re-opens the last menu opened (call when a menu item is chosen using
the adjust mouse button to keep the menu open).
Note that if no menu has been opened, or if the last menu opened
has been "dispose"d, this will have bad (dire) results.

defined in <Menu>Menu_AddSubMenu()
extern void Menu_AddSubMenu(<menu_ptr> menu, int entry, <menu_ptr> submenu);

Adds a menu to an existing menu as a submenu at a particular item.

defined in <Menu>Menu_MakeWritable()
extern void Menu_MakeWritable(<menu_ptr> menu, int entry,
                              char *buffer, int size, char *valid);

Makes a menu item writable. You supply the buffer into which the
menu item data will be written, as well as the size of this buffer
(including terminator), plus the validation string (as in Wimp icons)

defined in <Menu>Menu_SetFlags()
extern void Menu_SetFlags(<menu_ptr> menu, int entry, int ticked, int shaded);

Alters the state of a menu item. Setting ticked/shaded to 0 will
turn off the tick/make the item selectable. Setting them to 1 will
turn on a tick/make the item unselectable. Values other than 0 and 1
are undefined, so ensure the values you use are 0 and 1.

defined in <Menu>Menu_SetText()
extern void Menu_SetText(<menu_ptr> menu, int entry, char *text);

Retrieves the text for a menu entry.

defined in <Menu>Menu_CalcHeight()
extern int Menu_CalcHeight(<menu_ptr> menu);

Calculates the height of a menu in OS coords. For internal use.

defined in <Menu>Menu_SysHandle()
#define Menu_SysHandle(menu) (menu)

Returns a pointer to the 'underlying' Wimp menu definition. In DeskLib
this IS the menu definition.

defined in <Menu>Menu_SDispose()
#define Menu_SDispose(menu) free(menu)

Frees up the memory used by a menu. Note that this is a simple Dispose
which does not recursively dispose of attached submenus, and does not
dispose of memory used by long (indirected) item text.

defined in <Menu>var: menu_currentpos
extern <wimp_point> menu_currentpos;

menu_currentpos is a global variable which holds the
x,y position where the last menu was opened

If no menu has been opened, or the last menu has been disposed, then
the values will be invalid - use with care.

defined in <Coord>var: menu_currentopen
extern <menu_ptr>   menu_currentopen;

menu_currentopen is a global variable and points to the last menu opened.
If no menu has been opened, or the last menu has been disposed, then
the value will be invalid - use with care.

defined in <Menu>type: sprite
typedef struct <sprite_info>     *sprite;

defined in <Sprite>type: sprite_area
typedef struct <sprite_areainfo> *sprite_area;

defined in <Sprite>type: sprite_outputstate
typedef struct {
    int          callno ;
    <sprite_area>  spritearea ;
    <sprite=>sprite_ptr>       sprite ;
    void         *savearea ;
} sprite_outputstate;

defined in <Sprite>type: sprite_areainfo
typedef struct {
    unsigned int areasize;
    unsigned int numsprites;
    unsigned int firstoffset;
    unsigned int freeoffset;
} sprite_areainfo;

defined in <Sprite>type: sprite_info
typedef struct {
    unsigned int width;
    unsigned int height;
    unsigned int maskstatus;
    unsigned int mode;
} sprite_info;

defined in <Sprite>type: sprite_header
typedef struct
{
  int  offset_next;
  char name[<sprite_MAXNAME>];
  int  width;
  int  height;
  int  leftbit;
  int  rightbit;
  int  imageoffset;
  int  maskoffset;
  int  screenmode;
} sprite_header;

defined in <Sprite>Sprite_ScreenSave
extern <os_error> *Sprite_ScreenSave(char *filename, BOOL savepalette);

Save the screen as a sprite file - <SpriteOp 2=>SWI.OS_SpriteOp2>

defined in <Sprite>Sprite_ScreenLoad
extern <os_error> *Sprite_ScreenLoad(char *filename);

ScreenLoad a sprite file - <SpriteOp 3=>SWI.OS_SpriteOp3>

defined in <Sprite>Sprite_IconMemorySize
extern int Sprite_IconMemorySize(<window_block> *pWinBlock, <icon_handle> icon,
                                 int mode, <spritemem_flags> flags,
                                 <wimp_point> *dimensions);

This takes the given WIMP icon, and calculates the size of the sprite
needed to exactly fill it, by calling <Sprite_MemorySize> for you.
If 'dimensions' is not NULL, then it will be filled in with the needed
size (width/height) of the sprite in pixels.

The window is passed in as a window_block so that this can be applied
to templates as well as open windows.

Example:
{
<window_info> winfo;
int         s;

<Window_GetInfo>(mainwindow, &winfo);
s = Sprite_IconMemorySize(&winfo.block, 5,     /* Get info for icon 5    */
                          screen_mode,         /* in current screen mode */
                          sprite_HASNOMASKPAL, /* with no mask/palette   */
                          NULL);               /* Don't return dimensions*/
}

defined in <Sprite>Sprite_MemorySize
extern int Sprite_MemorySize(int width, int height, int mode,
                             <spritemem_flags> flags);

Returns the amount of memory to malloc to hold the sprite
defined by the parameters.

-- Example, create sprite area large enough for 3 identical sprites
   which are mode 12, 34x17, and have their own palettes.
{
<sprite_areainfo> *pUserSprites;

size = 3 * Sprite_MemorySize( 34, 17, 12, sprite_HASPAL );
size += sizeof( <sprite_areainfo> );
pUserSprites = (<sprite_areainfo>*) malloc( size );
}

defined in <Sprite>type: spritemem_flags
typedef enum
{
  sprite_HASNOMASKPAL = 0x00,   /* Sprite has no mask or palette */
  sprite_HASNOPALMASK = 0x00,
  sprite_HASMASK      = 0x01,   /* Sprite has a mask only        */
  sprite_HASPAL       = 0x02,   /* Sprite has a palette only     */
  sprite_HASMASKPAL   = 0x03,   /* Has both mask and palette     */
  sprite_HASPALMASK   = 0x03
} spritemem_flags;

defined in <Sprite>Sprite_InitArea
extern <os_error> *Sprite_InitArea(<sprite_area> area);

Initialise a sprite area - <SpriteOp 9=>SWI.OS_SpriteOp9>

defined in <Sprite>Sprite_Load
extern <os_error> *Sprite_Load(<sprite_area> area, char *filename);

Load a file into a sprite area - <SpriteOp 10=>SWI.OS_SpriteOp10>

defined in <Sprite>Sprite_Merge
extern os_error *Sprite_Merge(<sprite_area> area, char *filename);

Merge a file into a sprite area - SpriteOp 11

defined in <Sprite>Sprite_Save
extern <os_error> *Sprite_Save(<sprite_area> area, char *filename);

Save a sprite area into a file - <SpriteOp 12=>SWI.OS_SpriteOp12>

defined in <Sprite>Sprite_Create()
extern <os_error> *Sprite_Create(<sprite_area> area, char *name, int haspalette,
                               int width, int height, int screenmode);

Creates a sprite according to the parameters - <SpriteOp 15=>SWI.OS_SpriteOp15>

defined in <Sprite>Sprite_Delete
extern <os_error> *Sprite_Delete(<sprite_area> area, char *name);

Deletes the given sprite - <SpriteOp 25=>SWI.OS_SpriteOp25>

defined in <Sprite>Sprite_Rename
extern <os_error> *Sprite_Rename(<sprite_area> area,
                               char *oldname, char *newname);

Unsurprisingly, this renames a sprite - <SpriteOp 25=>SWI.OS_SpriteOp25>

defined in <Sprite>Sprite_Copy
extern <os_error> *Sprite_Copy(<sprite_area> area,
                             char *oldname, char *newname);

Unsurprisingly, this copies a sprite - <SpriteOp 26=>SWI.OS_SpriteOp26>

defined in <Sprite>Sprite_Get()
extern <os_error> *Sprite_Get(<sprite_area> area, char *name, int with_palette,
                            int left, int bottom, int right, int top,
                            <sprite=>sprite_ptr> *sprite_ptr);

Gets (creates and copies) a sprite from the given
screen rectangle - <SpriteOp 16=>SWI.OS_SpriteOp16>

defined in <Sprite>Sprite_Plot()
extern <os_error> *Sprite_Plot(<sprite_area> area, char *name, /* "PutUser" */
                             int x, int y, int plot_action);

Plots a sprite with it's bottom-left corners at the given coordinate,
using the given GCOL plot action (see <GFX>.h for plot actions) - <SpriteOp 34=>SWI.OS_SpriteOp34>

defined in <Sprite>Sprite_ReadInfo
extern <os_error> *Sprite_ReadInfo(<sprite_area> area, char *name,
                                 <sprite_info> *info);

Reads sprite information - <SpriteOp 40=>SWI.OS_SpriteOp40>

defined in <Sprite>Sprite_Redirect
extern <os_error> *Sprite_Redirect(<sprite_area> area, char *name,
                                 void *savearea, <sprite_outputstate> *oldstate);

redirects VDU output into the named sprite - <SpriteOp 60=>SWI.OS_SpriteOp60>

defined in <Sprite>Sprite_UnRedirect
extern <os_error> *Sprite_UnRedirect(<sprite_outputstate> *oldstate);

Un-redirects VDU output back to the saved state - <SpriteOp 60=>SWI.OS_SpriteOp60>

defined in <Sprite>Sprite_ReadSaveAreaSize
extern <os_error> *Sprite_ReadSaveAreaSize(<sprite_area> area, char *name,
                                         int *saveareasize);

Given a sprite area and a sprite name, returns the save area size needed
for the given sprite - <SpriteOp 62=>SWI.OS_SpriteOp62>

defined in <Sprite>Const: sprite_MAXNAME
#define sprite_MAXNAME    12

defined in <Sprite>spritepool_SYSTEM
#define spritepool_SYSTEM 0

defined in <Sprite>spritepool_WIMP
#define spritepool_WIMP   1

defined in <Sprite>Template_Initialise
extern void Template_Initialise(void);

Initialises the Template manager ready for use
Make sure you call this function before any other Template_ calls
--- In future, this call will be extended to include setting up
    the things necessary to use outline fonts in your windows.

defined in <Template>Template_Find
extern <window_block> *Template_Find(char *name);

Tries to find the named template, and return a pointer to it's
base window_block. This is so that you can alter the template
original. Note that this *is* the original, so don't stuff it up!
If you wish to USE the template, please use Template Clone!

defined in <Template>Template_Clone
extern <window_block> *Template_Clone(char *name, int maxtitlesize);

Makes a copy of the named template, and returns a pointer to the copy.

"maxtitlesize" is the number of bytes that should be allocated
for the title - this should be big enough to accomodate ANY title
string you expect to give to this window. This is because the only way
to alter the size of this indirected field is to re-create the window
which is usually an undesirable thing to do. (See below for a list of
the possible values for this argument)

A value of 0 for maxtitlesize will use the default value (currently 260)
If the window's title icon is not indirected, this value is ignored
(so most of the time, using 0 is a sensible thing to do)

Returns NULL if the template can't be found
Dies with an error if a serious error occurs (malloc failure, etc.)

The following values may be used for 'maxtitlesize':
  TITLEDEFAULT   0     reserves 260 bytes, enough for a full pathname
  TITLEMIN      -1     reserves for the title as much room as set in the
                       template file (title indirected data size)
                       (the recommended value - especially for windows
                        with constant title strings)
  (any positive value) reserves 'maxtitlesize' bytes of storage for
                        the indirected title data

defined in <Template>Template_Free
extern void Template_Free(<window_block> **windowdef);

Frees up the memory used by a <Template_Clone>'d template. Results are
undefined if you free a non-Clone'd template or try to free it more
than once. (i.e. don't do it!)
Pass in a pointer to a (<window_block> *). The window definition's
memory (including indirected title/icons) will be freed, and the
(<window_block> *) will be set to NULL to ensure you don't try to use
it now that it is invalid.

defined in <Template>Template_Delete
extern void Template_Delete(char *name);

Deletes the named template from the list of available templates, freeing
any memory claimed by the template. This will "pull the rug out from
under" any windows created using this template, and your program will
crash if any such windows are open.
However, any windows created using <Template_Clone>'d templates will
be unaffected. (Moral of the story: Always use Clone)
Pass in the identifier string of the template you wish to delete

defined in <Template>Template_ClearAll
extern void Template_ClearAll(void);

Clears ALL currently held templates. (equivalent to you calling
<Template_Delete>() for each template in turn)

defined in <Template>Template_LoadFile
extern void Template_LoadFile(char *leafname);

Loads all template definitions from the specified file.
Due to the essential nature of templates, if any errors occur, this
reports to <Error_ReportFatal>(Internal)
After loading a template file, use <Template_Clone> to get a copy
of any of the templates for use.

Loading a second file will simply ADD the new templates to the template
list. So long as there are no name clashes, you can then use any
template from either file.

Use Template_Delete/ClearAll if you don't want to keep old templates
when loading in new ones.

If you want to use outline fonts in windows, then remember to call
<Template_UseOutlineFonts>() BEFORE you call <Template_LoadFile>()

defined in <Template>Template_UseOutlineFonts
extern void Template_UseOutlineFonts(void);

Call this BEFORE calling <Template_LoadFile>() if you wish to use outline
fonts (rather than the system font) in your windows. It allocates the
font usage array, and also adds an atexit handler to lose all the fonts
you are using when your program exits.

NOTE that future versions of RISC OS *WILL* supply an outline font as the
system font, so your program should offer a choice of system font OR
outline font to the user.

defined in <Template>Const: UNDEFINED
#define UNDEFINED -1

defined in <KeyCodes>KeyCodes for Keys on their own
#define keycode_BACKSPACE   8
#define keycode_RETURN      13
#define keycode_ESCAPE      27
#define keycode_HOME        30
#define keycode_DELETE      127

#define keycode_F1          385
#define keycode_F2          386
#define keycode_F3          387
#define keycode_F4          388
#define keycode_F5          389
#define keycode_F6          390
#define keycode_F7          391
#define keycode_F8          392
#define keycode_F9          393

#define keycode_PRINT       384
#define keycode_TAB         394
#define keycode_COPY        395

#define keycode_CURSORLEFT  396
#define keycode_CURSORRIGHT 397
#define keycode_CURSORDOWN  398
#define keycode_CURSORUP    399
#define keycode_PAGEDOWN    414
#define keycode_PAGEUP      415

#define keycode_F10         458
#define keycode_F11         459
#define keycode_F12         460

#define keycode_INSERT      461

defined in <KeyCodes>KeyCodes for Keys in combination with SHIFT
#define keycode_SHIFT_BACKSPACE   <UNDEFINED>
#define keycode_SHIFT_RETURN      <UNDEFINED>
#define keycode_SHIFT_ESCAPE      <UNDEFINED>
#define keycode_SHIFT_HOME        <UNDEFINED>
#define keycode_SHIFT_DELETE      <UNDEFINED>

#define keycode_SHIFT_F1          401
#define keycode_SHIFT_F2          402
#define keycode_SHIFT_F3          403
#define keycode_SHIFT_F4          404
#define keycode_SHIFT_F5          405
#define keycode_SHIFT_F6          406
#define keycode_SHIFT_F7          407
#define keycode_SHIFT_F8          408
#define keycode_SHIFT_F9          409

#define keycode_SHIFT_PRINT       400
#define keycode_SHIFT_TAB         410
#define keycode_SHIFT_COPY        411

#define keycode_SHIFT_CURSORLEFT  412
#define keycode_SHIFT_CURSORRIGHT 413
#define keycode_SHIFT_CURSORDOWN  414
#define keycode_SHIFT_CURSORUP    415
#define keycode_SHIFT_PAGEDOWN    398
#define keycode_SHIFT_PAGEUP      399

#define keycode_SHIFT_F10         474
#define keycode_SHIFT_F11         475
#define keycode_SHIFT_F12         476

#define keycode_SHIFT_INSERT      477

defined in <KeyCodes>KeyCode for Keys in combination with CTRL
#define keycode_CTRL_BACKSPACE   <UNDEFINED>
#define keycode_CTRL_RETURN      <UNDEFINED>
#define keycode_CTRL_ESCAPE      <UNDEFINED>
#define keycode_CTRL_HOME        <UNDEFINED>
#define keycode_CTRL_DELETE      <UNDEFINED>

#define keycode_CTRL_F1          417
#define keycode_CTRL_F2          418
#define keycode_CTRL_F3          419
#define keycode_CTRL_F4          420
#define keycode_CTRL_F5          421
#define keycode_CTRL_F6          422
#define keycode_CTRL_F7          423
#define keycode_CTRL_F8          424
#define keycode_CTRL_F9          425

#define keycode_CTRL_PRINT       416
#define keycode_CTRL_TAB         426
#define keycode_CTRL_COPY        427

#define keycode_CTRL_CURSORLEFT  428
#define keycode_CTRL_CURSORRIGHT 429
#define keycode_CTRL_CURSORDOWN  430
#define keycode_CTRL_CURSORUP    431
#define keycode_CTRL_PAGEDOWN    446
#define keycode_CTRL_PAGEUP      447

#define keycode_CTRL_F10         490
#define keycode_CTRL_F11         491
#define keycode_CTRL_F12         492

#define keycode_CTRL_INSERT      493

#define keycode_CTRL_A             1
#define keycode_CTRL_B             2
#define keycode_CTRL_C             3
#define keycode_CTRL_D             4
#define keycode_CTRL_E             5
#define keycode_CTRL_F             6
#define keycode_CTRL_G             7
#define keycode_CTRL_H             8
#define keycode_CTRL_I             9
#define keycode_CTRL_J            10
#define keycode_CTRL_K            11
#define keycode_CTRL_L            12
#define keycode_CTRL_M            13
#define keycode_CTRL_N            14
#define keycode_CTRL_O            15
#define keycode_CTRL_P            16
#define keycode_CTRL_Q            17
#define keycode_CTRL_R            18
#define keycode_CTRL_S            19
#define keycode_CTRL_T            20
#define keycode_CTRL_U            21
#define keycode_CTRL_V            22
#define keycode_CTRL_W            23
#define keycode_CTRL_X            24
#define keycode_CTRL_Y            25
#define keycode_CTRL_Z            26

defined in <KeyCodes>Keys in combination with SHIFT & CTRL
#define keycode_CTRL_SHIFT_BACKSPACE   <UNDEFINED>
#define keycode_CTRL_SHIFT_RETURN      <UNDEFINED>
#define keycode_CTRL_SHIFT_ESCAPE      <UNDEFINED>
#define keycode_CTRL_SHIFT_HOME        <UNDEFINED>
#define keycode_CTRL_SHIFT_DELETE      <UNDEFINED>

#define keycode_CTRL_SHIFT_F1          0x1B1
#define keycode_CTRL_SHIFT_F2          0x1B2
#define keycode_CTRL_SHIFT_F3          0x1B3
#define keycode_CTRL_SHIFT_F4          0x1B4
#define keycode_CTRL_SHIFT_F5          0x1B5
#define keycode_CTRL_SHIFT_F6          0x1B6
#define keycode_CTRL_SHIFT_F7          0x1B7
#define keycode_CTRL_SHIFT_F8          0x1B8
#define keycode_CTRL_SHIFT_F9          0x1B9

#define keycode_CTRL_SHIFT_PRINT       0x1B0
#define keycode_CTRL_SHIFT_TAB         0x1BA
#define keycode_CTRL_SHIFT_COPY        0x1BB

#define keycode_CTRL_SHIFT_CURSORLEFT  0x1BC
#define keycode_CTRL_SHIFT_CURSORRIGHT 0x1BD
#define keycode_CTRL_SHIFT_CURSORDOWN  0x1BE
#define keycode_CTRL_SHIFT_CURSORUP    0x1BF
#define keycode_CTRL_SHIFT_PAGEDOWN    0x1AE
#define keycode_CTRL_SHIFT_PAGEUP      0x1AF

#define keycode_CTRL_SHIFT_F10         0x1FA
#define keycode_CTRL_SHIFT_F11         0x1FB
#define keycode_CTRL_SHIFT_F12         0x1FC

#define keycode_CTRL_SHIFT_INSERT      0x1FD

defined in <KeyCodes>Kbd_Keydown
extern BOOL Kbd_KeyDown(int keynum);

Checks to see if the given key is currently depressed.
'keynum' is a negative INKEY number see also <kbd_neginkey>
Generally, it's use is for things like (eg) checking if CTRL is held
down when a click is made, as in:
    if (Kbd_KeyDown(inkey_CTRL)) ...

defined in <Kbd>type: kbd_neginkey
In the DeskTop environment, you shouldn't ever need to read more than the
the following keys via this method (everything else should come in via WIMP
events). If you need other values, look up the Appendix on INKEY values
in the BBC BASIC Guide (mine has this on page 411)

typedef enum
{
  inkey_ADJUST       = -12,       /* MOUSE 'Adj              */
  inkey_MENU         = -11,       /* MOUSE 'Menu' button     */
  inkey_SELECT       = -10,       /* MOUSE 'Select' button   */

  inkey_RALT         = -9,        /* Right ALT key           */
  inkey_LALT         = -6,        /* Left ALT key            */
  inkey_ALT          = -3,        /* Either/Both ALT keys    */

  inkey_RCTRL        = -8,        /* Right CTRL key          */
  inkey_LCTRL        = -5,        /* Left CTRL key           */
  inkey_CTRL         = -2,        /* Either/Both CTRL keys   */

  inkey_RSHIFT       = -7,        /* Right SHIFT key         */
  inkey_LSHIFT       = -4,        /* Left SHIFT key          */
  inkey_SHIFT        = -1         /* Either/Both SHIFT keys  */
} kbd_neginkey;

defined in <Kbd>Window_SetTitle
extern void Window_SetTitle(<window_handle> window, char *title);

(equivalent of RISC OS Lib's win_settitle, only far better)
This sets the text in the titlebar of the given window to the given string

NOTE that if the title is not indirected, It will be unable to change
the text, i.e. nothing will happen!

It has several advantages over win_settitle, however:
 + It uses legal OS calls to work out the rectange to redrawm so works
   properly even with strange sized toolsprite sets
 + It doesn't try to redraw anything if the window is CLOSED!
 + It handles indirected and text-only title icons, rather than bombing
   completely if the titlebar is not indirected.
 + It actually terminates the string if it was too long to fit!!!

 (And people wonder why I think ROLib is a load of excrement!)

 Unfortunately it is not possible to only invalidate the VISIBLE area
 of the window, so this may still create the occasional flicker of any
 windows over the top of your titlebar... this can't be helped.

defined in <Window>Window_ModeChange
extern void Window_ModeChange(void);

This function will go through all your templates and all windows that
were created with Window_ calls, and re-find their outline fonts so
that they are displayed correctly - this needs to be done after some
mode changes. See <Handler>.h - <Handler_ModeChangeWithFonts>() to see
how this should/can be used.

NOTE: If you create ANY windows without using <Window_Create> calls, then
this function will not fix their outline font use - but MUCH MORE
IMPORTANTLY it will release the font, which may later be replaced
by another font (or worse, cease to exists totally), so strange or
unhealthy effects might ensue. i.e. ONLY use this if using <Window_Create>.

Note also that this does NOT attempt to fix fonts in window titles
because
 a) The WIMP currently gets antialiased fonts *very* wrong with toolsprites
    and/or titlebar selection, so they aren't recommended
 b) Acorn DO have a new WIMP which uses an Outline font instead of system,
    so the problem WILL go away with the next OS release.
 c) This would involve re-creating the window, which would mean a possible
    change in the window handle, which is something we can't do.

defined in <Window>Window_HelpHandler
extern BOOL Window_HelpHandler(<event_pollblock> *event, void *reference);

This is an event handler (added with <Window_AutoHelp>) which provides
help on windows and their icons.
If you wish to augment the help available for a window, you can call
this handler yourself. Checking if it returns TRUE or FALSE gives an
indicator of whether or not a help reply has been sent.
Generally, you will check if the pointer is in an area of the window
and supply help for that special area - if not, you drop back to a
"fallback" position, and allow the "default" action, by callinf this
handler.
The other method is to add your own specialised help handler with
<Event_Claim>, and then add this handler, so that your handler gets first
choice when the event comes in.

defined in <Window>Window_AutoHelp
extern BOOL Window_AutoHelp(<window_handle> window, <icon_handle> icon);

This adds an event handler for the given window and icon (event_ANY and
window_ICONBAR may be used). Every HelpRequest message thereafter
received for that window will be answered (if possible) with a message
from your messages (see <Msgs>) file.
The message tag used will be constructed from the window's template-name
and the icon number, as in:
   mainwind.-1   - Any part of the window not covered by an icon
   mainwind.3    - Icon 3 of any window created from "mainwind" template

In the messages file, you can also use a catch-all message of:
   mainwind.*
which will catch ALL helprequests for the window, so ANY part of the
window is guaranteed to give help (if no specific help for an icon is
found, then the catch-all help will be used)

NOTE that this function (Window.AutoHelp.c) may be recompiled to use
<EventMsg_Claim> rather than <Event_Claim> if you so desire. However,
note that currently EventMsg ignores the icon handle.
<EventMsg> is more efficient than having multiple <Event_Claim>s on
incoming message events (especially when you add individual handlers for
single windows/icons), but ONLY if you are using several message event
handlers. Thus, the default here is to use <Event_Claim> so as to not
"pull in" the code for <EventMsg> unless you want to use it.

defined <Window>Window_ParentName
extern void Window_ParentName(<window_handle> window, char *windowname);

Given any window's handle, this function attempts to find the name
(8 characters only, truncated if necessary) of the template from which
the window was created (only works if created with <Window_Create>)
- if the window handle is a negative number, "iconbar" is returned.

defined in <Window>Window_GetInfo
extern void Window_GetInfo(<window_handle> window, <window_info> *result);

This is simply a frontend to the <Wimp_GetWindowInfo> call. However, it
returns the Window info block with the icon definitions STRIPPED.
Thus, you can use a window_info structure in your local variables without
having to allocate enough memory to cope with any icons that the window
happens to have in it.

defined in <Window_GetInfo>Window_Delete
extern void Window_Delete(<window_handle> window);

This Hides and deletes ANY window.
It also removes any Event handlers attached to the window.
If the window was created with <Window_Create>(), then it also
deallocates any memory used by the window.

defined in <Window>Window_Hide
#define Window_Hide(handle) <Wimp_CloseWindow>(handle)

Closes the specified window (removes it from screen)
THE WINDOW IS NOT DELETED, just "hidden". It is preferable that you use
<Window_Create>() and <Window_Delete>() every time you want a window to
appear/disappear, to avoid problems.

defined in <Window>Window_CreateAndShow
extern <window_handle> Window_CreateAndShow(char *windowname,
                                          int  maxtitlesize,
                                          <window_openpos> openpos);

Simply calls <Window_Create>() and then <Window_Show>()
(Just to make your programs slightly tidier)

defined in <Window>Window_Show
extern void Window_Show(<window_handle> window, <window_openpos> openpos);

This opens the given window on-screen in the desired position.
(It can be used with ANY window, even if not created with <Window_Create>)

defined in <Window>Window_Create
extern <window_handle> Window_Create(char *windowname, int maxtitlesize);

This finds the named window template and creates a new copy of the window.
It also records the memory allocated for the window so that it can be
deallocated when the window is closed (using <Window_Delete>)

"maxtitlesize" is the maximum length the window's title will be allowed
grow to. (See <Template>.h: <Template_Clone>())

Returns: The WIMP handle of the newly-created window.

defined in <Window>type: window_openpos
typedef enum
{
  open_WHEREVER,
  open_CENTERED,        /* center of screen */
  open_OVERCARET,       /* Over the current caret position
                           NOTE: If no caret, window is opened open_CENTERED */
  open_UNDERPOINTER,    /* Under the current pointer position                */
  open_NEARLAST         /* Slightly offset from the T.L. pos of the last
                           window to be opened with <Window_Show>              */
} window_openpos;

defined in <Window>Screen_CacheModeInfo
extern BOOL Screen_CacheModeInfo(void);

This should be called before you try to use any of the global variables
in <Screen>. It only needs to be called whenever the screen mode changes
so call it:
  a) When you initialise your program, and whenever a mode change
     message is received (see <ModeChangeHandler>, below)
  b) Immediately before you use the variables (i.e. in your redraw
     handler, etc.)

It checks the screenmode, and if it has not changed, then the variables
are not updated, so it is not too bad if you call it more often than
you really need to (i.e. every time you redraw, for example).

defined in <Screen>type: filter_handler
typedef int (*filter_handler)(int event, const <event_pollblock> *event,
                             const int task);

defined in <Filter>Filter_RegisterPreFilter
extern void Filter_RegisterPreFilter(char *filtername,
                                     <filter_handler> handler, int R12,
                                     <task_handle> task);

defined in <Filter>Filter_RegisterPostFilte
extern void Filter_RegisterPostFilter(char *filtername,
                                      <filter_handler> handler, int R12,
                                      <task_handle> task, int eventmask);

defined in <Filter>Filter_DeRegisterPreFilter
extern void Filter_DeRegisterPreFilter(char *filtername,
                                       <filter_handler> handler, int R12,
                                       <task_handle> task);

defined in <Filter>Filter_DeRegisterPostFilter
extern void Filter_DeRegisterPostFilter(char *filtername,
                                        <filter_handler> handler, int R12,
                                        <task_handle> task);

defined in <Filter>type: os_error
typedef struct {
 int  errnum;
 char errmess[252];
} os_error;

defined in <Core>Validation_ScanString
extern int Validation_ScanString(char *string, char tag);

Scan the passed-in string for the special tag character, and return the
index of the next char. e.g. scanning "a0-9;b3" for the bordertype can be
done as follows:

if (border = Icon_ScanValidString(icon.data.indirecttext.validstring, 'B'))
{
  border = icon.data.indirecttext.validstring[border] - '0';
  switch (border)
  ...
}

If the tag is not found, a value of 0 will be returned, else the value
is the index of the character FOLLOWING the tag in the string.
(NOTE that the tag must be either the first character, or must directly
 follow a semicolon)

defined in <Validation>type: colourtrans_fontblock
typedef struct
{
  int font;
  int back;
  int fore;
  int max;
} colourtrans_fontblock;

defined in <ColourTran>ColourTrans_SetGCOL
extern <os_error> *ColourTrans_SetGCOL(int palette, int flag, int gcol);

defined in <ColourTran>ColourTrans_InvalidateCache
extern <os_error> *ColourTrans_InvalidateCache(void);

defined in <ColourTran>ColourTrans_SelectTable
extern <os_error> *ColourTrans_SelectTable(int src_mode, int *src_pal,
                                         int dst_mode, int *dst_pal,
                                         char *table);

defined in <ColourTran>ColourTrans_ReturnFontColours
extern <os_error> *ColourTrans_ReturnFontColours(<colourtrans_fontblock> *fontcols);

defined in <ColourTran>Resource_InitialisePath
extern void Resource_InitialisePath(char *respath);

Initialises the resource manager.

If you prefer to use a path variable for your resources (for easier
setting of language resources), then you can initialise the resources
by calling this function.
(Instead of setting the resource prefix to "\<AppName$Dir\>.", it will
 set it to "AppName:", where "AppName" is the 'respath' parameter)

See also the ALTERNATIVE call, <Resource_Initialise>()

defined in <Resource>Resource_Initialise
extern void Resource_Initialise(char *respath);

Initialises the resource manager. Pass in the name of your application
(e.g. if you have set \<appname$Dir\>, pass in "appname")
This tells all DeskLib modules where to look for your resources
by setting resource_pathname to "\<Appname$Dir\>." - this is prepended
to all leafnames to create full resource pathnames.
This pathname is used by various DeskLib modules (<Template>, <Msgs>, etc)
-it adds very little code size to your program, and saves you the
work of doing the pathname yourself. It also makes changing the
resource directory at a later development stage far easier.

See also the ALTERNATIVE call, <Resource_InitialisePath>()

defined in <Resource>var: resource_pathname
extern char resource_pathname[32];

This string is used as a prefix for all pathnames in DSEdit that load
resource files. It is set up by either of the following calls, to be either
  "\<Name$Dir\>."
or
  "Name:"
It is prepended to a leafname (e.g. \<Floob$Dir\>.Sprites or Floob:Sprites)
by some Desklib modules in order to find the resources.
(See Misc.c.ResInit, Misc.c.ResInitPth to see exactly what these very
simple functions do)

defined in <Resource>Msgs_ReportFatal
extern void Msgs_ReportFatal(int errnum, char *tag, ...);

As for <Msgs_Report> but calls <Error_ReportFatal>

defined in <Msgs>Msgs_Report
extern void Msgs_Report(int errnum, char *tag, ...);

Reports an error for the message specified by tag.
You can also pass variable parameters for substitution.
(See <Error>.h - <Error_Report> for the non-messagetrans'd version of this)

defined in <Msgs>Msgs_DropGroup
extern void Msgs_DropGroup(char *grouptag);

Drops (deletes) a message group from memory
This is useful for regaining memory when a set of messages is no longer
needed (e.g. Help messages can be discarded when a user turns off help)

To get discarded messages back, you must re-call <Msgs_LoadFile> for the
appropriate messages file.

defined in <Msgs>Msgs_LoadFile
extern BOOL Msgs_LoadFile(char *leafname);

Merges the given messages file into the current list of messages
(Uses <Resource> to supply the pathname)
Messages with the same group.msg tag will be overwritten by the
new messages coming in from the file.

Expects lines of the form:
    group.msg: message text continuing to newline
Leading spaces are stripped

defined in <Msgs>Msgs_printf
extern void Msgs_printf(char *result, char *formattag, ...);

Equivalent to sprintf(), but the "formattag" string is NOT a format
string, but rather a Msgs tag which is given to <Msgs_Lookup> in order
to generate a format string for subsequent use.

defined in <Msgs>Msgs_Lookup
extern BOOL Msgs_Lookup(char *tag, char *result, int maxlength);

Looks up the tag in the current message list, and copies the appropriate
message into result if found. (no more than maxlength characters will
be copied, so you can copy directly into icon indirected text, etc.
REMEMBER that arrays start at 0, so if you have "char result[12]", use
Msgs_Lookup(tag, result, 11))

The tag string should be of the form:
  "group.tag:default"  or  "group.tag"

The message found will be searched for <> includes. If any are found,
Msgs_Lookup() will be recursively invoked in order to compile
the final string. Note that circular references are not detected,
and will cause stack-chewing recursion until all memory is eaten up,
at which point the recursion (and all life as it we know it) will stop.

Remember also that more memory than is immediately obvious will
be needed for messages which include others. However, everything will
be truncated if necessary at "maxlength" characters.

NOTE: leading spaces are NOT removed by this call - you MUST use
      a compact, space-free format in your program (though you can use
      spaces for readability of your messages files)
      [This saves code size in this function, as well as forcing you to
       not waste space in your executable]

-If the message for group.tag is not found, then default is returned
 (if no default, then the null string is returned - result[0] == '\0')

-If the message is found in the message list, TRUE is returned
-If the default has to be used, TRUE is returned
Otherwise FALSE is returned, and result[0] == '\0'

(Thus, if you get (Msgs_Lookup(...) == FALSE) then you have no valid
text to use. (Acorn's msgs returns the tag, which is very annoying
when you don't want tags appearing in your interface if anything goes
wrong)

defined in <Msgs>TextFile_ReadToDelimiter
extern void TextFile_ReadToDelimiter(FILE *infile, char delimiter,
                                     char *line, int maxlength);

Reads characters from the given file until eof or delimiter character
Delimiter is typically a newline character, which gives read-to-eol
Leading spaces/tabs are ignored
Won't read more than "maxlength" characters (maxlength *includes* 0
string-terminating character)

defined in <TextFile>TextFile_GetToken
extern void TextFile_GetToken(FILE *infile, char delimiter,
                              char *token,  BOOL lowercase);
Read in a token from a file. A token is defined as:
  A sequence of up to 32 characters, delimited by a specific character
  or a newline. Leading spaces/tabs are ignored.

This is generally used to read a word from a textfile (delimiter = ' ')
or to read tags from a msgtrans style file (delimiter = ":")

defined in <TextFile>TextFile_SkipBlanks
extern void TextFile_SkipBlanks(FILE *infile);

reads characters from the given file until eof or until a non-blank
(space or tab character) is found.

defined in <TextFile>TextFile_Lowercase
#define TextFile_Lowercase(x) (((x)\>='A' && (x)\<='Z') ? (x)+32 : (x))

This macro converts all uppercase chars to lowercase

defined in <TextFile>type: dispatch_proc
typedef void (*dispatch_proc)();

Used in <Dispatch>()Event_CloseDown
extern void Event_CloseDown(void);

Call this to CloseDown (quit) the application

defined in <Event>Event_Initialise3
extern void Event_Initialise3(char *taskname, int version, int *messages);

Extended version of <Event_Initialise> which allows the wimp version
number to be set and the list of acceptable messages to be passed

This function should only be used for version numbers of 300 or greater
(i.e. for tasks which will only run on RISC OS 3 or later versions).

defined in <Event>Event_Initialise

extern void Event_Initialise(char *taskname);

Call this once to initialise the Wimp and the event manager
**** This call is obsolescent, and should only be used if you still need
     RISC OS 2 compatability - see <Event_Initialise3>

defined in <Event>Event_Poll
extern void Event_Poll(void);

Main event poll routine. Use as in:
  while (TRUE)
    Event_Poll();

defined in <Event>Event_Process
extern void Event_Process(<event_pollblock> *event);

Call this to process a <Wimp_Poll> event. It will cascade the event down
through the event-handler hierarchy until one of your event handlers
returns TRUE to indicate succesful handling of the message.
NOTE that <Event_Poll> calls <Wimp_Poll> and <Event_Process> for you.

defined in <Event>Event_ReleaseWindow
extern void Event_ReleaseWindow(<window_handle> window);

This is similar to <Event_Release>, but rather than delinking ONE handler
it delinks ALL handlers attached to the given window. This should be done
if you close/delete the window using low-level routines. (It is done
automatically if you use <Window>_ calls to remove the window)

defined in <Event>Event_Release
extern BOOL Event_Release(<event_type> event,
                          <window_handle>  window, <icon_handle> icon,
                          <event_handler> handler, void *reference);

This will release your claim on an event, removing the given handler
from further usage.
The parameters passed in should be the same as those passed to
<Event_Claim>

defined in <Event>Event_Claim
extern BOOL Event_Claim(<event_type> eventtype,
                        <window_handle> window,  <icon_handle> icon,
                        <event_handler> handler, void *reference);

Call this function to claim an event. This attaches the given handler
function to the given event for all future event processing.
   eventtype should be event_ANY  - to handle all events, or
             an event type        - to handle a specific event
   window    should be event_ANY  - if not window-specific, or
             a window handle      - to attach ONLY to that window
   icon      should be event_ANY  - if not icon-specific, or
             an icon handle       - to attach ONLY to that icon
             (NOTE: if icon != event_ANY, window MUST be defined)

   handler   is the address of your handler function
   reference is a handle for any user-data you want passed to the
             function whenever it is called.

defined in <Event>type: event_handler
typedef BOOL (*event_handler) (<event_pollblock> *poll_block, void *reference);

user event_handler function

defined in <Event>Var: event_mask
extern <event_pollmask> event_mask;

Mask used by event_ FNs for <Wimp_Poll>

defined in <Event>Var: event_taskhandle
extern int event_taskhandle;

WIMP task-handle of this application

defined in <Event>Var: event_wimpversion
extern unsigned int event_wimpversion;

Wimp version number * 100

defined in <Event>event_taskname
extern char event_taskname[40];

Application name

defined in <Event>event_lastevent
extern <event_pollblock> event_lastevent;

Last event received by event_()

defined in <Wimp>EventMsg_ReleaseMessage
extern BOOL EventMsg_ReleaseMessage(<message_action> messagetype);

Finds and removes all message handlers that relate to the specified
message type. If you pass in event_ANY as the type, all handlers that
are not message-specific will be released.

defined in <EventMsg>EventMsg_ReleaseWindow
extern int EventMsg_ReleaseWindow(<window_handle> window);

Finds and removes all message handlers that relate to the given window.
If you pass in event_ANY as the window handle, all non-window-specific
handlers will be released.

defined in <EventMsg>EventMsg_Release
extern int EventMsg_Release(<message_action> messagetype, <window_handle> window,
                            <event_handler> handler);

Release the handler for a specific message type and specific window
combination.
If you pass in event_ANY for the messagetype, only non-message-specific
handlers may be released. (c.f. <EventMsg_ReleaseMessage>)
If you pass in event_ANY for the window handle, only non-window-specific
handlers may be released. (c.f. <EventMsg_ReleaseWindow>)

defined in <EventMsg>EventMsg_Claim
extern BOOL EventMsg_Claim(<message_action> messagetype, <window_handle> window,
                           <event_handler> handler, void *reference);

Much like <Event_Claim>
Pass in the type of message (message action) you wish to handle, or
event_ANY to handle ALL messages.
Pass in the window for which this applies (event_ANY == all windows)
Also pass in the handler function itself (a standard event_handler)
and your own reference.
Specific-window handlers will have priority over general handlers when
an incoming message is dispatched to your registered handlers.

defined in <EventMsg>EventMsg_Initialise
extern void EventMsg_Initialise(void);

Initialises the EventMsg system ready for use. Attaches EventMsg event
handlers to catch all incoming Wimp messages (events 17, 18).

defined in <EventMsg>Handler_ModeChange
extern BOOL Handler_ModeChange(<event_pollblock> *event, void *reference);

This is a handler for mode change events. It calls <Screen_CacheModeInfo>()
every time the screen mode changes, guaranteeing that the screen variables
are always correct (EXCEPT, YOU must call <Screen_CacheModeInfo>() once
during initialisation.

If you have called <Template_UseOutlineFonts>() and the screen resolution
has changed in such a way as to necessitate it, it also calls
<Window_ModeChange> to fix all your icons which use outline fonts
(otherwise, they often become the wrong size upon a mode change)
(Note that this won't have a very useful effect unless you use <Template>
and <Window> functions to create all your windows - in fact, such windows
will no longer 'own' the fonts they are using, and these fonts may
disappear or change at random in the future - so DON'T use this function
unless ALL your windows were created with <Window_Create>

See also <Window>.h

Attach it to mode change messages using:
 <EventMsg_Claim>(message_MODECHANGE, event_any, Handler_ModeChange, NULL);

defined in <Handler>Handler_ClickOK
Handler for clicks on "OK" or "Cancel" (3-d) type buttons
(Indents the button, waits for 1/3 second, and un-indents the button)

extern BOOL Handler_ClickOK(<event_pollblock> *event, void *reference);

defined in <Handler>Handler_NullRedraw
extern BOOL Handler_NullRedraw(<event_pollblock> *event, void *reference);

Supplies a NULL redraw loop (gets rectangles from the WIMP until
all rectangles have been "redrawn"). Doesn't actually do any drawing
though.

defined in <Handler>Handler_OpenWindow
extern BOOL Handler_OpenWindow(<event_pollblock> *event, void *reference);

Simply calls <Wimp_OpenWindow>()

defined in <Handler>Handler_DeleteWindow
extern BOOL Handler_DeleteWindow(<event_pollblock> *event, void *reference);

Alternate handler to <Handler_Close>, which calls the higher-level
<Window_Delete>() to close and delete the window, release memory, and
remove all handlers attached to the window.

defined in <Handler>Handler_CloseWindow
extern BOOL Handler_CloseWindow(<event_pollblock> *event, void *reference);

Simply calls Wimp_CloseWindow()

defined in <Handler>Dialog_StillOpen
extern BOOL Dialog_StillOpen(<dialog=>dialog_t> d);

Returns TRUE if the dialogue window is still open

defined in <Dialog>type: dialog
typedef <dialog_record> *dialog;

defined in <Dialog>type dialog_record
typedef struct
{
  <window_handle> window;         /* The window handle of this dialogue window */
  <icon_handle>   lastclicked;    /* The icon handle of the last icon that was
                                 * clicked, or dialog_NOCHOICE if no icons
                                 * have been clicked yet.
                                 */
  struct
  {
    unsigned int stillopen : 1;    /* The dialogue window is still open      */
    unsigned int persist   : 1;    /* It should persist (adjust was clicked) */
    unsigned int isstatic  : 1;    /* It is a static (permanent) dialogue    */
  } state;
} dialog_record;

defined in <Dialog>Dialog_LastClicked
extern <icon_handle> Dialog_LastClicked(<dialog=>dialog_t> d);

Returns the icon number of the last icon which was clicked in the
dialogue window. If no icons have been clicked yet, returns
dialog_NOCHOICE.

defined in <Dialog>Dialog_Persist
extern BOOL Dialog_Persist(<dialog=>dialog_t> d);

Returns TRUE if the last choice made for this dialogue box was made with
adjust, and the dialogue window is still open - i.e. the user wants
the dialogue to stay open.
Unlike RISC OS Lib, this remembers the last click rather than just
checking if Adjust is down when called, so will work even after an
indentation delay.

defined in <Dialog>Dialog_WindowHandle
extern <window_handle> Dialog_WindowHandle(<dialog=>dialog_t> d);

Returns the RISC OS Wimp window handle associated with this dialogue box.
This allows filling in of fields using, e.g. DeskLib's '<Icon>' module.

defined in <Dialog>Dialog_WaitForClick
extern int Dialog_WaitForClick(<dialog=>dialog_t> d);

Waits for an icon to be clicked in the dialogue box.  All other events
are processed as usual.  If the user closes the window, dialog_CLOSE
is returned.
Note that <Dialog_LastClicked> can be called at any time up until you call
<Dialog_Destroy>() to find out what the last valid icon click was (i.e.
the last positive value that <WaitForClick> returned)

defined in <Dialog>Dialog_ShowStatic
extern void Dialog_ShowStatic(<dialog=>dialog_t> d,<window_openpos> openpos);

As <Dialog_Show>(), but more permanent - only a click on the close icon
(if present) will close it.  Of course it may be closed by other means
if the application assigns special meaning to an icon  - e.g. a cancel
button - and closes it itself when this icon is clicked on.
Opens the window at the position specifeid by openpos

(It is very convenient if dialogues always appear under the mouse pointer
especially as mouse-movement distances (screen sizes) increase)

defined in <Dialog>Dialog_Show
extern void Dialog_Show(<dialog=>dialog_t> d);

Shows a dialogue box in the centre of the screen, as a submenu window.
(i.e. clicking outside the window or pressing escape will remove it)

defined in <Dialog>Dialog_Destroy
extern void Dialog_Destroy(<dialog=>dialog_t> d);

Removes from display and deletes a dialogue box structure.
NOTE that the dialog structure is free'd by this, so you cannot call
any dialogue functions (except Create of course) with it after a Destroy

defined in <Dialog>Dialog_Create
extern <dialog=>dialog_t> Dialog_Create(char *template_name, int maxtitlesize);

Creates (but does not show) a dialog box from a named template.

defined in <Dialog>An example of how to use Dialog.h
(Assuming a window where icon 0 is the 'OK' button, and icon 1 is the
 'Cancel' button)

{
  <dialog=>dialog_t> dlog;

  dlog = <Dialog_Create>("template", 0);           /* Create the window    */
  <Dialog_ShowStatic>(dlog, open_UNDERPOINTER);    /* Pop up under pointer */

  while (<Dialog_WaitForClick>(dlog) > 1 || <Dialog_Persist>(dlog))
    /* Busy wait loop */ ;                       /* Wait for OK/Cancel   */

  <Window_Hide>(dlog);      /* Hide the window before we start processing  */

  if (<Dialog_LastClicked>(dlog) == 0)
     ProcessTheData();     /* OK was clicked, so go ahead with processing */

  <Dialog_Destroy>(dlog);
}GFX_Wait
extern void GFX_Wait(void);

(equivalent to WAIT, *FX 19, OS_Byte 19)

This call does not return until the vertical refresh has finished.
This means that you get control back after the hardware has
finshed updating the screen so if you do any drawing immediately
after this call it will be done while the screen is not being
drawn. This helps reduce flicker. Calling this procedure in Wimp
applications should be only used sparingly as overuse will slow down
screen output to an unacceptable level. Generally only use by
experimentation--write your graphics code, if it flickers too much try
putting in a GFX_Wait() and see if it helps. If it does and the update
speed isn't adversly affected then leave it in.

defined in <GFX>GFX_WriteN
extern void GFX_WriteN(char *string, int numchars);

Writes 'numchars' characters from the given string to the VDU stream
(veneer for <SWI OS_WriteN=>SWI.OS_WriteN>)

defined in <GFX>GFX_Write0
extern void GFX_Write0(char *string);

Writes the given zero-terminated string to the VDU stream
(veneer for <SWI OS_Write0=>SWI.OS_Write0>)

defined in <GFX>GFX_VDU
extern void GFX_VDU(char ch);
#define VDU(C) GFX_VDU(C)

(An <OS_WriteC=>SWI.OS_WriteC> veneer)
Writes the given ASCII character to the VDU stream
A macro is defined to allow use of the form VDU() as well as GFX_VDU()

defined in <GFX>GFX_CLG
extern void GFX_CLG(void);

Clears the current graphics window to the current background colour

defined in <GFX>GFX_CircleFill
#define GFX_CircleFill(x, y, r)                             \\
  {                                                         \\
    <GFX_Move>(x, y);                                         \\
    <GFX_Plot>(plot_CIRCLEFILL + plot_DRAWRELFORE, (r), 0);   \\
  }

defined in <GFX>GFX_Circle
#define GFX_Circle(x, y, r)                                 \\
  {                                                         \\
    <GFX_Move>(x, y);                                         \\
    <GFX_Plot>(plot_CIRCLE + plot_DRAWRELFORE, (r), 0);       \\
  }

defined in <GFX>GFX_RectangleFill
#define GFX_RectangleFill(x, y, w, h)                       \\
  {                                                         \\
    GFX_Move(x, y);                                         \\
    <GFX_Plot>(plot_RECTANGLEFILL + plot_DRAWRELFORE, w, h);  \\
  }

defined in <GFX>GFX_Rectangle
extern void GFX_Rectangle(int x, int y, int width, int height);

defined in <GFX>GFX_ miscellaneous drawing macros
Below are some macros using GFX_Plot to make life easier for you.
the "By" form (MoveBy, etc) moves/draws relative to the current cursor
position, while the other form draws in absolute OS coords.

GFX_Move(X, Y)  Moves the graphics cursor to the OS co-ordinates X, Y
GFX_Plot(X, Y)  Plots a pixel at the specified position
GFX_Draw(X, Y)  Draws a line from the current cursor position to x,y

#define GFX_Move(x, y) GFX_Plot(plot_SOLIDBOTH + plot_MOVECURSORABS, x, y)
#define GFX_MoveBy(x, y) GFX_Plot(plot_SOLIDBOTH + plot_MOVECURSORREL, x, y)
#define GFX_PlotPoint(x, y) GFX_Plot(plot_POINT + plot_DRAWABSFORE, x, y)
#define GFX_PlotPointBy(x, y) GFX_Plot(plot_POINT + plot_DRAWRELFORE, x, y)
#define GFX_Draw(x, y) GFX_Plot(plot_SOLIDBOTH + plot_DRAWABSFORE, x, y)
#define GFX_DrawBy(x, y) GFX_Plot(plot_SOLIDBOTH + plot_DRAWRELFORE, x, y)

defined in <GFX>GFX_Plot
extern void GFX_Plot(int plotcode, int x, int y);

Executes one OS Plot command.
plotcode is the <Plot code=>GFX_PlotCodes>
x and y are the X and Y screen coordinates to use

See also: <SWI OS_Plot=>SWI.OS_Plot>

defined in <GFX>Plot codes for GFX_Plot
#Table 12 28
plot_SOLIDBOTH       0x00
plot_SOLIDEXFINAL    0x08
plot_DOTTEDBOTH      0x10
plot_DOTTEDEXFINAL   0x18
plot_SOLIDEXINIT     0x20
plot_SOLIDEXBOTH     0x28
plot_DOTTEDEXINIT    0x30
plot_DOTTEDEXBOTH    0x38
plot_POINT           0x40
plot_HHORZLINEFILLNB 0x48
plot_TRIANGLEFILL    0x50
plot_HORIZLINEFILLB  0x58
plot_RECTANGLEFILL   0x60
plot_HORIZLINEFILLF  0x68
plot_PARALLELFILL    0x70
plot_HORIZLINEFILLNF 0x78
plot_FLOODTOBACK     0x80
plot_FLOODTOFORE     0x88
plot_CIRCLE          0x90
plot_CIRCLEFILL      0x98
plot_CIRCLEARC       0xA0
plot_SEGMENT         0xA8
plot_SECTOR          0xB0
plot_BLOCK           0xB8
plot_ELLIPSE         0xC0
plot_ELLIPSEFILL     0xC8
plot_GRAPHICSCHAR    0xD0
plot_SPRITE          0xE8
#EndTable

Within each block of eight the offset from the base number means:
#Table 3 28
plot_MOVECURSORREL   0
plot_DRAWRELFORE     1
plot_DRAWRELINVERSE  2
plot_DRAWRELBACK     3
plot_MOVECURSORABS   4
plot_DRAWABSFORE     5
plot_DRAWABSINVERSE  6
plot_DRAWABSBACK     7
#EndTable

The above applies except for plot_BLOCK where the codes are as follows:
#Table 3 28
plot_BMOVEREL        0
plot_BMOVERECTREL    1
plot_BCOPYRECTREL    2
plot_BMOVEABS        4
plot_BMOVERECTABS    5
plot_BCOPYRECTABS    6
#EndTable

defined in <GFX>DragASprite_Start
extern <os_error> *DragASprite_Start(int flags, void *spritearea, char *name,
                                   <wimp_rect> *bound, <wimp_rect> *parent);

defined in <DragASprite>DragASprite_Stop
extern os_error *DragASprite_Stop(void);

defined in <DragASprite>DragASprite_DragIcon
extern <os_error> *DragASprite_DragIcon(<window_handle> window, <icon_handle> icon);

This is a simple interface for DragASpr. Simply call it when you want
to start a drag operation of a sprite icon, and it starts a dragasprite
drag IF POSSIBLE, or a normal Wimp_DragBox if not (i.e. this is a
RISC OS 2 compatible call)

defined in <DragASprite>Icon_BarIcon
extern <icon_handle> Icon_BarIcon(char *spritename, <window_handle> pos);

This function places an icon on the iconbar. It makes a "normal"
sprite-only icon, with the "normal" default flags. If you want an
icon that is not this default, then create it yourself (it isn't hard!)

If you wish to attach handlers/menus to the baricon, then remember
it's handle, and pass this to <Event_Claim>...
(Or wait for release 2 of DeskLib, which should have an Event_BarIcon)

Pass in "spritename" -  the name of a sprite in the Wimp Sprite pool
and "pos", which should be iconbar_LEFT or iconbar_RIGHT
The correct size of the icon will be determined and used
Returns: The icon handle of the created icon

defined in <Icon>Icon_GetSelect
extern BOOL Icon_GetSelect(<window_handle> window, <icon_handle> icon);

Returns TRUE if the given icon is selected

defined in <Icon>Icon_GetShade
extern BOOL Icon_GetShade(<window_handle> window, <icon_handle> icon);

Returns TRUE if the given icon is shaded

defined in <Icon>Icon_SetSelect
extern void Icon_SetSelect(<window_handle> window, <icon_handle> icon, int flag);

Equivalent in action to <Icon_Select> + <Icon_Deselect>: Pass in a flag to
set the new selected status of the icon (0 = deselect, 1 = select)

defined in <Icon>Icon_Select
extern void Icon_Select(<window_handle> window, <icon_handle> icon);

If the given icon is currently deselected, it is selected

defined in <Icon>Icon_Deselect
extern void Icon_Deselect(<window_handle> window, <icon_handle> icon);

If the given icon is currently selected, it is deselected

defined in <Icon>Icon_SetShade
extern void Icon_SetShade(<window_handle> window, <icon_handle> icon, int flag);

Equivalent in action to <Icon_Shade> + <Icon_Unshade>: Pass in a flag to
set the new shaded status of the icon (0 = unshaded, 1 = shaded)

defined in <Icon>Icon_Shade
extern void Icon_Shade(<window_handle> window, <icon_handle> icon);

if the icon is currently unshaded (active) it is shaded (made inactive)
This includes removing the caret from the icon.

defined in <Icon>Icon_Unshade
extern void Icon_Unshade(<window_handle> window, <icon_handle> icon);

if the icon is currently shaded (inactive) it is unshaded (made active)

defined in <Icon>Icon_ForceWindowRedraw
extern void Icon_ForceWindowRedraw(<window_handle> window, <icon_handle> icon);

Force Redraws the area of WINDOW surrounding the icon, *including*
the 3-d border (validation string "b\<bordertype\>")

defined in <Icon>Icon_ForceRedraw
#define Icon_ForceRedraw(wind, icon) <Wimp_SetIconState>(wind, icon, 0, 0);

Forces the WIMP to redraw (just) the icon

defined in <Icon>Icon_SetCaret
extern void Icon_SetCaret(<window_handle> window, <icon_handle> icon);

This routine sets the caret within the requested icon. It places the
caret at the (righthand) end of the text in the icon. If the icon is not
a text icon, then the function returns quietly

defined in <Icon>Icon_LoseCaret
extern void Icon_LoseCaret(<window_handle> window, <icon_handle> icon);

This routine ensures that the caret is *not* contained within the
designated icon. Only sets a new position if the icon currently contains
the caret.

defined in <Icon>Icon_SetInteger
extern void Icon_SetInteger(<window_handle> w, <icon_handle> i, int value);

Sets the given icon's text to hold the number in "value". (and redraws icon)
If the number is too long (too many digits) it will be truncated to fit.
If unable to set the text (incorrect icon type), it returns quietly

defined in <Icon>Icon_SetDouble
extern void Icon_SetDouble(<window_handle> w, <icon_handle> i,
                           double value, int decimalplaces);

Sets the given icon's text to hold the number in "value". (and redraws icon)
Only the first "decimalplaces" digits after the decimal point are
printed. If the number is too long (too many digits) it will be truncated
to fit. This may affect the accuracy or actual value of the number.
If unable to set the text (incorrect icon type), it returns quietly

defined in <Icon>Icon_SetText
extern void Icon_SetText(<window_handle> w, <icon_handle> i, char *text);

Copies the text string into the icon's indirected string buffer (and redraws)
If unable to set the text (incorrect icon type), it returns quietly
If text passed in is a NULL pointer, sets icon text to " "

defined in <Icon>Icon_printf
extern void Icon_printf(<window_handle> window, <icon_handle> icon,
                        char *format, ...);

Exactly the same as sprintf, but instead of passing in a string into which
the result is written, you pass in the window+icon identifier of an
indirected icon. (Anything other than an indirected icon will return
quietly with NO effect)
e.g Icon_printf(window, 5, "%d bytes copied", current);

defined in <Icon>Icon_GetDouble
extern double Icon_GetDouble(<window_handle> w, <icon_handle> i);

Gets the given icon's text and returns it in the form of a "double"
floating-point value. 0 will be returned from any error/invalid text

defined in <Icon>Icon_GetInteger
extern int Icon_GetInteger(<window_handle> w, <icon_handle> i);

Gets the given icon's text and returns it in the form of an integer
numeric value. 0 will be returned from any error/invalid text

defined in <Icon>Icon_GetText
extern void Icon_GetText(<window_handle> w, <icon_handle> i, char *text);

Copies the text string from the icon (sprite name, text, or indirected)
into the array pointed to by "text"

defined in <Icon>Icon_SetRadios
extern void Icon_SetRadios(<window_handle> window,
                           <icon_handle> first, <icon_handle> last,
                           <icon_handle> onradio);

Pass in a group of icons (specified by lowest-numbered icon and
highest-numbered icon), and the icon from this group that you want
selected. All icons except the one you want selected will be deselected.

defined in <Icon>Icon_WhichRadio
extern int Icon_WhichRadio(<window_handle> window,
                           <icon_handle> first, <icon_handle> last);

This function accepts parameters for the first (lowest numbered) and
last (highest numnbered) in a group of icons (generally a group of radio
buttons). It returns the icon number of the first icon it finds within
this range which is selected (or "last" if none are selected).
Use it to find which of a group of radios is selected.

defined in <Icon>Icon_ClickWait
extern void Icon_ClickWait(int waittime);

Waits for the given number of centiseconds.
This is a MULTITASKING wait - although your program will do nothing,
the rest of the desktop will continue to run.
The wait is aborted after the given time, or as soon as an event is
received. If an attempt is made to re-enter ClickWait(), it will return
immediately (i.e. if a click event causes ClickWait to ba called, then
a second click while "waiting" from the first click will have no effect.

defined in <Icon>Icon_StartDrag
extern void Icon_StartDrag(<window_handle> window, <icon_handle> icon);

Starts a drag operation based on the given icon.
This is mainly used in "save as" windows to start drags of the file icon
when it is clicked on, but may be useful elsewhere.

This call DOES NOT use DragASprite

defined in <Icon>Icon_StartSolidDrag
extern void Icon_StartSolidDrag(<window_handle> window, <icon_handle> icon);

Starts a drag operation based on the given icon, using DragASprite if available

defined in <Icon>Icon_DisposeIndData
extern void Icon_DisposeIndData(<icon_data> *data, <icon_flags> flags);

This will free any indirected data for this icon. It uses free(), so
obviously expects that malloc() was used to get the memory in the first
place, so make sure this is the case if you use this function.

defined in <Icon>Icon_SetSlider
extern int Icon_SetSlider(<window_handle> window,
                          <icon_handle> baseicon, <icon_handle> slidericon,
                          int sliderpos);

Sets a slider icon-pair to the specified position (specify as a
percentage). Values \< 0 and > 1000 are clipped, and the value to which the
slider has been set is returned.

defined in <Icon>Icon_UpdateSlider
extern int Icon_UpdateSlider(<window_handle> window,
                             <icon_handle> baseicon, <icon_handle> slidericon,
                             int lastpos);

(call on null events while slider being dragged)
Calculates a new slider percentage from the mouse pointer position.
If this differs from lastpos, the slider is updated (by recreating the
slidericon to the new length.
returns the new slider position percentage value.
NOTE: Slider update is achieved by DELETING and re-creating the slider
icon. This relies upon no icons of a lower icon handle having been deleted!

defined in <Icon>Icon_DragSlider
extern int Icon_DragSlider(<window_handle> window,
                           <icon_handle> baseicon, <icon_handle> slidericon);

Initiates the drag operation on a slider. Call this when you get a click
in either baseicon or slidericon.
Returns the new percentage represented by the slider (remember this so
you can pass it in to Icon_UpdateSlider to save unnecessary (flickery)
update.)
NOTE: It is up to you to turn on Null events and remember that
<Icon_UpdateSlider> must be called on each poll...
An alternative is to make the 2 slider icons use button type ALWAYS, and
check the mouse button state yourself to see whether a drag needs to be
started/continued...

defined in <Icon>Icon_ReadSlider
extern int Icon_ReadSlider(<window_handle> window,
                           <icon_handle> baseicon, <icon_handle> slidericon);

Given a slider icon-pair, returns a percentage representing the state

defined in <Icon>Notes on the use of Event_ functions
Event supplies a set of high-level functions for proper handling of WIMP
events.
It polls the WIMP for you, and then passes the resulting event to one of
your designated handler routines. Events are cascaded down through your
handlers until one of them returns TRUE, indicating that the event has
been successfully dealt with. This allows you to have application-wide
defaults for certain event types, with occasional overrides of that
default for specific windows or icons.

Handlers can be registered for the following (priority-ordered) things:

  Specific window, specific icon, specific event.
  Specific window, specific icon, any event.
  Specific window, any icon, specific event.
  Specific window, any icon, any event.
  Any window, specific event.
  Any window, any event.

When an non window-related event occurs, the order is as follows:

  Any window, specific event.
  Any window, any event.

A set of default handlers is also provided (handlers.c): You can copy
the code for the handlers you need into your own program as a base event
handling system.

Any event which has no registered handlers will automatically be masked
out in subsequent Wimp_Polls. (Except for "Quit" messages)

NULL events are treated (slightly) specially compared to other events.
After registering handler(s) for NULL events they will be turned on.
(They will NOT be turned on if you request a handler for ALL events. To
enable NULL events, you must specifically register a handler for
event_NULL events.)
As a default, Wimp_Poll will be used, but functions are supplied for
you to set a minimum return time (as in Wimp_PollIdle) if NULL events
are wanted less frequently
TWO options for NULL event handling are open to you:
  Each NULL event is passed to ALL registered handlers,
    (To allow you to do important things as often as possible)
  Each handler gets one NULL event in turn, in a round-robin fashion.
    (To allow you to multitask several "subtask" functions alongside
     each other with ease)Notes on the use of Menu_ functions:
These are simple menu create and show functions along very
similar lines to RISC OS Lib's 'menu' functions. However, there
are major differences -
 + menu items are ALWAYS indexed starting from 0.
 + menu pointers point to real Wimp menu structures, no
   messing about
 + <Menu_Show> is provided to show the menus for you, including
   placing a menu in the correct position over the icon bar.Time_Monotonic
extern int Time_Monotonic(void);

Veneer for the OS_ReadMonotonicTime SWI
Returns an integer representing the time since the computer was switched
on, in centiseconds.
Used with Wimp_PollIdle to poll every now and then, as in:
  time = Time_Monotonic();
  <Wimp_PollIdle>(mask, block, time + 100);  /* Pollidle for 1 sec (100cs) */

Can also be used to time things, i.e.
  time = Time_Monotonic();
  while (Time_Monotonic \< time+100) /* wait */ ;    /* Wait for 1 second */

defined in <Time>Notes on Wimp_Poll handling:
DeskLib 2.04:
WimpSWIs.s.Poll has been updated to handle passing a WIMP pollword
under RISC OS 3. The new Poll functions have been named <Wimp_Poll3>
and <PollIdle3> so that you can't accidentally link with the new
forms of the functions.

<Wimp_Poll> and <Wimp_PollIdle> are now macros that map Poll calls
onto the new <Wimp_Poll3> functions (passing a zero for the pollword).
So long as you only try to use pollwords under RISC OS 3 onwards,
you should be fine!

If you wish to specifically use the pollword, then call the Poll3
functions directly, using the new parameter.SWI
<os_error> *SWI(int numregsin, int numregsout, int swicode, ... );

This function provides a general-purpose SWI call veneer.
It is not meant to be the most efficient SWI caller, but the most
general one. If you require faster SWI handling than this function
provides, then you will need to construct an assembler veneer for the SWI
(see <WimpSWIs> library source for examples)

Call it specifying the number of arguments you are passing in,
                   the number of arguments you want passed back,
                   the SWI number to call (X or normal),
                   and a list of parameters...
Parameters:
  The SWI list in should be a list of integers, exactly the number
  specified as "numregsin". These will be passed to the SWI as registers
  0, 1, 2, ... A maximum of 6 such registers can be specified.

  The SWI list out should be a list of pointers to result variables
  they will be assigned the register results from the SWI, in order.
  Pass in a NULL pointer for any of these if the result is to be ignored

<Examples=>SWI_Example>

When you want to use the SWI names, you have to #define your own
macros for them.

-- See <Hourglass>.h for examples of how to make low-level SWI calls
   look nice in your calling code without the extra expense of another
   function call.

defined in <SWI>.hExamples of the SWI function:
SWI(0, 0, SWI_Hourglass_On);
SWI(1, 0, SWI_Hourglass_Percentage, 33);
SWI(0, 0, SWI_XHourglass_Smash);

{ int ramsprites, romsprites;
  /* Read rom sprite and ram sprite pool base addresses: */
  SWI(0, 2, SWI_Wimp_BaseOfSprites, &romsprites, &ramsprites)

  /* Read ram sprite base ONLY */
  SWI(0, 2, SWI_Wimp_BaseOfSprites, NULL, &ramsprites)
}Error_ReportInternal
extern void Error_ReportInternal(int errornum, char *report, ...);

This is identical to <Error_Report>, except it is used for most DeskLib
library internal errors. User code should use <Error_Report>. This allows
you to modify the treatment of internal errors, without affecting your
own error handling.

defined in <Error>Error_ReportFatalInternal
extern void Error_ReportFatalInternal(int errornum, char *report, ...);

This does an <Error_ReportInternal>, and then calls exit()

defined in <Error>Error_Report
extern void Error_Report(int errornum, char *report, ...);

This is a centralised user-error reporting function.
Call it, citing any error number you want, and any error string you want.
The current implementation merely invokes Wimp_ReportError, but use it
from your code, as then the method by which you report errors can be
altered just by changing Error.c

The report is a 'printf' style formatting string, optionally followed
by arguments just as in printf commands. This saves you from having to
pre-assemble strings to pass in.
examples:
  Error_Report(5, "My VIDC just blew up!");
  Error_Report(6, "You can't put the number %d in there!", thenumber);

defined in <Error>Error_ReportFatal
extern void Error_ReportFatal(int errornum, char *report, ...);

Exactly the same as <Error_Report>, except after reporting the error, it
terminates the program by calling exit()

Takes variable arguments a la 'printf'. See <Error_Report> for more info.

defined in <Error>Error_Check
extern BOOL Error_Check(<os_error> *error);

Used to encapsulate an OS call to automatically check for error return.
If the OS call returns an error, then it will be reported, and the
function returns TRUE.
Otherwise, no action is taken, and FALSE is returned

defined in <Error>Error_CheckFatal
extern void Error_CheckFatal(<os_error> *error);

Identical to <Error_Check>, but calls exit() if an error ocurred

defined in <Error>Error_OutOfMemory
extern BOOL Error_OutOfMemory(BOOL fatal, char *place);

Reports a memory error (e.g. "Unable to claim enough memory for
[Messages]"), where you supply just the "place" of the failure
(e.g. in this case, in the "Messages" section)
if "fatal" is TRUE, <Error_ReportFatal> is used, else <Error_Report>
is used.

This function ALWAYS returns FALSE (== 0 == NULL), so you can use:
  if (spritearea == NULL)
    return(Error_OutOfMemory(FALSE, "icon sprites"));

defined in <Error>Mem_Size
extern int Mem_Size(<mem_anchor> *anchor);

Returns the current size (in bytes) of a mem chunk

defined in <Mem>Mem_Compact
extern void Mem_Compact(void);

This call compacts the mem heap, moving all free space to the end of
the chunk, and giving back as much memory as possible to the Wimp.
This may result in some mem chunks moving, so you cannot rely on
anchors remaining the same across this call.
Ideally, you should call this just before calling Wimp_Poll, to
ensure the Wimp has all possible available memory (and also keep the
heap tidy)
Note that this may be automatically called by other Mem_ functions
IF <mem_autocompact> allows it. However, it will NEVER be called if
<mem_autocompact> == mem_NOCOMPACT

defined in <Mem>Mem_Free
extern void Mem_Free(<mem_anchor> *anchor);

Releases a chunk of memory back to the free pool
The contents of the anchor will be set to NULL to indicate it is no
longer a valid pointer.
If permitted to by the contents of <mem_autocompact>, this call MAY
relocate other mem chunks.

defined in <Mem>Mem_MoveAnchor
extern void Mem_MoveAnchor(<mem_anchor> *from, <mem_anchor> *to);

Allows you to move an anchor from one variable to another.
This allows you to allocate a chunk with a temporary anchor and then
move the anchor into permanent storage at a later time (without having
to allocate a new chunk and copy, as is necessary under flex)

Use with care - i.e. remember to check anchors to see if they are NULL
(in which case you're using the wrong anchor!)

If all goes well (i.e. 'from' was a valid chunk), *from will be set
to NULL and *to will now point at the chunk. From this point on,
the anchor 'to' will be adjusted whenever the chunk is moved.

Otherwise, from is left as it was, and to will be set to NULL

<Example=>Mem_MoveAnchEx>

defined in <Mem>Example use of Mem_MoveAnchor:
{
  char *old, *new;
  <Mem_Alloc>((<mem_anchor> *) &old, 1024);   /* Get some memory */
  if (old != NULL)
  {
    old[5] = 'a';
    Mem_MoveAnchor((<mem_anchor> *) &old, (<mem_anchor> *) &new);
        /* if 'old' was valid, 'new' now points to where old was, */
        /* and old is now NULL                                    */

    if (new == NULL)    printf("Error - old was invalid! \n");
    if (new[5] != 'a')  printf("Error - Jason's code is buggy! \n");
  }
  :
}Mem_MidExtend
extern BOOL Mem_MidExtend(<mem_anchor> *anchor, int at, int by);

Attempts to alter the size of a mem chunk.
"at" is a byte-offset within the data chunk
"by" is the number of bytes to extend by (negative to reduce the chunk)
If "by" is positive,
  'by' bytes of indeterminate value will be inserted at 'at', shifting
  the rest of the data up to make room
else
  'by' bytes of data BELOW 'at' will be deleted by moving the data
  from 'at' onwards down by 'by' bytes.

Returns TRUE if the extension was successful.
The allocated memory starts at a word-aligned address

If permitted to by the setting of <mem_autocompact>, this call MAY
relocate other mem chunks.

defined in <Mem>Mem_Alloc
extern BOOL Mem_Alloc(<mem_anchor> *anchor, int numbytes);

Attempts to allocate the given amount of memory (in bytes) in the mem
heap. Updates the anchor you pass in to point to this block, or
to contain NULL if it is unable to allocate the requested memory.
The returned block of memory starts at a word-aligned address
Returns TRUE if it succeeded

If permitted to by the setting of <mem_autocompact>, this call MAY
relocate other mem chunks.

defined in <Mem>Mem_Initialise
extern BOOL Mem_Initialise(void);

Initialises the Mem system ready for use.
Note that this locks down the malloc and stack memory area to the
current WimpSlot size at the point of calling, and builds a mem
heap above this. Malloc and stack allocation will not be able to get
more memory than is originally available in your WimpSlot, so get it
right!
Note that Mem_Initialise() provides a function to
_kernel_register-slotextend() to stop the SharedCLib being able to
overwrite the Mem heap with the stack/malloc chunks.

defined in <Mem>Type: mem_compaction
typedef enum
{
  mem_NOCOMPACT   = 0,  /* ONLY compacts if <Mem_Compact> called  */
  mem_FASTCOMPACT = 1,  /* Compacts only if necessary           */
  mem_PARTCOMPACT = 1,
  mem_FULLCOMPACT = 2   /* Compacts on every heap change        */
} mem_compaction;

defined in <Mem>Type: mem_anchor
typedef void *mem_anchor;

defined in <Mem>Compaction control
<mem_compaction> mem_autocompact

Apart from compacting when you call <Mem_Compact>(), Mem will also
compact at the following times, depending on the value of mem_autocompact

  mem_NOCOMPACT:    Auto compaction never occurs. This may be useful if
                    you wish to guarantee that chunks ONLY move when you
                    call <Mem_Compact>().

  mem_PARTCOMPACT:  Auto compaction occurs whenever compaction might make
                    an otherwise impossible memory claim possible. This is
                    the recommended (and default) setting.

  mem_FULLCOMPACT:  Auto compaction occurs every time a chunk is freed
                    (the way that RISC OS Lib flex() operates)
                    This is not reccommended, as it can be very inefficient

NOTE that the value of mem_autocompact may be changed at any time
and will take immediate effect. Therefore, if you wish to ensure that
pointers into mem chunks remain 'safe' for a short period of time, you
can set mem_autocompact = mem_NOCOMPACT while procssing, and return
it to its former value when finished.

defined in <Mem>Notes on the Mem library
Mem memory chunks are held in a 'heap' of memory above the area grabbed
by the SharedCLibrary for mallocs and stackspace, extending up to the
end of the WimpSlot, which is adjusted up & down as necessary.

The major feature that externally distinguishes Mem from flex() is that
the heap is NOT compacted automatically (flex keeps the entire heap
compacted at all times). This has several advantages:
  - You can rely on pointers remaining constant at all times between
    calls to <Mem_Compact>() (and other Mem_ calls if you allow it)
  - everything is a lot faster if you are allocating and/or
    deallocating many chunks in one go.

The idea behind this is that you simply call <Mem_Compact> before
calling Wimp_Poll - this returns free memory to the Wimp as effectively
as the flex system did, but saves us from having to waste time on
multiple compactions between Wimp_Polls.

Automatic compaction (a la flex) can be turned on (or off) at any time
so the Mem system can be made to emulate flex_ if you really want it.
To do this, set <mem_autocompact>.
NOTE that by default, mem will only autocompact if it has no choice,
but *may* autocompact during any Mem_ call.strcpycr == strcpy
Copies s2 into s1. Returns s1.
The returned string will be zero terminated.

extern char *strcpycr(char *s1, char *s2);

defined in <StringCR>strcatcr == strcat
extern char *strcatcr(char *s1, char *s2);

Concatenates s2 onto the end of s1. Returns s1.
The returned string will be zero terminated.

defined in <StringCR>strcmpcr == strcmp
extern int strcmpcr(char *s1, char *s2);

Returns 0 if the strings match
Returns -1 if s1 \< s2  (alphabetically less than, and/or shorter)
Returns +1 if s1 \> s2  (alphabetcally greater than, and/or longer)

defined in <StringCR>strlencr == strlen
extern int strlencr(char *s);

NOTE **** With release 2 of DeskLib this has been changed to return
the length of the string EXCLUDING the terminator (i.e. it now returns
1 less than it used to in Desklib 1)

defined in <StringCR>Var: file_lasterror
extern <os_error> *file_lasterror;

file_lasterror is used to provide a more convenient SWI veneer for certain
file operations (Open, reading, etc, return handles/values directly,
rather than you having to provide the address of a variable for the
returned value, leaving no convenient way of returning errors!)

Thus, file_lasterror is set by the file operations:
#Table 3 20
<Open>
<Close>
<EOF>
<Read8/32/Bytes>
<Write8/32/Bytes>
<Seek>
<ReturnPos>
#EndTable

However, note that it is just a pointer to the error returned by the SWI
call, so it MUST be used immediately after the call, or else it may be
invalid or possibly even dangerously corrupted.
If for example, you wish to close the file before reporting the error,
you must first copy the error into your own <os_error> block.

If no error occurred on the last file op, file_lasterror will be NULL.
Most of the above functions also return values (filehandle = NULL etc)
that will indicate when an error may have occurred, at which time you
can interrogate file_lasterror to work out what the error was.

Note also that all of the above calls which do not have a specific
return value (Close, Write*, Seek) return the <os_error> pointer directly
as well as setting file_lasterror, for convenience.

defined in <File>File_Delete
extern <os_error> *File_Delete(char *filename);

Attempts to delete the named file. Use carefully!

defined in <File>File_Size
extern int File_Size(char *filename);

Reads the size (in bytes) of the file. A return value of 0 indicates
either the file is 0 bytes long, or an error occurred (which usually
means that the file doesn't exist)

defined in <File>File_Exists
extern BOOL File_Exists(char *filename);

This returns TRUE if the file exists.
(It attempts to open the file for reading - it returns TRUE if successful)

defined in <File>File_Open
extern <file_handle> File_Open(char *filename, <file_access> access);

Opens the given file for reading or writing (see file_access's above)
Returns the file handle, or NULL if it failed
(if NULL, you can check <file_lasterror> for the reason)

NOTE that the OS will return a NULL file handle if we try to open a
non existent file, but does NOT flag this as an error (i.e. File_Open
returns NULL, but file_lasterror is ALSO NULL). You must therefore
check <file_lasterror> before blindly trying to use it to report an error.

defined in <File>Type: file_access
typedef enum
{
  file_READ   = 0x40,   /* Open the file for reading                 */
  file_WRITE  = 0x80,   /* CREATE/WIPE the file, open it for writing */
  file_APPEND = 0xC0    /* Open for appending to existing file. NOTE
                         * that I don't have the PRMs so I can't tell
                         * you where this puts the initial file pointer
                         */
} file_access;

These values are used when opening files. NOTE that they correspond
directly to OS_File opening flags (OS_File R0 entry value)

defined in <File>File_Close
extern <os_error> *File_Close(<file_handle> handle);

Closes an open file stream, using the handle returned by <File_Open>
After a close, the file_handle is no longer valid, so do not try
to use it.

defined in <File>Type: file_handle
typedef int file_handle;

Specifies an open file for the File_* functions

defined in <File>File_EOF
extern BOOL File_EOF(<file_handle> handle);

Returns TRUE if the end of the file has been reached

defined in <File>File_Seek
extern <os_error> *File_Seek(<file_handle> handle, <file_position> position);

Seeks the file pointer to the given position (an offset in terms of
bytes offset from the start of the file). Subsequent read/write
operations will read from or write to that part of the file.

See also <File_ReturnPos>

defined in <File>Type: file_position
typedef int file_position;

defined in <File>File_ReturnPos
extern <file_position> File_ReturnPos(<file_handle> handle);

Returns the current file pointer position.
This is a value which, when passed to <File_Seek>, will return you
to the same position you were at when you called File_ReturnPos

defined in <File>File_WriteBytes
extern <os_error> *File_WriteBytes(<file_handle> handle,
                                 void *buffer, int numbytes);

This writes a chunk of data to the current position in a file opened
for writing. 'numbytes' bytes will be written from the given buffer.
It is important to check for errors from this call as Disc Full errors
are a common occurrence.

defined in <File>File_ReadBytes
extern int File_ReadBytes(<file_handle> handle, void *buffer, int numbytes);

Reads the given number of bytes of data from the given file, into the
given buffer. Returns the number of bytes NOT successfully read.
(i.e. if you hit EOF during the read, the return value will be non-zero)

defined in <File>File_Write8
extern <os_error> *File_Write8(<file_handle> handle, int byte);

Writes an 8-bit value (a byte/char) to the given output file.

defined in <File>File_WriteByte
#define File_WriteByte <File_Write8>

defined in <File>File_WriteChar
#define File_WriteChar <File_Write8>

defined in <File>File_Read8
extern int File_Read8(file_handle handle);

Reads an 8-bit value (a byte/char) from the given input file.
If an error (typically EOF) occurs during the read, <file_READERROR>
will be returned.

VERY IMPORTANT NOTE!
DO NOT use File_Read8() in a line like the following:
  shortvalue = File_Read8(infile) | (File_Read8(infile) \<\< 8);

The problem here is that the C compiler is allowed to evaluate the 2
functions in any order it sees fit, so may read the two bytes in the
incorrect order. You MUST therefore do such an operation with code
in the following form if you are to sure it will work:
  shortvalue = File_Read8(infile);
  shortvalue |= File_Read8(infile) \<\< 8;

defined in <File>File_ReadByte
#define File_ReadByte <File_Read8>

defined in <File>File_ReadChar
#define File_ReadChar <File_Read8>

defined in <File>File_Write32
extern <os_error> *File_Write32(<file_handle> handle, int word);

Writes an 32-bit value (a word/int/long) to the given output file.

defined in <File>File_WriteWord
#define File_WriteWord <File_Write32>

defined in <File>File_WriteInt
#define File_WriteInt <File_Write32>

defined in <File>File_WriteLong
#define File_WriteLong <File_Write32>

defined in <File>File_Read32
extern int File_Read32(<file_handle> handle);

Reads a 32-bit value (a word/int/long) from the given input file.
If an error (typically EOF) occurs during the read, <file_READERROR>
will be returned. (Note that this is a perfectly legal value to read
from the file, though, so you should check file_lasterror to see if
an error occurred).

defined in <File>File_Read32R
extern int File_Read32R(<file_handle> handle);

Identical to <File_Read32>, but reverses the byte ordering as it reads
(converts from little endian to big endian format). This is very useful
for reading textual tags from files, as they can then be compared to
integer constants of the form 'aTag' rather than having to reverse the
byte order manually (i.e. using the tag 'gaTa' which is less human
readable)

defined in <File>File_Write32R
extern <os_error> *File_Write32R(<file_handle> handle, int word);

Same as <File_Write32>, but reverses the byte order before
writing. See <File_Read32R> for more details about why you'd
want to do this.

defined in <File>File_ReadWord
#define File_ReadWord <File_Read32>

defined in <File>File_ReadInt
#define File_ReadInt <File_Read32>

defined in <File>File_ReadLong
#define File_ReadLong <File_Read32>

defined in <File>File_ReadLongR
#define File_ReadLongR <File_Read32R>

defined in <File>File_ReadIntR
#define File_ReadIntR <File_Read32R>

defined in <File>File_ReadWordR
#define File_ReadWordR <File_Read32R>

defined in <File>File_WriteWordR
#define File_WriteWordR <File_Write32R>

defined in <File>File_WriteIntR
#define File_WriteIntR <File_Write32R>

defined in <File>File_WriteLongR
#define File_WriteLongR <File_Write32R>

defined in <File>file_READERROR
#define file_READERROR (-1)

Returned by som File_ functions to indicate
errors, see also <file_lasterror>

defined in <File>LinkList_NextItem
extern void *LinkList_NextItem(<linklist_header> *item);

Return the next item of a given one. If the current item is at
the tail of the list, a NULL pointer will be returned.

Old definition:
  #define LinkList_NextItem(x) ((void *)(x)->next)

NEW definition:
  you can now use   LinkList_NextItem(&item);
  instead of        LinkList_NextItem(&item->header);

See also <LinkList_PreviousItem>

defined in <LinkList>LinkList_PreviousItem
extern void *LinkList_PreviousItem(<linklist_header> *item);

Return the previous item of a given one. If the current item is
at the head of the list, a NULL pointer will be returned.

Old definitions:
  #define LinkList_PreviousItem(x) ((void *)(x)->previous)

NEW definition:
  you can now use   LinkList_PreviousItem(&item);
  instead of        LinkList_PreviousItem(&item->header);

See also: <LinkList_NextItem>

defined in <LinkList>LinkList_InitItem
extern void LinkList_InitItem(<linklist_header> *item);

Initialises a list item. Should be called before item used,
except when that item is immediately linked into a list

defined in <LinkList>LinkList_Init
extern void LinkList_Init(<linklist_header> *item);

Initialises a list anchor. Should be called before anchor used

defined in <LinkList>LinkList_FirstItem
extern void *LinkList_FirstItem(<linklist_header> *anchor);

Return pointers to the first item in the list

defined in <LinkList>LinkList_LastItem
extern void *LinkList_LastItem(<linklist_header> *anchor);

Return pointers to the last item in the list

defined in <LinkList>LinkList_Unlink
extern void LinkList_Unlink(<linklist_header> *anchor, <linklist_header> *item);

Unlinks the item "item" from the given list.
You must then free the memory used by it yourself.

defined in <LinkList>LinkList_ListLength
extern BOOL LinkList_ListLength(<linklist_header> *anchor);

Returns the number of items in the list. It follows all the links
and counts them... if you need this value a lot, I suggest you modify
LinkList to keep a count in the anchor...

defined in <LinkList>LinkList_InList
extern BOOL LinkList_InList(<linklist_header> *anchor, <linklist_header> *item);

Returns TRUE if the item is curently in the list. Note that this does
NOT check item contents, merely compares item pointers.
To check item contents, you must chain through the list yourself.

defined in <LinkList>Type: linklist_header
typedef struct linklist_header
{
  struct linklist_header *next;
  struct linklist_header *previous;
} linklist_header ;

defined in <LinkList>Implementation notes for DeskLib:LinkList.h
This module provides support for a linked list structure.
YOU must supply an anchor for the list (a variable of type
<linklist_header>). This is used to record pointers to the start and end
of the list.
The list itself is made up of your own structures, defined as follows:
  struct listelement
  {
    <linklist_header> header;
    ... Your own data here ...
  } listelement;

a list-terminating pointer is represented as NULL

The header's next field stores a pointer to the FIRST item
         its previous field stores a pointer to the LAST item
         (both these pointers will be nulls if the list is empty)

To insert items into the list, you must malloc memory for one of your
own listelement data structures, then call the appropriate function.
To delete an item from the list, call the unlink function, and then free
all memory used by your structure.LinkList_AddToHead
extern void LinkList_AddToHead(<linklist_header> *anchor, <linklist_header> *item);

Insert an item in a linked list to the head of the list.

defined in <LinkList>LinkList_InsertAfter
extern void LinkList_InsertAfter(<linklist_header> *anchor,
                                 <linklist_header> *pos,
                                 <linklist_header> *item);

Inserts the given item AFTER the item "pos"

defined in <LinkList>LinkList_InsertBefore
extern void LinkList_InsertBefore(<linklist_header> *anchor,
                                  <linklist_header> *pos,
                                  <linklist_header> *item);

Inserts the given item BEFORE the item "pos"

defined in <LinkList>LinkList_AddToTail
extern void LinkList_AddToTail(<linklist_header> *anchor, <linklist_header> *item);

Inserts the given item at the end of the list

defined in <LinkList>PopUp_ShowStandalone
<popup_handle> PopUp_ShowStandalone(char *name, <popup_data> *definition);

This macro simply makes <PopUp_ShowPtr> nicer to use without causing more
code bulk. It is used to show a standalone-menu.

defined in <PopUp>PopUp_ShowStatic
<popup_handle> PopUp_ShowStatic(char *name, <popup_data> *definition);

This macros simply makes <PopUp_ShowPtr> nicer to use without causing more
code bulk. It is used to show a static (permanent window) PopUp.

defined in <PopUp>PopUp_ShowPtr
extern <popup_handle> PopUp_ShowPtr(char *name, BOOL isstatic,
                                  <popup_data> *definition);

Higher level interface to <PopUp_Open,> which will open a STANDALONE MENU
or STATIC PopUp by filling in the position to open at (over the pointer)
and other header data for you, and open the PopUp as defined by the
passed in "<popup_data>" block.

'name'       is the PopUp type name (e.g. "FontSelect")
'isstatic'   indicates if the PopUp should be a static or menu PopUp.
'definition' is the popup-specific description.

Rather than calling ShowPtr directly, use the macros
<PopUp_ShowStandalone>
<PopUp_ShowStatic>

defined in <PopUp>PopUp_ShowMenuLeaf
extern <popup_handle> PopUp_ShowMenuLeaf(char *name, <popup_data> *definition,
                                       <message_menuwarn> *msg);

Higher level interface to <PopUp_Open>, which will show a MENU-LEAF PopUp
given the PopUp type name and popup-specific data, plus the "menuwarn"
message that induced your desire to open the PopUp in the first place.

'name'       is the PopUp type name (e.g. "FontSelect")
'definition' is the popup-specific description.

<Hypothetical example of use=>PopUp_ShowMLEx>

defined in <PopUp>Example of PopUp_ShowMenuLeaf use:
case message_MENUWARN:
  switch(event->data.message.data.menuwarn.selection[0])
  {
    case 3: /* Save => menu item */
    {
      <popup_data> pud;

      strcpy(pud.saveas.iconsprite, "file_aff");   /* iconsprite name   */
      strcpy(pud.saveas.filename, "DrawFile");     /* Default file name */
      <PopUp_ShowMenuLeaf>("SaveAs", &saveas,
                         &event->data.message.datamenuwarn);PopUp_Close
extern void PopUp_Close(<popup_handle> handle);

Straight SWI veneer for PopUp_Close swi.
This will close any PopUp, given the handle as returned by other
PopUp calls (<PopUp_Open>, <PopUp_Show>)
Note that this is only necessary for STATIC PopUps, and that illegal
calls (popup isn't open, etc) will be ignored.

defined in <PopUp>PopUp_Open
extern <popup_handle> PopUp_Open(<popup_block> *params);

Straight SWI veneer for PopUp_Open swi.
You shouldn't have to call this function - use:
#Table 2 25
<PopUp_ShowMenuLeaf>
<PopUp_ShowPtr>
<PopUp_ShowStandalone>
<PopUp_ShowStatic>
#EndTable

defined in <PopUp>Type: popup_block
typedef struct
{
  <popup_header> header;
  <popup_data>   data;
} popup_block;

Block to send to <PopUp_Open>

defined in <PopUp>Type: popup_header
typedef struct
{
  char       name[12];      /* PopUp type name, eg "SaveAs"          */
  <wimp_point> openpos;       /* Position (top left) to open window at */
  char       flags;         /* menuleaf/standalone/static popup?     */
  char       reserved1, reserved2, reserved3;
} popup_header;

defined in <PopUp>Type: popup_data
typedef union
{
  <popup_magnify>    magnify;
  <popup_proginfo>   proginfo;
  <popup_report>     report;
  <popup_saveas>     saveas;
  <popup_wimpcolour> wimpcolour;
  <popup_truecolour> truecolour;
} popup_data;

Data to send to popup manager

defined in <PopUp>Type: popup_truecolour
typedef struct
{
  int colourmodel;    /* eg: popuptc_RGB + popuptc_TRANSPARENCY1 */
  union
  {
    <colour_rgb>  rgb;
    <colour_hsv>  hsv;
    <colour_cmyk> cmyk;
  } colour;

  int transparency;   /* 0..255 */
} popup_truecolour;

defined in <PopUp>Type: colour_rgb
typedef struct
{
  unsigned int transparency : 8;
  unsigned int red          : 8;
  unsigned int green        : 8;
  unsigned int blue         : 8;
} colour_rgb;

defined in <PopUp>Type: colour_hsv
typedef struct
{
  unsigned int value        : 8;    /* 0..255 */
  unsigned int saturation   : 8;    /* 0..255 */
  unsigned int hue          : 16;   /* 0..359 */
} colour_hsv;

defined in <PopUp>Type: colour_cmyk
typedef struct
{
  unsigned int key          : 8;
  unsigned int yellow       : 8;
  unsigned int magenta      : 8;
  unsigned int cyan         : 8;
} colour_cmyk;

defined in <PopUp>Type: popup_magnify
typedef struct
{
  int mul, div;
  int minmul, maxmul;
  int mindiv, maxdiv;
} popup_magnify;

defined in <PopUp>Type: popup_proginfo
typedef struct
{
  char appname[32];
  char purpose[32];
  char author[32];
  char version[32];
} popup_proginfo;

defined in <PopUp>Type: popup_saveas
typedef struct
{
  char iconsprite[12]; /* Save As file icon's Iconsprite name   */
  char filename[212];  /* Default text to put into writable icn */
} popup_saveas;

NOTE a different block is RETURNED: <popup_saveasreturn>

defined in <PopUp>Type: popup_saveasreturn
typedef struct
{
  struct
  {                                /* If TRUE:           | If FALSE:         */
    unsigned int wasdragged : 1;   /* File was dragged   | OK was 'pressed'  */
    unsigned int shiftdown  : 1;   /* SHIFT key was down | SHIFT key wasn't  */
    unsigned int reserved   : 30;
  } flags;

  int  reserved;
  char filename[212];              /* if (wasdragged) this is a leafname,
                                    * else            this is a full pathname
                                    */
} popup_saveasreturn;

defined in <PopUp>Note on PopUp.h
The PopUp system requires support of 2 Wimp message numbers. These
should be integrated into <Wimp>.h so that you can use:
  event->data.message.popupxxx. ...

However, to do this requires permanent wiring of the folowing typedefs
into Wimp.h, which is undesirable if you aren't using PopUps in every
.c file, as it will have a bad effect on compile time/memory use.

Thus, I recommend that you simply #include this file as needed, and
cast the generic message data type from Wimp.h into the specific type
of the message as necessary, e.g.

case message_POPUPSTATE:
{
  <message_popupstate> *state;
  state = (<message_popupstate> *) &event->data.message.data;
  switch (state->handle) ...Type: popup_handle
typedef int popup_handle;

defined in <PopUp>Type: message_popupstate
typedef struct
{
  <popup_handle>     handle;     /* PopUp handle                    */
  char             name[12];   /* PopUp type nam, e.g. "ProgInfo" */
  <popup_returndata> data;       /* Returned state data             */
} message_popupstate;

defined in <PopUp>Type: popup_returndata
typedef struct
{
  <popup_magnify>    magnify;
  <popup_report>     report;
  <popup_saveas>     saveasreturn;
  <popup_wimpcolour> wimpcolour;
  <popup_truecolour> truecolour;
} popup_returndata;

Data recieved in a <message_popupstate>

defined in <PopUp>To use the ProgInfo PopUp
 1. Call <EventMsg_Claim>(message_POPUPREQUEST, event_ANY, <OpenPopup=>PopUp_OpenPopup>, NULL)
    at some point in your initialisation.


 2. You would normally open the info dbox on a submenu warning, so call:

    <EventMsg_Claim>(message_MENUWARNING, event_ANY, <InfoRequest=>PopUp_InfoRequest>, NULL);

    somewhere in your initialisation code.

One note. The 'OpenPopUp' function decribed above is needed
for use of ANY type of MENU PopUp, not just the ProgInfo one.PopUp example code
BOOL InfoRequest(<event_pollblock> *event, void *reference)
{
  <popup_data> info;

  <Msgs_Lookup>("app.name", info.proginfo.appname, 32);
  <Msgs_Lookup>("app.purpose", info.proginfo.purpose, 32);
  <Msgs_Lookup>("app.author", info.proginfo.author, 32);
  <Msgs_Lookup>("app.version", info.proginfo.version, 32);

  <PopUp_ShowMenuLeaf>("ProgInfo", &info, &event->data.message.data.menuwarn);
  return TRUE;
}

    If you have more than one submenu warning set, you will need to check
    the hit code returned, eg

    switch (event->data.message.data.menuwarn.selection[0])
    {
      case iconmenu_INFO:
        ...PopUp example code
BOOL OpenPopup(<event_pollblock> *event, void *reference)
{
  <message_popuprequest> *request = (<message_popuprequest> *)
                                  &event->data.message.data;

  <Wimp_CreateSubMenu>((<menu_block> *)request->window,
                     request->openpos.x, request->openpos.y);

  return TRUE;
}

This gets called when the PopUp server needs your application to open
the window for it.To use the SaveAs PopUp
 1. Call <EventMsg_Claim>(message_POPUPSTATE, event_ANY, <PopUpState=>PopUp_PopUpState>, NULL) at
    some point in your initialisation. <PopUpState=>PopUp_PopUpState> will be called when the
    drag of the icon from the SaveAs box has been finished. Your
    application must then start the normal data transfer protocol.


 2. When you want the SaveAs PopUp to appear, go:

    strcpy(saveas.saveas.iconsprite, "file_fff");
    strcpy(saveas.saveas.filename, "FileName");
    <PopUp_ShowStandalone>("SaveAs", &saveas);PopUp example code
BOOL PopUpState(<event_pollblock> *event, void *reference)
{
  /* do a GetPointerInfo and build a datasave block */
  <message_block> message;
  <mouse_block> ptrinfo;

  <Wimp_GetPointerInfo>(&ptrinfo);
  memcpy(&message, &event->data, sizeof(message_block));
  message.header.yourref = 0;
  message.header.action = message_DATASAVE;
  message.data.datasave.window = ptrinfo.window;
  message.data.datasave.icon = ptrinfo.icon;
  message.data.datasave.pos = ptrinfo.pos;
  message.data.datasave.estsize = -1;
  message.data.datasave.filetype = 0xFFF;
  <Wimp_SendMessage>(event_SEND, &message, ptrinfo.window, ptrinfo.icon);

  return TRUE;
}Type: popup_report
typedef struct
{
  struct
  {
    unsigned int cancel     : 1;    /* Has cancel button / cancel was chosen */
    unsigned int ok         : 1;    /* Has OK button     / OK was chosen     */
    unsigned int reserved   : 6;
    unsigned int userhandle : 24;   /* Put anything you find useful here     */
  } flags;
  char oktext[12];                  /* Text for OK button (if any)           */
  char canceltext[12];              /* Text for cancel button (if any)       */
  char appname[12];                 /* Application name for window titlebar  */
  char message[188];                /* Text message to report to the user    */
} popup_report;

defined in <PopUp>Type: popup_wimpcolour
typedef struct
{
  char colour;     /* Colour 0..15 */
} popup_wimpcolour;

defined in <PopUp>Type: message_popuprequest
typedef struct
{
  <window_handle> window;
  <wimp_point>    openpos;
} message_popuprequest;

Pass this data directly to
<Wimp_CreateSubMenu>. Do not pass GO

defined in <PopUp>Constants defined in PopUp
PopUp flag byte: Values of flag bits
Preferably, use the 'all inclusive' values below instead

#define popup_ISLEAF   (0x01)
#define popup_ISSTATIC (0x02)


All-inclusive PopUp flag byte values

#define popup_STANDALONE (0x00)
#define popup_MENULEAF   (0x01)
#define popup_STATIC     (0x02)


Colour model numbers. See below for examples of use

#define popuptc_RGB  0
#define popuptc_HSV  1
#define popuptc_CMYK 2


Values to OR in to flag value for no transparency, 1 transparency value
('none' option) and full transparency (256 transparency levels)

#define popuptc_TRANSPARENT0   0x00000
#define popuptc_TRANSPARENT1   0x10000
#define popuptc_TRANSPARENT256 0x20000

Examples:
'Draw' style colour:   colourmodel  = popuptc_RGB | popuptc_TRANSPARENT1;
Full transparency HSV: colour model = popuptc_HSV | popuptc_TRANSPARENT256;Font_SetThresholds
extern <os_error> *Font_SetThresholds(<font_thresholds> *t);

defined in <Font>Font_ReadThresholds
extern <os_error> *Font_ReadThresholds(<font_thresholds> *t);

defined in <Font>Font_SetPalette
extern <os_error> *Font_SetPalette(int back_log,  int fore_log,
                                 int offset,
                                 int back_phys, int fore_phys);

defined in <Font>Font_SetFontColours
extern <os_error> *Font_SetFontColours(<font_handle> font,
                                     int back_colour, int fore_colour,
                                     int offset);

defined in <Font>Font_ReadScaleFactor
extern <os_error> *Font_ReadScaleFactor(int *xscale, int *yscale);

defined in <Font>Font_StringBBox
extern <os_error> *Font_StringBBox(char *string, <font_info> *info);

defined in <Font>Font_CharBBox
extern <os_error> *Font_CharBBox(<font_handle> font, char c,
                               int flags, <font_info> *info);

defined in <Font>Font_StringWidth
extern <os_error> *Font_StringWidth(<font_string> *string);

defined in <Font>Font_FindCaretJ
extern <os_error> *Font_FindCaretJ(<font_string> *s, int xoffset, int yoffset);

defined in <Font>Font_FindCaret
extern <os_error> *Font_FindCaret(<font_string> *string);

defined in <Font>Font_Caret
extern <os_error> *Font_Caret(int colour, int height, int flags, int x, int y);

defined in <Font>Font_Paint
extern <os_error> *Font_Paint(char *s, int options, int x, int y);

defined in <Font>Font_FutureFont
extern <os_error> *Font_FutureFont(<font_state> *state);

defined in <Font>Font_CurrentFont
extern <os_error> *Font_CurrentFont(<font_state> *state);

defined in <Font>Font_SetFont
extern <os_error> *Font_SetFont(<font_handle> font);

defined in <Font>Font_LoseAllFonts
extern void Font_LoseAllFonts(<font_array> *fonts);

Given a font usage array, this function calls <Font_LoseFont> for all fonts
used, and sets the font usage array to zeros. See <font_array> for info on
how a font usage array is organised...

defined in <Font>Type: font_handle
typedef int font_handle;

defined in <Font>Type: font_info
typedef struct
{
    int minx, miny, maxx, maxy;
} font_info;

defined in <Font>Type: font_defn
typedef struct
{
  char name[128];   /* NOTE: <Font_ReadDefn> returns this string CR terminated */
  int xsize, ysize, xres, yres;
  int age, usage;
} font_defn;

defined in <Font>Type: font_string
typedef struct
{
  char *s;        /* string */
  int x;          /* in/out, in 1/72000s of an inch */
  int y;          /* in/out, in 1/72000s of an inch */
  int split;      /* in/out: space char, or -1      */
                  /*         on exit, = count of space or printable */
  int term;       /* in/out: index into s */
} font_string;

defined in <Font>Type: font_state
typedef struct
{
  <font_handle>  font;
  <font_colours> colour;
  int          offset;
} font_state;

defined in <Font>Type: font_colours
typedef struct
{
  int background, foreground;
} font_colours;

defined in <Font>Type: font_thresholds
typedef struct
{
  char offset;
  char thresholds[15];
} font_thresholds;

defined in <Font>Font_CacheAddr
extern <os_error> *Font_CacheAddr(int *version, int *cacheused, int *cachesize);

defined in <Font>Font_ListFonts
extern <os_error> *Font_ListFonts(char *name, int *count);

defined in <Font>Font_ReadDefn
extern <os_error> *Font_ReadDefn(<font_handle> font, <font_defn> *defn);

defined in <Font>Font_ReadInfo
extern <os_error> *Font_ReadInfo(<font_handle> font, <font_info> *info);

defined in <Font>Font_ConvertToOS
extern <os_error> *Font_ConvertToOS(int x, int y, int *xout, int *yout);

Also Known As: Font_ConverttoOS()
                           ~
defined in <Font>Font_ConvertToPoints
extern <os_error> *Font_ConvertToPoints(int x, int y, int *xout, int *yout);

Also Known As: Font_Converttopoints
                           ~ ~
defined in <Font>Font_FindFont
extern <os_error> *Font_FindFont(<font_handle> *font, char *name,
                               int xsize, int ysize, int xres, int yres);
defined in <Font>Font_LoseFont
extern <os_error> *Font_LoseFont(<font_handle> font);

defined in <Font>PDriver_InsertIllustration
os_error *PDriver_InsertIllustration(int illustration_handle, void *drawpath,
                                     <wimp_point> *bottom_left,
                                     <wimp_point> *bottom_right,
                                     <wimp_point> *top_left);

NOTE - the drawpath will be changed from a void * when drawfile support
is added to DeskLib.

defined in <PDriver>PDriver_SelectIllustration
<os_error> *PDriver_SelectIllustration(<print_job> new, char *title, <print_job> *old);

defined in <PDriver>Type: print_job
typedef int print_job;

actually a RISC OS file handle

defined in <PDriver>PDriver_CancelJobWithError
<os_error> *PDriver_CancelJobWithError(<print_job> job, <os_error> *error);

defined in <PDriver>PDriver_EnumerateJobs
<os_error> *PDriver_EnumerateJobs

defined in <PDriver>PDriver_ScreenDump
<os_error> *PDriver_ScreenDump(<print_job> job);

defined in <PDriver>PDriver_CancelJob
<os_error> *PDriver_CancelJob(<print_job> job);

defined in <PDriver>PDriver_GetRectangle
<os_error> *PDriver_GetRectangle(<wimp_rect> *rectangle_to_print,
                               int *finished, int *rectangle_id);
defined in <PDriver>PDriver_DrawPage
<os_error> *PDriver_DrawPage(int copies, <wimp_rect> *rectangle_to_print,
                           int sequence_no, char *page,
                           int *finished, int *rectangle_id);

defined in <PDriver>PDriver_GiveRectangle
<os_error> *PDriver_GiveRectangle(int rectangle_id, <wimp_rect> *rectangle,
                                <print_transformation> *matrix,
                                <wimp_point> *position, int background_colour);
defined in <PDriver>Type: print_transformation
typedef struct
{
  int xx;
  int xy;
  int yx;
  int yy;
} print_transformation;

See Page 1554 of the RISC OS 2 PRMs

defined in <PDriver>PDriver_AbortJob
<os_error> *PDriver_AbortJob(<print_job> job);

defined in <PDriver>PDriver_EndJob
<os_error> *PDriver_EndJob(<print_job> job);

defined in <PDriver>PDriver_CurrentJob
<os_error> *PDriver_CurrentJob(<print_job> *current);

defined in <PDriver>PDriver_SelectJob
<os_error> *PDriver_SelectJob(<print_job> new, char *title, <print_job> *old);

defined in <PDriver>PDriver_PageSize
<os_error> *PDriver_PageSize(<wimp_point> *size, <wimp_rect> *printable);

defined in <PDriver>PDriver_CheckFeatures
<os_error> *PDriver_CheckFeatures(<print_features> mask, <print_features> value);

defined in <PDriver>Type: print_features
The 'features' word represented as a structure:

typedef union
{
  int <value=>print_featuresdef>;
  struct
  {
    unsigned int colour        : 1;
    unsigned int limited       : 1;
    unsigned int discrete      : 1;
    unsigned int filler1       : 5;   /* reserved */
    unsigned int nofill        : 1;
    unsigned int nothickness   : 1;
    unsigned int nooverwrite   : 1;
    unsigned int filler2       : 5;   /* reserved */
    unsigned int filler3       : 8;   /* reserved */
    unsigned int screendump    : 1;
    unsigned int transforms    : 1;
    unsigned int illustrations : 1;
    unsigned int filler4       : 5;   /* reserved */
  } data;
} print_features;

defined in <PDriver>Constants for the print_feature word:
These #defines represent the bits of the 'features' word:

#define printfeat_COLOUR         0x00000001
#define printfeat_LIMITED        0x00000002
#define printfeat_DISCRETE       0x00000004
#define printfeat_NOFILL         0x00000100
#define printfeat_NOTHICKNESS    0x00000200
#define printfeat_NOOVERWRITE    0x00000400
#define printfeat_SCREENDUMP     0x01000000
#define printfeat_TRANSFORMS     0x02000000
#define printfeat_ILLUSTRATIONS  0x04000000PDriver_Info
os_error *PDriver_Info(<printer_info> *block);

Reads information on the printer driver.

defined in <PDriver>Type: printer_info
typedef struct
{
  unsigned int     version    : 16;
  int              <drivertype=>printer_drivertype> : 16;
  <wimp_point>       resolution;
  <print_features>   features;
  char             *description;
  <wimp_point>       halftone_res;
  int              id_number;
} printer_info;

info returned by <PDriver_Info> (RO2 PRM's pg 1539)

defined in <PDriver>Values for the drivertype field of printer_info:
#define printdriver_POSTSCRIPT  0
#define printdriver_FX80        1
#define printdriver_LASERJET    2
#define printdriver_INTEGREX    3PDriver_PrinterName (pseudo-SWI veneer)
extern char *PDriver_PrinterName(void);

This function calls <PDriver_Info>, and returns the Printer name returned
by that SWI. If no Printer Driver is installed, it returns NULL.

NOTE that the returned string should be treated as READ ONLY, as it
is a pointer into the PDriver's RMA workspace!

defined in <PDriver>