Daylight v4.9
Release Date: 1 February 2008


dw_grins - grins 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_grins_create (Frame parent);
void dw_grins_destroy (int id);
void dw_grins_hide (int id);
void dw_grins_redraw (int id);
void dw_grins_reset (int id);
void dw_grins_setlabel(int id, char *label);
void dw_grins_show (int id);

/*** Functions specific to the Grins widget ***/

int dy_grins_invoke(int id, dt_Handle dep, void (*cb)());

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

void cb(dt_Handle dep);


The Grins Widget is a callable molecular editor which allows the user to specify a molecule and its 2-D coordinates. The Grins Widget was revamped for Daylight Release 4.33 leading to many user visible changes (see the "Widget's User's Manual". From the programmer's point-of-view, the only change is the addition of one function (dw_grins_invoke2()). Among other things, this function allows Grins to be used for SMARTS (pattern) specification as well as SMILES (molecule) specification. Communication with the 4.3 Grins widget may be done via depiction, molecule, and string objects. Although Grins is a very sophisticated widget, the calling syntax is extremely simple. Calling programs can treat the widget simply as a source of user-specified depictions, molecules, SMILES, and SMARTS. Grins may be used as a source of molecules (rather than depictions) by accessing the returned depiction's base molecule (i.e. dt_base(dep)).

Grins may also be used as a conventional molecular editor which reads and writes files in Thor datatree format.

Datatrees in these files contain SMILES ($SMI) and 2-D (2D) data items. A special directory containing such files is used to provide a number of starting templates (GRINS_PARENTDIR). Daylight supplies a directory tree with files containing ring systems and common drug parents. Grins responds to a number of other specialized options, described below.

dw_grins_create(Frame parent) => int

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

Destroy the given Grins widget.

dw_grins_hide(int id) => void

Unconditionally hide the given Grins widget.

dy_grins_invoke(int id, dt_Handle dep, void (*depcb)(int id, dt_Handle dep)) => int

Invoke Grins widget id starting with the given depiction. If no depiction is given (i.e. dep is set to NULL_OB), it will start up with the last depiction edited. The callback is called with the edited depiction when the user clicks "Select" (or NULL_OB on "Cancel"). Grins does not use the starting depiction (or it's molecule) directly, so they may be freely deallocated. The returned depiction is owned by Grins so the calling program should not deallocate it, and modify copies rather than the original.

dy_grins_invoke2(int id, dt_Handle ob, int lang, int langmask, void (*sobcb)(int id, int lang, dt_Handle sob) => int

Like dy_grins_invoke(), except that the input object may be a depiction, a molecule or a string object, and that the user may be allowed to specify a pattern as well as a molecule. The flags DX_LANG_SMILES and DX_LANG_SMARTS, defined in dt_widgets.h, are used to control language access. Initial widget state is determined by the value of argument `lang'. Langmask is an input variable determining which languages are available to the user, e.g., if dy_grins_invoke2 is called with langmask = DX_LANG_SMILES | DX_LANG_SMARTS, the user will be able to switch between them. The callback always returns a string object as well as the languages desired by the user.

dw_grins_redraw(int id) => void

Refresh the given widget.

dw_grins_reset(int id) => void

Clear the given Grins widget.

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

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

dw_grins_show(int id) => void

Make the given Grins widget visible. This is not typically needed, since dw_grins_invoke() automatically makes the widget visible.



Specify initial geometry for Grins window in pixels.


Minimum number of atoms for which "fast dragging" mode is used. When "fast dragging", drawing atomic symbols are suppressed for better performance. This is only a hint to the widget, which is free to do what it thinks is best (e.g. fast dragging will not be used for atoms which have no bonds).


Specify how to draw dragged parts of the molecule. The default, and best choice, is DOTTED. Some servers have problems XOR'ing dotted lines: if your server leaves "dirt" when dragging, set this to NONE.


Specify full names of fonts to be used when drawing atomic symbols and subscripts.


Specify Grins foreground and background colors as standard color names (see man page for dw_edgar()).


Specify the directory containing Thor datatree (.tdt) files of the parent templates. This can be a full path name or symbolic name.


Specify how many planes are XOR'ed when dragging. This is typically the number of planes used to represent white, e.g. 1 for Sun servers (0 is black, color cell 1 is white), and 3 for SGI servers (0 is black, planes 1, 2, 3 are red, green, blue).

Return Value

No error messages are generated by this widget.

Release 4.2 is the first release of this widget.

Release 4.3 supports all 4.2 requests.


Some older SGI X-servers have terribly poor performance which makes Grins almost unusable. See the man page for dw_3d() for more information.

Some Sun hardware leaves dirt when dragging (4/470 with CP6 graphics board). Since this is obsolete hardware Sun probably won't fix it; setting GRINS_DRAG_STYLE to NONE is the workaround.

Related Topics

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