Release Date: 1 February 2008
Namedw_status - status widget
C Prototype#include <X11/Xlib.h>
/*** Standard widget functions ***/
int dw_status_create (Frame parent );
/*** Functions specific to the status widget ***/
int dw_status_invoke (int id, int limit, int timeout);
DescriptionThe 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 ValueNo error messages are generated by this widget.
Release 4.3 is the first release of this widget.
BugsThis 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 TopicsDaylight Widget User's Guide
Daylight Widget Programmer's Guide