19. Widgets

Back to Table of Contents

19.1 Introduction

The Daylight Widget Toolkit (tm) provides powerful set of functions for displaying chemical information in a X-windows environment. Each "widget" is designed to handle a particular task that is needed in typical programs for chemical-information processing The widgets in the Widget Toolkit are:

• Depict Widget: Displays depictions and, optionally allows a user to select one or more of them. The Depict Widget is by far the most complex of the Daylight Widgets, as it has several modes of operation.

• 3D Widget: Displays conformations, allows the users to rotate the depictions with simple mouse action using a "trackball" conceptual model.

• TDT Widget: Displays THOR Datatrees, provides editing capabilities so users can enter and modify chemical information in a THOR database. Has several display options that allow different levels of detail to be shown.

• Edgar Widget: Graphic-attribute editor. Allows users to change the colors and styles of graphics, such as depictions and conformations, and to save the attributes in a personal options file.

• File Widget: Allows the user to select a file. While finding the file of interest, users can browse through the file system, selectively show only files of the desired type or all files, order the display alphabetically or by name, and cancel the selection.

• Status Widget: A simple widget that graphically shows the progress of a long operations, and provides a timeout and interactive-abort mechanisms.

• Message Widget: Displays errors and warnings returned by the Daylight Toolkit's error functions. Allows users to scroll back through a series of errors and to clear the error display.

The philosophy behind the design of the Daylight Widgets is quite different from other Daylight Toolkits. Because the X Window programming environment is really only useable by C programs, Daylight Widgets are only callable by C programs -- there is no FORTRAN or Pascal interface. Certain programming constructs that don't work well in mixed-language environments, such as pointers to functions, are not used in the other Daylight Toolkits, but the Widget Toolkit makes heavy use of them.

In addition, there is no concept of polymorphism or objects in the Widgets Toolkit. Each widget is referred to by an identifier, but it is not a "Handle" in the sense used by the other Toolkits.

19.2 Widget Functional Interface

The Daylight Widgets Toolkit shares a key idea with the regular Daylight Toolkits: both use a functional interface. That is, the Daylight Widget Toolkit has no externally-visible C structs, "common blocks", or the like. When a widget is created, it is associated with an id, a simple integer. This identifier is then used for all further operations on the widget: the widget is invoked, hidden, displayed, and destroyed by passing this identifier to widget functions.

By design, the internal operation of all Daylight Widgets is hidden from the application program that uses the widgets. For example, the Daylight GRINS widget is a very sophisticated widget that provides users with a powerful tool for specifying molecules and depictions, but from the application program's point of view, it is simply a source of depiction objects. That is, the operation of GRINS is hidden; all the application has to do is invoke the GRINS widget and wait for a depiction to come back.

The basis of the functional interface is the idea that a widget provides a "service" or "functionality" that is independent of the particular implementation. For example, the GRINS widget task is to return a depiction object to the calling program. How it does that is irrelevant to the calling program: a "cheap imitation" GRINS widget might ask the use to enter a SMILES then use the Daylight SMILES and Depict Toolkits to generate a depiction. This cheap imitation GRINS widget would meet the functional specification, and the application program would be happy (the users, of course, would be unhappy; the real GRINS widget is a powerful graphical input tool for molecular structure).

As another example of the functional nature of the Widgets, consider the Edgar Widget. When invoked, it provides users with the ability to change the graphics (colors, line styles) being used throughout a program, and to save changes in an options file. A user can, for example, change the colors being used by the Depict Widget, change the "depth cue" colors used by the 3D widget, then save these changes for use the next time the program is invoked. Yet with all of these capabilities, the application program has essentially no interaction with the Edgar widget other than to invoke it.

We might summarize this idea by saying the programmer's view of widgets has nothing to do with their operation, only their function.

19.3 Widget Callback Functions

Modern user interfaces, such as Motif and XView, use an event-driven architecture in which input from users (keyboard and mouse activities) drive the application program. Specific actions, such as opening a database, drawing a picture, or starting a database search, are "bound" to particular keys and buttons; these actions are invoked by the event mechanism when the user presses the key or mouse button.

To operate in this environment, Daylight Widgets use "callback" functions to return their results. For example, the File Widget allows users to peruse the file system and select a file; when the user is done the selected file is returned to the application program by invoking an application-program-supplied function that was given to the File Widget for this purpose.

19.4 Options

The Daylight Widgets make use of the Daylight "option manager". The option manager is not a separate program (as the name might suggest), but rather is an integral part of the Daylight Toolkit. It is not used by the other Daylight Toolkit products (except to verify licenses), but is heavily used by Daylight Widgets.

Options specify the configurable behavior of widgets. They typically include the initial location of each widget, the colors that are used for depictions, conformations, and so on, and fonts.

The Daylight Installation Guide contains more information about the options manager. The specific options used by each widget are described on the manual page for each widget.

19.5 The Widgets

Below is an outline of each widget's capabilities. As the saying goes, "A picture is woth a thousand words." In this case, it is difficult to express in words what is obvious to the eye. Most readers of this document will have some aquaintance with the actual widgets, so we will not attempt to describe the widget's operation in detail.

All widgets have a set of "standard" functions; most also have functions specific to the widget. Note that the standard functions are not polymorphic like regular Daylight Toolkit functions; there are actually separate functions for each widget, but they follow a standard naming convention. Each widgth has the following, where "xxx" is replaced by the widget's name:

int dw_xxx_create(Frame parent);

