NAME

DrawArea − a drawing area widget

SYNOPSIS

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/DrawArea.h>
 . . .
Widget my_drawarea, my_parent;
String my_name;
ArgList args;
Cardinal num_args;

my_drawarea =  XtCreate( my_name, drawAreaWidgetClass,

my_parent, args, num_args);

DESCRIPTION

Drawing Window

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

DrawArea                  Resource       Set
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                SG
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
 
TRAVERSAL                 XtNnextTop     XtCCallback         XtCallbackList
XtNresizeCallback         XtCallbackList NULL                SGI
XtNsensitive              Boolean        TRUE                GIO
XtNuserData               XtPointer      NULL                SGI
 
TRANSPARENT               XtNtransparent XtCTransparent      Boolean
XtNvisual                 Visual∗        (parent’s)          GI
XtNwidth                  Dimension      (calculated)        SGI
XtNx                      Position       0                   SGI
XtNy                      Position       0                   SGI

Access:S = XtSetValues G = XtGetValues
        I = init timeO = 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, OlExposeCallbackStruct, that looks like:

typedef struct
{
int reason;
XEvent ∗event;
} OlExposeCallbackStruct;

reasonThe reason the callback was invoked, OlCR_EXPOSE.

eventA pointer to the XEvent that triggered the callback.

For V3 FCS this structure will change to OlDrawAreaCallbackStruct which looks like:

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

reasonThe reason the callback was invoked, OlCR_EXPOSE.

eventA pointer to the XEvent that triggered the callback.

x,yThe upper left corner of the exposed area.

width,heightThe 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, OlGExposeCallbackStruct, that looks like:

typedef struct
{
int reason;
XEvent ∗event;
} OlGExposeCallbackStruct;

reasonThe reason the callback was invoked, OlCR_GRAPHICS_EXPOSE.

eventA pointer to the XEvent that triggered the callback.

For V3 FCS this structure will change to OlDrawAreaCallbackStruct which looks like:

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

reasonThe reason the callback was invoked, OlCR_GRAPHICS_EXPOSE.

eventA pointer to the XEvent that triggered the callback.

x,yThe upper left corner of the obscured area.

width,heightThe 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 structure, OlResizeCallbackStruct, that looks like:

typedef struct
{
int reason;
Position x;
Position y;
Dimension width;
Dimension height;
} OlResizeCallbackStruct;

reasonThe reason the callback was invoked, OlCR_RESIZE.

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

width, heightThe dimensions of the DrawArea.

For V3 FCS this structure will change to OlDrawAreaCallbackStruct which looks like:

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

reasonThe reason the callback was invoked, OlCR_RESIZE.

eventA NULL pointer.

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

width,heightThe dimensions of the DrawArea.

XtNvisual

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

Action: Determines 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 use their depth resource and parent’s visual class to find the widget’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  —  Last change: 19 July 91  —  Last change: 19 July 91