This header provides function prototypes for a low-level interface to the Wimp SWIs.
This function registers a task with the Wimp, and must be called once and once only when the task starts up.
'version' points to the minimum Wimp version needed for this task (* 100), 'name' points to a short description of the task which appears in the task manager. 'mess' points to an array of message numbers the task wants to receive (zero-terminated). This only applies for RISC OS versions 300 and later.
The actual Wimp version is returned in 'version', and the task handle in 'task'.
This function must be called immediately before the program finishes. 'task' should be the handle of your task.
This function is used to start a task from within a program. The text in 'command' can be any * command which will case a Wimp program to be executed. Control will be returned to your program when the new task exits, or when it first calls Wimp_Poll.
This function is used to start a task from within a program. The text in 'command' can be any * command which will case a Wimp program to be executed. Control will be returned to your program when the new task exits, or when it first calls Wimp_Poll.
This returns the task handle of the started task if it is still alive, or zero if it isn't.
This function can be used to read or set the size of the current slot (ie. your program's slot size) and the next slot (the default slot size). To alter one of the values, invoke the function with the parameter set to the value you wish to set it to (you cannot alter the free space).
If you just want to read the current value, set the variables to -1 instead. On exit, the new values will be returned.
This function copies a block of memory from the 'sourcebuffer' in the source tasks's address space to the 'destbuffer' in the destination task's workspace. The amount of data to transfer (in bytes) is given in 'length'.
This reports an error using a standard Wimp non-multitasking error box. 'name' is the name of the task reporting the error, and should be less than twenty character. 'err' should contain the details of the error. 'flags' is passed in as an int, but can be cast from an error_flags.
You should avoid using this for errors other than very serious ones where you cannot do anything until you get user feedback. For other cases, use some sort of multi-tasking window so that all tasks do not stop functioning while you wait for a response.
This is identical to Wimp_ReportError, except it passes on the return code from the SWI so you can detect which button has been pressed (1 for OK, 2 for Cancel).
This function sends a message to a task or broadcasts one to all tasks. 'type' contains the event code for the message you want to send, 'msg' contains the message data and 'dest' contains the task handle or window handle of the destinee, or 0 to broadcast it. If 'destinee' is the icon bar (-2), then 'icon' contains the icon number.
This is almost always used to send user messages, for which it fills in the sender and the 'myref' fields on your behalf. It can, however, be used to send any Wimp event.
This function extends the set of user messages the task is sent by the Wimp. You pass a pointer to a zero-terminated array of user message codes, and the Wimp adds these to the messages given when you called Wimp_Initialise to allow you to receive these messages as well.
This funciton removes messages from the list of user messages the task is sent by the Wimp. You pass a pointer to a zero-terminated array of user message codes, and the Wimp removes these from the messages your task is currently set to receive.
This function opens the specified template file and reads in some header information about the file. Only one template file may be open at a time. You can then call Wimp_LoadTemplate to load each template and then Wimp_CloseTemplate to close the file.
This function closes the template file previously opened with Wimp_OpenTemplate.
This function loads a template. You must previously have called Wimp_OpenTemplate to open the template file from which you want to load the template.
This function tells the Wimp what the characteristics of a window are. The window definition is held in 'block' and the handle of the window is returned in 'window'.
This function updates the list of active windows (ones that should be displayed by the Wimp).
This function removes the specified window from the list of active window (ones that should be displayed by the Wimp).
This functions closes the specified window if it is open, and then removes the definition of the window from memory.
This function is used to start a redraw of the parts of a window that are not up to date. It should be called as the first Wimp operation after the Wimp Poll which returned the redraw window request.
Wimp_RedrawWindow draws the window outline and then exits via Wimp_GetRectangle, which returns the coordinates of the first invalid rectangle of the work area. It also returns a flag 'more' saying whether there is anything else to redraw.
This function is used to start a redraw of the parts of a window that are not up to date. On entry, 'block' contains the area of the window to be updated. The function exits via Wimp_GetRectangle which returns the coordinates of the first rectanlge of the work area. It also returns a flag 'more' saying whether there is anything else to redraw.
This function is used repeatedly following a call to Wimp_RedrawWindow or Wimp_UpdateWindow, until 'more' is returned as FALSE. You should redraw the rectangles of the window's work area that are returned in 'block'.
This function finds the state of the given window, and returns it in 'state'.
This returns information about the window specified by info->window. It returns a window_info block *and* the icon blocks for all the icons in the window. This means that it will write past the end of the window_info block. If you want to read the icons, allocate a block of memory you know to be big enough to hold them all and use this call. Otherwise, you are probably better off using Window_GetInfo, which returns just the "window" part of the information.
This returns information about the window specified by info->window. It returns only the window_info block, not the data about the icons in the window.
This function returns the given window's bounding box - the box which completely covers the window including all scrollbars, title bar, etc.
This function sets the work area extent of the specified window to be the box specified in 'newextent'.
This function marks an area of screen to be redrawn. block->window should contain the window handle and block->rect then contains the area of the work area to redraw. If block->window is -1, then block->rect contains a screen area to redraw rather than a window work area.
This is a version of Wimp_OpenWindow for the nested Wimp, which allows access to the new features.
This forces the redraw of the titlebar of the given window.
This is only available under the Nested Wimp.
This function allows you to enumerate the windows in the window stack. You pass in a window handle (or -1 for the top level), and the type of information you want to find out, as defined by 'item'. You can use this to find the window handle of the parent window, the top child window, the botom child window, the sibling immediately below or the sibling immediately above.
The window handle you asked for is returned in 'window'. If there is no matching window, -1 is returned in 'window.
This is only available under the Nested Wimp.
This function tells the Wimp to create an icon, whose characteristics are given in 'block'. The handle of the created icon is returned in 'icon'.
This function removes the definition of the specified icon from the gven window. If it is not the last icon in the window, is is just marked as deleted. If it is the last icon, the space occupied by it is freed. This call does not update the screen unles you are deleting an icon bar icon. You should call Wimp_ForceRedraw to redraw the area yourself.
This function sets the state of the given icon. The value of a bit in the new flags is given as follows: if value and mask are both zero, the bit is left unchanged; if the mask is zero and the value one, the bit is toggled; if the mask is one and the value is the zero, the bit is cleared; and if the mask is one and the value is one the bit is set.
ie. the new flags are given by (old flags AND NOT mask) EOR value
This function returns the specified icon's definition in the block pointed to by 'iconinfo'.
This function searches for icons that match a given flag word. All icons in the given window will be checked, and the list placed in the array pointed to by 'icons'. 'mask' determines which bits are to be checked, 'settings' says what should be looked for.
It checks if: iconflags & mask == settings & mask.
This function can be used to plot an icon in a window during a window redraw or update loop. The icon doesn't exist as part of the window definition - you give the definition directly to this function to plot it. If you call this outside a redraw loop the coordinates are screen coordinates rather than work area coordinates.
This function polls the Wimp to see whether certain events have occurred. You call it in the main loop of a program you wish to run under the Wimp. This lets the Wimp pass control to other taks, and it returns when there is some event for you to process.
You pass a pollmask in 'mask' which determines which events you want to be notified about, and it returns the results of the poll in 'event'. If you want to be notified of a pollword non-zero event, you should set the appropriate flag in the event mask, and pass a pointer to the pollword in 'pollword'.
This function polls the Wimp to see whether certain events have occurred. You call it in the main loop of a program you wish to run under the Wimp. This lets the Wimp pass control to other tasks, and it returns when there is some event for you to process.
You pass a pollmask in 'mask' which determines which events you want to be notified about, and it returns the results of the poll in 'event'.If you want to be notified of a pollword non-zero event, you should set the appropriate flag in the event mask, and pass a pointer to the pollword in 'pollword'.
You pass the earliest monotonic time you want a null event to be returned in 'earliest'. You can use this when you want to do things in the background, to prevent your task from using more processor time than you need.
This function returns information about the position of the pointer and the instantaneous state of the mouse buttons, in the block pointed to by 'ptrinfo'.
This function sets the shape and active point of the pointer. This SWI is no longer the recommended way to do this - use Wimp_SpriteOp 36 instead.
This function initiates a Wimp drag operation. You pass in the drag type, the initial size of the box being dragged or the window to be affected, and where approriate a rectangle to specify a limit for the drag.
This function removes the caret from its old position and redraws it in a new position, as defined by 'caret'. If caret->window is -1, the caret is removed from its current location.
If caret->height is -1 then the offset and height are calculated from the given window, icon and index. If caret->index is -1 then the index and height are calculated from the given window, icon and offset.
THis function returns details of the caret's state in the block pointed to by 'caret'. If the caret is not currently in any window, caret->height is returned as -1.
This function opens a Wimp menu from the details supplied in 'menu'. The menu is initially displayed with its top-left corner at the screen coordinated (xpos, ypos).
This function is called to open a submenu when you receive a MenuWarning message from the Wimp. The three arguments can be obtained from the message, or altered by you if required.
This converts the given list of menu selections for the given menu to a text string made up of the text in the selected menu items. eg. "Options.Confirm" for a filer menu.
Note that this is a CR-terminated string, and *not* a nul-terminated C string. You should also make sure that the buffer pointed to by 'result' is big enough to hold the resulting string.
This call causes the wimp to offer the given character to other applications. This can be used to pass on keypress events your program is not interested in, or to insert "new" keypresses into the wimp buffer.
You should not insert more that one or two characters at a time this way, or you will confuse the Wimp. Characters inserted this way take precendence over characters actually typed.
This function changes the Wimp mode to that given. You should generally avoid its use, and make your program work in any mode.
This function sets the current graphics colour to one of the sixteen standard Wimp colours, and the GCOL plot action. For ease of use, you should probably cast the argument from a wimp_colour.
This function reads the current Wimp palette settings into the block pointed to by 'palette'.
This function sets the Wimp palette to that given in 'palette'. In sixteen-colour modes the video palette is also reprogrammed, and in other modes the colou lookup table may change.
You should force a redraw of the screen after calling this function.
This function finds out how the Wimp would plot the given sprite. If areaindex is less than 256 the sprite is in a system area, if it is less that 512 it is in the given user area and 'ptsprite' points to the sprite name and if it is less than 768 then 'ptsprite' points directly to the sprite. 'area' points to the user sprite area, 1 for the Wimp area or zero for the system sprites area.
On exit, 'scaleblock' and 'transblock' will contain information on how the Wimp would display the sprite.
This function sets the anti-aliased font colours based on the foreground and background Wimp colours given. The colours will not be preserved across calls to Wimp_Poll.
This function allows operations on Wimp sprites without having to specify the sprite area pointer. r[0] contains the reason code, r[2] contains a pointer to the sprite nameand r[3] onwards contain the other parameters. Only read operations are allowed with this function.
This function returns the addresses of the ROM and RAM parts of the Wimp sprite pool. The RAM address moves around as its contents change. You should not normally need to know these locations.
This function copies as much as possible of the source rectangle to another position (x, y). Any part that cannot be copied will be invalidated by the Wimp, to be redrawn by you. This call cannot be made from inside a redraw or update loop.
This function opens a text window in which VDU 4-type output can be displayed. The exact action depends on the value of 'x'.
If x is greater than 1, it is a pointer to the window title - the window is only opened the next time a character is printed on screen. If x is 1, the window is set to "active". If x is zero then window is closed after giving a "Press SPACE or click mouse to continue". If x is -1 the window is closed without giving a prompt.
#define Wimp_Poll(mask, evt) Wimp_Poll3(mask, evt, 0)
Macro: os_error *Wimp_Poll(event_pollmask mask, event_pollblock *event);
This function polls the Wimp to see whether certain events have occurred. You call it in the main loop of any program you wish to run under the Wimp. This lets the Wimp pass control to other taks, and it returns when there is some event for you to process.
You pass a pollmask in 'mask' which determines which events you want to be notified about, and it returns the results of the poll in 'event'.
#define Wimp_PollIdle(mask, evt, time) Wimp_PollIdle3(mask, evt, time, 0)
Macro: os_error *Wimp_PollIdle(event_pollmask *mask, event_pollblock *event, int earliest);
This function polls the Wimp to see whether certain events have occurred. You call it in the main loop of a program you wish to run under the Wimp. This lets the Wimp pass control to other tasks, and it returns when there is some event for you to process.
You pass a pollmask in 'mask' which determines which events you want to be notified about, and it returns the results of the poll in 'event'.
You pass the earliest monotonic time you want a null event to be returned in 'earliest'. You can use this when you want to do things in the background, to prevent your task from using more processor time than you need.