This header defines some relatively high-level routines for handling icons.
For slider functionality, see the Slider module.
This creates a sprite-only iconbar icon with the normal default flags for such an icon. If you want something more complicated you should create it yourself.
If you want to attach handlers or otherwise make use of the icon, you should store the returned icon handle for use with Event_Claim or similar. The returned icon handle is 0 if there is an error.
You pass the name of a sprite in the Wimp sprite pool and 'pos' which should be iconbar_LEFT or iconbar_RIGHT. The icon will be created the correct size for the named sprite.
This creates a indirected sprite-only iconbar icon from a sprite in a user sprite area.
If you want to attach handlers or otherwise make use of the icon, you should store the returned icon handle for use with Event_Claim or similar.
You pass the name of a sprite, a pointer to the sprite area in which it is stored and 'pos' which should be iconbar_LEFT or iconbar_RIGHT. The icon will be created the correct size for the named sprite.
This returns TRUE if the given icon is selected, and FALSE otherwise.
This returns TRUE if the given icon is currently shaded (greyed out).
This sets whether or not the given icon is selected. If flag is 0 it means will be deselected, 1 means it will be selected.
This sets whether or not the given icon has its "deleted" flag set. If the value of flag passed to the function is 0, the "deleted" icon flag will be unset. If 1 is passed, the icon "deleted" flag will be set.
If the given icon is currently deselected, it is selected.
If the given icon is currently selected, it is deselected.
This sets whether or not the given icon is shaded. If flag is 0 it means will be unshaded, 1 means it will be shaded.
If the icon is currently unshaded (active) it is shaded (made inactive) This includes removing the caret from the icon.
If the icon is currently shaded (inactive) it is unshaded (made active).
This sets an icon's foreground colour to the given Wimp colour (0-15). This shouldn't be used on icons with the "outline font" flag set.
This sets an icon's background colour to the given Wimp colour (0-15). This shouldn't be used on icons with the "outline font" flag set.
This forces a redraw of a small area of the window around and including the given icon.
You will probably have no use for this now that 3D borders are supplied by the Wimp rather than external modules.
The places the caret in the given icon, and the righthand side of any text in the icon. If it isn't a text icon, nothing will happen.
This ensures that the caret will not be in the given icon when it returns. If the caret is not in the icon it does nothing.
This sets the text in the given icon to the decimal representation of 'value', and redraw the icon. If the number has too many digits it will be truncated to fit. If it cannot set the text it fails quietly.
This sets the text in the given icon to the decimal representation of 'value' and redraws the icon. Onlt the first 'decimalplaces' digits after the decimal point are printed. If the number has too many digits it will be truncated to fit. If it cannot set the text is fails quietly.
This copies 'text' into the icon's indirected text buffer and redraws the icon. If the text won't fit in the buffer, it is truncated. If 'text' is NULL, it places " " in the icon. If it cannot set the text it fails quietly.
This copies 'text' into the icon's indirected text buffer and redraws the icon. This text is "right-justified", so if the text won't fit in the buffer, it is truncated at the *left* hand side preceded by an ellipsis character ('...').
If 'text' is NULL, it sets the icon text to '\0'. If it cannot set the text it fails quietly.
This "prints" text to the given icon under the control of the printf-style format string 'format'. This will have no effect on any icon that isn't indirected.
Note that while text that is too long for the indirected text buffer will be truncated, if the resulting string before truncation is longer than 512 characters nastiness will occur (ie. your program will crash).
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.
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
Copies the text string from the icon (sprite name, text, or indirected) into the string pointed to by 'text'.
Note that 'text' must be big enough to hold the icon buffer, so the minimum sizes are 12 characters for a non-indirected icon and the size of the icon's buffer for an indirected icon.
This returns a pointer to the actual indirected text buffer for the given icon. If the icon is not indirected it returns NULL.
This takes a window and a -1 terminated list of icon handles which specifies the icons to set the state of. If 'shade' is TRUE the icons will all be shaded (greyed out), if it is FALSE they will be unshaded.
This takes a window and a -1 terminated list of icon handles which specifies the icons to set the state of. If 'select' is TRUE the icons will all be selected, if it is FALSE they will be deselected.
This takes an icon_block as returned by Wimp_GetIconState, and returns the foreground colour. This copes with anti-aliased icons as well as "normal" ones.
This takes an icon_block as returned by Wimp_GetIconState, and returns the background colour. This copes with anti-aliased icons as well as "normal" ones.
This sets one icon in a group, and unsets all the others. The group is from the lowest-numbered icon ('first') to highest-numbered icon ('last') inclusive.
This finds which icon in a group is selected. The group is from the lowest-numbered icon ('first') to highest-numbered icon ('last') inclusive. It returns the icon handle of the first selected icon in the group, or 'last' if none are selected.
This finds which icon in the given ESG is selected. This means the icons do not have to be consecutively numbered.
It returns the icon handle of the selected icon.
This 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.
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.
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.
This changes the given icon so that it contains the correct filetype sprite for the given filetype number (eg. file_ff9 for filetype 0xff9).
This requires that the icon is already an indirected icon with enough room in the buffer to hold the sprite name. This function converts it to an indirected sprite-only icon, fills in the sprite name and sets the sprite area to the Wimp pool. It doesn't check that the sprite actually exists.
It returns the new icon handle, in case it has changed when it was recreated.
This finds the screen coordinates of the given icon, and places them in 'rect'.
This sets up an IncDec icon set. This is a set of three icons: an indirected display icon 'texticon', and two icons to "bump up" and "bump down" the integer value in that icon. You also specify an upper and lower limit for the integer in 'min' and 'max' and can choose whether you want the values to loop around when you go past the limits (by setting loop to TRUE) or just stop. 'step' is used as the step for both incrementing and decrementing the value. 'start' is set as the initial value in the 'texticon'.
This uses Event_Claim to claim clicks on the increment and decrement icons (so you must have initialised and be using the Event system) and handles Select and Adjust clicks on those icons correctly.
It returns NULL if it couldn't claim the events, or else a pointer to the block of data about this icon set, which you will need to release the events with Icon_ReleaseIncDecHandler.
This releases the handlers set up by Icon_InitIncDecHandler and frees the memory used by the icon_incdecblock for this icon set. It returns TRUE if the handlers were released successfully, and FALSE otherwise.
This alters the validation string of the given icon to hold the text given in 'newvalidation', and redraws the icon. If the validation string is already set to the given value (or if the icon is not indirected), it does nothing (and returns 0).
** Note **
This function will cause a buffer overrun if you pass a string longer than the space allocated for the icon validation string, so needs to be used with care.
There is no way to determine the size of the available buffer but this function can help by returning some useful information.
If newvalidation is NULL, then the function will return the length of the existing validation string. If this is done after the icon is created and before any changes to the validation string, this will be the minimum size of the buffer.
If newvalidation is non-NULL then the function will return the difference (in bytes) between the length of the existing validation string and the length of newvalidation. So if it returns a negative number, it has written beyond the end of the existing string.
This returns TRUE if any mouse button is held down.
This scans the given string for the tag character given, and returns the index of the *next* character, or zero if the tag character is not found. The tag must be either the first character or directly follow a semi-colon.
For instance, if you search for the tag 'r' in "sicon;r5", it will return the index of '5' (7, in this example).
#define Icon_ForceRedraw(wind, icon) Wimp_SetIconState(wind, icon, 0, 0);
MACRO: os_error *Icon_ForceRedraw(window_handle wind, icon_handle icon);
This gets the Wimp to redraw the given icon. It returns NULL if there is no error.
#define Icon_SetFlags(window, icon, flags, set) \ Wimp_SetIconState((window), (icon), ((set) ? (flags) : 0), (flags))
MACRO: os_error *Icon_SetFlags(window_handle w, icon_handle i, int flags, BOOL set);
This is a neat interface to the Wimp_SetIconState SWI for the given icon. If 'set' is TRUE, all the flags given in 'flags' will be set to 1, otherwise they will be set to 0.
It returns NULL if there is no error.
#define Icon_SetFgCol(w, i, col) \ Wimp_SetIconState((w), (i), (col) * icon_FORECOLOUR, 0xF * icon_FORECOLOUR)
MACRO: os_error *Icon_SetFgCol(window_handle window, icon_handle icon, int col);
This is a macro to set the foreground colour of an icon. This shouldn't be used on icons with the "outline font" flag set.
#define Icon_SetBgCol(w, i, col) \ Wimp_SetIconState((w), (i), \ (unsigned) (col) * (unsigned) icon_BACKCOLOUR, \ (unsigned) 0xF * (unsigned) icon_BACKCOLOUR)
MACRO: os_error *Icon_SetBgCol(window_handle window, icon_handle icon, int col);
This is a macro to set the background colour of an icon. This shouldn't be used on icons with the "outline font" flag set.
#define Icon_StartSolidDrag(w, i) DragASprite_DragIcon(w, i)
MACRO: os_error *Icon_StartSolidDrag(window_handle w, icon_handle i);
Starts a drag operation based on the given icon, using DragASpr if available.
This type holds data for the IncDec handlers. Most of the fields are self-explanatory. If' loop' is TRUE then the value in 'texticon' will looop around at min and max limits rather than stopping. The step is the step to be used for both incrementing and decrementing the value.