The "panel" Package

These routines are meant to provide high level definition and processing of command lines.

Library: karma
Link With: -lkarma

Functions

panel_create	Create a control panel object.
panel_create_group	Create a panel to contain a group.
panel_add_item	Add an item to a panel.
panel_push_onto_stack	Push a control panel object onto the control panel stack.
panel_pop_from_stack	Pop last pushed control panel object from control panel stack.
panel_process_command_with_stack	Process a command.
panel_put_history_with_stack	Put history into Karma multi_array structure.
panel_set_extra_comment_string	Set the extra comment string for a panel.

Prototype Functions

panel_PROTO_decode_func

Command line decode callback.

Tables

panel_ATTRIBUTES	List of attributes for panel item objects
panel_ITEM_TYPES	List of Karma data types

Functions

KControlPanel panel_create (flag blank)

Create a control panel object.

Parameters:

blank : If TRUE, then the routine will create a blank form, else it will add some internally defined panel items.

Returns: A KControlPanel object on success, else NULL.
Multithreading Level: Unsafe

KControlPanel panel_create_group ()

This routine will create a control panel object which is a container for a group of items. Panel items may be added to this panel object, and the panel object itself may be later added as panel item to another panel object (of type PIT_GROUP).

Parameters:

Returns: A KControlPanel object on success, else NULL.
Multithreading Level: Unsafe

void panel_add_item (KControlPanel panel, char *name, char *comment, unsigned int type, void *value_ptr, ...)

This routine will add a panel item to a KControlPanel object. Each panel item has a number of "attributes". First come the "core" attributes, follwed by the optional attributes. Below are the core attributes:

Parameters:

panel : The control panel to add to.
name : The name of the panel item.
comment : the comment (eg. name of the units: "(km/sec)").
type : The type of the panel item. See DS_KARMA_DATA_TYPES and panel_ITEM_TYPES for legal values.
value_ptr : A pointer to the panel item data storage.
... : The optional attributes are given as pairs of attribute-key attribute-value pairs. This list must be terminated with the value PIA_END. See panel_ATTRIBUTES for a list of defined attributes.

Returns: Nothing.
Multithreading Level: Unsafe

void panel_push_onto_stack (KControlPanel panel)

Push a control panel object onto the control panel stack.

Parameters:

panel : The control panel.

Returns: Nothing.
Multithreading Level: Unsafe

void panel_pop_from_stack ()

Pop last pushed control panel object from control panel stack.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe

flag panel_process_command_with_stack (char *cmd, flag (*unknown_func) (), FILE *fp)

This routine will process a command, using the top control panel on the stack to interpret it.

Parameters:

cmd : The command.
unknown_func : The function that is called when the command is not understood. If this is NULL, then a message is displayed if the command is not understood. The prototype function is panel_PROTO_decode_func.
fp : Output messages are directed here.

Returns: TRUE if more commands should be processed, else FALSE, indicating that the control panel's "exit" command was entered.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag panel_put_history_with_stack (multi_array *multi_desc, flag module_header)

Put history into Karma multi_array structure.

Parameters:

multi_desc : The data structure to append history to.
module_header : If TRUE the module name and version are appended before the parameter information.

Returns: TRUE on sucess, else FALSE
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void panel_set_extra_comment_string (KControlPanel panel, CONST char *string)

Set the extra comment string for a panel.

Parameters:

panel : The control panel.
string : The comment string. The contents are copied.

Returns: Nothing.
Multithreading Level: Unsafe

Prototype Functions

flag panel_PROTO_decode_func (char *command, FILE *fp)

This function is called whenever a command string is to be processed.

Parameters:

command : The command string.
fp : The output file.

Returns: TRUE if more commands should be processed, else FALSE, indicating that the "exit" command was entered.
Multithreading Level: Unsafe

Tables

panel_ATTRIBUTES

Name Type Meaning

PIA_END End of varargs list
PIA_NUM_CHOICE_STRINGS unsigned int Number of choice strings
PIA_CHOICE_STRINGS char ** Choice strings
PIA_ARRAY_LENGTH unsigned int * Current array length
PIA_ARRAY_MIN_LENGTH unsigned int Minimum array length
PIA_ARRAY_MAX_LENGTH unsigned int Maximum array length
PIA_CHOICE_COMMENTS char ** Choice string comments
PIA_MIN_VALUE double Minimum value
PIA_MAX_VALUE double Maximum value
PIA_TOP_OF_PANEL flag Place item at top of panel

panel_ITEM_TYPES

Name value_ptr type Meaning

PIT_FUNCTION void (*) (char *) Execute function
PIT_EXIT_FORM Exit form
PIT_FLAG flag * Flag type
PIT_CHOICE_INDEX unsigned int * Choice index (requires: PIA_NUM_CHOICE_STRINGS and PIA_CHOICE_STRINGS)
PIT_GROUP KControlPanel Group item

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services

Name	Type	Meaning

PIA_END		End of varargs list
PIA_NUM_CHOICE_STRINGS	unsigned int	Number of choice strings
PIA_CHOICE_STRINGS	char **	Choice strings
PIA_ARRAY_LENGTH	unsigned int *	Current array length
PIA_ARRAY_MIN_LENGTH	unsigned int	Minimum array length
PIA_ARRAY_MAX_LENGTH	unsigned int	Maximum array length
PIA_CHOICE_COMMENTS	char **	Choice string comments
PIA_MIN_VALUE	double	Minimum value
PIA_MAX_VALUE	double	Maximum value
PIA_TOP_OF_PANEL	flag	Place item at top of panel

Name	value_ptr type	Meaning

PIT_FUNCTION	void () (char )	Execute function
PIT_EXIT_FORM		Exit form
PIT_FLAG	flag *	Flag type
PIT_CHOICE_INDEX	unsigned int *	Choice index (requires: PIA_NUM_CHOICE_STRINGS and PIA_CHOICE_STRINGS)
PIT_GROUP	KControlPanel	Group item