Drawing

Drawing(3fe)                Finite Element Package                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.




Version 2.21                        7/11/94                       Drawing(3fe)