Creates a widget as a child of XView Frame parent. The widget is initially invisible and has nothing in it. A positive widget id is returned on success, 0 is returned on failure; this id is used by all other widget functions. In general, any number of each type of widget can exist at one time, but in most situations one of each type of widget is appropriate.

void dw_xxx_destroy(int id);

Destroys the widget .

void dw_xxx_hide(int id);

Makes the widget invisible.

void dw_xxx_redraw(int id);

Causes the widget to redraw its contents.

void dw_xxx_reset(int id);

Clears the visual and logical contents of the widget. May also reset the widget's label to its default; see the specific description of each widget.

void dw_xxx_setlabel(int id, char *label);

Changes the widget's title.

void dw_xxx_show(int id);

Makes the widget visible. This function is not typically needed unlsee dw_xxx_hide() is used, as the dw_xxx_invoke() functions automatically make the widget visible.

The following is a brief description of each widget.

19.5.1 3D or "Trackball" Widget

The "Trackball" widget, so called because of the visual model used, provides the ability to display a single conformation. The widget can be thought of as "write-only" -- you pass it a conformation and it does everything else; there is no callback function or return value.

19.5.2 Depict Widget

The depict widget is the most complex of the Daylight Widgets, as it has several modes of operation and has a callback function to return results in several forms.

The typical sequence of operations on a Depict Widget are:

• Create the widget

• Add depictions to the widget. One or more objects, either depictions or sequence objects that contain depictions, can be added.

• Invoke the widget using one of the modes described below. This makes it visible and causes the depictions it contains to be displayed.

The Depict Widget's modes are:

• depict mode: Depictions are displayed only.

• pickone mode: Depictions are displayed; the user can select one depiction in a "thoughtful" manner, pressing an "OK" button when the selection is made. The depiction is returned via a callback function.

• pickhot mode: Identical to the pickone mode except that the depiction is selected in a "hasty" manner: the selection is made immediately when the depiction is selected rather than via an "OK" button.

• pickmany mode: Depictions are displayed, and the user can select any number (including zero) of the depictions. The "OK" button causes a sequence of depiction to be returned via the callback function.

19.5.3 Edgar Widget

The Edgar Widget (Edit Graphical Attribute Resources) is a color- picker utility which allows users to asociate real properties (such as color, line style, and width) with functionally-defined graphic attributes (such as background, border, bonds, and atom labels).

From the application program's point of view, the Edgar Widget is simply invoked; the Edgar Widget returns no values.

19.5.4 File Widget

The file widget allows users to peruse the file system and select a file for some particular operation. Its specification allows the application program great flexibility in selecting those files that are to be shown to the user; for example, users could be shown only writeable files with a particular suffix.

The File Widget has two callback functions. The first is called when the user selects a file; the file selected is passed to this callback function. The second callback function is a "filter" -- each file is passed to this function before being shown to the user; the function returns 1 or 0 according to whether the file is to be shown to the user or not.

19.5.5 Font Utility

(Not a widget.) The font utility, dw_font(), is a utility that accesses the Daylight Options manager, and creates an XView menu showing the optional fonts. It is provided as a convenience, and is used internally by some of the Daylight Widgets.

19.5.6 GRINS Widget

The GRINS Widget is a powerful editor that allows fast specification of molecular structure using a graphical molecule editor. GRINS was designed specifically for input tasks; it is not intended to replace molecule editors that produce publication-quality pictures. Instead, GRINS is optimized for fast entry of structure, and includes features such as templates and "parent" molecules that speed this task.

The GRINS widget has one callback function, that is invoked with a depiction as its parameter when the user selects "OK".

19.5.7 Help Widget

The Help Widget provides online user manuals, and allows context- dependent positioning in the manuals. Help-Widget files are simply 80-character-wide text files containing section headings that serve as the keys to context-sensitive invocation.

The Help Widget is invoked with a topic and key. For example, invoking it with the topic "thor" and the key "CREATING DATABASES" would cause it to find the file "thor.hw", then look for the string "CREATING DATABASES". The widget would be made visible with "thor.hw" as its contents, positioned at the key of interest.

19.5.8 Message Widget

The Message Widget is a convenient was of allowing the user to browse the message sent to the error facility provided by the Daylight Toolkit. It has no callback functions.

19.5.9 Status Widget

The Status Widget keeps the user informed of the progress of lengthy operations. It shows a graphical "thermometer" display that fills up as the task proceeds, and shows a textual summary of the task's progress, including an estimated time of completion.

In addition, the Status Widget has a timeout and abort facility. The application program can indicate a time at which the process will be interrupted; at this point the user can choose to proceed, set another timeout, or abort the operation. In addition, the user can at any point abort the operation.

The Status Widget is somewhat more difficult to use than the other widgets due to the design of XView; a special main event loop must be written for XViews event processing. The Widget Toolkit comes with an example illustrating how this is done.

19.5.10 TDT Widget

The TDT Widget provides for the display and editing of THOR Datatrees. It uses two callback functions:

• A "done" callback function, which is invoked when the user is finished editing the TDT and presses "Save".

• A "datatypes" callback, which should return a sequence of the datatypes that are to be available to the person editing the datatree.

If the TDT supplied is from a read-only database, then the TDT widget automatically uses the "Browse" mode; no editing is possible. Otherwise, the widget has add, delete, move, and modify modes that allow data to be entered and modified.

19.6 Widget Programmer's Reference

The details of calling syntax, features, and functionality for programming the Widgets Toolkit are described in a separate document, a set of UNIX-style " man pages". It is called the Daylight Widgets Toolkit Reference.

Back to Table of Contents Go to previous chapter Merlin Toolkit
Go to next chapter Reaction Toolkit.