1XmDisplay(library call)                                XmDisplay(library call)
2
3
4

NAME

6       XmDisplay — The Display widget class
7

SYNOPSIS

9       #include <Xm/Display.h>
10

DESCRIPTION

12       The  XmDisplay object is used by the Motif widgets to store information
13       that is specific to a display. It also allows  the  toolkit  to  access
14       certain  information  on  widget  hierarchies  that  would otherwise be
15       unavailable. Each client has one XmDisplay object for each  display  it
16       accesses.
17
18       An  XmDisplay object is automatically created when the application cre‐
19       ates the first shell on a display (usually accomplished by  a  call  to
20       XtAppInitialize or XtAppCreateShell).  It is not necessary to create an
21       XmDisplay object by any other means.  An application can use the  func‐
22       tion XmGetXmDisplay to obtain the widget ID of the XmDisplay object for
23       a given display.
24
25       An application cannot supply initial values for XmDisplay resources  as
26       arguments to a call to any function that creates widgets.  The applica‐
27       tion or user can supply initial values in a resource file.  After  cre‐
28       ating  the  first  shell  on  the  display,  the  application  can  use
29       XmGetXmDisplay to obtain the widget ID of the XmDisplay object and then
30       call XtSetValues to set the XmDisplay resources.
31
32       XmDisplay  resources  specify the drag protocol style for a client par‐
33       ticipating in drag and drop transactions. The two basic protocol  types
34       are  preregister  and dynamic. When a preregister protocol is used, the
35       toolkit handles any communication between the  initiator  and  receiver
36       clients  and  displays  the appropriate drag-over and drag-under visual
37       effects. A client registers its drop sites in advance and this informa‐
38       tion  is  stored in a property for each top-level window. When the drag
39       pointer enters a top-level window, the drop site information is read by
40       the  initiator.  A  dynamic  protocol allows the source and destination
41       clients to dynamically communicate  drag  and  drop  state  information
42       between each other, and to update their respective visuals accordingly.
43       The toolkit provides drop site information as the pointer  passes  over
44       any  given  drop site.  In this mode, a receiver can supply a procedure
45       to generate its own drag-under effects.
46
47   Classes
48       Display inherits behavior and resources from  Core,  Composite,  Shell,
49       WMShell, VendorShell, TopLevelShell, and ApplicationShell classes.
50
51       The class pointer is xmDisplayClass.
52
53       The class name is XmDisplay.
54
55   New Resources
56       The  following table defines a set of widget resources used by the pro‐
57       grammer to specify data. The programmer can also set the resource  val‐
58       ues  for  the  inherited classes to set attributes for this widget.  To
59       reference a resource by name or by class in a .Xdefaults  file,  remove
60       the XmN or XmC prefix and use the remaining letters.  To specify one of
61       the defined values for a resource in a .Xdefaults file, remove  the  Xm
62       prefix and use the remaining letters (in either lowercase or uppercase,
63       but include any underscores between words). The  codes  in  the  access
64       column  indicate if the given resource can be set at creation time (C),
65       set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
66       not applicable (N/A).
67
68       ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
69       │                              │              XmDisplay Resourc│e Set            │                        │        │
70Name                          Class                         Type           Default                Access 
71       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
72       │XmNdefaultButtonEmphasis      │ XmCDefaultButtonEmphasis      │ XtEnum         │ XmEXTERNAL_HIGHLIGHT   │ C      │
73       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
74       │XmNdefaultVirtualBindings     │ XmCDefaultVirtualBindings     │ String         │ dynamic                │ C      │
75       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
76       │XmNdragInitiatorProtocolStyle │ XmCDragInitiatorProtocolStyle │ unsigned char  │ XmDRAG_PREFER_RECEIVER │ CG     │
77       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
78       │XmNdragReceiverProtocolStyle  │ XmCDragReceiverProtocolStyle  │ unsigned char  │ XmDRAG_PREFER_DYNAMIC  │ CG     │
79       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
80       │XmNdragStartCallback          │ XmCCallback                   │ XtCallbackList │ NULL                   │ C      │
81       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
82       │XmNenableBtn1Transfer         │ XmCEnableBtn1Transfer         │ XtEnum         │ XmOFF                  │ C      │
83       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
84       │XmNenableButtonTab            │ XmCEnableButtonTab            │ Boolean        │ False                  │ C      │
85       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
86       │XmNenableDragIcon             │ XmCEnableDragIcon             │ Boolean        │ False                  │ C      │
87       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
88       │XmNenableEtchedInMenu         │ XmCEnableEtchedInMenu         │ Boolean        │ False                  │ C      │
89       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
90       │XmNenableToggleColor          │ XmCEnableToggleColor          │ Boolean        │ False                  │ C      │
91       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
92       │XmNenableToggleVisual         │ XmCEnableToggleVisual         │ Boolean        │ False                  │ C      │
93       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
94       │XmNenableUnselectableDrag     │ XmCEnableUnselectableDrag     │ Boolean        │ True                   │ C      │
95       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
96       │XmNenableWarp                 │ XmCEnableWarp                 │ XtEnum         │ True                   │ CSG    │
97       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
98       │XmNmotifVersion               │ XmCMotifVersion               │ int            │ XmVERSION              │ CSG    │
99       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
100       │XmNnoFontCallback             │ XmCCallback                   │ XtCallbackList │ NULL                   │ C      │
101       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
102       │XmNnoRenditionCallback        │ XmCCallback                   │ XtCallbackList │ NULL                   │ C      │
103       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
104       │XmNuserData                   │ XmCUserData                   │ XtPointer      │ NULL                   │ CSG    │
105       ├──────────────────────────────┼───────────────────────────────┼────────────────┼────────────────────────┼────────┤
106       └──────────────────────────────┴───────────────────────────────┴────────────────┴────────────────────────┴────────┘
107       XmNdefaultButtonEmphasis
108                 Specifies whether to change the look of the PushButton widget
109                 and gadget that have the XmNshowAsDefault resource set.  When
110                 the  PushButton  is  the default, it has an etched out button
111                 which is enclosed with another etched in border.  The  XmNde‐
112                 faultButtonEmphasis  has  the  follow  possible values, which
113                 affect the location cursor:
114
115                 XmINTERNAL_HIGHLIGHT
116                           Causes the location cursor to appear in between the
117                           two etched borders to minimize the space required.
118
119                 XmEXTERNAL_HIGHLIGHT
120                           Causes  the  PushButton to draw the location cursor
121                           outside the second border.
122
123       XmNdefaultVirtualBindings
124                 Specifies the default virtual bindings for the display.  Fol‐
125                 lowing is an example of a specification for the defaultVirtu‐
126                 alBindings resource in a resource file:
127
128       *defaultVirtualBindings: \
129               osfBackSpace:       <Key>BackSpace       \n\
130               osfInsert:       <Key>InsertChar      \n\
131               osfDelete:       <Key>DeleteChar      \n\
132               ...
133               osfLeft:       <Key>left, Ctrl<Key>H
134
135       XmNdragInitiatorProtocolStyle
136                 Specifies the drag and drop protocol requirements or  prefer‐
137                 ence when the client is an initiator. The possible values are
138
139                 XmDRAG_PREREGISTER
140                           As  an  initiator,  this  client  does  not use the
141                           dynamic  protocol  and  can  only  arrange   visual
142                           effects  with  receivers  who provide preregistered
143                           information.
144
145                 XmDRAG_DYNAMIC
146                           As an initiator, this client does not make  use  of
147                           any preregistered drop site information made avail‐
148                           able by other clients, and can only arrange  visual
149                           effects  with  receivers who use the dynamic proto‐
150                           col.
151
152                 XmDRAG_NONE
153                           Specifies that drag and drop is disabled  for  this
154                           client.
155
156                 XmDRAG_DROP_ONLY
157                           As  an  initiator,  this client does not use either
158                           the preregistered  drop  site  information  or  the
159                           dynamic  protocol.  It  supports  dragging, and any
160                           time the cursor is over a client that supports drag
161                           and  drop, valid feedback is provided. There are no
162                           other visual effects.
163
164                 XmDRAG_PREFER_DYNAMIC
165                           As an initiator, this client can support  both  the
166                           preregister  and  dynamic protocols, but prefers to
167                           use dynamic protocols whenever possible in order to
168                           provide high-quality drag-under feedback.
169
170                 XmDRAG_PREFER_PREREGISTER
171                           As  an  initiator, this client can support both the
172                           preregister and dynamic protocols, but  prefers  to
173                           use  the  preregister protocol whenever possible in
174                           order to accommodate performance needs or  to  pro‐
175                           vide consistent drag-over feedback.
176
177                 XmDRAG_PREFER_RECEIVER
178                           Indicates that this client can support both prereg‐
179                           ister and dynamic protocols, but will defer to  the
180                           preference  of  the receiver client.  This value is
181                           valid only  for  the  XmNdragInitiatorProtocolStyle
182                           resource, and is its default value.
183
184       XmNdragReceiverProtocolStyle
185                 Specifies  the drag and drop protocol requirements or prefer‐
186                 ence when this client is a receiver. The values are
187
188                 XmDRAG_PREREGISTER
189                           As a receiver, this client preregisters  drop  site
190                           information  and does not use the dynamic protocol.
191                           It can only arrange visual effects with  initiators
192                           who make use of the preregistered information.
193
194                 XmDRAG_DYNAMIC
195                           As  a receiver, this client uses the dynamic proto‐
196                           col and does not preregister drop site information.
197                           It  can only arrange visual effects with initiators
198                           who use the dynamic protocol.
199
200                 XmDRAG_NONE
201                           Specifies that drag and drop is disabled  for  this
202                           client.
203
204                 XmDRAG_DROP_ONLY
205                           As a receiver, this client neither uses the dynamic
206                           protocol nor preregisters drop site information. It
207                           supports  dropping,  and  when  dragging  over this
208                           client, valid  feedback  is  always  provided,  but
209                           there are no other visual effects.
210
211                 XmDRAG_PREFER_DYNAMIC
212                           As  a  receiver,  this  client can support both the
213                           preregister and dynamic protocols, but  prefers  to
214                           use the dynamic protocol whenever possible in order
215                           to provide high-quality drag-under feedback.
216
217                 XmDRAG_PREFER_PREREGISTER
218                           As a receiver, this client  can  support  both  the
219                           preregister  and  dynamic protocols, but prefers to
220                           use the preregister protocol whenever  possible  in
221                           order to accommodate performance needs.
222
223                 The  default value of this resource is dependent on the capa‐
224                 bilities of the display. If the display  supports  the  shape
225                 extension,  allowing  the dynamic protocol to use arbitrarily
226                 sized  drag  cursors,  the  default  of  this   resource   is
227                 XmDRAG_PREFER_DYNAMIC,  otherwise  the default is XmDRAG_PRE‐
228                 FER_PREREGISTER.
229
230                 The actual protocol used between an initiator and a  receiver
231                 is based on the protocol style of the receiver and initiator.
232                 The decision matrix is described in the following table.
233
234                 ┌───────────────┬──────────────────────────────────────────────┐
235Drag Initiator │                              │   │   │       │
236                 │               │ Drag Receiver Protocol Style │   │   │       │
237                 ├───────────────┼──────────────────────────────┼───┼───┼───────┤
238                 ├───────────────┼──────────────────────────────┼───┼───┼───────┤
239                 ├───────────────┼──────────────────────────────┼───┼───┼───────┤
240                 ├───────────────┼──────────────────────────────┼───┼───┼───────┤
241                 ├───────────────┼──────────────────────────────┼───┼───┼───────┤
242                 ├───────────────┼──────────────────────────────┼───┼───┼───────┤
243                 └───────────────┴──────────────────────────────┴───┴───┴───────┘
244                 The value XmDRAG_NONE does not appear  in  the  matrix.  When
245                 specified   for   either  the  initiator  or  receiver  side,
246                 XmDRAG_NONE implies that drag and drop transactions  are  not
247                 supported.  A  value  of XmDRAG_DROP_ONLY (Drop Only) results
248                 when an initiator and  receiver  cannot  compromise  protocol
249                 styles,  that  is, one client requires dynamic mode while the
250                 other can only support preregister mode, or if either explic‐
251                 itly has specified XmDRAG_DROP_ONLY.
252
253       XmNdragStartCallback
254                 Specifies  the  list  of  callbacks that are invoked when the
255                 XmDragStart function is called. The type of  structure  whose
256                 address  is  passed  to this callback is XmDragStartCallback‐
257                 Struct.  The callback reason is XmCR_DRAG_START.
258
259       XmNenableBtn1Transfer
260                 Specifies if selection and transfer actions are integrated on
261                 Btn1  and extend actions are activated on Btn2. This resource
262                 can take the following values:
263
264                 XmOFF     Disables integration and  selection  activation  on
265                           Btn1.
266
267                 XmBUTTON2_TRANSFER
268                           Enables  integration  and  selection  activation on
269                           Btn1 and transfer on Btn2.
270
271                 XmBUTTON2_ADJUST
272                           Enables integration  and  selection  activation  on
273                           Btn1 and adjust on Btn2.
274
275                 This  resource  affects the actions of Text, TextField, List,
276                 and Container.
277
278       XmNenableButtonTab
279                 Specifies if the action for the  <Tab>  key  (KNextField  and
280                 KPrevField actions) is to be modified.  A value of True modi‐
281                 fies the key to move as an arrow key until the boundary of  a
282                 tab group is reached. Then, at the boundary of the tab group,
283                 KNextField and KPrevField will move to the next  or  previous
284                 tab group, respectively. A value of False does not cause mod‐
285                 ification.
286
287       XmNenableDragIcon
288                 Specifies which set of  icons  are  to  be  used  for  system
289                 default  cursors  during drag and drop operations. A value of
290                 False specifies that earlier versions of Motif release  icons
291                 are  used, a value of True specifies that alternate icons are
292                 used. This resource affects both  the  16x16  and  the  32x32
293                 icons that the system defaults for each of the Screen objects
294                 associated with this display.
295
296       XmNenableEtchedInMenu
297                 Specifies the shadowing of the button widgets and gadgets  in
298                 menus  when  the control is activated. A value of True causes
299                 the selected menu to be drawn with the shadow etched in; this
300                 shadow  style  is  consistent with the selected appearance of
301                 other button widgets outside  of  menus.  A  value  of  False
302                 causes  the  selected  menu to be draw with the shadow etched
303                 out. This resource affects the actions of PushButton, Toggle‐
304                 Button,  and  CascadeButton widgets and gadgets when they are
305                 children of Menu.
306
307                 When this resource is set, the background of a  button  in  a
308                 menu  uses  the  XmNselectColor  (derived from the XmNselect‐
309                 Pixel) when armed as a default. A PushButton uses the XmNarm‐
310                 Color  if  it  is defined. A ToggleButton uses the XmNselect‐
311                 Color if XmNindicatorOn is False and XmNfillOnSelect is True.
312
313       XmNenableToggleColor
314                 Specifies how to determine the default value  of  the  XmNse‐
315                 lectColor resource of ToggleButton and ToggleButtonGadget.  A
316                 value of True causes the default value of  XmNselectColor  to
317                 be  set  to the value of XmNhighlightColor.  A value of False
318                 causes the default value of XmNselectColor to be set  to  the
319                 value  of  XmNbackground.   This  resource  only  affects the
320                 appearance of ToggleButton widgets and gadgets  that  are  in
321                 XmONE_OF_MANY   or  XmONE_OF_MANY_ROUND  mode.  In  addition,
322                 XmNenableToggleColor only influences  the  default  value  of
323                 XmNselectColor.  That  is,  if the user or application sets a
324                 value  for  XmNselectColor,  then   XmNenableToggleColor   is
325                 ignored.
326
327       XmNenableToggleVisual
328                 Specifies  the  visual  appearance of the ToggleButton widget
329                 and/or gadget. This resource affects the default value of the
330                 ToggleButton[Gadget]   XmNindicatorType   and  XmNindicatorOn
331                 resources. When the ToggleButton is in a RadioBox, a value of
332                 True causes the XmONE_OF_MANY_ROUND (a shadowed circle) to be
333                 the default.  Otherwise, when this resource is True, the Tog‐
334                 gleButton   XmNindicatorOn   resource  causes  a  default  of
335                 XmN_OF_MANY, which will be a shadowed  square  with  a  check
336                 mark (check box).
337
338                 A value of False causes the following:
339
340                 XmONE_OF_MANY
341                           Is a shadowed diamond.
342
343                 XmN_OF_MANY
344                           Is a shadowed square.
345
346       XmNenableUnselectableDrag
347                 Specifies  whether  or  not it is possible to drag from Label
348                 and Scale.  A value of True enables  the  drag;  a  value  of
349                 False disables it.
350
351       XmNenableWarp
352                 Specifies  if  an  application is allowed to warp the pointer
353                 from the user. A value of True enables warping,  a  value  of
354                 False does not.
355
356       XmNmotifVersion
357                 Specifies  the  current  version  of  Motif  that the current
358                 implementation is supposed to behave like. By  default,  this
359                 resource gets its value from release values in Xm.h.
360
361       XmNnoFontCallback
362                 This callback is called whenever a rendition attempts to load
363                 a font or fontset and fails. This can happen on  creation  if
364                 the  font is specified as XmLOAD_IMMEDIATE or when an attempt
365                 is made to render an  XmString  using  a  font  specified  as
366                 XmLOAD_DEFERRED.   An  application  can  have  this  callback
367                 attempt to remedy this problem by  calling  XmRenditionUpdate
368                 on  the  input  rendition to provide a font for the widget to
369                 use. This may be done by either providing an  an  alternative
370                 font  name to be loaded using the XmNfontName and XmNfontType
371                 resources or with an already loaded font  using  the  XmNfont
372                 resource.  The callback reason is XmCR_NO_FONT. This callback
373                 uses the XmDisplayCallbackStruct structure.
374
375       XmNnoRenditionCallback
376                 This callback is called whenever an attempt is made to render
377                 a  segment with a RENDITION tag which does not match any ren‐
378                 ditions in a given  render  table.  The  callback  reason  is
379                 XmCR_NO_RENDITION.  This callback uses the XmDisplayCallback‐
380                 Struct structure.
381
382                 An application can have this callback attempt to remedy  this
383                 problem  by  creating  a new rendition with the given tag and
384                 adding it to render_table.
385
386                 The XmNnoRenditionCallback should deallocate the render table
387                 passed  in  in  the render_table field of the callback struc‐
388                 ture. Note that the table will automatically  be  deallocated
389                 if  the  XmRenderTableAddRenditions function is called on it.
390                 The callback should NOT deallocate the modified render  table
391                 that  is  passed  back to Motif in the render_table field. If
392                 the application wishes to manipulate this render  table  fur‐
393                 ther,  it should make a copy with the XmRenderTableCopy func‐
394                 tion before returning from the callback.
395
396       XmNuserData
397                 Specifies a client data pointer for applications.  An  inter‐
398                 nally unused resource.
399
400   Inherited Resources
401       All  of  the superclass resources inherited by XmDisplay are designated
402       N/A (not applicable).
403
404   Callback Information
405       A pointer to the following structure is passed to the XmNdragStartCall‐
406       back callback:
407
408       typedef struct
409       {
410               int reason;
411               XEvent  *event;
412               Widget timeStamp;
413               Boolean doit;
414       }XmDragStartCallbackStruct;
415
416       reason    Indicates why the callback was invoked
417
418       event     Points to the XEvent that triggered the callback
419
420       widget    Indicates the ID of the widget from which the drag was initi‐
421                 ated.
422
423       doit      Is an IN/OUT member that allows  the  callback  to  determine
424                 whether  to continue with the drag or cancel. Setting doit to
425                 False will cancel the drag. The default value is NULL.
426
427       A pointer to the following structure is passed to the XmNnoFontCallback
428       and XmNnoRenditionCallback callbacks:
429
430       typedef struct
431       {
432               int reason;
433               XEvent *event;
434               XmRendition rendition;
435               char *font_name;
436               XmRenderTable render_table;
437               XmStringTag tag;
438       }XmDisplayCallbackStruct;
439
440       reason    Indicates why the callback was invoked.
441
442       event     Points  to  the XEvent that triggered the callback. It can be
443                 NULL.
444
445       rendition Specifies the rendition with the missing font.
446
447       font_name Specifies the name of the font or font set which could not be
448                 loaded.
449
450       render_table
451                 Specifies the render table with the missing rendition.
452
453       tag       Specifies the tag of the missing rendition.
454
455       The  following  table  describes  the  reasons for which the individual
456       callback structure fields are valid.
457
458       ┌──────────────────┬──────────────────────┐
459Reason            Valid Fields         
460       ├──────────────────┼──────────────────────┤
461       │XmCR_NO_FONT      │ rendition, font_name
462       ├──────────────────┼──────────────────────┤
463       │XmCR_NO_RENDITION │ render_table, tag
464       ├──────────────────┼──────────────────────┤
465       └──────────────────┴──────────────────────┘
467       ApplicationShell(3), Composite(3), Core(3),  TopLevelShell(3),  Vendor‐
468       Shell(3), WMShell(3), XmGetXmDisplay(3), and XmScreen(3).
469
470
471
472                                                       XmDisplay(library call)
Impressum