Drawing - general purpose drawing widget

# include <X11/Intrinsic.h>

# include "Drawing.h"

These files define a general purpose drawing widget that is subclass of the Athena Simple widget. The widget provides a scalable, two dimensional drawing area with a cartesian coordinate system and an optional background grid and pointer snap. The widget is intended to provide mechanisms and not policies. For example, there is no "select rectangular area with mouse" feature. Instead, the application writer can specify callbacks associated with pointer movement and mouse button actions.

The widget operations allow the creation, removal, and dynamic configuration of figures. The figures are maintained on a display list by the widget. Figures are referenced by the application writer though the opaque type Figure. The current figure types include lines, polygons, rectangles, arcs, text, pixmaps, bitmaps, and groups. The properties associated with figures include grouping, scaling, line width, line style, visibility, color, and position.

The Drawing widget adds the following resources to the Athena Simple widget:

XtNcoordinates (class XtCCoordinates) XtRWidget

Specifies a label widget to be used in displaying the current coordinates of the pointer within the widget or NULL if no display is desired. Default value: NULL

XtNgrid (class XtCGrid) XtRBoolean

Specifies if the background grid should be displayed. The grid consists of a series of intersecting dashed lines lying behind all figures whose spacing is specified by the gridSize resource. Default value: False

XtNgridSize (class XtCGridSize) XtRFloat

Specifies the grid spacing in real units. The grid lines will be drawn with spacing according to the value of this resource if the grid resource is True. Default value: 1.00

XtNsnap (class XtCSnap) XtRBoolean

Specifies if pointer snap should be enabled. Pointer snap indicates that in addition to reporting the actual coordinates of the pointer in a callback, the coordinates lying closest to the pointer and along an invisible grid whose spacing is given by the snapSize resource should also be reported.

XtNSnapSize (class XtCSnapSize) XtRFloat

Specifies the snap grid spacing in real units. The invisible snap grid with be spaced according to the value of this resource. This resource has no effect if the snap resource is False. Default value: 1.00

XtNxMin (class XtCXMin) XtRFloat

Specifies the minimum value for the x axis. This value must be less than the value specified by the xMax resource. Default value: 0.0

XtNxMax (class XtCXMax) XtRFloat

Specifies the maximum value for the x axis. This value must be greater than the value specified by the xMin resource. Default value: 10.0

XtNyMin (class XtCYMin) XtRFloat

Specifies the minimum value for the y axis. This value must be less than the value specified by the yMax resource. Default value: 0.0

XtNyMax (class XtCYMax) XtRFloat

Specifies the maximum value for the y axis. This value must be greater than the value specified by the yMin resource. Default value: 10.0

XtNxScale (class XtCXScale) XtRFloat

Specifies the scale for the x axis in pixels per real unit. This value must be greater than zero. Default value: 50.0

XtNyScale (class XtCYScale) XtRFloat

Specifies the scale for the y axis in pixels per real unit. This value must be greater than zero. Default value: 50.0

XtNbuttonCallback (class XtCButtonCallback) XtRCallback

A callback list whose procedures should be called upon a button action (press, release, or drag). These events include ButtonPress, ButtonRelease, and MotionNotify events. The call data to the callback procedure will be a pointer to a DrawingReport structure which includes both the snapped and unsnapped coordinates (the snapped coordinates will be identical to the unsnapped coordinates if the snap resource is False) and a pointer to the corresponding XEvent structure. The topmost figure located under the pointer will also be included if the autoFind resource is True and the corresponding event type is ButtonPress. Default value: NULL

XtNmotionCallback (class XtCMotionCallback) XtRCallback

A callback list whose procedures should be called upon pointer motion in the widget. The call data to the callback procedure will be a pointer to a DrawingReport structure as described above. The corresponding event type will always be MotionNotify. Default value: NULL

XtNinteractive (class XtCInteractive) XtRBoolean

Specifies if interactive drawing mode is enabled. In interactive mode, an exclusive-or graphics context is used which provides for more efficient redrawing and removal of figures than if the normal graphics context were used. However, the exclusive-or graphics context does not handle exposure events properly. Thus, interactive mode should be used for any interactive operations such as moving a figure by following the pointer. The general policy should be to enable interactive mode, perform the necessary operation, and then disable interactive mode. The preferred way to set this resource is through the DW_SetInteractive function. Default value: False

XtNautoFind (class XtCAutoFind) XtRBoolean

Specifies if the display list is to be searched upon a button press. If this resource is True then the topmost figure located under the pointer, or NULL if no such figure exists, will be returned in the DrawingReport structure. The preferred way to set this resource is through the DW_SetAutoFind function. Default value: False

XtNautoRedraw (class XtCAutoRedraw) XtRBoolean

