home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH04 < prev    next >
Encoding:
Text File  |  1991-08-27  |  25.7 KB  |  1,146 lines
  1. .\" $XConsortium: CH04,v 1.8 91/08/27 10:01:11 swick Exp $
  2. .\"
  3. .\" Copyright 1985, 1986, 1987, 1988, 1991
  4. .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
  5. .\" and Digital Equipment Corporation, Maynard, Massachusetts.
  6. .\"
  7. .\" Permission to use, copy, modify and distribute this documentation for any
  8. .\" purpose and without fee is hereby granted, provided that the above copyright
  9. .\" notice appears in all copies and that both that copyright notice and this
  10. .\" permission notice appear in supporting documentation, and that the name of
  11. .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
  12. .\" to distribution of the software without specific, written prior permission.
  13. .\" M.I.T and Digital makes no representations about the suitability of the
  14. .\" software described herein for any purpose.
  15. .\" It is provided ``as is'' without express or implied warranty.
  16. \&
  17. .sp 1
  18. .ce 3
  19. \s+1\fBChapter 4\fP\s-1
  20.  
  21. \s+1\fBShell Widgets\fP\s-1
  22. .sp 2
  23. .nr H1 4
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 4 \- Shell Widgets
  31. .XE
  32. .IN "Shell" "" "@DEF@"
  33. .LP
  34. Shell widgets hold an application's top-level widgets to allow them to
  35. communicate with the window manager.
  36. Shells have been designed to be as nearly invisible as possible.
  37. Clients have to create them,
  38. but they should never have to worry about their sizes.
  39. .LP
  40. If a shell widget is resized from the outside (typically by a window manager),
  41. the shell widget also resizes its managed child widget automatically.
  42. Similarly, if the shell's child widget needs to change size,
  43. it can make a geometry request to the shell,
  44. and the shell negotiates the size change with the outer environment.
  45. Clients should never attempt to change the size of their shells directly.
  46. .LP
  47. The four types of public shells are:
  48. .TS
  49. lw(1.5i) lw(4.25i).
  50. T{
  51. .PN OverrideShell
  52. T}    T{
  53. Used for shell windows that completely bypass the window manager
  54. (for example, pop-up menu shells).
  55. T}
  56. .sp
  57. T{
  58. .PN TransientShell
  59. T}    T{
  60. Used for shell windows that have the
  61. .PN \s-1WM_TRANSIENT_FOR\s+1
  62. property set. The effect of this property is dependent upon the
  63. window manager being used.
  64. T}
  65. .sp
  66. T{
  67. .PN TopLevelShell
  68. T}    T{
  69. Used for normal top-level windows
  70. (for example, any additional top-level widgets an application needs).
  71. T}
  72. .sp
  73. T{
  74. .PN ApplicationShell
  75. T}    T{
  76. Used for the single main top-level window that
  77. the window manager identifies as an application instance and
  78. that interacts with the session manager.
  79. T}
  80. .IN "ApplicationShell" "" "@DEF@"
  81. .TE
  82.  
  83. .NH 2
  84. Shell Widget Definitions
  85. .XS
  86. \*(SN Shell Widget Definitions
  87. .XE
  88. .LP
  89. Widgets negotiate their size and position with their parent widget, 
  90. that is, the widget that directly contains them.
  91. Widgets at the top of the hierarchy do not have parent widgets. 
  92. Instead, they must deal with the outside world.
  93. To provide for this, 
  94. each top-level widget is encapsulated in a special widget, called a
  95. shell widget.
  96. .LP
  97. Shell
  98. widgets, whose class is a subclass of the 
  99. Composite class,
  100. encapsulate other widgets and can allow a widget to avoid the
  101. geometry clipping imposed by the parent-child window relationship.
  102. They also can provide a layer of communication with the window manager.
  103. .LP
  104. The seven different types of shells are
  105. .TS
  106. lw(1.5i) lw(4.5i).
  107. T{
  108. .PN Shell
  109. T}    T{
  110. The base class for shell widgets; provides the
  111. fields needed for all types of shells.
  112. Shell
  113. is a direct subclass of
  114. .PN compositeWidgetClass .
  115. T}
  116. .sp 6p
  117. T{
  118. .PN OverrideShell
  119. T}    T{
  120. A subclass of Shell; used for shell windows that completely
  121. bypass the window manager.
  122. T}
  123. .sp 6p
  124. T{
  125. .PN WMShell
  126. T}    T{
  127. A subclass of Shell; contains fields needed by the
  128. common window manager protocol .
  129. T}
  130. .sp 6p
  131. T{
  132. .PN VendorShell
  133. T}    T{
  134. A subclass of WMShell; contains fields used by
  135. vendor-specific window managers.
  136. T}
  137. .sp 6p
  138. T{
  139. .PN TransientShell
  140. T}    T{
  141. A subclass of VendorShell; used for shell windows that
  142. desire the
  143. .PN \s-1WM_TRANSIENT_FOR\s+1
  144. property.
  145. T}
  146. .sp 6p
  147. T{
  148. .PN TopLevelShell
  149. T}    T{
  150. A subclass of VendorShell; used for normal top level windows.
  151. T}
  152. .sp 6p
  153. T{
  154. .PN ApplicationShell
  155. T}    T{
  156. A subclass of TopLevelShell; used for an application's main top-level window.
  157. T}
  158. .TE
  159. .LP
  160. Note that the classes
  161. Shell,
  162. WMShell,
  163. and
  164. VendorShell
  165. are internal and should not be instantiated or subclassed.
  166. Only
  167. OverrrideShell,
  168. TransientShell,
  169. TopLevelShell,
  170. and
  171. ApplicationShell
  172. are intended for public use.
  173.  
  174. .NH 3
  175. ShellClassPart Definitions
  176. .XS
  177. \*(SN ShellClassPart Definitions
  178. .XE
  179. .LP
  180. Only the
  181. Shell
  182. class has additional class fields, which are all contained in the
  183. .PN ShellClassExtensionRec .
  184. None of the other Shell classes have any additional class fields:
  185. .LP
  186. .KS
  187. .Ds 0
  188. .TA .5i 3i
  189. .ta .5i 3i
  190. typedef struct { XtPointer extension; } ShellClassPart, OverrideShellClassPart,
  191.     WMShellClassPart, VendorShellClassPart, TransientShellClassPart,
  192.     TopLevelShellClassPart, ApplicationShellClassPart;
  193. .De
  194. .KE
  195. .LP
  196. The full Shell class record definitions are
  197. .IN "ShellClassExtension" "" "@DEF@"
  198. .IN "ShellClassExtensionRec" "" "@DEF@"
  199. .LP
  200. .KS
  201. .Ds 0
  202. .TA .5i 4i
  203. .ta .5i 4i
  204. typedef struct _ShellClassRec {
  205.     CoreClassPart core_class;
  206.     CompositeClassPart composite_class;
  207.     ShellClassPart shell_class;
  208. } ShellClassRec;
  209.  
  210. typedef struct {
  211.     XtPointer next_extension;    See Section 1.6.12
  212.     XrmQuark record_type;    See Section 1.6.12
  213.     long version;    See Section 1.6.12
  214.     Cardinal record_size;    See Section 1.6.12
  215.     XtGeometryHandler root_geometry_manager;    See below
  216. } ShellClassExtensionRec, *ShellClassExtension;
  217.  
  218. typedef struct _OverrideShellClassRec {
  219.     CoreClassPart core_class;
  220.     CompositeClassPart composite_class;
  221.     ShellClassPart shell_class;
  222.     OverrideShellClassPart override_shell_class;
  223. } OverrideShellClassRec;
  224. .De
  225. .KE
  226. .KS
  227. .Ds 0
  228. .TA .5i 3i
  229. .ta .5i 3i
  230. typedef struct _WMShellClassRec {
  231.     CoreClassPart core_class;
  232.     CompositeClassPart composite_class;
  233.     ShellClassPart shell_class;
  234.     WMShellClassPart wm_shell_class;
  235. } WMShellClassRec;
  236. .De
  237. .KE
  238. .KS
  239. .Ds 0
  240. .TA .5i 3i
  241. .ta .5i 3i
  242. typedef struct _VendorShellClassRec {
  243.     CoreClassPart core_class;
  244.     CompositeClassPart composite_class;
  245.     ShellClassPart shell_class;
  246.     WMShellClassPart wm_shell_class;
  247.     VendorShellClassPart vendor_shell_class;
  248. } VendorShellClassRec;
  249. .De
  250. .KE
  251. .KS
  252. .Ds 0
  253. .TA .5i 3i
  254. .ta .5i 3i
  255. typedef struct _TransientShellClassRec {
  256.     CoreClassPart core_class;
  257.     CompositeClassPart composite_class;
  258.     ShellClassPart shell_class;
  259.     WMShellClassPart wm_shell_class;
  260.     VendorShellClassPart vendor_shell_class;
  261.     TransientShellClassPart transient_shell_class;
  262. } TransientShellClassRec;
  263. .De
  264. .KE
  265. .KS
  266. .Ds 0
  267. .TA .5i 3i
  268. .ta .5i 3i
  269. typedef struct _TopLevelShellClassRec {
  270.     CoreClassPart core_class;
  271.     CompositeClassPart composite_class;
  272.     ShellClassPart shell_class;
  273.     WMShellClassPart wm_shell_class;
  274.     VendorShellClassPart vendor_shell_class;
  275.     TopLevelShellClassPart top_level_shell_class;
  276. } TopLevelShellClassRec;
  277. .De
  278. .KE
  279. .KS
  280. .Ds 0
  281. .TA .5i 3i
  282. .ta .5i 3i
  283. typedef struct _ApplicationShellClassRec {
  284.     CoreClassPart core_class;
  285.     CompositeClassPart composite_class;
  286.     ShellClassPart shell_class;
  287.     WMShellClassPart wm_shell_class;
  288.     VendorShellClassPart vendor_shell_class;
  289.     TopLevelShellClassPart top_level_shell_class;
  290.     ApplicationShellClassPart application_shell_class;
  291. } ApplicationShellClassRec;
  292. .De
  293. .KE
  294. .LP
  295. The single occurrences of the class records and pointers for creating
  296. instances of shells are
  297. .LP
  298. .KS
  299. .Ds 0
  300. .TA .5i 3i
  301. .ta .5i 3i
  302. extern ShellClassRec shellClassRec;
  303. extern OverrideShellClassRec overrideShellClassRec;
  304. extern WMShellClassRec wmShellClassRec;
  305. extern VendorShellClassRec vendorShellClassRec;
  306. extern TransientShellClassRec transientShellClassRec;
  307. extern TopLevelShellClassRec topLevelShellClassRec;
  308. extern ApplicationShellClassRec applicationShellClassRec;
  309.  
  310. extern WidgetClass shellWidgetClass;
  311. extern WidgetClass overrideShellWidgetClass;
  312. extern WidgetClass wmShellWidgetClass;
  313. extern WidgetClass vendorShellWidgetClass;
  314. extern WidgetClass transientShellWidgetClass;
  315. extern WidgetClass topLevelShellWidgetClass;
  316. extern WidgetClass applicationShellWidgetClass;
  317. .De
  318. .KE
  319. .LP
  320. The following opaque types and opaque variables are defined
  321. for generic operations on widgets whose class is a subclass of
  322. Shell.
  323. .bp
  324. .TS
  325. lw(2.75i) lw(2.75i).
  326. _
  327. .sp 6p
  328. Types    Variables
  329. .sp 6p
  330. _
  331. .sp 6p
  332. T{
  333. .PN ShellWidget
  334. T}    T{
  335. .PN shellWidgetClass
  336. T}
  337. T{
  338. .PN OverrideShellWidget
  339. T}    T{
  340. .PN overrideShellWidgetClass
  341. T}
  342. T{
  343. .PN WMShellWidget
  344. T}    T{
  345. .PN wmShellWidgetClass
  346. T}
  347. T{
  348. .PN VendorShellWidget
  349. T}    T{
  350. .PN vendorShellWidgetClass
  351. T}
  352. T{
  353. .PN TransientShellWidget
  354. T}    T{
  355. .PN transientShellWidgetClass
  356. T}
  357. T{
  358. .PN TopLevelShellWidget
  359. T}    T{
  360. .PN topLevelShellWidgetClass
  361. T}
  362. T{
  363. .PN ApplicationShellWidget
  364. T}    T{
  365. .PN applicationShellWidgetClass
  366. T}
  367. .PN ShellWidgetClass
  368. .PN OverrideShellWidgetClass
  369. .PN WMShellWidgetClass
  370. .PN VendorShellWidgetClass
  371. .PN TransientShellWidgetClass
  372. .PN TopLevelShellWidgetClass
  373. .PN ApplicationShellWidgetClass
  374. .sp 6p
  375. _
  376. .TE
  377. .LP
  378. The declarations for all Intrinsics-defined shells except
  379. VendorShell appear in
  380. .PN Shell.h
  381. and
  382. .PN ShellP.h .
  383. VendorShell has separate public and private .h files which are included by
  384. .PN Shell.h
  385. and
  386. .PN ShellP.h .
  387. .LP
  388. .PN Shell.h
  389. uses incomplete structure definitions to ensure that the
  390. compiler catches attempts to access private data in any of the Shell
  391. instance or class data structures.
  392. .LP
  393. The symbolic constant for the
  394. .PN ShellClassExtension
  395. version identifier is
  396. .PN XtShellExtensionVersion
  397. (see Section 1.6.12).
  398. .IN "XtShellExtensionVersion" "" "@DEF@"
  399. .LP
  400. .IN "Shell" "root_geometry_manager"
  401. .IN "root_geometry_manager procedure"
  402. The root_geometry_manager procedure acts as
  403. the parent geometry manager for geometry requests made by shell
  404. widgets.  When a shell widget calls either
  405. .PN XtMakeGeometryRequest
  406. or
  407. .PN XtMakeResizeRequest ,
  408. the root_geometry_manager procedure is invoked to
  409. negotiate the new geometry with the window manager.  If the window
  410. manager permits the new geometry, the root_geometry_manager
  411. procedure should
  412. return
  413. .PN XtGeometryYes ;
  414. if the window manager denies the geometry
  415. request or it does not change the window geometry within some timeout
  416. interval (equal to \fIwm_timeout\fP in the case of WMShells), the
  417. .IN "Shell" "wm_timeout" "@DEF@"
  418. .IN "wm_timeout" "" "@DEF@"
  419. root_geometry_manager procedure should return
  420. .PN XtGeometryNo .
  421. If the window manager makes some alternative geometry change, the
  422. root_geometry_manager procedure may either return
  423. .PN XtGeometryNo
  424. and handle the new geometry as a resize, or may return
  425. .PN XtGeometryAlmost
  426. in anticipation that the shell will accept the compromise.  If the
  427. compromise is not accepted, the new size must then be handled as a
  428. resize.  Subclasses of
  429. Shell
  430. that wish to provide their own
  431. root_geometry_manager procedures are strongly encouraged to use enveloping to
  432. invoke their superclass's root_geometry_manager procedure under most
  433. situations, as the window manager interaction may be very complex.
  434. .LP
  435. If no
  436. .PN ShellClassPart
  437. extension record is declared with \fIrecord_type\fP
  438. equal to
  439. .PN \s-1NULLQUARK\s+1 ,
  440. then
  441. .PN XtInheritRootGeometryManager
  442. is assumed.
  443.  
  444. .NH 3
  445. ShellPart Definition
  446. .XS
  447. \*(SN ShellPart Definition
  448. .XE
  449. .LP
  450. The various shell widgets have the following additional instance
  451. fields defined in
  452. their widget records:
  453. .LP
  454. .IN "ShellPart" "" "@DEF@"
  455. .KS
  456. .Ds 0
  457. .TA .5i 3i
  458. .ta .5i 3i
  459. typedef struct {
  460.     String geometry;
  461.     XtCreatePopupChildProc create_popup_child_proc;
  462.     XtGrabKind grab_kind;
  463.     Boolean spring_loaded;
  464.     Boolean popped_up;
  465.     Boolean allow_shell_resize;
  466.     Boolean client_specified;
  467.     Boolean save_under;
  468.     Boolean override_redirect;
  469.     XtCallbackList popup_callback;
  470.     XtCallbackList popdown_callback;
  471.     Visual* visual;
  472. } ShellPart;
  473. .De
  474. .KE
  475. .Ds 0
  476. .TA .5i 3i
  477. .ta .5i 3i
  478. typedef struct { int empty; } OverrideShellPart;
  479. .De
  480. .KS
  481. .Ds 0
  482. .TA .5i 1i 1.5i 2i
  483. .ta .5i 1i 1.5i 2i
  484. typedef struct {
  485.     String title;
  486.     int wm_timeout;
  487.     Boolean wait_for_wm;
  488.     Boolean transient;
  489.     struct _OldXSizeHints {
  490.         long flags;
  491.         int x, y;
  492.         int width, height;
  493.         int min_width, min_height;
  494.         int max_width, max_height;
  495.         int width_inc, height_inc;
  496.         struct {
  497.             int x;
  498.             int y;
  499.         } min_aspect, max_aspect;
  500.     } size_hints;
  501.     XWMHints wm_hints;
  502.     int base_width, base_height, win_gravity;
  503.     Atom title_encoding;
  504. } WMShellPart;
  505.  
  506. typedef struct {
  507.     int vendor_specific;
  508. } VendorShellPart;
  509. .De
  510. .KE
  511. .KS
  512. .Ds 0
  513. .TA .5i 3i
  514. .ta .5i 3i
  515. typedef struct {
  516.     Widget transient_for;
  517. } TransientShellPart;
  518.  
  519. typedef struct {
  520.     String icon_name;
  521.     Boolean iconic;
  522.     Atom icon_name_encoding;
  523. } TopLevelShellPart;
  524. .De
  525. .KE
  526. .KS
  527. .Ds 0
  528. .TA .5i 3i
  529. .ta .5i 3i
  530. typedef struct {
  531.     char *class;
  532.     XrmClass xrm_class;
  533.     int argc;
  534.     char **argv;
  535. } ApplicationShellPart;
  536. .De
  537. .KE
  538. The full shell widget instance record definitions are
  539. .LP
  540. .IN "ShellWidget" "" "@DEF@"
  541. .KS
  542. .Ds 0
  543. .TA .5i 3i
  544. .ta .5i 3i
  545. typedef struct {
  546.     CorePart core;
  547.     CompositePart composite;
  548.     ShellPart shell;
  549. } ShellRec, *ShellWidget;
  550.  
  551. typedef struct {
  552.     CorePart core;
  553.     CompositePart composite;
  554.     ShellPart shell;
  555.     OverrideShellPart override;
  556. } OverrideShellRec, *OverrideShellWidget;
  557. .De
  558. .KE
  559. .KS
  560. .Ds 0
  561. .TA .5i 3i
  562. .ta .5i 3i
  563. typedef struct {
  564.     CorePart core;
  565.     CompositePart composite;
  566.     ShellPart shell;
  567.     WMShellPart wm;
  568. } WMShellRec, *WMShellWidget;
  569.  
  570. typedef struct {
  571.     CorePart core;
  572.     CompositePart composite;
  573.     ShellPart shell;
  574.     WMShellPart wm;
  575.     VendorShellPart vendor;
  576. } VendorShellRec, *VendorShellWidget;
  577. .De
  578. .KE
  579. .KS
  580. .Ds 0
  581. .TA .5i 3i
  582. .ta .5i 3i
  583. typedef struct {
  584.     CorePart core;
  585.     CompositePart composite;
  586.     ShellPart shell;
  587.     WMShellPart wm;
  588.     VendorShellPart vendor;
  589.     TransientShellPart transient;
  590. } TransientShellRec, *TransientShellWidget;
  591. .De
  592. .KE
  593. .KS
  594. .Ds 0
  595. .TA .5i 3i
  596. .ta .5i 3i
  597. typedef struct {
  598.     CorePart core;
  599.     CompositePart composite;
  600.     ShellPart shell;
  601.     WMShellPart wm;
  602.     VendorShellPart vendor;
  603.     TopLevelShellPart topLevel;
  604. } TopLevelShellRec, *TopLevelShellWidget;
  605. .De
  606. .KE
  607. .KS
  608. .Ds 0
  609. .TA .5i 3i
  610. .ta .5i 3i
  611. .IN "ApplicationShellWidget" "" "@DEF@"
  612. typedef  struct {
  613.     CorePart  core;
  614.     CompositePart  composite;
  615.     ShellPart  shell;
  616.     WMShellPart wm;
  617.     VendorShellPart vendor;
  618.     TopLevelShellPart topLevel;
  619.     ApplicationShellPart application;
  620. } ApplicationShellRec, *ApplicationShellWidget;
  621. .De
  622. .KE
  623.  
  624. .NH 3
  625. Shell Resources
  626. .XS
  627. \fB\*(SN Shell Resources\fP
  628. .XE
  629. .LP
  630. .IN "ShellWidget" "Resources"
  631. The resource names, classes, and representation types specified in
  632. the
  633. .PN shellClassRec
  634. resource list are
  635. .LP
  636. .TS
  637. lw(1.7i) lw(1.7i) lw(1.2i) .
  638. _
  639. .sp 6p
  640. Name    Class    Representation
  641. .sp 6p
  642. _
  643. .sp 6p
  644. XtNallowShellResize    XtCAllowShellResize    XtRBoolean
  645. XtNcreatePopupChildProc    XtCCreatePopupChildProc    XtRFunction
  646. XtNgeometry    XtCGeometry    XtRString
  647. XtNoverrideRedirect    XtCOverrideRedirect    XtRBoolean
  648. XtNpopdownCallback    XtCCallback    XtRCallback
  649. XtNpopupCallback    XtCCallback    XtRCallback
  650. XtNsaveUnder    XtCSaveUnder    XtRBoolean
  651. XtNvisual    XtCVisual    XtRVisual
  652. .sp 6p
  653. _
  654. .TE
  655. .LP
  656. OverrideShell
  657. declares no additional resources beyond those defined by
  658. Shell.
  659. .LP
  660. The resource names, classes, and representation types specified in
  661. the
  662. .PN wmShellClassRec
  663. .IN "WMShell" "resources"
  664. resource list are
  665. .LP
  666. .TS
  667. lw(1.7i) lw(1.7i) lw(1.2i) .
  668. _
  669. .sp 6p
  670. Name    Class    Representation
  671. .sp 6p
  672. _
  673. .sp 6p
  674. XtNbaseHeight    XtCBaseHeight    XtRInt
  675. XtNbaseWidth    XtCBaseWidth    XtRInt
  676. XtNheightInc    XtCHeightInc    XtRInt
  677. XtNiconMask    XtCIconMask    XtRBitmap
  678. XtNiconPixmap    XtCIconPixmap    XtRBitmap
  679. XtNiconWindow    XtCIconWindow    XtRWindow
  680. XtNiconX    XtCIconX    XtRInt
  681. XtNiconY    XtCIconY    XtRInt
  682. XtNinitialState    XtCInitialState    XtRInitialState
  683. XtNinput    XtCInput    XtRBool
  684. XtNmaxAspectX    XtCMaxAspectX    XtRInt
  685. XtNmaxAspectY    XtCMaxAspectY    XtRInt
  686. XtNmaxHeight    XtCMaxHeight    XtRInt
  687. XtNmaxWidth    XtCMaxWidth    XtRInt
  688. XtNminAspectX    XtCMinAspectX    XtRInt
  689. XtNminAspectY    XtCMinAspectY    XtRInt
  690. XtNminHeight    XtCMinHeight    XtRInt
  691. XtNminWidth    XtCMinWidth    XtRInt
  692. XtNtitle    XtCTitle    XtRString
  693. XtNtitleEncoding    XtCTitleEncoding    XtRAtom
  694. XtNtransient    XtCTransient    XtRBoolean
  695. XtNwaitForWm    XtCWaitForWm    XtRBoolean
  696. XtNwidthInc    XtCWidthInc    XtRInt
  697. XtNwinGravity    XtCWinGravity    XtRInt
  698. XtNwindowGroup    XtCWindowGroup    XtRWindow
  699. XtNwmTimeout    XtCWmTimeout    XtRInt
  700. .sp 6p
  701. _
  702. .TE
  703. .LP
  704. The class resource list for
  705. VendorShell
  706. is implementation-defined.
  707. .LP
  708. The resource names, classes, and representation types that are specified in the
  709. .PN transient\%ShellClassRec
  710. .IN "TransientShell" "resources"
  711. resource list are
  712. .LP
  713. .TS
  714. lw(1.7i) lw(1.7i) lw(1.2i) .
  715. _
  716. .sp 6p
  717. Name    Class    Representation
  718. .sp 6p
  719. _
  720. .sp 6p
  721. XtNtransientFor    XtCTransientFor    XtRWidget
  722. .sp 6p
  723. _
  724. .TE
  725. .LP
  726. The resource names, classes, and representation types that are specified in the
  727. .PN topLevelShellClassRec
  728. .IN "TopLevelShell" "resources"
  729. resource list are
  730. .LP
  731. .TS
  732. lw(1.7i) lw(1.7i) lw(1.2i) .
  733. _
  734. .sp 6p
  735. Name    Class    Representation
  736. .sp 6p
  737. _
  738. .sp 6p
  739. XtNiconName    XtCIconName    XtRString
  740. XtNiconNameEncoding    XtCIconNameEncoding    XtRAtom
  741. XtNiconic    XtCIconic    XtRBoolean
  742. .sp 6p
  743. _
  744. .TE
  745. .LP
  746. The resource names, classes, and representation types that are specified in the
  747. .PN application\%ShellClassRec
  748. resource list are
  749. .LP
  750. .TS
  751. lw(1.7i) lw(1.7i) lw(1.2i) .
  752. _
  753. .sp 6p
  754. Name    Class    Representation
  755. .sp 6p
  756. _
  757. .sp 6p
  758. XtNargc    XtCArgc    XtRInt
  759. XtNargv    XtCArgv    XtRStringArray
  760. .sp 6p
  761. _
  762. .TE
  763.  
  764. .NH 3
  765. ShellPart Default Values
  766. .XS
  767. \fB\*(SN ShellPart Default Values\fP
  768. .XE
  769. .LP
  770. The default values for fields common to all classes of public shells
  771. (filled in by the 
  772. Shell
  773. resource lists and the 
  774. Shell 
  775. initialize procedures) are
  776. .TS
  777. lw(1.75i) lw(3i).
  778. _
  779. .sp 6p
  780. Field    Default Value
  781. .sp 6p
  782. _
  783. .sp 6p
  784. geometry    NULL
  785. create_popup_child_proc    NULL
  786. grab_kind    (none)
  787. spring_loaded    (none)
  788. popped_up    T{
  789. .PN False
  790. T}
  791. allow_shell_resize    T{
  792. .PN False
  793. T}
  794. client_specified    (internal)
  795. save_under    T{
  796. .PN True 
  797. for
  798. OverrideShell 
  799. and
  800. TransientShell,
  801. .PN False 
  802. otherwise
  803. T}
  804. override_redirect    T{
  805. .PN True 
  806. for
  807. OverrideShell,
  808. .PN False 
  809. otherwise
  810. T}
  811. popup_callback    NULL
  812. popdown_callback    NULL
  813. visual    T{
  814. .PN CopyFromParent
  815. T}
  816. .sp 6p
  817. _
  818. .TE
  819. .LP
  820. The \fIgeometry\fP field specifies the size and position
  821. and is usually given only on a command line or in a defaults file.
  822. If the \fIgeometry\fP field is non-NULL when
  823. a widget of class WMShell
  824. is realized, the geometry specification is parsed using
  825. .PN XWMGeometry
  826. with a default geometry
  827. string constructed from the values of \fIx\fP, \fIy\fP, \fIwidth\fP,
  828. \fIheight\fP, \fIwidth_inc\fP,
  829. and \fIheight_inc\fP and the size and position flags in the window manager
  830. size hints are set.  If the geometry specifies an x or y position,
  831. then
  832. .PN USPosition
  833. is set.  If the geometry specifies a width or height, then
  834. .PN USSize
  835. is set.  Any fields in the geometry specification
  836. override the corresponding values in the
  837. Core \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP fields.
  838. If \fIgeometry\fP is NULL or contains only a partial specification, then the
  839. Core \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP fields are used and
  840. .PN PPosition
  841. and
  842. .PN PSize
  843. are set as appropriate.
  844. The geometry string is not copied by any of the \*(xI
  845. Shell classes; a client specifying the string in an arglist
  846. or varargs list must ensure
  847. that the value remains valid until the shell widget is realized.
  848. For further information on the geometry string, see Section 10.3
  849. in \fI\*(xL\fP.
  850. .LP
  851. The \fIcreate_popup_child_proc\fP procedure is called by the
  852. .PN XtPopup
  853. procedure and may remain NULL.
  854. The \fIgrab_kind\fP, \fIspring_loaded\fP,
  855. and \fIpopped_up\fP fields maintain widget
  856. state information as described under
  857. .PN XtPopup ,
  858. .PN XtMenuPopup ,
  859. .PN XtPopdown ,
  860. and
  861. .PN XtMenuPopdown .
  862. The \fIallow_shell_resize\fP field controls whether the widget contained
  863. by the shell is allowed to try to resize itself.
  864. If allow_shell_resize is 
  865. .PN False , 
  866. any geometry requests made by the child will always return
  867. .PN XtGeometryNo
  868. without interacting with the window manager.
  869. Setting \fIsave_under\fP
  870. .PN True
  871. instructs the server to attempt
  872. to save the contents of windows obscured by the shell when it is mapped
  873. and to restore those contents automatically when the shell is unmapped.
  874. It is useful for pop-up menus.
  875. Setting \fIoverride_redirect\fP
  876. .PN True
  877. determines
  878. whether the window manager can intercede when the shell window
  879. is mapped.
  880. The pop-up and pop-down callbacks are called during
  881. .PN XtPopup
  882. and
  883. .PN XtPopdown .
  884. For further information on override_redirect,
  885. see Section 3.2 in \fI\*(xL\fP and Sections 4.1.10 and 4.2.2 in the
  886. \fI\*(xC\fP.
  887. .LP
  888. The default values for Shell fields in
  889. WMShell
  890. and its subclasses are
  891. .LP
  892. .IN "XtUnspecifiedShellInt" "" "@DEF@"
  893. .IN "XtUnspecifiedWindow"
  894. .TS
  895. lw(1i) lw(4i).
  896. _
  897. .sp 6p
  898. Field    Default Value
  899. .sp 6p
  900. _
  901. .sp 6p
  902. title    T{
  903. Icon name, if specified, otherwise the application's name.
  904. T}
  905. wm_timeout    Five seconds, in units of milliseconds.
  906. wait_for_wm    T{
  907. .PN True
  908. T}
  909. transient    T{
  910. .PN True 
  911. for
  912. TransientShell,
  913. .PN False 
  914. otherwise
  915. T}
  916. min_width    \fBXtUnspecifiedShellInt\fP
  917. min_height    \fBXtUnspecifiedShellInt\fP
  918. max_width    \fBXtUnspecifiedShellInt\fP
  919. max_height    \fBXtUnspecifiedShellInt\fP
  920. width_inc    \fBXtUnspecifiedShellInt\fP
  921. height_inc    \fBXtUnspecifiedShellInt\fP
  922. min_aspect_x    \fBXtUnspecifiedShellInt\fP
  923. min_aspect_y    \fBXtUnspecifiedShellInt\fP
  924. max_aspect_x    \fBXtUnspecifiedShellInt\fP
  925. max_aspect_y    \fBXtUnspecifiedShellInt\fP
  926. input    T{
  927. .PN False
  928. T}
  929. initial_state    Normal
  930. icon_pixmap    None
  931. icon_window    None
  932. icon_x    \fBXtUnspecifiedShellInt\fP
  933. icon_y    \fBXtUnspecifiedShellInt\fP
  934. icon_mask    None
  935. window_group    \fBXtUnspecifiedWindow\fP
  936. base_width    \fBXtUnspecifiedShellInt\fP
  937. base_height    \fBXtUnspecifiedShellInt\fP
  938. win_gravity    \fBXtUnspecifiedShellInt\fP
  939. title_encoding    See text
  940. .sp 6p
  941. _
  942. .TE
  943. .LP
  944. The \fItitle\fP and
  945. \fItitle_encoding\fP fields are stored in the
  946. .PN \s-1WM_NAME\s+1
  947. property on the shell's window by the WMShell realize procedure.
  948. If the \fItitle_encoding\fP field is
  949. .PN None ,
  950. the \fItitle\fP string is assumed to be in the encoding of the current
  951. locale and the encoding of the
  952. .PN \s-1WM_NAME\s+1
  953. property is set to
  954. .PN XStdICCTextStyle .
  955. If a language procedure has not been set
  956. the default value of \fItitle_encoding\fP is
  957. \fB\s-1XA_STRING\s+1\fP, otherwise the default value is
  958. .PN None .
  959. The \fIwm_timeout\fP field specifies, in milliseconds,
  960. the amount of time a shell is to wait for
  961. confirmation of a geometry request to the window manager.
  962. If none comes back within that time,
  963. the shell assumes the window manager is not functioning properly
  964. and sets \fIwait_for_wm\fP to
  965. .PN False 
  966. (later events may reset this value).
  967. When \fIwait_for_wm\fP is 
  968. .PN False ,
  969. the shell does not wait for a response but relies on asynchronous 
  970. notification.
  971. If \fItransient\fP is
  972. .PN True ,
  973. the
  974. .PN \s-1WM_TRANSIENT_FOR\s+1
  975. property
  976. will be stored on the shell window with a value as specified below.
  977. The interpretation of this property is specific to the window manager
  978. under which the application is run; see the \fI\*(xC\fP for more details.
  979. All other resources specify fields in the window manager hints
  980. and the window manager size hints.
  981. The realize and set_values procedures of
  982. WMShell
  983. set the corresponding flag bits in the
  984. hints if any of the fields contain non-default values.  In addition, if
  985. a flag bit is set that refers to a field with the value
  986. .PN XtUnspecifiedShellInt ,
  987. the value of the field is modified as follows:
  988. .br
  989. .sp
  990. .TS
  991. lw(2i) lw(3i).
  992. _
  993. .sp 6p
  994. Field    Replacement
  995. .sp 6p
  996. _
  997. .sp 6p
  998. base_width, base_height    0
  999. width_inc, height_inc    1
  1000. max_width, max_height    32767
  1001. min_width, min_height    1
  1002. min_aspect_x, min_aspect_y    -1
  1003. max_aspect_x, max_aspect_y    -1
  1004. icon_x, icon_y    -1
  1005. win_gravity    T{
  1006. value returned by
  1007. .PN XWMGeometry
  1008. if called,
  1009. else \fBNorthWestGravity\fP
  1010. T}
  1011. .sp 6p
  1012. _
  1013. .TE
  1014.  
  1015. .IN "XWMGeometry"
  1016. .LP
  1017. If the shell widget has a non-NULL parent, then the
  1018. realize and set_values procedures replace the value
  1019. .PN XtUnspecifiedWindow
  1020. .IN "XtUnspecifiedWindow" "" "@DEF@"
  1021. in the \fIwindow_group\fP field with the window id of the root widget
  1022. of the widget tree if the
  1023. root widget is realized. The symbolic constant
  1024. .PN XtUnspecifiedWindowGroup
  1025. .IN "XtUnspecifiedWindowGroup" "" "@DEF@"
  1026. may be used to indicate that the \fIwindow_group\fP hint flag bit is not
  1027. to be set.  If \fItransient\fP is
  1028. .PN True
  1029. and the shell's class is not a subclass of
  1030. TransientShell
  1031. and \fIwindow_group\fP is not
  1032. .PN XtUnspecifiedWindowGroup
  1033. the WMShell realize and set_values procedures then store the
  1034. .PN \s-1WM_TRANSIENT_FOR\s+1
  1035. property with the value of \fIwindow_group\fP.
  1036. .LP
  1037. Transient
  1038. shells have the following additional resource:
  1039. .TS
  1040. l l.
  1041. _
  1042. .sp 6p
  1043. Field    Default Value
  1044. .sp 6p
  1045. _
  1046. .sp 6p
  1047. transient_for    NULL
  1048. .sp 6p
  1049. _
  1050. .TE
  1051. .LP
  1052. The realize and set_values procedures of
  1053. TransientShell
  1054. store the
  1055. .PN \s-1WM_TRANSIENT_FOR\s+1
  1056. property on the shell window if \fItransient\fP is
  1057. .PN True .
  1058. If \fItransient_for\fP is non-NULL and the widget specified by
  1059. \fItransient_for\fP is realized, then its window is used as the value of the
  1060. .PN \s-1WM_TRANSIENT_FOR\s+1
  1061. property; otherwise, the value of \fIwindow_group\fP is used.
  1062. .LP
  1063. .PN TopLevel
  1064. shells have the the following additional resources:
  1065. .TS
  1066. l l.
  1067. _
  1068. .sp 6p
  1069. Field    Default Value
  1070. .sp 6p
  1071. _
  1072. .sp 6p
  1073. icon_name    Shell widget's name
  1074. iconic    T{
  1075. .PN False
  1076. T}
  1077. icon_name_encoding    See text
  1078. .sp 6p
  1079. _
  1080. .TE
  1081. .LP
  1082. The \fIicon_name\fP
  1083. and \fIicon_name_encoding\fP fields are stored in the
  1084. .PN \s-1WM_ICON_NAME\s+1
  1085. property on the shell's window by the TopLevelShell realize
  1086. procedure.
  1087. If the \fIicon_name_encoding\fP field is
  1088. .PN None ,
  1089. the \fIicon_name\fP string is assumed to be in the encoding of the
  1090. current locale and the encoding of the
  1091. .PN \s-1WM_ICON_NAME\s+1
  1092. property is set to
  1093. .PN XStdICCTextStyle .
  1094. If a language procedure has not been set
  1095. the default value of \fIicon_name_encoding\fP is
  1096. \fB\s-1XA_STRING\s+1\fP, otherwise the default value is
  1097. .PN None .
  1098. The \fIiconic\fP field may be used by a client to request
  1099. that the window manager iconify or deiconify the shell; the
  1100. TopLevelShell
  1101. set_values procedure will send the appropriate
  1102. .PN \s-1WM_CHANGE_STATE\s+1
  1103. message (as specified by the \fI\*(xC\fP)
  1104. if this resource is changed from
  1105. .PN False
  1106. to
  1107. .PN True ,
  1108. and will call
  1109. .PN XtPopup
  1110. specifying \fIgrab_kind\fP as
  1111. .PN XtGrabNone
  1112. if \fIiconic\fP is changed from
  1113. .PN True
  1114. to
  1115. .PN False .
  1116. The XtNiconic resource is also an alternative way to set
  1117. the XtNinitialState resource
  1118. to indicate that a shell should be initially displayed as an icon; the
  1119. TopLevelShell
  1120. initialize procedure will set \fIinitial_state\fP to
  1121. .PN IconicState
  1122. if \fIiconic\fP is
  1123. .PN True .
  1124. .LP
  1125. Application
  1126. shells have the following additional resources:
  1127. .TS
  1128. l l.
  1129. _
  1130. .sp 6p
  1131. Field    Default Value
  1132. .sp 6p
  1133. _
  1134. .sp 6p
  1135. argc    0
  1136. argv    NULL
  1137. .sp 6p
  1138. _
  1139. .TE
  1140. .LP
  1141. The \fIargc\fP and \fIargv\fP fields are used to initialize
  1142. the standard property
  1143. .PN \s-1WM_COMMAND\s+1 .
  1144. See the \fI\*(xC\fP for more information.
  1145. .bp
  1146.