Name

C Prototype

/*** Standard widget functions ***/

int dw_depict_create (Frame parent);
void dw_depict_destroy (int id);
void dw_depict_hide (int id);
void dw_depict_redraw (int id);
void dw_depict_reset (int id);
void dw_depict_setlabel(int id, char *label);
void dw_depict_show (int id);

/*** Functions specific to the Depict widget ***/

dw_depict_addcontent(int id, dt_Handle depseq);
dw_depict_autodraw (int id, int ppp);
dw_depict_content (int id);
dw_depict_display (int id);
dw_depict_gethigh (int id);
dw_depict_pickhot (int id, dt_Handle dep, void (*cb1)());
dw_depict_pickmany (int id, dt_Handle sel, void (*cbm)());
dw_depict_pickone (int id, dt_Handle dep, void (*cb1)());
dw_depict_setcontent(int id, dt_Handle depseq);
dw_depict_sethigh (int id, dt_Handle depseq);

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

void cb1(dt_Handle dep, int id);
void cbm(dt_Handle seq, int id);

Description

The calling program provides depictions to the widget which then handles all user interaction. Labels and graphic attributes (colors) of depiction components are displayed as per depiction object properties, and should be set by the calling program. The widget uses the depiction objects supplied (not copies), so the calling program must not deallocate the depictions (or their underlying molecules) until the widget is cleared via dw_depict_reset() or reinvoked with dw_depict_setcontent().

By design, the operation of the widget is hidden from the main program. The 4.3 XView Depict widget provides the user with a number of features such as resizing, help, highlighting, and popup/zooming. This version of the widget is limited to displaying 64 depictions at once.

Any number of trackball widgets can exist concurrently with each instance displaying up to 64 structures. In general, applications should avoid displaying multiple windows with multiple structures because it's easy to visually overload the user.

dw_depict_addcontent(int id, dt_Handle depseq) => int ok

Add depiction(s) to the widget content. If depseq is a depiction, it will be added; if a sequence, depictions in that sequence (starting at the current position) will be added; otherwise this is a no-op. This function has no visible effect unless autodraw is active. TRUE is returned on success, FALSE on any error.

dw_depict_autodraw(int id, int ppp) => void

Indicate that it is appropriate to display contents as they are added to the widget content and indicate the number of pictures-per-page (ppp) expected. Calling this function with ppp equal to zero disables autodraw. By design, this function provides a hint to the widget; it doesn't guarantee any particular behavior. If autodraw is set to a non-zero value, the 4.3 XView widget will attempt to maintain a display which reflects the current content its display as current whenever possible, and will resize/redraw if the content exceeds the expected value.

dw_depict_content(int id) => dt_Handle seq

Return the contents of the given widget as a sequence of depictions. The returned sequence becomes the property of the calling program which is responsible for deallocating it. If the widget is empty, an empty sequence is returned. NULL_OB is returned only on error (e.g. invalid id).

dw_depict_create(Frame parent) => int id

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

Destroy the given Depict widget.

dw_depict_display(int id)

Invoke the depict widget in "display" mode, i.e. show its contents. Returns TRUE (1) on success, FALSE (0) on failure (e.g. invalid id).

dw_depict_gethigh(int id) => dt_Handle seq

Return the highlighted contents of the given widget as a sequence of depictions. The returned sequence becomes the property of the calling program which is responsible for deallocating it. If the widget is empty, an empty sequence is returned. NULL_OB is returned only on error (e.g. invalid id). This function is not frequently needed.

dw_depict_hide(int id) => void

Hide the given Depict widget.

dw_depict_pickhot(int id, dt_Handle dep, void (*cb1)()) => int ok

Invoke the depict widget in "hot picking" mode, i.e. allow the user to pick single depictions, invoking the callback function immediately. The callback function will be called with the selected depiction (or NULL_OB if "Cancel" was selected). Other than the immediate response to picking action, this is functionally equivalent to dw_depict_pickone(). TRUE (1) is returned on success, FALSE (0) on failure (e.g. invalid id).

dw_depict_pickmany(int id, dt_Handle sel, void (*cbm)()) => int ok

Invoke the depict widget in "Pick many" mode, i.e. allow the user to pick none, one, many, or all of the depictions in the current content. Depictions in input sequence sel define the initial selection presented to the user. If not NULL, the callback function will be called when the user chooses "Select" (called with a sequence of selected depictions) or "Cancel" (called with NULL_OB). TRUE (1) is returned on success, FALSE (0) on failure (e.g. invalid id).

dw_depict_pickone(int id, dt_Handle dep, void (*cb1)()) => int ok

Invoke the depict widget in "Pick one" mode, i.e. allow the user to pick a single depiction. The callback function will be invoked when the user chooses "Select" (called with selected depiction) or "Cancel" (called with NULL_OB). Other than requiring explicit picking action, this is functionally equivalent to dw_depict_pickhot(). TRUE (1) is returned on success, FALSE (0) on failure (e.g. invalid id).

dw_depict_redraw(int id) => void

Refresh the given widget.

dw_depict_reset(int id) => void

Clear the visual and logical content of the widget.

dw_depict_setcontent(int id, dt_Handle depseq) => int ok

Clear the depict widget then add depiction(s) as per dw_depict_addcontent(). If depseq is a depiction, the widget will contain only that depiction; if a sequence, the widget will contain depictions in that sequence starting at the current position; otherwise this is equivalent to dw_depict_reset(); This function has no visible effect unless autodraw is active. TRUE is returned on success, FALSE on any error.

dw_depict_sethigh(int id, dt_Handle depseq) => int

Define which depictions are highlighted; depseq may be a depiction or a sequence containing depictions. Depictions which are not in the current contents and other object types are silently ignored. TRUE is returned on success, FALSE on any error.

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

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

dw_depict_show(int id) => void

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

OPTIONS:

The initial Depict widget display format is controlled by the following options. The HUE_ options may be dynamically altered via the Edgar Widget.

DEPICT_FRAME_X, DEPICT_FRAME_Y

Initial location of the widget in pixels.

DEPICT_FRAME_WIDTH, DEPICT_FRAME_HEIGHT

Initial size of the widget in pixels.

DEPICT_POPUP_X, DEPICT_POPUP_Y

Initial location of the popup window in pixels.

DEPICT_POPUP_WIDTH, DEPICT_POPUP_HEIGHT

Initial size of the popup window in pixels.

HUE_BACKGROUND, HUE_BORDER, HUE_TEXT_LABEL

Specifies the colors used to draw for background, borders, and titles.

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 "DEPICT WIDGET".

Return Value

Release 4.2 is the first release of this widget so there are no "official" compatibility issues. The 4.3 Depict Widget is functionally identical to the 4.3 version.

Bugs

Related Topics