XmDisplay(3X) UNIX System V XmDisplay(3X)
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 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 XtAppInitialize or
XtAppCreateShell). It is not necessary to create an
XmDisplay object by any other means. An application can use
the function 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 application or user can supply initial
values in a resource file. After creating 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 participating 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 Core,
Composite, Shell, WMShell, VendorShell, TopLevelShell, and
1 (printed 6/8/92)
XmDisplay(3X) UNIX System V XmDisplay(3X)
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 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 an .Xdefaults file, remove the XmN or XmC
prefix and use the remaining letters. To specify one of the
defined values for a resource in an .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 Resource Set
Name Class Type Default Access
__________________________________________________________________________________________________________________
XmNdefaultVirtualBindings DefaultVirtualBindings String dynamic CG
XmNdragInitiatorProtocolStyle XmCDragInitiatorProtocolStyle unsigned char XmDRAG_PREFER_RECEIVER CG
XmNdragReceiverProtocolStyle XmCDragReceiverProtocolStyle unsigned char XmDRAG_PREFER_PREREGISTER CG
XmNdefaultVirtualBindings
Specifies the default virtual bindings for the
display. Following is an example of a
specification for the defaultVirtualBindings
resource in a resource file:
*defaultVirtualBindings: \
osfBackSpace : <Key>BackSpace\n\
osfInsert : <Key>InsertChar\n\
...
osfDelete : <Key>DeleteChar
XmNdragInitiatorProtocolStyle
Specifies the drag and drop protocol requirements
or preference when the client is an initiator.
The possible values are
XmDRAGPREREGISTER
As an initiator, this client does not use the
dynamic protocol and can only arrange visual
effects with receivers who provide preregistered
information.
2 (printed 6/8/92)
XmDisplay(3X) UNIX System V XmDisplay(3X)
XmDRAGDYNAMIC
As an initiator, this client does not make use
of any preregistered drop site information made
available by other clients, and can only arrange
visual effects with receivers who use the
dynamic protocol.
XmDRAGNONE
Specifies that drag and drop is disabled for
this client.
XmDRAGDROPONLY
As an initiator, this client does not use either
the preregistered 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.
XmDRAGPREFERDYNAMIC
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.
XmDRAGPREFERPREREGISTER
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 provide consistent drag-over
feedback.
XmDRAGPREFERRECEIVER
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
XmNdragInitiatorProtocolStyle resource, and is
its default value.
XmNdragReceiverProtocolStyle
Specifies the drag and drop protocol requirements
or preference when this client is a receiver. The
values are
XmDRAGPREREGISTER
As a receiver, this client preregisters drop
site information and does not use the dynamic
3 (printed 6/8/92)
XmDisplay(3X) UNIX System V XmDisplay(3X)
protocol. It can only arrange visual effects
with initiators who make use of the
preregistered information.
XmDRAGDYNAMIC
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.
XmDRAGNONE
Specifies that drag and drop is disabled for
this client.
XmDRAGDROPONLY
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.
XmDRAGPREFERDYNAMIC
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.
XmDRAGPREFERPREREGISTER
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 _______________________________________________________________
Preregister Prefer Preregister Prefer Dynamic Dynamic
__________________________________________________________________________________
Preregister Preregister Preregister Preregister Drop Only
__________________________________________________________________________________
4 (printed 6/8/92)
XmDisplay(3X) UNIX System V XmDisplay(3X)
Prefer Preregister Preregister Preregister Preregister Dynamic
__________________________________________________________________________________
Prefer Receiver Preregister Preregister Dynamic Dynamic
__________________________________________________________________________________
Prefer Dynamic Preregister Dynamic Dynamic Dynamic
__________________________________________________________________________________
Dynamic Drop Only Dynamic Dynamic Dynamic
The value XmDRAGNONE does not appear in the above
matrix. When specified for either the initiator
or receiver side, XmDRAGNONE implies that drag
and drop transactions are not supported. A value
of XmDRAGDROPONLY (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
XmDRAGDROPONLY.
Inherited Resources
All of the superclass resources inherited by XmDisplay are
designated N/A (not applicable).
RELATED INFORMATION
ApplicationShell(3X), Composite(3X), Core(3X),
TopLevelShell(3X), VendorShell(3X), WMShell(3X),
XmGetXmDisplay(3X), and XmScreen(3X).
5 (printed 6/8/92)