Normally the display list is automatically redrawn upon a change to the display list though a DW_RemoveFigure, DW_LowerFigure, or DW_SetAttributes operation. If this resource is False then the display list will not automatically be redrawn and the corresponding redraw requests will be buffered. Upon setting this resource to True, any buffered requests will be processed. The general policy should be to disable redrawing before making substantial changes to the display list and to re-enable redrawing once those changes are complete. The preferred way to set this resource is through the DW_SetAutoRedraw function. Default value: True

For convenience a function, Float2Arg, is provided which converts a floating point value to an Arg suitable for use with XtSetArg.

The Drawing widget provides a variety of functions for drawing figures, altering the display list, changing the internal state of the widget, and retrieving information about the widget:

Figure DW_DrawLine (drawing, x1, y1, x2, y2)

Widget

drawing;

float

x1, y1;

float

x2, y2;

DW_DrawLine draws a line in the current foreground color from (x1,y1) to (x2,y2) using XDrawLine. The figure representing the line, or NULL upon an error, is returned.

Figure DW_DrawPolygon (drawing, scaled, points, npoints)

Widget

drawing;

Boolean

scaled;

Point

points [ ];

int

npoints;

DW_DrawPolygon draws a optionally scaled polygon whose vertices are given in the points array in the current foreground color using XDrawLines. The number of vertices is specified by npoints. If a closed polygon is desired then the first and last vertices should be identical. If scaled is True then the polygon will be scaled, indicating that the vertices should rescale as the widget is rescaled. Unscaled polygons are not currently supported. The figure representing the polygon, or NULL upon an error, is returned.

Figure DW_FillPolygon (drawing, scaled, points, npoints)

Widget

drawing;

Boolean

scaled;

Point

points [ ];

int

npoints;

DW_FillPolygon draws a filled polygon figure using XFillPolygon in the same manner as DW_DrawPolygon. However, if a closed polygon is desired the first and last vertices need not be identical. The figure representing the polygon, or NULL upon an error, is returned.

Figure DW_DrawRectangle (drawing, scaled, x, y, width, height)

Widget

drawing;

Boolean

scaled;

float

x, y;

float

width, height;

DW_DrawRectangle draws a rectangle in the current foreground color using XDrawRectangle. The bottom left corner of the rectangle is located at (x,y). The dimensions of the rectangle are specified by the width and height parameters. A positive dimension is along the corresponding axis and a negative dimension is opposite from the corresponding axis. If scaled is True then the rectangle will be rescaled as the widget is rescaled. If scaled is False then width and height specify the dimensions in pixels which will not rescale. The figure representing the rectangle, or NULL upon an error, is returned.

Figure DW_FillRectangle (drawing, scaled, x, y, width, height)

Widget

drawing;

Boolean

scaled;

float

x, y;

float

width, height;

DW_FillRectangle is identical to DW_DrawRectangle except a filled rectangle is drawn using XFillRectangle.

Figure DW_DrawArc (drawing, scaled, x, y, width, height, angle, length)

Widget

drawing;

Boolean

scaled;

float

x, y;

float

width, height;

float

angle, length;

DW_DrawArc draws an arc in the current foreground color using XDrawArc. The arc is drawn inscribed in a rectangle whose center is located at (x,y) and whose dimensions are specified by width and height. The starting angle in degrees in specified by angle and the arc length is specified by length. Scaling, as specified by the scaled parameter, is similar to DW_DrawRectangle. The figure representing the arc, or NULL upon an error, is returned.

Figure DW_FillArc (drawing, scaled, x, y, width, height, angle, length)

Widget

drawing;

Boolean

scaled;

float

x, y;

float

width, height;

float

angle, length;

DW_FillArc is identical to DW_DrawArc except a filled arc is drawn using XFillArc.

Figure DW_DrawText (drawing, scaled, x, y, text)

Widget

drawing;

Boolean

scaled;

float

x, y;

String

text;

DW_DrawText draws a text figure in the current foreground color and font using XDrawString. The lower left corner of the text is located at (x,y). The text string is specified by text and must be null terminated. The scaled flag is currently ignored. The figure representing the text, or NULL upon an error, is returned.

"Figure DW_FindFigure (drawing, x, y)

Widget

drawing;

float

x, y;

DW_FindFigure searches the display list for the topmost figure which includes the point (x,y). This function is used if the autoFind resource is True and a ButtonPress event has occurred. If the located figure is a member of a group then the figure representing the group is returned. Otherwise the located figure, or NULL if no such figure exists, is returned.

void DW_RaiseFigure (drawing, figure)

Widget

drawing;

Figure

figure;

DW_RaiseFigure raises the figure specified by figure to the top of the display list. If figure is NULL then no changes are made to the display list. If figure is of type GroupFigure then all figures in the group are raised. A redraw request is not issued as the specified figures are simply redrawn.

