XmDisplay(3X)XmDisplay(3X)NAMEXmDisplay — The Display widget class
SYNOPSIS
#include <Xm/Display.h>
VERSION
This page documents version 1.2 of the Motif library.
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 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. 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 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 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
Specifies the default virtual bindings for the display. Following is
an example of a specification for the defaultVirtualBindings resource
in a resource file: *defaultVirtualBindings: \ osf‐
BackSpace : <Key>BackSpace\n\ osfIn‐
sert : <Key>InsertChar\n\ ...
osfDelete : <Key>DeleteChar Specifies the drag and drop
protocol requirements or preference when the client is an initiator.
The possible values are As an initiator, this client does not use the
dynamic protocol and can only arrange visual effects with receivers who
provide preregistered information. 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. Specifies that drag and drop is disabled
for this client. As an initiator, this client does not use either the
preregistered drop site information or the dynamic protocol. It sup‐
ports 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. 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. As an
initiator, this client can support both the preregister and dynamic
protocols, but prefers to use the preregister protocol whenever possi‐
ble in order to accommodate performance needs or to provide consistent
drag-over feedback. Indicates that this client can support both pre‐
register and dynamic protocols, but will defer to the preference of the
receiver client. This value is valid only for the XmNdragInitiatorPro‐
tocolStyle resource, and is its default value. Specifies the drag and
drop protocol requirements or preference when this client is a
receiver. The values are 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 preregis‐
tered information. 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.
Specifies that drag and drop is disabled for this client. As a
receiver, this client neither uses the dynamic protocol nor preregis‐
ters drop site information. It supports dropping, and when dragging
over this client, valid feedback is always provided, but there are no
other visual effects. 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.
As a receiver, this client can support both the preregister and dynamic
protocols, but prefers to use the preregister protocol whenever possi‐
ble 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
───────────────────────────────────────────────────────────────────────────────────
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 XmDRAG_NONE does not appear in the above matrix. When speci‐
fied for either the initiator or receiver side, XmDRAG_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
explicitly has specified XmDRAG_DROP_ONLY.
Inherited Resources
All of the superclass resources inherited by XmDisplay are designated
N/A (not applicable).
RELATED INFORMATIONApplicationShell(3X), Composite(3X), Core(3X), TopLevelShell(3X), Ven‐
dorShell(3X), WMShell(3X), XmGetXmDisplay(3X), and XmScreen(3X).
XmDisplay(3X)