NAME

DrawArea − drawing area widget

SYNOPSIS

#include <Xol/OpenLook.h>
#include <Xol/DrawArea.h>
 . . .

ANCESTRY

Core-Composite-Constraint-Manager-Bulletin-DrawArea

DESCRIPTION

The DrawArea widget provides a window on which an application can render images using Xlib calls.  The DrawArea widget uses Callbacks to notify the application that the image needs to be redrawn.  To get the window associated with the DrawArea widget use XtWindow(). 

Simple Composite Widget

The DrawArea widget is a composite widget that enforces no ordering on its children.  It is up to the application to specify the x- and y-coordinates of each child inserted; otherwise, it will be placed in the upper left corner of the DrawArea widget. 

No Children

The DrawArea widget can be mapped with no children.  It displays an empty space, possibly surrounded by a border. 

Multiple Visuals Support

Like Shell Widgets, the DrawArea widget can be created with a non-default depth, visual and colormap.  This is done by setting the widget’s XtNdepth, XtNvisual, or XtNcolormap resource. 

DrawArea Coloration

The figure below illustrates the resources that affect the coloration of the DrawArea widget. 

  Figure 1 Draw Area Coloration

Keyboard Traversal

The DrawArea widget is a composite widget and cannot be accessed via keyboard traversal.  Input focus moves between the children of this widget. 

RESOURCES

  Table 1 DrawArea Resource Summary

Name                      Type           Default             Access
XtNancestorSensitive-       Boolean          TRUE                  G
XtNbackground-              Pixel            XtDefaultBackground   SGI
XtNbackgroundPixmap-        Pixmap           (none)                SGI
XtNborderColor-             Pixel            XtDefaultForeground   SGI
XtNborderPixmap-            Pixmap           (none)                SGI
XtNborderWidth-             Dimension        0                     SGI
XtNcolormap                 Colormap         (parent’s)            SGI
XtNconsumeEvent-            XtCallbackList   NULL                  SGIO
XtNdepth                    int              (parent’s)            GI
XtNdestroyCallback-         XtCallbackList   NULL                  SI
XtNexposeCallback           XtCallbackList   NULL                  SGI
XtNgraphicsExposeCallback   XtCallbackList   NULL                  SGI
XtNheight-                  Dimension        (calculated)          SGI
XtNinputFocusColor-         Pixel            Red                   SGI
XtNlayout                   OlDefine         OL_MINIMIZE           SGI
XtNmappedWhenManaged-       Boolean          TRUE                  SGI
XtNresizeCallback           XtCallbackList   NULL                  SGI
XtNsensitive-               Boolean          TRUE                  GIO
XtNuserData-                XtPointer        NULL                  SGI
XtNvisual                   Visual∗          (parent’s)            GI
XtNwidth-                   Dimension        (calculated)          SGI
XtNx-                       Position         0                     SGI
XtNy-                       Position         0                     SGI

Access:   S = XtSetValues   G = XtGetValues
            I = init time   O = other access

† see resources(3W)

XtNcolormap

class:XtCColormap type:Colormap default:(parent´s)access:SGI

Action: Determines the colormap used to interpret pixels drawn in the widget’s window. 

Values: Any colormap supported by the current display and compatible with the widget’s visual resource. 

If not XtNcolormap is not specified, Shell and DrawArea widgets use their visual resource to find (share or create) the widget’s colormap. 

Only widgets have a colormap resource.  To get the colormap associated with any widget or gadget, use the function OlColormapOfObject(). 

XtNdepth

class:XtCDepth type:int default:(parent´s)access:GI

Action: Determines how many bits should be used for each pixel in the widget’s window. 

Values: Any depth supported by the current display. 

The value of this resource is used to set the depth of the widget’s window when the widget is created. 

Only widgets have a depth resource.  To get the depth associated with any widget or gadget, use the function OlDepthOfObject(). 

XtNexposeCallback

class:XtCCallback type:XtCallbackList default:NULLaccess:SGI

Action: procedure called whenever the DrawArea widget gets an expose event.  The call_data parameter is a pointer to a structure, OlDrawAreaCallbackStruct which looks like:

typedef struct
{
int reason;
XEvent ∗event;
Position x;
Position y;
Dimension width;
Dimension height;
} OlDrawAreaCallbackStruct;

reason OL_REASON_EXPOSE, which tells the callback which of the remaining fields in the OlDrawAreaCallbackStruct structure are valid. 

event A pointer to the XEvent that triggered the callback. 

x,y The upper left corner of the exposed area. 

width,height
The dimensions of the exposed area.

XtNgraphicsExposeCallback

class:XtCCallback type:XtCallbackList default:NULLaccess:SGI

Action: Procedure called whenever the DrawArea widget gets a graphics expose event.  Graphics expose events are generated when a XCopyArea or XCopyPlane fails to copy the entire source area because part of the source area was obscured. 

The call_data parameter is a pointer to a structure, OlDrawAreaCallbackStruct, which looks like:

typedef struct
{
int reason;
XEvent ∗event;
Position x;
Position y;
Dimension width;
Dimension height;
} OlDrawAreaCallbackStruct;

reason
OL_REASON_GRAPHICS_EXPOSE.  indicating the validity of the remaining fields of the OlDrawAreaCallbackStruct structure. 

event pointer to the XEvent that triggered the callback. 

x,y The upper left corner of the obscured area. 

width,height
The dimensions of the obscured area.

XtNlayout

class:XtCLayout type:OlDefine default:OL_MINIMIZEaccess:SGI

Action: identifies the layout policy the DrawArea widget is to follow:

OL_MINIMIZE/minimize – the DrawArea widget will always be just large enough to contain all its children, regardless of any provided width and height values.  Thus the DrawArea widget will grow and shrink depending on the size needs of its children. 

OL_IGNORE/ignore – the DrawArea widget will honor its own width and height; it will not grow or shrink in response to the addition, deletion, or altering of its children. 

OL_MAXIMIZE/maximize  – the DrawArea widget will ask for additional space when it needs it for new or altered children, but will not give up extra space. 

XtNresizeCallback

class:XtCCallback type:XtCallbackList default:NULLaccess:SGI

Action: Procedure called whenever the DrawArea widget is resized. 

The call_data parameter is a pointer to a OlDrawAreaCallbackStruct structure, which looks like

typedef struct
{
int reason;
XEvent ∗event;
Position x;
Position y;
Dimension width;
Dimension height;
} OlDrawAreaCallbackStruct;

reason the reason the callback was invoked, OL_REASON_RESIZE. 

event invalid field

x,y The upper left corner of the DrawArea relative to its parent widget. 

width,height
The dimensions of the DrawArea. 

XtNvisual

class:XtCVisual type:Visual∗ default:(parent´s)access:GI

Action: Specifies the visual used to create the widget’s window. 

Values: A pointer to any visual structure supported by the current display and compatible with the widget’s depth and colormap. 

Only Shell and DrawArea Widgets have a visual resource.  All other widgets are created using their parent’s visual. 

If XtNvisual is not specified, Shell and DrawArea widgets inherit their parent’s visual. 

The prefered method of setting a Shell or DrawArea widget’s visual resource is to use the Intrinsics typed args interface.  A string containing the desired Visual Class Name should be passed to the String to Visual resource converter. 

To get the visual associated with any widget or gadget, use the function,
OlVisualOfObject(). 
 

Version 3.0.1  —  Last change: June 92