Drawing(3fe)

NAME
Drawing - general purpose drawing widget

SYNOPSIS
# include <X11/Intrinsic.h>
# include "Drawing.h"

DESCRIPTION
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.

RESOURCES
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.

OPERATIONS
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.

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

SEE ALSO
velvet(1fe), xfelt(1fe).

BUGS
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.