Name

C Prototype

/*** Standard widget functions ***/

int dw_status_create (Frame parent );
void dw_status_destroy (int id );
void dw_status_hide (int id );
void dw_status_redraw (int id );
void dw_status_reset (int id );
void dw_status_setlabel(int id, char *label );
void dw_status_show (int id );

/*** Functions specific to the status widget ***/

int dw_status_invoke (int id, int limit, int timeout);
int dw_status_update (int id, int value );
int dw_status_tick (int id );
void dw_status_done (int id );

Description

This process is complicated in X-Windows (and other event-driven environments) when implicit event-loop dispatching is used (e.g. xv_main_loop()). In such cases, explicit event dispatching should be used as is done in the example program status_usage (see SEE ALSO).

dw_status_create(Frame parent) => int

Create a status widget as a child of XView Frame parent. The widget is initially empty and is not visible. A positive widget id is returned on success; 0 is returned on error.

dw_status_done(int id) => void

Indicate that process on status widget id is done. The widget will remain visible and its contents will reflect the final status.

dw_status_destroy(int id) => void

Destroy status widget of given id.

dw_status_hide(int id) => void

Unconditionally hide status widget of given id.

dw_status_invoke(int id, int limit, int timeout) => int

Invoke status widget id with given limit and timeout. A positive value of limit indicates the expected value at completion; a zero value indicates that the completion value is unknown. A positive value of timeout indicates the timeout interval in seconds; a zero value disables timing out. 1 is returned on success, 0 on error.

dw_status_redraw(int id) => void

Refresh the given widget.

dw_status_reset(int id) => void

Return widget to its initial state.

dw_status_setlabel(int id, char *label) => void

Set the label on the given status widget. A value of NULL sets the default label.

dw_status_show(int id) => void

Make the status widget visible. This is not typically needed, since dw_status_invoke() automatically makes the widget visible.

dw_status_tick(int id) => int

Update status widget id with value incremented by one. Returns 0 on error or if user requested an abort; returns 1 otherwise.

dw_status_update(int id, int value) => int

Update status widget id to indicate given value. Returns 0 on error or if user requested an abort; returns 1 otherwise.

Return Value

Release 4.3 is the first release of this widget.

Bugs

This utility is cumbersome to use in X-Windows environments because of the need for explicit event dispatching. However, this seems to be an inevitable consequence of the design of X. Another quirky consequence is that the "Quit" choice in XView frame menus can't kill functions running in parallel with XView. Such programs need to control exiting explicitly (e.g. with a "Quit" button callback).

Related Topics