Documentation from icons.h


Introduction	[top]

ROV - Easy applications from C

Copyright - © Jason Tribbeck / 7th ARM 1994-2001

Contributing authors - Jason Tribbeck

File - icons.h

Type - core

Description

The icon core system deals with all aspects of icons. It co-exists with the canvas core system in that it extends handlers for canvas events that pertain to icons.

Note - ROV icons claim memory for storing pointers to their handlers, unless they are created as unhandled (called 'forgetful') icons. These forgetful icons cannot have handlers attached to them, and are purely decorative.


icon_data (type definition)	[top]

Definition of an icon
Fields:
- char[12] text - the text in the icon, or the name of the sprite.
- char* indirecttext.text - the pointer to the indirected text.
- char* indirecttext.valid - the pointer to the icon's validation text.
- int indirecttext.length - the length of the pointed to text.
typedef union {
  char text[12];
  struct {
    char *text;
    char *valid;
    int length;
  } indirecttext;
} icon_data;


icon_init	[top]

Initialise the icon core system
void icon_init(void);


icon_createtext	[top]

Create a standard height text icon.
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *text - the pointer to the text icon.
Returns:
- the created icon.
Note - This creates an icon of 52 OS units high.
icon icon_createtext(canvas c,
		     int x,
		     int y,
		     char *text);
See also: icon_createoldtext(), icon_createrjtext()


icon_createoldtext	[top]

Create a smaller height text icon.
Parameters:
- canvas c - the canvas
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *text - the pointer to the text icon.
Returns:
- the created icon.
Note - This creates an icon of 44 OS units high.
icon icon_createoldtext(canvas c,
			int x,
			int y,
			char *text);
See also: icon_create(), icon_createtext()


icon_createrjtext	[top]

Create a right-aligned standard height text icon.
Parameters:
- canvas c - the canvas.
- int x - the (canvas) right hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *text - the pointer to the text.
Returns:
- the created icon.
Note - This creates an icon of 52 OS units high.
icon icon_createrjtext(canvas c,
		       int x,
		       int y,
		       char *text);
See also: icon_create()


icon_createsprite	[top]