void DW_LowerFigure (drawing, figure)

Widget

drawing;

Figure

figure;

DW_LowerFigure lowers the figure specified by figure to the bottom of the display list. If figure is NULL then no changes are made to the display list. If figure is of type GroupFigure then all figures in the group are lowered. A redraw request is issued for each figure which is lowered (see the autoRedraw resource for details).

void DW_RemoveFigure (drawing, figure)

Widget

drawing;

Figure

figure;

DW_RemoveFigure removes the figure specified by figure from the display list. If figure is NULL then no changes are made to the display list. If figure is of type GroupFigure then all figures in the group are removed. A redraw request is issued for each figure which is removed (see the autoRedraw resource for details).

void DW_RemoveAll (drawing)

Widget

drawing;

DW_RemoveAll removes all figures from the display list, effectively clearing the widget.

void DW_Redraw (drawing)

Widget

drawing;

DW_Redraw forces a redraw of the entire display list. This function should ideally never need to be called.

void DW_GetAttributes (drawing, figure, attributes)

Widget

drawing;

Figure

figure;

FigureAttributes

*attributes;

DW_GetAttributes retrieves the attributes associated with the figure specified by figure. The attributes are returned in the structure pointed to by attributes. A FigureAttributes structure includes the following members which apply to the types of figures as indicated.

FigureType type;
// all figures (read only)
Figure group;
// all figures
unsigned line_width;
// lines, polygons, rectangles, arcs
int line_style;
// lines, polygons, rectangles, arcs
Boolean visible;
// lines, polygons, rectangles, arcs, text
Boolean filled;
// polygons, rectangles, arcs
Boolean scaled;
// polygons, rectangles, arcs, text
String color;
// lines, polygons, rectangles, arcs, text
String text;
// text
String font;
// text
float x;
// rectangles, arcs, text
float y;
// rectangles, arcs, text
float width;
// rectangles, arcs
float height;
// rectangles, arcs
float arc_start;
// arcs
float arc_length;
// arcs
Point *points;
// lines, polygons
unsigned npoints;
// lines, polygons (read only)
Figure *figures;
// groups (read only)
unsigned nfigures;
// groups (read only)
Pixmap pixmap;
// pixmaps, bitmaps
char *user_data;
// all figures
XFontStruct *font_struct;
// text (read only)


Only those fields which are valid for the specified figure type are defined.
The user_data field is not used by the widget and is provided for the
use of the application writer.  The types of figures are shown below.

LineFigure



PolygonFigure



RectangleFigure



ArcFigure



TextFigure



GroupFigure



PixmapFigure



BitmapFigure

The types of line styles are shown below.

DW_LineSolid



DW_LineDashed



DW_LineDotted



DW_LineDotDashed



DW_LineLongDashed

If figure is NULL then the structure pointed to by
attributes is unchanged.


Boolean DW_SetAttributes (drawing, figure, valuemask, attributes)

Widget
drawing;
Figure
figure;
unsigned
valuemask;
FigureAttributes
*attributes;

DW_SetAttributes changes the attributes of a previously drawn figure.
The figure whose attributes are to be changed is specified by figure.
The attributes are specified in the structure pointed to by attributes.
Only those attributes as specified by the valuemask are changed.  The
mask is a bitwise inclusive OR of zero or more of the following
flags:

DW_FigureGroup
// group
DW_FigureLineWidth
// line_width
DW_FigureLineStyle
// line_style
DW_FigureVisible
// visible
DW_FigureScaled
// scaled
DW_FigureColor
// color
DW_FigureFont
// font
DW_FigureText
// text and font_struct
DW_FigureX
// x
DW_FigureY
// y
DW_FigureWidth
// width
DW_FigureHeight
// height
DW_FigureArcStart
// arc_start
DW_FigureArcLength
// arc_length
DW_FigurePoints
// points
DW_FigurePixmap
// pixmap
DW_FigureUserData
// user_data
DW_FigureLocation
// x and y
DW_FigureSize
// width and height
DW_FigureArc
// arc_start and arc_length

If figure is of type GroupFigure then all figures in the group
are modified.  If figure is NULL then no changes are made.  If
any errors occur then False is returned.  Otherwise, True is
returned.


void DW_ClipBox (figure, clip_box)

Figure
figure;
XRectangle
*clip_box;

DW_ClipBox returns the actual window coordinates of the bounding box
for the figure specified by figure.  The box is returned in the
structure pointed to by clip_box.  Note that unlike other functions the
first argument to this function is not a widget.


"void DW_TranslateCoords (drawing, x, y, rx, ry)

Widget
widget;
float
x, y;
float
*rx, *ry;

