DeskLib 2.90a:Icon.h


Contents


Introduction and Overview

This header defines some relatively high-level routines for handling icons.

For slider functionality, see the Slider module.


Functions


Icon_BarIcon

icon_handle Icon_BarIcon(const char *spritename, window_handle pos);

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.


Icon_BarIconUser

icon_handle Icon_BarIconUser(const char *spritename, window_handle pos, void *area);

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.


Icon_GetSelect

BOOL Icon_GetSelect(window_handle window, icon_handle icon);

This returns TRUE if the given icon is selected, and FALSE otherwise.


Icon_GetShade

BOOL Icon_GetShade(window_handle window, icon_handle icon);

This returns TRUE if the given icon is currently shaded (greyed out).


Icon_SetSelect

void Icon_SetSelect(window_handle window, icon_handle icon, int flag);

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.


Icon_SetDeleted

void Icon_SetDeleted(window_handle window, icon_handle icon, int flag);

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.


Icon_Select

void Icon_Select(window_handle window, icon_handle icon);

If the given icon is currently deselected, it is selected.


Icon_Deselect

void Icon_Deselect(window_handle window, icon_handle icon);

If the given icon is currently selected, it is deselected.


Icon_SetShade

void Icon_SetShade(window_handle window, icon_handle icon, int flag);

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.


Icon_Shade

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.


Icon_Unshade

void Icon_Unshade(window_handle window, icon_handle icon);

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


Icon_SetForeColour

void Icon_SetForeColour(window_handle window, icon_handle icon, int wimpcolour);

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.


Icon_SetBackColour

void Icon_SetBackColour(window_handle window, icon_handle icon, int wimpcolour);

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.


Icon_ForceWindowRedraw

void Icon_ForceWindowRedraw(window_handle window, icon_handle icon);

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.


Icon_SetCaret

void Icon_SetCaret(window_handle window, icon_handle icon);

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.


Icon_LoseCaret

void Icon_LoseCaret(window_handle window, icon_handle icon);

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.


Icon_SetInteger

void Icon_SetInteger(window_handle w, icon_handle i, int value);

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.


Icon_SetDouble

void Icon_SetDouble(window_handle w, icon_handle i, double value, int decimalplaces);

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.


Icon_SetText

void Icon_SetText(window_handle w, icon_handle i, const char *text);

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.


Icon_SetTextRJ

void Icon_SetTextRJ(window_handle w, icon_handle i, const char *text);

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.


Icon_Printf

void Icon_Printf(window_handle window, icon_handle icon, const char *format, ... );

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).


Icon_GetDouble

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.


Icon_GetInteger

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


Icon_GetText

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


Icon_GetTextPtr

char * Icon_GetTextPtr(window_handle w, icon_handle i);

This returns a pointer to the actual indirected text buffer for the given icon. If the icon is not indirected it returns NULL.


Icon_ShadeGroup

void Icon_ShadeGroup(window_handle window, icon_handle icons[], BOOL shade);

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.


Icon_SelectGroup

void Icon_SelectGroup(window_handle window, icon_handle icons[], BOOL select);

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.


Icon_GetFgCol

int Icon_GetFgCol(icon_block *icon);

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.


Icon_GetBgCol

int Icon_GetBgCol(icon_block *icon);

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.


Icon_SetRadios

void Icon_SetRadios(window_handle window, icon_handle first, icon_handle last, icon_handle onradio);

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.


Icon_WhichRadio

int Icon_WhichRadio(window_handle window, icon_handle first, icon_handle last);

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.


Icon_WhichRadioInEsg

int Icon_WhichRadioInEsg(window_handle wh, int esg);

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.


Icon_ClickWait

void Icon_ClickWait(int waittime);

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.


Icon_StartDrag

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.


Icon_DisposeIndData

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.


Icon_FileIcon

icon_handle Icon_FileIcon(window_handle window, icon_handle icon, int filetype);

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.


Icon_ScreenPos

void Icon_ScreenPos(window_handle window, icon_handle icon, wimp_rect *rect);

This finds the screen coordinates of the given icon, and places them in 'rect'.


Icon_InitIncDecHandler

icon_incdecblock * Icon_InitIncDecHandler(const window_handle window, const icon_handle texticon, const icon_handle incrementicon, const icon_handle decrementicon, const BOOL loop, const unsigned int step, const int min, const int max, const int start);

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.


Icon_ReleaseIncDecHandler

BOOL Icon_ReleaseIncDecHandler(icon_incdecblock *incdecblock);

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.


Icon_AlterValidation

int Icon_AlterValidation(window_handle window, icon_handle icon, const char *newvalidation);

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.


Icon_ButtonIsHeld

BOOL Icon_ButtonIsHeld(void );

This returns TRUE if any mouse button is held down.


Icon_ScanValidationString

int Icon_ScanValidationString(const char *string, char tag);

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).


Function-like macros


Icon_ForceRedraw

#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.


Icon_SetFlags

#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.


Icon_SetFgCol

#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.


Icon_SetBgCol

#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.


Icon_StartSolidDrag

#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.


Type


icon_incdecblock

typedef struct
{
window_handle window;
icon_handle texticon;
icon_handle incrementicon;
icon_handle decrementicon;
BOOL loop;
unsigned int step;
int min;
int max;

} icon_incdecblock;

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.