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

FreeBSD Manual Pages

  
 
  

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

NAME
       XmDisplay -- The	Display	widget class

SYNOPSIS
       #include	<Xm/Display.h>

DESCRIPTION
       The  XmDisplay object is	used by	the Motif widgets to store information
       that is specific	to a display. It also allows  the  toolkit  to	access
       certain	information  on	widget hierarchies that	would otherwise	be un-
       available. Each client has one XmDisplay	object for each	display	it ac-
       cesses.

       An  XmDisplay object is automatically created when the application cre-
       ates the	first shell on a display (usually accomplished by  a  call  to
       XtAppInitialize or XtAppCreateShell).  It is not	necessary to create an
       XmDisplay object	by any other means.  An	application can	use the	 func-
       tion XmGetXmDisplay to obtain the widget	ID of the XmDisplay object for
       a given display.

       An application cannot supply initial values for XmDisplay resources  as
       arguments to a call to any function that	creates	widgets.  The applica-
       tion or user can	supply initial values in a resource file.  After  cre-
       ating  the  first  shell	 on  the  display,  the	 application  can  use
       XmGetXmDisplay to obtain	the widget ID of the XmDisplay object and then
       call XtSetValues	to set the XmDisplay resources.

       XmDisplay  resources  specify the drag protocol style for a client par-
       ticipating in drag and drop transactions. The two basic protocol	 types
       are  preregister	 and dynamic. When a preregister protocol is used, the
       toolkit handles any communication between the  initiator	 and  receiver
       clients	and  displays  the appropriate drag-over and drag-under	visual
       effects.	A client registers its drop sites in advance and this informa-
       tion  is	 stored	in a property for each top-level window. When the drag
       pointer enters a	top-level window, the drop site	information is read by
       the  initiator.	A  dynamic  protocol allows the	source and destination
       clients to dynamically communicate drag and drop	state information  be-
       tween  each  other, and to update their respective visuals accordingly.
       The toolkit provides drop site information as the pointer  passes  over
       any  given  drop	site.  In this mode, a receiver	can supply a procedure
       to generate its own drag-under effects.

   Classes
       Display inherits	behavior and resources from  Core,  Composite,	Shell,
       WMShell,	VendorShell, TopLevelShell, and	ApplicationShell classes.

       The class pointer is xmDisplayClass.

       The class name is XmDisplay.

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

       +-----------------------------------------------------------------------------------------------------------------+
       |			      |		     XmDisplay ResourceSet	       |			|	 |
       |Name			      |	Class			      |	Type	       | Default		| Access |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNdefaultButtonEmphasis      |	XmCDefaultButtonEmphasis      |	XtEnum	       | XmEXTERNAL_HIGHLIGHT	| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNdefaultVirtualBindings     |	XmCDefaultVirtualBindings     |	String	       | dynamic		| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNdragInitiatorProtocolStyle |	XmCDragInitiatorProtocolStyle |	unsigned char  | XmDRAG_PREFER_RECEIVER	| CG	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNdragReceiverProtocolStyle  |	XmCDragReceiverProtocolStyle  |	unsigned char  | XmDRAG_PREFER_DYNAMIC	| CG	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNdragStartCallback	      |	XmCCallback		      |	XtCallbackList | NULL			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNenableBtn1Transfer	      |	XmCEnableBtn1Transfer	      |	XtEnum	       | XmOFF			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNenableButtonTab	      |	XmCEnableButtonTab	      |	Boolean	       | False			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNenableDragIcon	      |	XmCEnableDragIcon	      |	Boolean	       | False			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNenableEtchedInMenu	      |	XmCEnableEtchedInMenu	      |	Boolean	       | False			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNenableToggleColor	      |	XmCEnableToggleColor	      |	Boolean	       | False			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNenableToggleVisual	      |	XmCEnableToggleVisual	      |	Boolean	       | False			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNenableUnselectableDrag     |	XmCEnableUnselectableDrag     |	Boolean	       | True			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNenableWarp		      |	XmCEnableWarp		      |	XtEnum	       | True			| CSG	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNmotifVersion		      |	XmCMotifVersion		      |	int	       | XmVERSION		| CSG	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNnoFontCallback	      |	XmCCallback		      |	XtCallbackList | NULL			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNnoRenditionCallback	      |	XmCCallback		      |	XtCallbackList | NULL			| C	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       |XmNuserData		      |	XmCUserData		      |	XtPointer      | NULL			| CSG	 |
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       +------------------------------+-------------------------------+----------------+------------------------+--------+
       XmNdefaultButtonEmphasis
		 Specifies whether to change the look of the PushButton	widget
		 and gadget that have the XmNshowAsDefault resource set.  When
		 the  PushButton  is  the default, it has an etched out	button
		 which is enclosed with	another	etched in border.  The	XmNde-
		 faultButtonEmphasis has the follow possible values, which af-
		 fect the location cursor:

		 XmINTERNAL_HIGHLIGHT
			   Causes the location cursor to appear	in between the
			   two etched borders to minimize the space required.

		 XmEXTERNAL_HIGHLIGHT
			   Causes  the	PushButton to draw the location	cursor
			   outside the second border.

       XmNdefaultVirtualBindings
		 Specifies the default virtual bindings	for the	display.  Fol-
		 lowing	is an example of a specification for the defaultVirtu-
		 alBindings resource in	a resource file:

       *defaultVirtualBindings:	\
	       osfBackSpace:	   <Key>BackSpace	\n\
	       osfInsert:	<Key>InsertChar	     \n\
	       osfDelete:	<Key>DeleteChar	     \n\
	       ...
	       osfLeft:	      <Key>left, Ctrl<Key>H

       XmNdragInitiatorProtocolStyle
		 Specifies the drag and	drop protocol requirements or  prefer-
		 ence when the client is an initiator. The possible values are

		 XmDRAG_PREREGISTER
			   As  an  initiator, this client does not use the dy-
			   namic protocol and can only arrange visual  effects
			   with	 receivers  who	provide	preregistered informa-
			   tion.

		 XmDRAG_DYNAMIC
			   As an initiator, this client	does not make  use  of
			   any preregistered drop site information made	avail-
			   able	by other clients, and can only arrange	visual
			   effects  with  receivers who	use the	dynamic	proto-
			   col.

		 XmDRAG_NONE
			   Specifies that drag and drop	is disabled  for  this
			   client.

		 XmDRAG_DROP_ONLY
			   As  an  initiator,  this client does	not use	either
			   the preregistered drop site information or the  dy-
			   namic  protocol. It supports	dragging, and any time
			   the cursor is over a	client that supports drag  and
			   drop,  valid	 feedback  is  provided.  There	are no
			   other visual	effects.

		 XmDRAG_PREFER_DYNAMIC
			   As an initiator, this client	can support  both  the
			   preregister	and  dynamic protocols,	but prefers to
			   use dynamic protocols whenever possible in order to
			   provide high-quality	drag-under feedback.

		 XmDRAG_PREFER_PREREGISTER
			   As  an  initiator, this client can support both the
			   preregister and dynamic protocols, but  prefers  to
			   use	the  preregister protocol whenever possible in
			   order to accommodate	performance needs or  to  pro-
			   vide	consistent drag-over feedback.

		 XmDRAG_PREFER_RECEIVER
			   Indicates that this client can support both prereg-
			   ister and dynamic protocols,	but will defer to  the
			   preference  of  the receiver	client.	 This value is
			   valid only  for  the	 XmNdragInitiatorProtocolStyle
			   resource, and is its	default	value.

       XmNdragReceiverProtocolStyle
		 Specifies  the	drag and drop protocol requirements or prefer-
		 ence when this	client is a receiver. The values are

		 XmDRAG_PREREGISTER
			   As a	receiver, this client preregisters  drop  site
			   information	and does not use the dynamic protocol.
			   It can only arrange visual effects with  initiators
			   who make use	of the preregistered information.

		 XmDRAG_DYNAMIC
			   As  a receiver, this	client uses the	dynamic	proto-
			   col and does	not preregister	drop site information.
			   It  can only	arrange	visual effects with initiators
			   who use the dynamic protocol.

		 XmDRAG_NONE
			   Specifies that drag and drop	is disabled  for  this
			   client.

		 XmDRAG_DROP_ONLY
			   As a	receiver, this client neither uses the dynamic
			   protocol nor	preregisters drop site information. It
			   supports  dropping,	and  when  dragging  over this
			   client, valid  feedback  is	always	provided,  but
			   there are no	other visual effects.

		 XmDRAG_PREFER_DYNAMIC
			   As  a  receiver,  this  client can support both the
			   preregister and dynamic protocols, but  prefers  to
			   use the dynamic protocol whenever possible in order
			   to provide high-quality drag-under feedback.

		 XmDRAG_PREFER_PREREGISTER
			   As a	receiver, this client  can  support  both  the
			   preregister	and  dynamic protocols,	but prefers to
			   use the preregister protocol	whenever  possible  in
			   order to accommodate	performance needs.

		 The  default value of this resource is	dependent on the capa-
		 bilities of the display. If the display  supports  the	 shape
		 extension,  allowing  the dynamic protocol to use arbitrarily
		 sized drag cursors, the  default  of  this  resource  is  Xm-
		 DRAG_PREFER_DYNAMIC,  otherwise  the  default	is XmDRAG_PRE-
		 FER_PREREGISTER.

		 The actual protocol used between an initiator and a  receiver
		 is based on the protocol style	of the receiver	and initiator.
		 The decision matrix is	described in the following table.

		 +---------------+----------------------------------------------+
		 |Drag Initiator |				|   |	|	|
		 |		 | Drag	Receiver Protocol Style	|   |	|	|
		 +---------------+------------------------------+---+---+-------+
		 +---------------+------------------------------+---+---+-------+
		 +---------------+------------------------------+---+---+-------+
		 +---------------+------------------------------+---+---+-------+
		 +---------------+------------------------------+---+---+-------+
		 +---------------+------------------------------+---+---+-------+
		 +---------------+------------------------------+---+---+-------+
		 The value XmDRAG_NONE does not	appear	in  the	 matrix.  When
		 specified  for	 either	 the  initiator	 or receiver side, Xm-
		 DRAG_NONE implies that	drag and  drop	transactions  are  not
		 supported.  A	value  of XmDRAG_DROP_ONLY (Drop Only) results
		 when an initiator and	receiver  cannot  compromise  protocol
		 styles,  that	is, one	client requires	dynamic	mode while the
		 other can only	support	preregister mode, or if	either explic-
		 itly has specified XmDRAG_DROP_ONLY.

       XmNdragStartCallback
		 Specifies the list of callbacks that are invoked when the Xm-
		 DragStart function is called. The type	of structure whose ad-
		 dress	is  passed  to	this  callback is XmDragStartCallback-
		 Struct.  The callback reason is XmCR_DRAG_START.

       XmNenableBtn1Transfer
		 Specifies if selection	and transfer actions are integrated on
		 Btn1  and extend actions are activated	on Btn2. This resource
		 can take the following	values:

		 XmOFF	   Disables integration	and  selection	activation  on
			   Btn1.

		 XmBUTTON2_TRANSFER
			   Enables  integration	 and  selection	 activation on
			   Btn1	and transfer on	Btn2.

		 XmBUTTON2_ADJUST
			   Enables integration	and  selection	activation  on
			   Btn1	and adjust on Btn2.

		 This  resource	 affects the actions of	Text, TextField, List,
		 and Container.

       XmNenableButtonTab
		 Specifies if the action for the  <Tab>	 key  (KNextField  and
		 KPrevField actions) is	to be modified.	 A value of True modi-
		 fies the key to move as an arrow key until the	boundary of  a
		 tab group is reached. Then, at	the boundary of	the tab	group,
		 KNextField and	KPrevField will	move to	the next  or  previous
		 tab group, respectively. A value of False does	not cause mod-
		 ification.

       XmNenableDragIcon
		 Specifies which set of	icons are to be	used  for  system  de-
		 fault	cursors	 during	 drag  and drop	operations. A value of
		 False specifies that earlier versions of Motif	release	 icons
		 are  used, a value of True specifies that alternate icons are
		 used. This resource affects both  the	16x16  and  the	 32x32
		 icons that the	system defaults	for each of the	Screen objects
		 associated with this display.

       XmNenableEtchedInMenu
		 Specifies the shadowing of the	button widgets and gadgets  in
		 menus	when  the control is activated.	A value	of True	causes
		 the selected menu to be drawn with the	shadow etched in; this
		 shadow	 style	is  consistent with the	selected appearance of
		 other button widgets outside  of  menus.  A  value  of	 False
		 causes	 the  selected	menu to	be draw	with the shadow	etched
		 out. This resource affects the	actions	of PushButton, Toggle-
		 Button,  and  CascadeButton widgets and gadgets when they are
		 children of Menu.

		 When this resource is set, the	background of a	 button	 in  a
		 menu  uses  the  XmNselectColor  (derived from	the XmNselect-
		 Pixel)	when armed as a	default. A PushButton uses the XmNarm-
		 Color	if  it	is defined. A ToggleButton uses	the XmNselect-
		 Color if XmNindicatorOn is False and XmNfillOnSelect is True.

       XmNenableToggleColor
		 Specifies how to determine the	default	value  of  the	XmNse-
		 lectColor resource of ToggleButton and	ToggleButtonGadget.  A
		 value of True causes the default value	of  XmNselectColor  to
		 be  set  to the value of XmNhighlightColor.  A	value of False
		 causes	the default value of XmNselectColor to be set  to  the
		 value	of  XmNbackground.  This resource only affects the ap-
		 pearance of ToggleButton widgets  and	gadgets	 that  are  in
		 XmONE_OF_MANY	or  XmONE_OF_MANY_ROUND	mode. In addition, Xm-
		 NenableToggleColor only influences the	default	value of XmNs-
		 electColor.  That is, if the user or application sets a value
		 for XmNselectColor, then XmNenableToggleColor is ignored.

       XmNenableToggleVisual
		 Specifies the visual appearance of  the  ToggleButton	widget
		 and/or	gadget.	This resource affects the default value	of the
		 ToggleButton[Gadget] XmNindicatorType and XmNindicatorOn  re-
		 sources.  When	 the ToggleButton is in	a RadioBox, a value of
		 True causes the XmONE_OF_MANY_ROUND (a	shadowed circle) to be
		 the default.  Otherwise, when this resource is	True, the Tog-
		 gleButton  XmNindicatorOn  resource  causes  a	  default   of
		 XmN_OF_MANY,  which  will  be	a shadowed square with a check
		 mark (check box).

		 A value of False causes the following:

		 XmONE_OF_MANY
			   Is a	shadowed diamond.

		 XmN_OF_MANY
			   Is a	shadowed square.

       XmNenableUnselectableDrag
		 Specifies whether or not it is	possible to  drag  from	 Label
		 and  Scale.   A  value	 of  True enables the drag; a value of
		 False disables	it.

       XmNenableWarp
		 Specifies if an application is	allowed	to  warp  the  pointer
		 from  the  user.  A value of True enables warping, a value of
		 False does not.

       XmNmotifVersion
		 Specifies the current version of Motif	that the  current  im-
		 plementation is supposed to behave like. By default, this re-
		 source	gets its value from release values in Xm.h.

       XmNnoFontCallback
		 This callback is called whenever a rendition attempts to load
		 a  font  or fontset and fails.	This can happen	on creation if
		 the font is specified as XmLOAD_IMMEDIATE or when an  attempt
		 is  made  to render an	XmString using a font specified	as Xm-
		 LOAD_DEFERRED.	An application can have	this callback  attempt
		 to  remedy  this  problem by calling XmRenditionUpdate	on the
		 input rendition to provide a font for the widget to use. This
		 may  be  done by either providing an an alternative font name
		 to be loaded using the	XmNfontName and	XmNfontType  resources
		 or  with  an  already loaded font using the XmNfont resource.
		 The callback reason is	XmCR_NO_FONT. This callback  uses  the
		 XmDisplayCallbackStruct structure.

       XmNnoRenditionCallback
		 This callback is called whenever an attempt is	made to	render
		 a segment with	a RENDITION tag	which does not match any  ren-
		 ditions  in  a	 given	render	table.	The callback reason is
		 XmCR_NO_RENDITION. This callback uses the  XmDisplayCallback-
		 Struct	structure.

		 An  application can have this callback	attempt	to remedy this
		 problem by creating a new rendition with the  given  tag  and
		 adding	it to render_table.

		 The XmNnoRenditionCallback should deallocate the render table
		 passed	in in the render_table field of	 the  callback	struc-
		 ture.	Note  that the table will automatically	be deallocated
		 if the	XmRenderTableAddRenditions function is called  on  it.
		 The  callback should NOT deallocate the modified render table
		 that is passed	back to	Motif in the  render_table  field.  If
		 the  application  wishes to manipulate	this render table fur-
		 ther, it should make a	copy with the XmRenderTableCopy	 func-
		 tion before returning from the	callback.

       XmNuserData
		 Specifies  a  client data pointer for applications. An	inter-
		 nally unused resource.

   Inherited Resources
       All of the superclass resources inherited by XmDisplay  are  designated
       N/A (not	applicable).

   Callback Information
       A pointer to the	following structure is passed to the XmNdragStartCall-
       back callback:

       typedef struct
       {
	       int reason;
	       XEvent  *event;
	       Widget timeStamp;
	       Boolean doit;
       }XmDragStartCallbackStruct;

       reason	 Indicates why the callback was	invoked

       event	 Points	to the XEvent that triggered the callback

       widget	 Indicates the ID of the widget	from which the drag was	initi-
		 ated.

       doit	 Is  an	 IN/OUT	 member	 that allows the callback to determine
		 whether to continue with the drag or cancel. Setting doit  to
		 False will cancel the drag. The default value is NULL.

       A pointer to the	following structure is passed to the XmNnoFontCallback
       and XmNnoRenditionCallback callbacks:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       XmRendition rendition;
	       char *font_name;
	       XmRenderTable render_table;
	       XmStringTag tag;
       }XmDisplayCallbackStruct;

       reason	 Indicates why the callback was	invoked.

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

       rendition Specifies the rendition with the missing font.

       font_name Specifies the name of the font	or font	set which could	not be
		 loaded.

       render_table
		 Specifies the render table with the missing rendition.

       tag	 Specifies the tag of the missing rendition.

       The following table describes the  reasons  for	which  the  individual
       callback	structure fields are valid.

       +------------------+----------------------+
       |Reason		  | Valid Fields	 |
       +------------------+----------------------+
       |XmCR_NO_FONT	  | rendition, font_name |
       +------------------+----------------------+
       |XmCR_NO_RENDITION | render_table, tag	 |
       +------------------+----------------------+
       +------------------+----------------------+
RELATED
       ApplicationShell(3),  Composite(3),  Core(3), TopLevelShell(3), Vendor-
       Shell(3), WMShell(3), XmGetXmDisplay(3),	and XmScreen(3).

								  XmDisplay(3)

NAME | SYNOPSIS | DESCRIPTION | RELATED

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

home | help