DW_TranslateCoords translates from window coordinates to real
coordinates.  The window coordinate is given by (x,y).  The real
coordinate is retrieved as (*rx,*ry).  This function is useful in
action procedures where only the window coordinate is known.


Boolean DW_SetForeground (drawing, color)

Widget
drawing;
String
color;

DW_SetForeground sets the foreground color for drawing new figures.  To
change the color of a previously drawn figure use DW_SetAttributes.
The new foreground color is specified by color which is passed to
XParseColor.  A cache of the assigned foreground color names is
maintained to improve lookup time.  If the color is successfully allocated
then True is returned.  Otherwise, False is returned and the
current foreground color remains unchanged.


Boolean DW_SetFont (drawing, font)

Widget
drawing;
String
font;

DW_SetFont sets the font for drawing new text figures.  To change the
font of a previously drawn figure use DW_SetAttributes.  The new font
is specified by font which is passed to XLoadQueryFont.  A cache
of the assigned font names is maintained to improve lookup time.  If the font
is successfully loaded then True is returned.  Otherwise, False
is returned and the current font remains unchanged.


void DW_SetLineWidth (drawing, line_width)

Widget
drawing;
unsigned
line_width;

DW_SetLineWidth sets the line width for drawing new figures.  To change
the line width of a previously drawn figure use DW_SetAttributes.


void DW_SetLineStyle (drawing, line_style)

Widget
drawing;
int
line_style;

DW_SetLineStyle sets the line style for drawing new figures.  To change
the line style of a previously drawn figure use DW_SetAttributes.  The
line style is specified by line_style (see DW_GetAttributes
above).


void DW_SetInteractive (drawing, interactive)

Widget
drawing;
Boolean
interactive;

DW_SetInteractive sets the interactive resource of the widget to
the value specified by interactive (see the interactive resource
for details).


void DW_SetAutoFind (drawing, auto_find)

Widget
drawing;
Boolean
auto_find;

DW_SetAutoFind sets the autoFind resource of the widget to the
value specified by auto_find (see the autoFind resource for
details).


void DW_SetAutoRedraw (drawing, auto_redraw)

Widget
drawing;
Boolean;
auto_redraw;

DW_SetAutoRedraw sets the autoRedraw resource of the widget to
the value specified by auto_redraw (see the autoRedraw resource
for details).


Figure *DW_SearchArea (drawing, points, npoints, nfigures)

Widget
drawing;
Point
points [ ];
unsigned
npoints;
unsigned
*nfigures;

DW_SearchArea searches the specified area and returns all figures
located within the area.  The area is specified as a polygon whose vertices
are given in the points array.  The number of vertices is specified by
npoints.  The number of figures within the area is returned in the
memory pointed to by nfigures.  The figures are returned by the
function in space which has been allocated by XtMalloc.  The topmost
figure found will be first in the array.  If no figures are located within
the area then nfigures will contain zero and NULL is returned.


Figure *DW_RetrieveAll (drawing, nfigures)

Widget
drawing;
unsigned
*nfigures;

DW_RetrieveAll retrieves all the figures on the display list.  The
figures are returned by the function in space which has been allocated by
XtMalloc.  The topmost figure will be first in the array.  If no
figures are located within the area then nfigures will contain zero and
NULL is returned.


Figure DW_Group (drawing, figures, nfigures)

Widget
drawing;
Figure
figures [ ];
unsigned
nfigures;

DW_Group creates a new figure of type GroupFigure.  The members
of the group are specified by the figures array.  The number of
members is specified by nfigures.  Group figures are not placed on the
display list but do affect the DW_RaiseFigure, DW_LowerFigure,
DW_RemoveFigure, and DW_SetAttributes functions.  Groups may be
hierarchical.  The figure representing the group, or NULL upon an
error, is returned.


void DW_Ungroup (drawing, group)

Widget
drawing;
Figure
group;

DW_Ungroup disbands the group pointed to by group and
deallocates the corresponding group figure.  The members of the group are
unaffected except that they will not belong to any group.


void DW_GetTextExtents (drawing, string, width, height)

Widget
drawing;
String
string;
float
*width;
float
*height;

DW_GetTextExtents retrieves the width and height of a text string, but
does not draw the string.  The text width and height are stored in width
and height respectively.

The Drawing widget was developed by Darren C. Atkinson (atkinson@ucsd.edu) and Jason I. Gobat (jgobat@mit.edu).

velvet(1), xfelt(1).

Unscaled polygons are currently not implemented. Greater control is needed over drawing attributes such as fill patterns. Scalable text figures need to be implemented if I can ever figure out scalable fonts under X11R5. The policies applied to grouped figures may need to be changed. Figures may be associated with only one widget and thus the widget parameter to many functions is redundant.