


XmDisplay(3X)							XmDisplay(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmDDiissppllaayy - The Display widget class

SYNOPSIS


  ##iinncclluuddee <<XXmm//DDiissppllaayy..h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 unavailable.
  Each client has one XmDisplay	object for each	display	it accesses.

  An XmDisplay object is automatically created when the	application creates
  the first shell on a display (usually	accomplished by	a call to XXttAAppppIInnii--
  ttiiaalliizzee or XXttAAppppCCrreeaatteeSShheellll).	 It is not necessary to	create an XmDisplay
  object by any	other means.  An application can use the function
  XXmmGGeettXXmmDDiissppllaayy 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 application
  or user can supply initial values in a resource file.	 After creating	the
  first	shell on the display, the application can use XXmmGGeettXXmmDDiissppllaayy to
  obtain the widget ID of the XmDisplay	object and then	call XXttSSeettVVaalluueess to
  set the XmDisplay resources.

  XmDisplay resources specify the drag protocol	style for a client partici-
  pating in drag and drop transactions.	 There are two basic protocol types,
  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 information 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 between 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 CCoorree, CCoommppoossiittee,	SShheellll,
  WWMMSShheellll, VVeennddoorrSShheellll,	TTooppLLeevveellSShheellll, and AApppplliiccaattiioonnSShheellll classes.

  The class pointer is xxmmDDiissppllaayyCCllaassss.

  The class name is XXmmDDiissppllaayy.

  New Resources

  The following	table defines a	set of widget resources	used by	the program-
  mer 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 an ..XXddeeffaauullttss	file, remove the XXmmNN or	XXmmCC
  prefix and use the remaining letters.	 To specify one	of the defined values
  for a	resource in an ..XXddeeffaauullttss file,	remove the XXmm prefix and use the
  remaining letters (in	either lowercase or uppercase, but include any under-
  scores between words).  The codes in the access column indicate if the
  given	resource can be	set at creation	time (CC), set by using XXttSSeettVVaalluueess
  (SS), retrieved by using XXttGGeettVVaalluueess (GG), or is not applicable	(NN//AA).

			    XXmmDDiissppllaayy RReessoouurrccee SSeett
   ________________________________________________________________________
   NNaammee					 DDeeffaauulltt		     AAcccceessss
	 CCllaassss				       TTyyppee
   ________________________________________________________________________
   ________________________________________________________________________
   XmNdefaultVirtualBindings		 dynamic		     CG
	 DefaultVirtualBindings			String
   ________________________________________________________________________
   XmNdragInitiatorProtocolStyle	 XmDRAG_PREFER_RECEIVER	     CG
	 XmCDragInitiatorProtocolStyle		unsigned char
   ________________________________________________________________________
   XmNdragReceiverProtocolStyle		 XmDRAG_PREFER_PREREGISTER   CG
	 XmCDragReceiverProtocolStyle		unsigned char
   ________________________________________________________________________

  XXmmNNddeeffaauullttVViirrttuuaallBBiinnddiinnggss
	    Specifies the default virtual bindings for the display.  Follow-
	    ing	is an example of a specification for the ddeeffaauullttVViirrttuuaallBBiinndd--
	    iinnggss resource in a resource	file:
		 *defaultVirtualBindings: \
		      osfBackSpace   :	  <Key>BackSpace\n\
		      osfInsert	     :	  <Key>InsertChar\n\
		 ...
		      osfDelete	     :	  <Key>DeleteChar

  XXmmNNddrraaggIInniittiiaattoorrPPrroottooccoollSSttyyllee
	    Specifies the drag and drop	protocol requirements or preference
	    when the client is an initiator.  The possible values are:

	    XXmmDDRRAAGG__PPRREERREEGGIISSTTEERR
	      As an initiator, this client does	not use	the dynamic protocol
	      and can only arrange visual effects with receivers who provide
	      preregistered information.

	    XXmmDDRRAAGG__DDYYNNAAMMIICC
	      As an initiator, this client does	not make use of	any prere-
	      gistered drop site information made available by other clients,
	      and can only arrange visual effects with receivers who use the
	      dynamic protocol.

	    XXmmDDRRAAGG__NNOONNEE
	      Specifies	that drag and drop is disabled for this	client.

	    XXmmDDRRAAGG__DDRROOPP__OONNLLYY
	      As an initiator, this client does	not use	either the prere-
	      gistered drop site information or	the dynamic 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.

	    XXmmDDRRAAGG__PPRREEFFEERR__DDYYNNAAMMIICC
	      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.

	    XXmmDDRRAAGG__PPRREEFFEERR__PPRREERREEGGIISSTTEERR
	      As an initiator, this client can support both the	preregister
	      and dynamic protocols, but prefers to use	the preregister	pro-
	      tocol whenever possible in order to accommodate performance
	      needs or to provide consistent drag-over feedback.

	    XXmmDDRRAAGG__PPRREEFFEERR__RREECCEEIIVVEERR
	      Indicates	that this client can support both preregister and
	      dynamic protocols, but will defer	to the preference of the
	      receiver client.	This value is valid only for the XXmmNNddrraaggIInnii--
	      ttiiaattoorrPPrroottooccoollSSttyyllee resource, and	is its default value.

  XXmmNNddrraaggRReecceeiivveerrPPrroottooccoollSSttyyllee
	    Specifies the drag and drop	protocol requirements or preference
	    when this client is	a receiver.  The values	are:

	    XXmmDDRRAAGG__PPRREERREEGGIISSTTEERR
	      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 prere-
	      gistered information.

	    XXmmDDRRAAGG__DDYYNNAAMMIICC
	      As a receiver, this client uses the dynamic protocol and does
	      not preregister drop site	information.  It can only arrange
	      visual effects with initiators who use the dynamic protocol.

	    XXmmDDRRAAGG__NNOONNEE
	      Specifies	that drag and drop is disabled for this	client.

	    XXmmDDRRAAGG__DDRROOPP__OONNLLYY
	      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.

	    XXmmDDRRAAGG__PPRREEFFEERR__DDYYNNAAMMIICC
	      As a receiver, this client can support both the preregister and
	      dynamic protocols, but prefers to	use dynamic protocol whenever
	      possible in order	to provide high-quality	drag-under feedback.

	    XXmmDDRRAAGG__PPRREEFFEERR__PPRREERREEGGIISSTTEERR
	      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 actual protocol used between an initiator	and a receiver is based	on
  the protocol style of	the receiver and initiator.  The decision matrix is
  as follows:
       _______________________________________________________
		      |
       Drag Initiator |	      Drag Receiver Protocol Style
       Protocol	Style |
       ---------------|---------------------------------------
		      |
		      |	Pre    Prefer Pre    Prefer Dyn	   Dyn
       ---------------|---------------------------------------
	Pre	      |	Pre    Pre	     Pre	   D-O
		      |
	Prefer Pre    |	Pre    Pre	     Pre	   Dyn
		      |
	Prefer Rec    |	Pre    Pre	     Dyn	   Dyn
		      |
	Prefer Dyn    |	Pre    Dyn	     Dyn	   Dyn
		      |
	Dyn	      |	D-O    Dyn	     Dyn	   Dyn
       _______________|_______________________________________

	  Pre =	Preregister
	  Dyn =	Dynamic
	  D-P =	Drop Only

  The value XXmmDDRRAAGG__NNOONNEE	does not appear	in the above matrix.  When specified
  for either the initiator or receiver side, XXmmDDRRAAGG__NNOONNEE implies that drag
  and drop transactions	are not	supported.  A value of XXmmDDRRAAGG__DDRROOPP__OONNLLYY	(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 explicitly has	specified
  XXmmDDRRAAGG__DDRROOPP__OONNLLYY.

  Inherited Resources

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

RELATED	INFORMATION
  AApppplliiccaattiioonnSShheellll((33XX)),	CCoommppoossiittee((33XX)), CCoorree((33XX)), TTooppLLeevveellSShheellll((33XX)),
  VVeennddoorrSShheellll((33XX)), WWMMSShheellll((33XX)),	XXmmGGeettXXmmDDiissppllaayy((33XX)), and	XXmmSSccrreeeenn((33XX)).















