Create a sprite icon.
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- void *spr_area - the sprite area (1 for the WIMP's area)
- char *spr_name - the name of the sprite.
Returns:
- the created icon.
Note - The size of the icon is taken from the sprite itself. If the size cannot be worked out (sprite non-existant, or mode invalid), then undefined results occur.
icon icon_createsprite(canvas c,
		       int x,
		       int y,
		       void *spr_area,
		       char *spr_name);
See also: icon_create()


icon_create	[top]

Create an icon
Parameters:
- canvas c - the canvas.
- int x0 - the (canvas) left hand coordinate.
- int y0 - the (canvas) bottom coordinate.
- int x1 - the (canvas) right hand coordinate.
- int y1 - the (canvas) top coordinate.
- int flags - the icon flags.
- icon_data *data - the icon data.
Returns:
- the created icon.
icon icon_create(canvas c,
		 int x0,
		 int y0,
		 int x1,
		 int y1,
		 int flags,
		 icon_data *data);
See also: Icon flags, icon_createforgetful(), icon_data


icon_createradio	[top]

Create a radio icon.
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *text - the text to follow after the radio icon.
Returns:
- the created icon.
Note - This creates an icon of 52 OS units high.
Note - Neither the button flags nor the ESG is set for this button to work as expected.
icon icon_createradio(canvas c,
		      int x,
		      int y,
		      char *text);
See also: icon_create(), icon_setbuttontype(), icon_setgroup()


icon_createoption	[top]

Create an option button.
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *text - the text to follow after the option icon.
Returns:
- the created icon.
Note - This creates an icon of 52 OS units high.
Note - Neither the button flags nor the ESG is set for this button to work as expected.
icon icon_createoption(canvas c,
		       int x,
		       int y,
		       char *text);
See also: icon_create(), icon_setbuttontype(), icon_setgroup()


icon_createinfofield	[top]

Create an information field (slabbed in).
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *text - the text in the information field.
Returns:
- the created icon.
Note - This creates an icon of 52 OS units high, and uses the text pointed to in order to get the width (using main_strwidth() from main.h, and adding 24 to it).
Note - If 2D has been configured, then the icon becomes a 2D white background with black border icon.
icon icon_createinfofield(canvas c,
			  int x,
			  int y,
			  char *text);
See also: icon_create(), icon_createfixedinfofield(), main.h


icon_createfixedinfofield	[top]

Create a fixed width information field (slabbed in).
Parameters:
- canvas c - the canvas
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *text - the text in the information field.
- int width - the width of the icon.
Returns:
- the created icon.
Note - This creates an icon of 52 OS units high.
Note - If 2D has been configured, then the icon becomes a white background with a black border.
icon icon_createfixedinfofield(canvas c,
			       int x,
			       int y,
			       char *text,
			       int width);
See also: icon_create()


icon_createdefaultbutton	[top]

Create a button that is normally the default button (validation string "r5,3").
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand inside coordinate.
- int y - the (canvas) bottom inside coordinate.
- char *text - the text in the button.
- int width - the width of the inside of the button.
Returns:
- the created icon.
Note - If 3D has been configured, the actual size of the button is larger than the given sizes.
Note - If 2D is set, then the icon becomes a beige background with a black border.
icon icon_createdefaultbutton(canvas c,
			      int x,
			      int y,
			      char *text,
			      int width);
See also: icon_create(), icon_createbutton()


icon_createbutton	[top]

Create a button.
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *text - the text in the button.
- int width - the width of the button.
Returns:
- the created icon.
Note - If 2D is set, then the icon becomes a white background with a black border.
icon icon_createbutton(canvas c,
		       int x,
		       int y,
		       char *text,
		       int width);
See also: icon_create(), icon_createbutton()


icon_createmenubutton	[top]

Create a menu button.
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
Returns:
- the created icon.
Note - If 2D is set, then the icon becomes a text icon with a mid-grey background and a black border. 2D is a 44x44 OS unit sized icon, moved up by 4 OS units (to vertically align it with any information field next to it).
Note - if 3D is set, then the icon becomes a sprite icon called "gright" (with a depressed version called "pgright"). 3D is a 52x52 OS unit sized icon.
icon icon_createmenubutton(canvas c,
			   int x,
			   int y);
See also: icon_create()


icon_createwriteable	[top]

Create a writeable icon.
Parameters:
- canvas c - the canvas.
- int x - the (canvas) left hand coordinate.
- int y - the (canvas) bottom coordinate.
- char *str - the pointer to the text in the icon.
- char *valid - the pointer to the validation string.
- int len - the maximum length of the text in the icon.
- int width - the width of the writeable icon.
Returns:
- the created icon.
Note - There is no difference between the 2D and the 3D versions.
icon icon_createwriteable(canvas c,
			  int x,
			  int y,
			  char *str,
			  char *valid,
			  int len,
			  int width);
See also: icon_create()


icon_createbox	[top]

Create a 'group box' icon.
Parameters:
- canvas c - the canvas.
- int x0 - the (canvas) left hand coordinate.
- int y0 - the (canvas) bottom coordinate.
- int x1 - the (canvas) right hand coordinate.
- int y1 - the (canvas) top coordinate.
- char *name - the group name (at the top left of the box).
Note - This creates two forgetful icons.
void icon_createbox(canvas c,
		    int x0,
		    int y0,
		    int x1,
		    int y1,
		    char *name);
See also: icon_create(), icon_createforgetful()


icon_remove	[top]

Remove an icon from the screen.
Parameters:
- icon ic - the icon to remove.
Note - Do not call this for removing forgetful icons.
void icon_remove(icon ic);
See also: icon_removeforgetful()


icon_handle	[top]

Get the WIMP icon handle.
Parameters:
- icon ic - the icon.
Returns:
- the WIMP icon handle.
int icon_handle(icon ic);


icon_find	[top]

Find an icon
Parameters:
- canvas c - the canvas to search in.
- int i - the WIMP icon handle to search for.
Returns:
- the icon, or NULL if not found.
icon icon_find(canvas c,
	       int i);


icon_canvas	[top]

Get the canvas.
Parameters:
- icon ic - the icon.
Returns:
- the canvas in which the icon presides.
canvas icon_canvas(icon ic);


icon_useexisting	[top]

Create an icon from an existing WIMP icon.
Parameters:
- canvas c - the canvas
- int i - the WIMP icon handle.
Returns:
- the generated icon.
icon icon_useexisting(canvas c,
		      int i);


icon_addhandler	[top]

Add a handler to an icon.
Parameters:
- icon ic - the icon.
- int event - the icon event.
- ... - the pointer to the event handler.
void icon_addhandler(icon ic,
		     int event,
		     ...);
See also: icon_carethandler(), icon_clickhandler(), icon_helphandler(), icon_keyhandler(), icon_menuhandler()


icon_setfore	[top]

Set the foreground colour of the icon.
Parameters:
- icon ic - the icon.
- int col - the WIMP colour.
void icon_setfore(icon ic,
		  int col);


icon_setback	[top]

Set the background colour of an icon.
Parameters:
- icon ic - the icon.
- int col - the WIMP colour.
void icon_setback(icon ic,
		  int col);


icon_setfont	[top]

Set the font handle for an icon.
Parameters:
- icon ic - the icon.
- int handle - the font handle.
void icon_setfont(icon ic,
		  int handle);
See also: font.h


icon_update	[top]

Redraw an icon.
Parameters:
- icon ic - the icon.
Note - This calls Wimp_SetIconState with no effects.
void icon_update(icon ic);


icon_fill	[top]

Set/reset the filled icon flag.
Parameters:
- icon ic - the icon.
- int filled - non-zero for filled, zero for unfilled.
void icon_fill(icon ic,
	       int filled);


icon_border	[top]

Set/reset the border icon flag.
Parameters:
- icon ic - the icon.
- int border - non-zero for having a border, zero for unbordered.
void icon_border(icon ic,
		 int border);


icon_select	[top]

Select/deselect an icon.
Parameters:
- icon ic - the icon.
- int selected - non-zero for selected, zero for selected.
void icon_select(icon ic,
		 int selected);


icon_fade	[top]

Fade/unfade an icon.
Parameters:
- icon ic - the icon.
- int faded - non-zero for faded, zero for faded.
void icon_fade(icon ic,
	       int faded);


icon_selected	[top]

Find out if an icon is selected.
Parameters:
- icon ic - the icon.
Returns:
- non-zero for selected.
int icon_selected(icon ic);


icon_faded	[top]

Find out if an icon is faded.
Parameters:
- icon ic - the icon.
Returns:
- non-zero for faded.
int icon_faded(icon ic);


icon_setbuttontype	[top]

Set the button type of an icon.
Parameters:
- icon ic - the icon.
- int type - the button type.
void icon_setbuttontype(icon ic,
			int type);
See also: Icon button types.


icon_setgroup	[top]

Set the ESG of an icon.
Parameters:
- icon ic - the icon.
- int group - the group number (0-31).
void icon_setgroup(icon ic,
		   int group);


icon_setjustification	[top]

Set the horizontal justification of an icon.
Parameters:
- icon ic - the icon.
- int justify - the justification.
void icon_setjustification(icon ic,
			   int justify);
See also: Icon justification.


icon_createforgetful	[top]

Create a 'forgetful' icon.
Parameters:
- canvas c - the canvas.
- int x0 - the (canvas) left hand coordinate.
- int y0 - the (canvas) bottom coordinate.
- int x1 - the (canvas) right hand coordinate.
- int y1 - the (canvas) top coordinate.
- int flags - the icon flags.
- icon_data *data - the icon data.
Returns:
- the WIMP icon handle.
int icon_createforgetful(canvas c,
			 int x0,
			 int y0,
			 int x1,
			 int y1,
			 int flags,
			 icon_data *data);
See also: Icon flags, icon_create(), icon_data


icon_removeforgetful	[top]

Remove a 'forgetful' icon.
Parameters:
- canvas c - the canvas.
- int i - the WIMP icon handle.
int icon_removeforgetful(canvas c,
			 int i);


icon_textpointer	[top]

Get the address of the text data in an icon.
Parameters:
- icon ic - the icon.
Returns:
- the text pointer.
char *icon_textpointer(icon ic);


icon_validpointer	[top]

Get the address of the validation string in an icon.
Parameters:
- icon ic - the icon.
Returns:
- the validation pointer.
char *icon_validpointer(icon ic);


icon_setcaret	[top]

Set the caret position in an icon.
Parameters:
- icon ic - the icon.
- int x - the x coordinate.
- int y - the y coordinate.
- int index - the index in the string.
void icon_setcaret(icon ic,
		   int x,
		   int y,
		   int index);


radio_valid (external variable)	[top]

Validation string for the radio icon - 'Sradiooff,radioon'.
extern char radio_valid[];


option_valid (external variable)	[top]

Validation string for the option icon - 'Soptoff,opton'.
extern char option_valid[];


ICON_NULL (definition)	[top]

The null icon.
#define ICON_NULL	((icon)0)


Icon button types	[top]

#define ICON_BNONE		(0)
#define ICON_BALWAYS		(1)
#define ICON_BREPEAT		(2)
#define ICON_BCLICK		(3)
#define ICON_BRELEASE		(4)
#define ICON_BDOUBLE		(5)
#define ICON_BCLICKDRAG		(6)
#define ICON_BDOUBLEDRAG	(7)
#define ICON_BRELEASEDRAG	(8)
#define ICON_BMENUTYPE		(9)
#define ICON_BCLICKDOUBLEDRAG	(10)
#define ICON_BSELECTDRAG	(11)
#define ICON_BWRITEDRAG		(14)
#define ICON_BWRITEABLE		(15)


Icon flags	[top]

#define ICON_TEXT               (1<<0)
#define ICON_SPRITE		(1<<1)
#define ICON_BORDER		(1<<2)
#define ICON_HCENTRED		(1<<3)
#define ICON_VCENTRED		(1<<4)
#define ICON_FILLED		(1<<5)
#define ICON_ANTIALIASED	(1<<6)
#define ICON_NEEDSREDRAWHELP	(1<<7)
#define ICON_INDIRECTED		(1<<8)
#define ICON_RIGHTJUSTIFIED	(1<<9)
#define ICON_BUTTONSHIFT	(12)
#define ICON_BUTTONFLAGS	(15<<12)
#define ICON_ESGSHIFT		(16)
#define ICON_ESGFLAGS		(31<<16)
#define ICON_SELECTED		(1<<21)
#define ICON_FADED		(1<<22)
#define ICON_DELETED		(1<<23)
#define ICON_FORECOLOURSHIFT	(24)
#define ICON_FORECOLOUR		(15<<24)
#define ICON_BACKCOLOURSHIF	(28)
#define ICON_BACKCOLOUR		(15<<28)


Icon event codes	[top]

#define ICON_CLICKHANDLER	(0)
#define ICON_MENUHANDLER	(1)
#define ICON_KEYHANDLER		(2)
#define ICON_CARETHANDLER	(3)
#define ICON_HELPHANDLER	(4)


Icon justification	[top]

#define ICON_TSL_TBST           (0x000000000)
#define ICON_TSR_TBST		(0x100000000)
#define ICON_SLT12R_TSC		(0x000001000)
#define ICON_TLSR_TSC		(0x100001000)
#define ICON_TSC_TBST		(0x000000100)
#define ICON_TSC_TTSB		(0x000001100)
#define ICON_TSC_TSC		(0x100000100)
#define ICON_TRSL_TSC		(0x100001100)


icon_clickhandler (function pointer)	[top]

Icon click handler function prototype.
Parameters:
- canvas c - the canvas.
- icon ic - the icon.
- canvas_mousestr *mouse_str - the mouse event block.
typedef void (*icon_clickhandler)(canvas c,
				  icon ic,
				  canvas_mousestr *mouse_str);


icon_menuhandler (function pointer)	[top]

Icon menu handler function prototype.
Parameters:
- canvas c - the canvas.
- icon ic - the icon.
- canvas_mousestr *mouse_str - the mouse event block.
typedef void (*icon_menuhandler)(canvas c,
				 icon ic,
				 canvas_mousestr *mouse_str);


icon_keyhandler (function pointer)	[top]

Icon key handler function prototype.
Parameters:
- canvas c - the canvas.
- icon ic - the icon.
- canvas_keystr *key_str - the key event block.
typedef void (*icon_keyhandler)(canvas c,
				icon ic,
				canvas_keystr *key_str);


icon_carethandler (function pointer)	[top]

Icon caret handler function prototype.
Parameters:
- canvas c - the canvas.
- icon ic - the icon.
- canvas_caretstr *caret_str - the caret event block.
typedef void (*icon_carethandler)(canvas c,
				  icon ic,
				  canvas_caretstr *caret_str);


icon_helphandler (function pointer)	[top]

Icon help handler function prototype.
Parameters:
- canvas c - the canvas.
- icon ic - the icon.
typedef void (*icon_helphandler)(canvas c,
				 icon ic);

Generated Thu Feb 7 23:22:51 2002

Documentation from icons.h

Introduction

ROV - Easy applications from C

Description

icon_data (type definition)

icon_init

icon_createtext

icon_createoldtext

icon_createrjtext

icon_createsprite

icon_create

icon_createradio

icon_createoption

icon_createinfofield

icon_createfixedinfofield

icon_createdefaultbutton

icon_createbutton

icon_createmenubutton

icon_createwriteable

icon_createbox

icon_remove

icon_handle

icon_find

icon_canvas

icon_useexisting

icon_addhandler

icon_setfore

icon_setback

icon_setfont

icon_update

icon_fill

icon_border

icon_select

icon_fade

icon_selected

icon_faded

icon_setbuttontype

icon_setgroup

icon_setjustification

icon_createforgetful

icon_removeforgetful

icon_textpointer

icon_validpointer

icon_setcaret

radio_valid (external variable)

option_valid (external variable)

ICON_NULL (definition)

Icon button types

Icon flags

Icon event codes

Icon justification

icon_clickhandler (function pointer)

icon_menuhandler (function pointer)

icon_keyhandler (function pointer)

icon_carethandler (function pointer)

icon_helphandler (function pointer)