Documentation from extras.h

ROV

Introduction

[top]

ROV - Easy applications from C

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

Contributing authors - Jason Tribbeck

File - extras.h

Type - helper

Description

The extras are a collection of miscellaneous components that assist in a standard look-and-feel for applications.

infobox_3d

[top]

Makes infoboxes 3D. Note that this is deprecated, as the 3D logic is automatically called.

void infobox_3d(void);

create_infobox

[top]

Creates a standard infobox.

Parameters:

 - char *name - the name of the application.
 - char *purpose - the purpose of the application.
 - char *author - the author of the application.
 - char *version - the version of the application.

Returns:

 -  the generated canvas.

canvas create_infobox(char *name,
		      char *purpose,
		      char *author,
		      char *version);

See also: create_compileinfobox(), create_licenseinfobox()

create_licenseinfobox

[top]

Creates an info box with a license key.

Parameters:

 - char *name - the name of the application.
 - char *purpose - the purpose of the application.
 - char *author - the author of the application.
 - char *version - the version of the application.
 - char *license - the license key for the application.

Returns:

 -  the generated canvas.

canvas create_licenseinfobox(char *name,
			     char *purpose,
			     char *author,
			     char *version,
			     char *license);

See also: create_compileinfobox(), create_infobox()

create_compileinfobox

[top]

Creates an info box with a compile version.

Parameters:

 - char *name - the name of the application.
 - char *purpose - the purpose of the application.
 - char *author - the author of the application.
 - char *version - the version of the application.
 - char *compile - the compile version of the application.

Returns:

 -  the generated canvas.

canvas create_compileinfobox(char *name,
			     char *purpose,
			     char *author,
			     char *version,
			     char *compile);

See also: create_infobox(), create_licenseinfobox()

return_help

[top]

Responds to a HelpRequest message with a string.

Parameters:

 - char *response - the string to respond with.

void return_help(char *response);

werr

[top]

Display error message.

Parameters:

 - int fatal - a flag indicating whether this is fatal or not (non-zero is fatal).
 - char *pf_str - printf-style string.
 - ... - optional list of parameters.

Note - This uses an internal error generation reporting that is designed to be extendable in the same way that RISC OS 3.5+ error boxes are. As a result, it will look different on non 3.5+ machines. If this is undesireable, then call swerr() instead.

void werr(int fatal,
	  char *pf_str,
	  ...);

See also: message_box(), swerr()

swerr

[top]

Display error message.

Parameters:

 - int fatal - a flag indicating whether this is fatal or not (non-zero is fatal).
 - char *pf_str - printf-style string.
 - ... - optional list of parameters.

Note - This differs from werr() in that it uses the standard error reporting for the OS.

void swerr(int fatal,
	   char *pf_str,
	   ...);

See also: message_box(), werr()

message_box

[top]

Displays a message.

Parameters:

 - int flags - flags for the message box.
 - char *title - the title for the message box.
 - char *pf_str - printf-style string.
 - ... - optional list of parameters.

Returns:

 -  the button that was clicked to acknowledge the message box.

Note - This uses the standard error box reporting for the OS to display the message box.

int message_box(int flags,
		char *title,
		char *pf_str,
		...);

See also: Message box flags, swerr(), werr()

poll_init

[top]

Poll until first null event.

Note - This must be called before main_poll (see main.h for information).

void poll_init(void);

msg_menu

[top]

Create a menu from a messages file.

Parameters:

 - char *prefix - the prefix for the menu held in the messages file.
 - int items - the number of items in the messages file.
 - ... - two parameters, the first is the menu choose handler function, the second is the sub-menu creation handler function.

Returns:

 -  the generated menu.

Note - This function is prototyped in this way, as the handler functions can have shortcuts if they do not require the full information passed into them. See menu.h for more information.

Note - The messages file requires fields in a certain format. The format is the prefix followed by a two digit number. The code '00' is the title of the menu, and the code is incremented for each item in the list. This means that the code '01' is the first item, '02' is the second and so forth.

Note - msg_read() must have been called before calling this function.

menu msg_menu(char *prefix,
	      int items,
	      ...);

See also: menu.h, msg.h, msg_menu()

msg_menuwriteable

[top]

Create a menu from a messages file, with the last entry being writeable.

Parameters:

 - char *prefix - the prefix for the menu held in the messages file.
 - int items - the number of items in the messages file.
 - char *store - the pointer to the text string store.
 - char *valid - the validation string.
 - int length - the maximum length of the string.
 - ... - two parameters, the first is the menu choose handler function, the second is the sub-menu creation handler function.

Returns:

 -  the generated menu.

Note - This function is prototyped in this way, as the handler functions can have shortcuts if they do not require the full information passed into them. See menu.h for more information.

Note - The messages file requires fields in a certain format. The format is the prefix followed by a two digit number. The code '00' is the title of the menu, and the code is incremented for each item in the list. This means that the code '01' is the first item, '02' is the second and so forth.

Note - msg_read() must have been called before calling this function.

menu msg_menuwriteable(char *prefix,
		       int items,
		       char *store,
		       char *valid,
		       int length,
		       ...);

See also: menu.h, msg.h, msg_menu()

check_key

[top]

Check for a keyboard press

Parameters:

 - int key - the key to check.

Returns:

 -  non-zero indicating that the key is pressed.

Note - The key is not the ASCII code, but the INKEY code.

int check_key(int key);

Message box flags

[top]
#define MB_OK		(1)
#define MB_CANCEL	(2)
#define MB_HILITECANCEL	(4)

Generated Thu Feb 7 23:22:51 2002