# The "listw" Package

These routines are meant to provide a simple mechanism to display a list of strings. NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karmagraphics
Link With: -lkarmagraphics

#### Functions

listw_create | Create a list widget.
listw_bind | Bind a list widget to a pixel canvas.
listw_destroy | Destroy a list widget
listw_register_position_event_func | Register position event callback.
listw_get_attributes | Get list widget attributes.
listw_set_attributes | Set list widget attributes.
listw_register_att_notify_func | Register an attribute change function.

#### Prototype Functions

listw_PROTO_position_func | Position event callback.
listw_PROTO_att_notify_func | Registers a change in the attributes of a list widget.

## Functions

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

KListWidget listw_create ()

Create a list widget.

Parameters:

This function takes no parameters

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

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

void listw_bind (KListWidget list, KPixCanvas canvas)

Bind a list widget to a pixel canvas.

Parameters:

- canvas : The pixel canvas object.

Returns: Nothing. On failure, the process aborts.
Multithreading Level: Unsafe
Note:

- Only one list widget may be bound per pixel canvas.

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

void listw_destroy (KListWidget list)

Destroy a list widget

Parameters:

- list : The list widget.

Returns: Nothing.
Multithreading Level: Unsafe

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

KCallbackFunc listw_register_position_event_func (KListWidget list, flag (*func) (), void *f_info)

This routine will register a position event function for a list widget. The position event function will be called whenever a position event on the list widget has not been consumed. Many position event functions may be registered per list widget. The first function registered is the first function called upon a position event.

Parameters:

- list : The list widget.
- func : The function that is called when a position event occurs. The prototype function is listw_PROTO_position_func.
- f_info : The initial arbitrary function information pointer.

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

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

void listw_get_attributes (KListWidget list, ...)

Get list widget attributes.

Parameters:

- list : The list widget.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pointer pairs. The list must be terminated with LISTW_ATT_END. See listw_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

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

flag listw_set_attributes (KListWidget list, flag refresh_if_needed, ...)

Set list widget attributes.

Parameters:

- list : The list widget.
- refresh_if_needed : If TRUE, the list display is refreshed if something has changed.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. The list must be terminated with LISTW_ATT_END. See listw_ATTRIBUTES for the list of attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

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

KCallbackFunc listw_register_att_notify_func (KListWidget list, void (*func) (), void *info)

This routine will register an attribute notify function for a list widget. The attribute notify function will be called whenever the list widget attributes are changed (see listw_set_attributes). Many attribute notify functions may be registered per list widget. The first function registered is the first function called upon attribute changes.

Parameters:

- list : The list widget.
- func : The function which is called when the attributes are changed. The prototype function is listw_PROTO_att_notify_func.
- info : The initial arbitrary information pointer.

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

## Prototype Functions

flag listw_PROTO_position_func (KListWidget list, unsigned int index, unsigned int event_code, void *e_info, void **f_info)

This routine is a position event consumer for a list widget.

Parameters:

- list : The list widget on which the event occurred.
- index : The index in list of strings for which the event occurred.
- event_code : The arbitrary event code.
- e_info : A pointer to arbitrary event information.
- f_info : A pointer to an arbitrary function information pointer.

Returns: TRUE if the event was consumed, else FALSE indicating that the event is still to be processed.
Multithreading Level: Unsafe

void listw_PROTO_att_notify_func (KListWidget list, void **info)

Registers a change in the attributes of a list widget.

Parameters:

- list : The list widget.
- info : A pointer to an arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

Back to Karma Home Page