Name

C Prototype

/*** Standard widget functions ***/

int dw_tdt_create (Frame parent);
void dw_tdt_destroy (int id);
void dw_tdt_hide (int id);
void dw_tdt_redraw (int id);
void dw_tdt_reset (int id);
void dw_tdt_setlabel(int id, char *label);
void dw_tdt_show (int id);

/*** Functions specific to the Tdt widget ***/

dw_tdt_invoke(int id, char *title, dt_Handle tdt, void (*twcb()), void (*dtcb)());
dw_tdt_invoke_isnew(int id, char *title, dt_Handle tdt, void (*twcb()), void (*dtcb)());
dy_tdt_invoke2(int id, char *tit, dt_Handle tdt, dt_Handle (*twcb)(), dt_Handle (*dtypecb)(), char *findstr);

/*** User-supplied callback functions ***/

void dtcb(dt_Handle db, int ids, int nonids);
void twcb(dt_Handle tdt);

Description

The calling program provides a datatree object to the TDT widget which then handles all user interaction. The widget calls back only to obtain datatypes (dtcb()) and to return edited datatrees to be saved (twcb()). If the twcb() result callback is specified as NULL, the widget will be invoked for browsing only. The datatree provided can be empty, but will in any event belong to a database.

The datatype callback (dtcb()) is called with database handle and two non-exclusive integer flags (ids and nonids) which indicate what kind of datatypes are required. The callback is responsible for returning an appropriate sequence of datatypes. If `ids' is TRUE (1) identifier datatypes should be included in the sequence; if `nonids' is TRUE (1), non-identifier datatypes should be included. These will be the datatypes offered in "Add" mode.

The result callback (twcb()) is called with the handle of a modified datatree when the user requests "Save". The callback is responsible for saving it to its database and (possibly merging it with data already there) and returning the resultant datatree. The new datatree then becomes the current content of the TDT widget.

By design, the operation of the widget is hidden from the main program. The 4.3 XView TDT widget provides the user with lots of features which the programmer need not worry about.

dw_tdt_create(Frame parent) => int id

Create a TDT 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_tdt_destroy(int id) => void

Destroy the given TDT widget.

dw_tdt_invoke(int id, char *title, dt_Handle tdt, void (*twcb()), void (*dtcb)())
dw_tdt_invoke_isnew(int id, char *title, dt_Handle tdt, void (*twcb()), void (*dtcb)())
dy_tdt_invoke2(int id, char *tit, dt_Handle tdt, dt_Handle (*twcb)(), dt_Handle (*dtypecb)(), char *findstr);

These functions invoke the TDT widget with the given datatree. If twcb() is NULL, the user will be limited to browsing, otherwise, it will be called when the user elects to save a edited datatree in the database. In the first and second forms, dtcb() will be called to supply datatypes as described above. In the third, a callback function is used for the same purpose. The only difference between the first and second functions is in the first, the callback is only called if the TDT was modified by the widget. In the second, the TDT is marked as modified immediately, so the callback always gets called. dy_tdt_invoke2() also allows the user to search for a string in the currently-displayed datatree. If `findstring' is not NULL, it will be provided as the first search string.

dw_tdt_hide(int id) => void

Hide the given TDT widget.

dw_tdt_redraw(int id) => void

Refresh the given widget.

dw_tdt_reset(int id) => void

Clear the visual and logical content of the widget.

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

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

dw_tdt_show(int id) => void

Make the given TDT widget visible. This is not typically needed unless dw_tdt_hide() was called, the invocation functions is automatically make the widget visible.

OPTIONS:

The initial TDT widget responds to the following options. The HUE_ options may be dynamically altered via the Edgar Widget.

DATATREE_IREFS_EDITFILE

Name (full or symbolic) of a file containing indirect reference datatrees. These are (optionally) presented to users editing fields containing indirect data.

TDT_FRAME_X, TDT_FRAME_Y, TDT_FRAME_WIDTH, TDT_FRAME_HEIGHT

Geometry of the widget in pixels.

HUE_BACKGROUND, HUE_BORDER

Colors used for datatree background and decorations.

HUE_DATA, HUE_TEXTLABEL

Colors used for datatype content and labels.

HUE_HIGHLIGHT

Color used to highlight selections.

HELP_PATH

The option HELP_PATH should include a directory which contains the file widgets.hw. When "Help..." is requested, this file will be activated at the first line containing the string "DATATREE WIDGET".

PRINT_COLORMODE PRINT_DELETE_CMD PRINT_DIRECTORY PRINT_EXECUTE_FG_CMD PRINT_PS_COLOR_CMD PRINT_PS_COLOR_ZAP_CMD PRINT_PS_MONO_CMD

These options (described elsewhere) control datatree printing via treetops, which is accessible via a button on the 4.3 TDT Widget frame.

FONT_DEFAULT, FONT_FAMILY_*, FONT_*.*

Fonts used to display datatree.

Return Value

Release 4.2 is the first release of this widget. The 4.3 TDT Widget provides all functionally of the 4.2 version.

Bugs

The TDT widget doesn't provide any way to find out if the user selects "Cancel".

Because of size information needed by the scrollbar, the TDT widget formats the entire TDT before displaying any of it. In some cases, particularly where there are hundreds or thousands of indirect references, this can take considerable time, during which the TDT widget is blank.

Related Topics