# 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.
panel_item_register_callback | Register a function to be called when a panel item changes.

#### Prototype Functions

panel_PROTO_decode_func | Command line decode callback.
panel_PROTO_change_func | Item change 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:

This function takes no parameters

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

KPanelItem 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: A KPanelItem object on success, else NULL.
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:

This function takes no parameters

Returns: Nothing.
Multithreading Level: Unsafe

flag panel_process_command_with_stack (CONST 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc panel_item_register_callback (KPanelItem item, void (*func) (), void *info)

Register a function to be called when a panel item changes.

Parameters:

- item : The panel item.
- func : The function to be called when the panel item changes. The prototype function is <panel_PROTO_change_func>.
- info : An arbitrary information pointer to pass to func.
- c_unregister_callback : . On failure NULL is returned. */ { static char function_name[] = "panel_item_register_callback"; VERIFY_PANELITEM (item); return c_register_callback (&item->change_list, ( flag (*) () ) func, item, info, TRUE, NULL, FALSE, FALSE); } /* End Function panel_item_register_callback */ /* Temporary private functions follow (will probably be made public later) */ static flag _panel_process_command (KControlPanel panel, CONST char *cmd, flag (*unknown_func) (), FILE *fp) /* [PURPOSE] This routine will process a command, using a given control panel.
- panel : The control panel.
- 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

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

void panel_PROTO_change_func (KPanelItem item, void **info)

This function is called whenever an items value is changed.

Parameters:

- item : The panel item which changed.
- info : The pointer to the arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

## Tables

panel_ATTRIBUTES List of attributes for panel item objects

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 List of Karma data 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