'\" t
...\" DrawAr.sgm /main/11 1996/09/08 20:40:20 rws $
.de P!
.fl
\!!1 setgray
.fl
\\&.\"
.fl
\!!0 setgray
.fl			\" force out current output buffer
\!!save /psv exch def currentpoint translate 0 0 moveto
\!!/showpage{}def
.fl			\" prolog
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
\!!psv restore
.
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
.TH "XmDrawingArea" "library call"
.SH "NAME"
\fBXmDrawingArea\fP \(em The DrawingArea widget class
.iX "XmDrawingArea"
.iX "widget class" "DrawingArea"
.SH "SYNOPSIS"
.PP
.nf
#include <Xm/DrawingA\&.h>
.fi
.SH "DESCRIPTION"
.PP
DrawingArea is an empty widget that is easily adaptable
to a variety of purposes\&.
It does no drawing and defines no behavior except for invoking
callbacks\&.
Callbacks notify the application when graphics need to be drawn
(exposure events or widget resize) and when the widget receives input from
the keyboard or mouse\&.
.PP
Applications are responsible for defining appearance and behavior as needed
in response to DrawingArea callbacks\&.
.PP
DrawingArea is also a composite widget and subclass of
\fBXmManager\fP that supports
minimal geometry management for multiple widget or gadget children\&.
.PP
DrawingArea uses the \fBXmNinitialFocus\fP resource of \fBXmManager\fP
to define whether or not DrawingArea will receive focus when it is
traversed to, even if it has traversable children\&. If
\fBXmNinitialFocus\fP is NULL, DrawingArea receives focus only if it
does not have any traversable children\&. If \fBXmNinitialFocus\fP is
not NULL, then DrawingArea receives focus when traversed to\&. In the latter
case, the application first needs to be able to realize that the DrawingArea
will receive focus, then, as appropriate, needs to either call the
\fBXmProcessTraversal\fP function for the desired child, or to navigate
across the private DrawingArea graphics objects\&.
.PP
The following resources are not currently used by the DrawingArea
widget: \fBXmNshadowThickness\fP, \fBXmNtopShadowPixmap\fP,
\fBXmNbottomShadowPixmap\fP, \fBXmNtopShadowColor\fP, and
\fBXmNbottomShadowColor\fP
.SS "Data Transfer Behavior"
.PP
DrawingArea has no widget class conversion or destination procedure\&.
Subclasses and the \fBXmNconvertCallback\fP procedures are responsible
for any conversion of selections\&.
Subclasses and the \fBXmNdestinationCallback\fP procedures are
responsible for any data transfers to the widget\&.
.SS "Classes"
.PP
DrawingArea inherits behavior and resources from the \fBCore\fP,
\fBComposite\fP, \fBConstraint\fP, and \fBXmManager\fP classes\&.
.PP
The class pointer is \fBxmDrawingAreaWidgetClass\fP\&.
.PP
The class name is \fBXmDrawingArea\fP\&.
.SS "New Resources"
.PP
The following table defines a set of widget resources used by the programmer
to specify data\&. The programmer can also set the resource values for the
inherited classes to set attributes for this widget\&. To reference a
resource by name or by class in a \fB\&.Xdefaults\fP file, remove the \fBXmN\fP or
\fBXmC\fP prefix and use the remaining letters\&. To specify one of the defined
values for a resource in a \fB\&.Xdefaults\fP file, remove the \fBXm\fP prefix and use
the remaining letters (in either lowercase or uppercase, but include any
underscores between words)\&.
The codes in the access column indicate if the given resource can be
set at creation time (C),
set by using \fBXtSetValues\fP (S),
retrieved by using \fBXtGetValues\fP (G), or is not applicable (N/A)\&.
.PP
.TS
tab() box;
c s s s s
l| l| l| l| l.
\fBXmDrawingArea Resource Set\fP
\fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP
_____
XmNconvertCallbackXmCCallbackXtCallbackListNULLC
_____
XmNdestinationCallbackXmCCallbackXtCallbackListNULLC
_____
XmNexposeCallbackXmCCallbackXtCallbackListNULLC
_____
XmNinputCallbackXmCCallbackXtCallbackListNULLC
_____
XmNmarginHeightXmCMarginHeightDimension10CSG
_____
XmNmarginWidthXmCMarginWidthDimension10CSG
_____
XmNresizeCallbackXmCCallbackXtCallbackListNULLC
_____
XmNresizePolicyXmCResizePolicyunsigned charXmRESIZE_ANYCSG
_____
.TE
.IP "\fBXmNconvertCallback\fP" 10
Specifies a list of callbacks called when the DrawingArea is asked to
convert a selection\&.
The type of the structure whose address is passed to these callbacks is
\fBXmConvertCallbackStruct\fR\&.
The reason is \fBXmCR_OK\fP\&.
.IP "\fBXmNdestinationCallback\fP" 10
Specifies a list of callbacks called when the DrawingArea is the
destination of a transfer operation\&.
The type of the structure whose address is passed to these callbacks is
\fBXmDestinationCallbackStruct\fR\&.
The reason is \fBXmCR_OK\fP\&.
.IP "\fBXmNexposeCallback\fP" 10
Specifies the list of callbacks that is
called when DrawingArea receives an exposure event\&.
The callback reason is \fBXmCR_EXPOSE\fP\&.
The callback structure also includes the exposure event\&.
.IP "" 10
The default bit gravity for Manager windows is \fBNorthWestGravity\fP\&.
This may cause the \fBXmNexposeCallback\fP procedures not to be invoked
when the DrawingArea window is made smaller\&.
.IP "\fBXmNinputCallback\fP" 10
Specifies the list of callbacks that is
called when the DrawingArea receives a keyboard
or mouse event (key or button, up or down)\&.
The callback reason is \fBXmCR_INPUT\fP\&.
The callback structure also includes the input event\&.
.IP "\fBXmNmarginHeight\fP" 10
Specifies the minimum spacing in pixels between the top or bottom edge
of DrawingArea and any child widget\&.
.IP "\fBXmNmarginWidth\fP" 10
Specifies the minimum spacing in pixels between the left or right edge
of DrawingArea and any child widget\&.
.IP "\fBXmNresizeCallback\fP" 10
Specifies the list of callbacks that is
called when the DrawingArea is resized\&.
The callback reason is \fBXmCR_RESIZE\fP\&.
.IP "\fBXmNresizePolicy\fP" 10
Controls the policy for resizing DrawingArea widgets\&.
Possible values include \fBXmRESIZE_NONE\fP (fixed size),
\fBXmRESIZE_ANY\fP (shrink or grow as needed), and
\fBXmRESIZE_GROW\fP (grow only)\&.
.SS "Inherited Resources"
.PP
DrawingArea inherits behavior and resources from the following
superclasses\&. For a complete description of each resource, refer to the
reference page for that superclass\&.
.PP
.TS
tab() box;
c s s s s
l| l| l| l| l.
\fBXmManager Resource Set\fP
\fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP
_____
XmNbottomShadowColorXmCBottomShadowColorPixeldynamicCSG
_____
XmNbottomShadowPixmapXmCBottomShadowPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
_____
XmNforegroundXmCForegroundPixeldynamicCSG
_____
XmNhelpCallbackXmCCallbackXtCallbackListNULLC
_____
XmNhighlightColorXmCHighlightColorPixeldynamicCSG
_____
XmNhighlightPixmapXmCHighlightPixmapPixmapdynamicCSG
_____
XmNinitialFocusXmCInitialFocusWidgetNULLCSG
_____
XmNlayoutDirectionXmCLayoutDirectionXmDirectiondynamicCG
_____
XmNnavigationTypeXmCNavigationTypeXmNavigationTypeXmTAB_GROUPCSG
_____
XmNpopupHandlerCallbackXmCCallbackXtCallbackListNULLC
_____
XmNshadowThicknessXmCShadowThicknessDimension0CSG
_____
XmNstringDirectionXmCStringDirectionXmStringDirectiondynamicCG
_____
XmNtopShadowColorXmCTopShadowColorPixeldynamicCSG
_____
XmNtopShadowPixmapXmCTopShadowPixmapPixmapdynamicCSG
_____
XmNtraversalOnXmCTraversalOnBooleanTrueCSG
_____
XmNunitTypeXmCUnitTypeunsigned chardynamicCSG
_____
XmNuserDataXmCUserDataXtPointerNULLCSG
_____
.TE
.PP
.TS
tab() box;
c s s s s
l| l| l| l| l.
\fBComposite Resource Set\fP
\fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP
_____
XmNchildrenXmCReadOnlyWidgetListNULLG
_____
XmNinsertPositionXmCInsertPositionXtOrderProcNULLCSG
_____
XmNnumChildrenXmCReadOnlyCardinal0G
_____
.TE
.PP
.TS
tab() box;
c s s s s
l| l| l| l| l.
\fBCore Resource Set\fP
\fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP
_____
XmNacceleratorsXmCAcceleratorsXtAcceleratorsdynamicCSG
_____
XmNancestorSensitiveXmCSensitiveBooleandynamicG
_____
XmNbackgroundXmCBackgroundPixeldynamicCSG
_____
XmNbackgroundPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
_____
XmNborderColorXmCBorderColorPixelXtDefaultForegroundCSG
_____
XmNborderPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
_____
XmNborderWidthXmCBorderWidthDimension0CSG
_____
XmNcolormapXmCColormapColormapdynamicCG
_____
XmNdepthXmCDepthintdynamicCG
_____
XmNdestroyCallbackXmCCallbackXtCallbackListNULLC
_____
XmNheightXmCHeightDimensiondynamicCSG
_____
XmNinitialResourcesPersistentXmCInitialResourcesPersistentBooleanTrueC
_____
XmNmappedWhenManagedXmCMappedWhenManagedBooleanTrueCSG
_____
XmNscreenXmCScreenScreen *dynamicCG
_____
XmNsensitiveXmCSensitiveBooleanTrueCSG
_____
XmNtranslationsXmCTranslationsXtTranslationsdynamicCSG
_____
XmNwidthXmCWidthDimensiondynamicCSG
_____
XmNxXmCPositionPosition0CSG
_____
XmNyXmCPositionPosition0CSG
_____
.TE
.SS "Callback Information"
.PP
A pointer to the following structure is passed to the
\fBXmNexposeCallback\fP, \fBXmNinputCallback\fP, and
\fBXmNresizeCallback\fP procedures:
.PP
.nf
typedef struct
{
        int \fIreason\fP;
        XEvent \fI* event\fP;
        Window \fIwindow\fP;
} XmDrawingAreaCallbackStruct;
.fi
.IP "\fIreason\fP" 10
Indicates why the callback was invoked\&.
.IP "\fIevent\fP" 10
Points to the \fBXEvent\fP that triggered the callback\&.
This is NULL for the \fBXmNresizeCallback\fP\&.
.IP "\fIwindow\fP" 10
Is set to the widget window\&.
.PP
A pointer to the following structure is passed to the
\fBXmNconvertCallback\fP procedures:
.PP
.nf
typedef struct
{
        int \fIreason\fP;
        XEvent *\fIevent\fP;
        Atom \fIselection\fP;
        Atom \fItarget\fP;
        XtPointer \fIsource_data\fP;
        XtPointer \fIlocation_data\fP;
        int \fIflags\fP;
        XtPointer \fIparm\fP;
        int \fIparm_format\fP;
        unsigned long \fIparm_length\fP;
        int \fIstatus\fP;
        XtPointer \fIvalue\fP;
        Atom \fItype\fP;
        int \fIformat\fP;
        unsigned long \fIlength\fP;
} XmConvertCallbackStruct;
.fi
.IP "\fIreason\fP" 10
Indicates why the callback was invoked\&.
.IP "\fIevent\fP" 10
Points to the \fBXEvent\fP that triggered the callback\&.
It can be NULL\&.
.IP "\fIselection\fP" 10
Indicates the selection for which conversion is being requested\&.
Possible values are \fBCLIPBOARD\fP, \fBPRIMARY\fP, \fBSECONDARY\fP,
and \fB_MOTIF_DROP\fP\&.
.IP "\fItarget\fP" 10
Indicates the conversion target\&.
.IP "\fIsource_data\fP" 10
Contains information about the selection source\&.
When the selection is \fB_MOTIF_DROP\fP, \fIsource_data\fP is the
DragContext\&.
Otherwise, it is NULL\&.
.IP "\fBlocation_data\fP" 10
Contains information about the location of data to be converted\&.
If the value is NULL, the data to be transferred consists of the
widget\&'s current selection\&.
.IP "\fIflags\fP" 10
Indicates the status of the conversion\&. Following are the possible
values:
.RS
.IP "\fBXmCONVERTING_NONE\fP" 10
This flag is currently unused\&.
.IP "\fBXmCONVERTING_PARTIAL\fP" 10
The target widget was able to be converted, but some data was lost\&.
.IP "\fBXmCONVERTING_SAME\fP" 10
The conversion target is the source of the data to be transferred\&.
.IP "\fBXmCONVERTING_TRANSACT\fP" 10
This flag is currently unused\&.
.RE
.IP "\fIparm\fP" 10
Contains parameter data for this target\&.
If no parameter data exists, the value is NULL\&.
.IP "" 10
When \fIselection\fP is \fBCLIPBOARD\fP and \fItarget\fP is
\fB_MOTIF_CLIPBOARD_TARGETS\fP or
\fB_MOTIF_DEFERRED_CLIPBOARD_TARGETS\fP, the value is the requested
operation (\fBXmCOPY\fP, \fBXmMOVE\fP, or \fBXmLINK\fP)\&.
.IP "\fIparm_format\fP" 10
Specifies whether the data in \fIparm\fP should be viewed
as a list of \fIchar\fP, \fIshort\fP, or \fIlong\fP quantities\&.
Possible values are 0 (when \fIparm\fP is NULL),
8 (when the data in \fIparm\fP should be viewed as a list of \fIchar\fPs),
16 (when the data in \fIparm\fP should be viewed as a list of \fIshort\fPs),
or 32 (when the data in \fIparm\fP should be viewed as a list of \fIlong\fPs)\&.
Note that \fIparm_format\fP symbolizes a data type, not the number of bits
in each list element\&.
For example, on some machines, a \fIparm_format\fP of 32 means that
the data in \fIparm\fP should be viewed as a list of 64-bit quantities,
not 32-bit quantities\&.
.IP "\fIparm_length\fP" 10
Specifies the number of elements of data in \fIparm\fP, where each
element has the size specified by \fIparm_format\fP\&.
When \fIparm\fP is NULL, the value is 0\&.
.IP "\fIstatus\fP" 10
An IN/OUT member that specifies the status of the conversion\&.
The initial value is \fBXmCONVERT_DEFAULT\fP\&.
The callback procedure can set this member to one of the following
values:
.RS
.IP "\fBXmCONVERT_DEFAULT\fP" 10
This value means that the widget class conversion procedure, if any, is
called after the callback procedures return\&.
If the widget class conversion procedure produces any data, it
overwrites the data provided by the callback procedures in the \fIvalue\fP
member\&.
.IP "\fBXmCONVERT_MERGE\fP" 10
This value means that the widget class conversion procedure, if any, is
called after the callback procedures return\&.
If the widget class conversion procedure produces any data, it appends
its data to the data provided by the callback procedures in the
\fIvalue\fP member\&.
This value is intended for use with targets that result in lists of
data, such as \fBTARGETS\fP\&.
.IP "\fBXmCONVERT_DONE\fP" 10
This value means that the callback procedure has successfully finished
the conversion\&.
The widget class conversion procedure, if any, is not called after the
callback procedures return\&.
.IP "\fBXmCONVERT_REFUSE\fP" 10
This value means that the callback procedure has terminated the
conversion process without completing the requested conversion\&.
The widget class conversion procedure, if any, is not called after the
callback procedures return\&.
.RE
.IP "\fIvalue\fP" 10
An IN/OUT parameter that contains any data that the callback procedure
produces as a result of the conversion\&.
The initial value is NULL\&.
If the callback procedure sets this member, it must ensure that the
\fItype\fP, \fIformat\fP, and \fIlength\fP members correspond
to the data in \fIvalue\fP\&.
The callback procedure is responsible for allocating, but not for
freeing, memory when it sets this member\&.
.IP "\fItype\fP" 10
An IN/OUT parameter that indicates the type of the data in the
\fIvalue\fP member\&.
The initial value is \fBINTEGER\fP\&.
.IP "\fIformat\fP" 10
An IN/OUT parameter that specifies whether the data in \fIvalue\fP should
be viewed as a list of \fIchar\fP, \fIshort\fP, or \fIlong\fP quantities\&.
The initial value is 8\&.
The callback procedure can set this member to 8 (for a list of \fIchar\fP),
16 (for a list of \fIshort\fP), or 32 (for a list of \fIlong\fP)\&.
.IP "\fIlength\fP" 10
An IN/OUT member that specifies the number of elements of data in
\fIvalue\fP, where each element has the size symbolized by \fIformat\fP\&.
The initial value is 0\&.
.PP
A pointer to the following callback structure is passed to the
\fBXmNdestinationCallback\fP procedures:
.PP
.nf
typedef struct
{
        int \fIreason\fP;
        XEvent *\fIevent\fP;
        Atom \fIselection\fP;
        XtEnum \fIoperation\fP;
        int \fIflags\fP;
        XtPointer \fItransfer_id\fP;
        XtPointer \fIdestination_data\fP;
        XtPointer \fIlocation_data\fP;
        Time \fItime\fP;
} XmDestinationCallbackStruct;
.fi
.IP "\fIreason\fP" 10
Indicates why the callback was invoked\&.
.IP "\fIevent\fP" 10
Points to the \fBXEvent\fP that triggered the callback\&.
It can be NULL\&.
.IP "\fIselection\fP" 10
Indicates the selection for which data transfer is being requested\&.
Possible values are \fBCLIPBOARD\fP, \fBPRIMARY\fP, \fBSECONDARY\fP, and
\fB_MOTIF_DROP\fP\&.
.IP "\fIoperation\fP" 10
Indicates the type of transfer operation requested\&.
.RS
.IP "   \(bu" 6
When the selection is \fBPRIMARY\fP, possible values are \fBXmMOVE\fP,
\fBXmCOPY\fP, and \fBXmLINK\fP\&.
.IP "   \(bu" 6
When the selection is \fBSECONDARY\fP or \fBCLIPBOARD\fP, possible
values are \fBXmCOPY\fP and \fBXmLINK\fP\&.
.IP "   \(bu" 6
When the selection is \fB_MOTIF_DROP\fP, possible values are
\fBXmMOVE\fP, \fBXmCOPY\fP, \fBXmLINK\fP, and \fBXmOTHER\fP\&.
A value of \fBXmOTHER\fP means that the callback procedure must get
further information from the \fBXmDropProcCallbackStruct\fR in the
\fIdestination_data\fP member\&.
.RE
.IP "\fIflags\fP" 10
Indicates whether or not the destination widget is also the source of
the data to be transferred\&.
Following are the possible values:
.RS
.IP "\fBXmCONVERTING_NONE\fP" 10
The destination widget is not the source of the data to be transferred\&.
.IP "\fBXmCONVERTING_SAME\fP" 10
The destination widget is the source of the data to be transferred\&.
.RE
.IP "\fBtransfer_id\fP" 10
Serves as a unique ID to identify the transfer transaction\&.
.IP "\fIdestination_data\fP" 10
Contains information about the destination\&.
When the selection is \fB_MOTIF_DROP\fP, the callback procedures are
called by the drop site\&'s \fBXmNdropProc\fP, and \fIdestination_data\fP
is a pointer to the \fBXmDropProcCallbackStruct\fR passed to the
\fBXmNdropProc\fP procedure\&.
When the selection is \fBSECONDARY\fP, \fIdestination_data\fP is an Atom
representing a target recommmended by the selection owner for use in
converting the selection\&.
Otherwise, \fIdestination_data\fP is NULL\&.
.IP "\fBlocation_data\fP" 10
Contains information about the location where data is to be transferred\&.
The value is always NULL when the selection is \fBSECONDARY\fP or
\fBCLIPBOARD\fP\&.
If the value is NULL, the data is to be inserted at the widget\&'s cursor
position\&. \fBlocation_data\fP is only valid for the duration of a
transfer\&. Once \fBXmTransferDone\fP procedures start to be called,
\fBlocation_data\fP will no longer be stable\&.
.IP "\fItime\fP" 10
Indicates the time when the transfer operation began\&.
.SS "Translations"
.PP
XmDrawingArea inherits translations from XmManager\&.
Before calling the XmManager actions, all events in the inherited
translations except \fB<BtnMotion>\fP, \fB<EnterWindow>\fP,
\fB<LeaveWindow>\fP, \fB<FocusIn>\fP, and \fB<FocusOut>\fP also call the
DrawingAreaInput() action\&.
.PP
XmDrawingArea has the following additional translations\&.
The following key names are listed in the
X standard key event translation table syntax\&.
This format is the one used by Motif to
specify the widget actions corresponding to a given key\&.
A brief overview of the format is provided under
\fBVirtualBindings\fP(3)\&.
For a complete description of the format, please refer to the
X Toolkit Instrinsics Documentation\&.
.IP "\fB<BtnDown>\fP:" 10
DrawingAreaInput()
.IP "\fB<BtnUp>\fP:" 10
DrawingAreaInput()
.IP "\fB<KeyDown>\fP:" 10
DrawingAreaInput()
ManagerGadgetKeyInput()
.IP "\fB<KeyUp>\fP:" 10
DrawingAreaInput()
.SS "Action Routines"
.PP
The \fBXmDrawingArea\fP action routines are
.IP "DrawingAreaInput():" 10
Unless the event takes place in a gadget, calls the callbacks for
\fBXmNinputCallback\fP
.IP "ManagerGadgetKeyInput():" 10
Causes the current gadget to process a keyboard event
.SS "Additional Behavior"
.PP
The XmDrawingArea widget has the following additional behavior:
.IP "\fB<Expose>\fP:" 10
Calls the callbacks for \fBXmNexposeCallback\fP
.IP "\fB<Widget\ Resize>\fP:" 10
Calls the callbacks for \fBXmNresizeCallback\fP
.SS "Virtual Bindings"
.PP
The bindings for virtual keys are vendor specific\&.
For information about bindings for virtual buttons and keys, see \fBVirtualBindings\fP(3)\&.
.SH "RELATED"
.PP
\fBComposite\fP(3), \fBConstraint\fP(3), \fBCore\fP(3),
\fBXmCreateDrawingArea\fP(3),
\fBXmManager\fP(3),
\fBXmVaCreateDrawingArea\fP(3), and
\fBXmVaCreateManagedDrawingArea\fP(3)\&.