Daylight v4.9
Release Date: 1 February 2008


dw_status - status widget

C Prototype

#include <X11/Xlib.h>
#include <xview/xview.h>
#include "dw_xv_widget.h"

/*** 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 );


The status widget is designed to keep the user informed of the status of a (usually lengthy) task in progress. When this widget is invoked, the caller may optionally specify a timeout interval (in seconds) and the size of the task (arbitrary units). The widget is then repeatedly updated by the program as the task proceeds; the update function indicates whether to continue or interrupt processing (e.g. user aborted task). When the task is complete, the caller should inform the widget (dw_status_done()) and may optionally hide the widget (dw_status_hide()). All interaction with the user is the widget's responsibility.

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

No error messages are generated by this widget.

Release 4.3 is the first release of this widget.


This widget should probably provide options for the initial frame position. The 4.3 Error Widget is functionally identical to the 4.3 version.

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

Daylight Widget User's Guide
Daylight Widget Programmer's Guide