Daylight v4.9
Release Date: 1 February 2008


dw_3d - 3D (trackball) widget

C Prototype

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

/*** Standard widget functions ***/

int dw_3d_create (Frame parent);
void dw_3d_destroy (int id);
void dw_3d_hide (int id);
void dw_3d_redraw (int id);
void dw_3d_reset (int id);
void dw_3d_setlabel(int id, char *label);
void dw_3d_show (int id);

/*** Functions specific to the 3D widget ***/

int dy_3d_invoke(int id, dt_Handle conf);


The 3D widget allows the user to examine a conformation (a depiction of three dimensional structure).

The calling program simply supplies a conformation to the widget which then handles all user interaction. The widget uses the conformation supplied (not a copy), so the calling program must not deallocate the conformation (or its underlying molecule) until the widget is cleared (via dw_3d_reset() or invoked with another conformation. By design, the operation of the widget is hidden from the main program. The XView widget provides a variety of rotation and depth cueing options which are selectable by the user.

Any number of trackball widgets can exist concurrently, with each instance displaying a single conformation.

dw_3d_create(Frame parent) => int

Create a 3D 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_3d_destroy(int id) => void

Destroy the given 3D widget.

dw_3d_hide(int id) => void

Unconditionally hide the given 3D widget.

dw_3d_invoke(int id, dt_Handle conformation) => int

Invoke 3D widget id with given conformation.

dw_3d_redraw(int id) => void

Refresh the given widget.

dw_3d_reset(int id) => void

Clear the given 3D widget.

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

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

dw_3d_show(int id) => void

Make the given 3D widget visible. This is not typically needed, since dw_3d_invoke() automatically makes the widget visible.


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


Specify the initial geometry of the widget in pixels.


If FALSE, the user will be allowed to pin-up property menus (ala olwm); if TRUE, pin-ups will be disabled (ala mwm).


Specify the initial depth cueing method for monochrome and color displays, respectively. Valid choices are NONE (the default), STYLE, WIDTH, and GRAYSCALE (not valid for monochrome displays).


Specifies the background color.


Specifies the color of the trackball circle.


Specify atom colors by element to be used on color displays with NONE, STYLE, or WIDTH depth cueing.


Specify colors for GRAYSCALE depth cueing.

Return Value

No error messages are generated by this widget. Release 4.2 is the first release of this widget. The 4.3 Trackball Widget is functionally identical to the 4.2 version.


Rotation performance of the 4.2 and 4.3 XView versions of this widget are highly dependent the I/O environment, ranging from very good to dismal. Factors adversely affecting performance are low network throughput and poor intrinsic X-server performance. In general, very good performance obtained on machines providing "native" X (e.g. Sun Sparc's, SGI Indigo). Good-to-acceptable performance can be expected from X-terminals and X-emulators on fast LAN's (e.g. Mac-X over TCP/Ethernet) but degrades to marginal over serial lines (e.g. using TCP/SLIP or AppleTalk). Some X-servers appear to have such low intrinsic performance that they can't support this widget in an acceptable fashion. The X-server supplied with SGI Irix 3.3 and 4.01 appears to fall into this category when used on machines other than the Indigo.

Related Topics

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