Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XmDrawingArea(3)	   Library Functions Manual	      XmDrawingArea(3)

NAME
       XmDrawingArea --	The DrawingArea	widget class

SYNOPSIS
       #include	<Xm/DrawingA.h>

DESCRIPTION
       DrawingArea is an empty widget that is easily adaptable to a variety of
       purposes.  It does no drawing and defines no behavior except for	invok-
       ing  callbacks.	Callbacks notify the application when graphics need to
       be drawn	(exposure events or widget resize) and	when  the  widget  re-
       ceives input from the keyboard or mouse.

       Applications  are  responsible  for defining appearance and behavior as
       needed in response to DrawingArea callbacks.

       DrawingArea is also a composite widget and subclass of  XmManager  that
       supports	 minimal  geometry  management	for  multiple widget or	gadget
       children.

       DrawingArea uses	the XmNinitialFocus resource of	 XmManager  to	define
       whether	or not DrawingArea will	receive	focus when it is traversed to,
       even if it  has	traversable  children.	If  XmNinitialFocus  is	 NULL,
       DrawingArea  receives  focus  only  if it does not have any traversable
       children. If XmNinitialFocus is not NULL, then DrawingArea receives fo-
       cus  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 XmProcessTraversal function for
       the desired child, or to	navigate across	the private DrawingArea	graph-
       ics objects.

       The  following resources	are not	currently used by the DrawingArea wid-
       get: XmNshadowThickness,	XmNtopShadowPixmap, XmNbottomShadowPixmap, Xm-
       NtopShadowColor,	and XmNbottomShadowColor

   Data	Transfer Behavior
       DrawingArea  has	 no  widget class conversion or	destination procedure.
       Subclasses and the XmNconvertCallback procedures	 are  responsible  for
       any  conversion	of selections.	Subclasses and the XmNdestinationCall-
       back procedures are responsible for any data transfers to the widget.

   Classes
       DrawingArea inherits behavior and resources from	the  Core,  Composite,
       Constraint, and XmManager classes.

       The class pointer is xmDrawingAreaWidgetClass.

       The class name is XmDrawingArea.

   New Resources
       The  following table defines a set of widget resources used by the pro-
       grammer to specify data.	The programmer can also	set the	resource  val-
       ues  for	 the  inherited	 classes to set	attributes for this widget. To
       reference a resource by name or by class	in a .Xdefaults	 file,	remove
       the  XmN	or XmC prefix and use the remaining letters. To	specify	one of
       the defined values for a	resource in a .Xdefaults file, remove  the  Xm
       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 XtSetValues	(S), retrieved by using	XtGetValues (G), or is
       not applicable (N/A).

       +----------------------------------------------------------------------------------+
       |		       |   XmDrawingArea Resource Set	  |		 |	  |
       |Name		       | Class		 | Type		  | Default	 | Access |
       +-----------------------+-----------------+----------------+--------------+--------+
       |XmNconvertCallback     | XmCCallback	 | XtCallbackList | NULL	 | C	  |
       +-----------------------+-----------------+----------------+--------------+--------+
       |XmNdestinationCallback | XmCCallback	 | XtCallbackList | NULL	 | C	  |
       +-----------------------+-----------------+----------------+--------------+--------+
       |XmNexposeCallback      | XmCCallback	 | XtCallbackList | NULL	 | C	  |
       +-----------------------+-----------------+----------------+--------------+--------+
       |XmNinputCallback       | XmCCallback	 | XtCallbackList | NULL	 | C	  |
       +-----------------------+-----------------+----------------+--------------+--------+
       |XmNmarginHeight	       | XmCMarginHeight | Dimension	  | 10		 | CSG	  |
       +-----------------------+-----------------+----------------+--------------+--------+
       |XmNmarginWidth	       | XmCMarginWidth	 | Dimension	  | 10		 | CSG	  |
       +-----------------------+-----------------+----------------+--------------+--------+
       |XmNresizeCallback      | XmCCallback	 | XtCallbackList | NULL	 | C	  |
       +-----------------------+-----------------+----------------+--------------+--------+
       |XmNresizePolicy	       | XmCResizePolicy | unsigned char  | XmRESIZE_ANY | CSG	  |
       +-----------------------+-----------------+----------------+--------------+--------+
       +-----------------------+-----------------+----------------+--------------+--------+
       XmNconvertCallback
		 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	XmConvertCall-
		 backStruct.  The reason is XmCR_OK.

       XmNdestinationCallback
		 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
		 XmDestinationCallbackStruct.  The reason is XmCR_OK.

       XmNexposeCallback
		 Specifies   the   list	 of  callbacks	that  is  called  when
		 DrawingArea receives an exposure event.  The callback	reason
		 is XmCR_EXPOSE.  The callback structure also includes the ex-
		 posure	event.

		 The default bit gravity for Manager windows is	NorthWestGrav-
		 ity.	This may cause the XmNexposeCallback procedures	not to
		 be invoked when the DrawingArea window	is made	smaller.

       XmNinputCallback
		 Specifies the list of	callbacks  that	 is  called  when  the
		 DrawingArea  receives	a keyboard or mouse event (key or but-
		 ton, up or down).  The	callback reason	 is  XmCR_INPUT.   The
		 callback structure also includes the input event.

       XmNmarginHeight
		 Specifies  the	 minimum  spacing in pixels between the	top or
		 bottom	edge of	DrawingArea and	any child widget.

       XmNmarginWidth
		 Specifies the minimum spacing in pixels between the  left  or
		 right edge of DrawingArea and any child widget.

       XmNresizeCallback
		 Specifies  the	 list  of  callbacks  that  is called when the
		 DrawingArea is	resized.  The callback reason is XmCR_RESIZE.

       XmNresizePolicy
		 Controls the policy for resizing DrawingArea widgets.	Possi-
		 ble  values  include XmRESIZE_NONE (fixed size), XmRESIZE_ANY
		 (shrink or grow as needed), and XmRESIZE_GROW (grow only).

   Inherited Resources
       DrawingArea inherits behavior and resources from	the  following	super-
       classes.	For a complete description of each resource, refer to the ref-
       erence page for that superclass.

       +----------------------------------------------------------------------------------------------------+
       |			|	      XmManager	Resource Set	    |			   |	    |
       |Name			| Class			| Type		    | Default		   | Access |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNbottomShadowColor	| XmCBottomShadowColor	| Pixel		    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNbottomShadowPixmap	| XmCBottomShadowPixmap	| Pixmap	    | XmUNSPECIFIED_PIXMAP | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNforeground		| XmCForeground		| Pixel		    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhelpCallback		| XmCCallback		| XtCallbackList    | NULL		   | C	    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhighlightColor	| XmCHighlightColor	| Pixel		    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhighlightPixmap	| XmCHighlightPixmap	| Pixmap	    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNinitialFocus		| XmCInitialFocus	| Widget	    | NULL		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNlayoutDirection	| XmCLayoutDirection	| XmDirection	    | dynamic		   | CG	    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNnavigationType	| XmCNavigationType	| XmNavigationType  | XmTAB_GROUP	   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNpopupHandlerCallback	| XmCCallback		| XtCallbackList    | NULL		   | C	    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNshadowThickness	| XmCShadowThickness	| Dimension	    | 0			   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNstringDirection	| XmCStringDirection	| XmStringDirection | dynamic		   | CG	    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNtopShadowColor	| XmCTopShadowColor	| Pixel		    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNtopShadowPixmap	| XmCTopShadowPixmap	| Pixmap	    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNtraversalOn		| XmCTraversalOn	| Boolean	    | True		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNunitType		| XmCUnitType		| unsigned char	    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNuserData		| XmCUserData		| XtPointer	    | NULL		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       +------------------------+-----------------------+-------------------+----------------------+--------+
       +-----------------------------------------------------------------------+
       |		  |	Composite Resource Set	    |	      |	       |
       |Name		  | Class	      |	Type	    | Default |	Access |
       +------------------+-------------------+-------------+---------+--------+
       |XmNchildren	  | XmCReadOnly	      |	WidgetList  | NULL    |	G      |
       +------------------+-------------------+-------------+---------+--------+
       |XmNinsertPosition | XmCInsertPosition |	XtOrderProc | NULL    |	CSG    |
       +------------------+-------------------+-------------+---------+--------+
       |XmNnumChildren	  | XmCReadOnly	      |	Cardinal    | 0	      |	G      |
       +------------------+-------------------+-------------+---------+--------+
       +------------------+-------------------+-------------+---------+--------+
       +---------------------------------------------------------------------------------------------------------------+
       |			      |		      Core Resource SetName			      |	Class			      |	Type	       | Default	      |	Access |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNaccelerators		      |	XmCAccelerators		      |	XtAccelerators | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNancestorSensitive	      |	XmCSensitive		      |	Boolean	       | dynamic	      |	G      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNbackground		      |	XmCBackground		      |	Pixel	       | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNbackgroundPixmap	      |	XmCPixmap		      |	Pixmap	       | XmUNSPECIFIED_PIXMAP |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderColor		      |	XmCBorderColor		      |	Pixel	       | XtDefaultForeground  |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderPixmap		      |	XmCPixmap		      |	Pixmap	       | XmUNSPECIFIED_PIXMAP |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderWidth		      |	XmCBorderWidth		      |	Dimension      | 0		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNcolormap		      |	XmCColormap		      |	Colormap       | dynamic	      |	CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNdepth		      |	XmCDepth		      |	int	       | dynamic	      |	CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNdestroyCallback	      |	XmCCallback		      |	XtCallbackList | NULL		      |	C      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNheight		      |	XmCHeight		      |	Dimension      | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNinitialResourcesPersistent |	XmCInitialResourcesPersistent |	Boolean	       | True		      |	C      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNmappedWhenManaged	      |	XmCMappedWhenManaged	      |	Boolean	       | True		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNscreen		      |	XmCScreen		      |	Screen *       | dynamic	      |	CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNsensitive		      |	XmCSensitive		      |	Boolean	       | True		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNtranslations		      |	XmCTranslations		      |	XtTranslations | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNwidth		      |	XmCWidth		      |	Dimension      | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNx			      |	XmCPosition		      |	Position       | 0		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNy			      |	XmCPosition		      |	Position       | 0		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       +------------------------------+-------------------------------+----------------+----------------------+--------+
   Callback Information
       A pointer to the	following structure is passed  to  the	XmNexposeCall-
       back, XmNinputCallback, and XmNresizeCallback procedures:

       typedef struct
       {
	       int reason;
	       XEvent *	event;
	       Window window;
       } XmDrawingAreaCallbackStruct;

       reason	 Indicates why the callback was	invoked.

       event	 Points	 to  the  XEvent that triggered	the callback.  This is
		 NULL for the XmNresizeCallback.

       window	 Is set	to the widget window.

       A pointer to the	following structure is passed to  the  XmNconvertCall-
       back procedures:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Atom selection;
	       Atom target;
	       XtPointer source_data;
	       XtPointer location_data;
	       int flags;
	       XtPointer parm;
	       int parm_format;
	       unsigned	long parm_length;
	       int status;
	       XtPointer value;
	       Atom type;
	       int format;
	       unsigned	long length;
       } XmConvertCallbackStruct;

       reason	 Indicates why the callback was	invoked.

       event	 Points	 to the	XEvent that triggered the callback.  It	can be
		 NULL.

       selection Indicates the selection for which  conversion	is  being  re-
		 quested.   Possible values are	CLIPBOARD, PRIMARY, SECONDARY,
		 and _MOTIF_DROP.

       target	 Indicates the conversion target.

       source_data
		 Contains information about the	selection  source.   When  the
		 selection  is	_MOTIF_DROP,  source_data  is the DragContext.
		 Otherwise, it is NULL.

       location_data
		 Contains information about the	location of data  to  be  con-
		 verted.   If  the  value  is NULL, the	data to	be transferred
		 consists of the widget's current selection.

       flags	 Indicates the status of the  conversion.  Following  are  the
		 possible values:

		 XmCONVERTING_NONE
			   This	flag is	currently unused.

		 XmCONVERTING_PARTIAL
			   The	target	widget	was  able to be	converted, but
			   some	data was lost.

		 XmCONVERTING_SAME
			   The conversion target is the	source of the data  to
			   be transferred.

		 XmCONVERTING_TRANSACT
			   This	flag is	currently unused.

       parm	 Contains  parameter  data  for	 this target.  If no parameter
		 data exists, the value	is NULL.

		 When  selection  is  CLIPBOARD	 and  target  is  _MOTIF_CLIP-
		 BOARD_TARGETS or _MOTIF_DEFERRED_CLIPBOARD_TARGETS, the value
		 is the	requested operation (XmCOPY, XmMOVE, or	XmLINK).

       parm_format
		 Specifies whether the data in parm should be viewed as	a list
		 of  char,  short,  or long quantities.	 Possible values are 0
		 (when parm is NULL), 8	(when  the  data  in  parm  should  be
		 viewed	 as a list of chars), 16 (when the data	in parm	should
		 be viewed as a	list of	shorts), or 32 (when the data in  parm
		 should	 be viewed as a	list of	longs).	 Note that parm_format
		 symbolizes a data type, not the number	of bits	in  each  list
		 element.   For	example, on some machines, a parm_format of 32
		 means that the	data in	parm should be viewed  as  a  list  of
		 64-bit	quantities, not	32-bit quantities.

       parm_length
		 Specifies  the	number of elements of data in parm, where each
		 element has the size specified	by parm_format.	 When parm  is
		 NULL, the value is 0.

       status	 An IN/OUT member that specifies the status of the conversion.
		 The initial value is XmCONVERT_DEFAULT.  The callback	proce-
		 dure can set this member to one of the	following values:

		 XmCONVERT_DEFAULT
			   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 value
			   member.

		 XmCONVERT_MERGE
			   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
			   value  member.  This	value is intended for use with
			   targets that	result in lists	of data, such as  TAR-
			   GETS.

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

		 XmCONVERT_REFUSE
			   This	value means that the  callback	procedure  has
			   terminated  the conversion process without complet-
			   ing the requested  conversion.   The	 widget	 class
			   conversion  procedure,  if any, is not called after
			   the callback	procedures return.

       value	 An IN/OUT parameter that contains any data that the  callback
		 procedure  produces  as a result of the conversion.  The ini-
		 tial value is NULL.  If the callback procedure	sets this mem-
		 ber, it must ensure that the type, format, and	length members
		 correspond to the data	in value.  The callback	 procedure  is
		 responsible  for allocating, but not for freeing, memory when
		 it sets this member.

       type	 An IN/OUT parameter that indicates the	type of	 the  data  in
		 the value member.  The	initial	value is INTEGER.

       format	 An  IN/OUT parameter that specifies whether the data in value
		 should	be viewed as a list of char, short,  or	 long  quanti-
		 ties.	 The  initial  value is	8.  The	callback procedure can
		 set this member to 8 (for a list of char), 16 (for a list  of
		 short), or 32 (for a list of long).

       length	 An  IN/OUT  member  that  specifies the number	of elements of
		 data in value,	where each element has the size	symbolized  by
		 format.  The initial value is 0.

       A  pointer to the following callback structure is passed	to the XmNdes-
       tinationCallback	procedures:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Atom selection;
	       XtEnum operation;
	       int flags;
	       XtPointer transfer_id;
	       XtPointer destination_data;
	       XtPointer location_data;
	       Time time;
       } XmDestinationCallbackStruct;

       reason	 Indicates why the callback was	invoked.

       event	 Points	to the XEvent that triggered the callback.  It can  be
		 NULL.

       selection Indicates  the	selection for which data transfer is being re-
		 quested.  Possible values are CLIPBOARD, PRIMARY,  SECONDARY,
		 and _MOTIF_DROP.

       operation Indicates the type of transfer	operation requested.

		    o  When  the selection is PRIMARY, possible	values are Xm-
		       MOVE, XmCOPY, and XmLINK.

		    o  When the	selection is SECONDARY or CLIPBOARD,  possible
		       values are XmCOPY and XmLINK.

		    o  When  the selection is _MOTIF_DROP, possible values are
		       XmMOVE,	XmCOPY,	 XmLINK,  and  XmOTHER.	  A  value  of
		       XmOTHER means that the callback procedure must get fur-
		       ther information	from the  XmDropProcCallbackStruct  in
		       the destination_data member.

       flags	 Indicates  whether  or	not the	destination widget is also the
		 source	of the data to be transferred.	Following are the pos-
		 sible values:

		 XmCONVERTING_NONE
			   The	destination  widget  is	 not the source	of the
			   data	to be transferred.

		 XmCONVERTING_SAME
			   The destination widget is the source	of the data to
			   be transferred.

       transfer_id
		 Serves	as a unique ID to identify the transfer	transaction.

       destination_data
		 Contains  information about the destination.  When the	selec-
		 tion is _MOTIF_DROP, the callback procedures  are  called  by
		 the  drop  site's  XmNdropProc,  and  destination_data	 is  a
		 pointer to the	XmDropProcCallbackStruct passed	 to  the  XmN-
		 dropProc  procedure.  When the	selection is SECONDARY,	desti-
		 nation_data is	an Atom	representing a target recommmended  by
		 the  selection	 owner	for  use  in converting	the selection.
		 Otherwise, destination_data is	NULL.

       location_data
		 Contains information about the	location where data is	to  be
		 transferred.	The value is always NULL when the selection is
		 SECONDARY or CLIPBOARD.  If the value is NULL,	the data is to
		 be inserted at	the widget's cursor position. location_data is
		 only valid for	the duration of	a transfer.  Once  XmTransfer-
		 Done  procedures  start  to  be called, location_data will no
		 longer	be stable.

       time	 Indicates the time when the transfer operation	began.

   Translations
       XmDrawingArea inherits translations from	XmManager.  Before calling the
       XmManager actions, all events in	the inherited translations except <Bt-
       nMotion>, <EnterWindow>,	<LeaveWindow>, <FocusIn>, and <FocusOut>  also
       call the	DrawingAreaInput() action.

       XmDrawingArea has the following additional translations.	 The following
       key names are listed in the X standard key event	translation table syn-
       tax.   This  format  is the one used by Motif to	specify	the widget ac-
       tions corresponding to a	given key.  A brief overview of	the format  is
       provided	 under	VirtualBindings(3).  For a complete description	of the
       format, please refer to the X Toolkit Instrinsics Documentation.

       <BtnDown>:
		 DrawingAreaInput()

       <BtnUp>:	 DrawingAreaInput()

       <KeyDown>:
		 DrawingAreaInput() ManagerGadgetKeyInput()

       <KeyUp>:	 DrawingAreaInput()

   Action Routines
       The XmDrawingArea action	routines are

       DrawingAreaInput():
		 Unless	the event takes	place in a gadget, calls the callbacks
		 for XmNinputCallback

       ManagerGadgetKeyInput():
		 Causes	the current gadget to process a	keyboard event

   Additional Behavior
       The XmDrawingArea widget	has the	following additional behavior:

       <Expose>: Calls the callbacks for XmNexposeCallback

       <Widget Resize>:
		 Calls the callbacks for XmNresizeCallback

   Virtual Bindings
       The  bindings  for  virtual  keys are vendor specific.  For information
       about bindings for virtual buttons and keys, see	VirtualBindings(3).

RELATED
       Composite(3), Constraint(3),  Core(3),  XmCreateDrawingArea(3),	XmMan-
       ager(3),	XmVaCreateDrawingArea(3), and XmVaCreateManagedDrawingArea(3).

							      XmDrawingArea(3)

NAME | SYNOPSIS | DESCRIPTION | RELATED

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmDrawingArea&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help