CH04.xml revision 9e7bcd65
1<chapter id='Shell_Widgets'> 2<title>Shell Widgets</title> 3 4<para> 5Shell widgets hold an application's top-level widgets to allow them to 6communicate with the window manager and session manager. 7Shells have been designed to be as nearly invisible as possible. 8Clients have to create them, 9but they should never have to worry about their sizes. 10</para> 11 12<para> 13If a shell widget is resized from the outside (typically by a window manager), 14the shell widget also resizes its managed child widget automatically. 15Similarly, if the shell's child widget needs to change size, 16it can make a geometry request to the shell, 17and the shell negotiates the size change with the outer environment. 18Clients should never attempt to change the size of their shells directly. 19</para> 20 21<para>The five types of public shells are:</para> 22<variablelist> 23 <varlistentry> 24 <term>OverrideShell</term> 25 <listitem> 26 <para> 27 Used for shell windows that completely bypass the window manager 28 (for example, pop-up menu shells). 29 </para> 30 </listitem> 31 </varlistentry> 32 <varlistentry> 33 <term>TransientShell</term> 34 <listitem> 35 <para>Used for shell windows that have the 36 <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis> 37 property set. The effect of this property is dependent upon the 38 window manager being used. 39 </para> 40 </listitem> 41 </varlistentry> 42 <varlistentry> 43 <term>TopLevelShell</term> 44 <listitem> 45 <para>Used for normal top-level windows 46 (for example, any additional top-level widgets an application needs). 47 </para> 48 </listitem> 49 </varlistentry> 50 <varlistentry> 51 <term>ApplicationShell</term> 52 <listitem> 53 <para>Formerly used for the single main top-level window that 54 the window manager identifies as an application instance and 55 made obsolete by SessionShell. 56 </para> 57 </listitem> 58 </varlistentry> 59 <varlistentry> 60 <term>SessionShell</term> 61 <listitem> 62 <para> 63 Used for the single main top-level window that 64 the window manager identifies as an application instance and 65 that interacts with the session manager. 66 </para> 67 </listitem> 68 </varlistentry> 69</variablelist> 70 71<sect1 id="Shell_Widget_Definitions"> 72<title>Shell Widget Definitions</title> 73<para> 74Widgets negotiate their size and position with their parent widget, 75that is, the widget that directly contains them. 76Widgets at the top of the hierarchy do not have parent widgets. 77Instead, they must deal with the outside world. 78To provide for this, 79each top-level widget is encapsulated in a special widget, called a 80shell widget. 81</para> 82 83<para> 84Shell 85widgets, whose class is a subclass of the 86Composite class, 87encapsulate other widgets and can allow a widget to avoid the 88geometry clipping imposed by the parent-child window relationship. 89They also can provide a layer of communication with the window manager. 90</para> 91 92<para>The eight different types of shells are:</para> 93<variablelist> 94 <varlistentry> 95 <term>Shell</term> 96 <listitem> 97 <para>The base class for shell widgets; provides the 98 fields needed for all types of shells. Shell 99 is a direct subclass of 100 <emphasis role='strong'>compositeWidgetClass</emphasis>. 101 </para> 102 </listitem> 103 </varlistentry> 104 <varlistentry> 105 <term>OverrideShell</term> 106 <listitem> 107 <para>A subclass of Shell; used for shell windows that completely 108 bypass the window manager.</para> 109 </listitem> 110 </varlistentry> 111 <varlistentry> 112 <term>WMShell</term> 113 <listitem> 114 <para>A subclass of Shell; contains fields needed by the 115 common window manager protocol.</para> 116 </listitem> 117 </varlistentry> 118 <varlistentry> 119 <term>VendorShell</term> 120 <listitem> 121 <para>A subclass of WMShell; contains fields used by 122 vendor-specific window managers. 123 </para> 124 </listitem> 125 </varlistentry> 126 <varlistentry> 127 <term>TransientShell</term> 128 <listitem> 129 <para>A subclass of VendorShell; used for shell windows that 130 desire the <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis> 131 property.</para> 132 </listitem> 133 </varlistentry> 134 <varlistentry> 135 <term>TopLevelShell</term> 136 <listitem> 137 <para>A subclass of VendorShell; used for normal top-level windows. 138 </para> 139 </listitem> 140 </varlistentry> 141 <varlistentry> 142 <term>ApplicationShell</term> 143 <listitem> 144 <para>A subclass of TopLevelShell; may be used for an application's additional 145 root windows.</para> 146 </listitem> 147 </varlistentry> 148 <varlistentry> 149 <term>SessionShell</term> 150 <listitem> 151 <para>A subclass of ApplicationShell; used for an application's 152 main root window.</para> 153 </listitem> 154 </varlistentry> 155</variablelist> 156 157<para> 158Note that the classes 159Shell, 160WMShell, 161and 162VendorShell 163are internal and should not be instantiated or subclassed. 164Only 165OverrrideShell, 166TransientShell, 167TopLevelShell, 168ApplicationShell, 169and 170SessionShell 171are intended for public use. 172</para> 173 174<sect2 id="ShellClassPart_Definitions"> 175<title>ShellClassPart Definitions</title> 176<para> 177Only the Shell 178class has additional class fields, which are all contained in the 179<function>ShellClassExtensionRec</function>. 180None of the other Shell classes have any additional class fields: 181</para> 182 183<literallayout > 184typedef struct { 185 XtPointer extension; 186} ShellClassPart, OverrideShellClassPart, 187WMShellClassPart, VendorShellClassPart, TransientShellClassPart, 188TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart; 189</literallayout> 190 191<para>The full Shell class record definitions are:</para> 192 193<literallayout > 194typedef struct _ShellClassRec { 195 CoreClassPart core_class; 196 CompositeClassPart composite_class; 197 ShellClassPart shell_class; 198} ShellClassRec; 199</literallayout> 200 201<literallayout > 202typedef struct { 203 XtPointer next_extension; See <xref linkend='Class_Extension_Records' /> 204 XrmQuark record_type; See <xref linkend='Class_Extension_Records' /> 205 long version; See <xref linkend='Class_Extension_Records' /> 206 Cardinal record_size; See <xref linkend='Class_Extension_Records' /> 207 XtGeometryHandler root_geometry_manager; See below 208} ShellClassExtensionRec, *ShellClassExtension; 209</literallayout> 210 211<literallayout > 212typedef struct _OverrideShellClassRec { 213 CoreClassPart core_class; 214 CompositeClassPart composite_class; 215 ShellClassPart shell_class; 216 OverrideShellClassPart override_shell_class; 217} OverrideShellClassRec; 218</literallayout> 219 220<literallayout > 221typedef struct _WMShellClassRec { 222 CoreClassPart core_class; 223 CompositeClassPart composite_class; 224 ShellClassPart shell_class; 225 WMShellClassPart wm_shell_class; 226} WMShellClassRec; 227</literallayout> 228 229<literallayout > 230typedef struct _VendorShellClassRec { 231 CoreClassPart core_class; 232 CompositeClassPart composite_class; 233 ShellClassPart shell_class; 234 WMShellClassPart wm_shell_class; 235 VendorShellClassPart vendor_shell_class; 236} VendorShellClassRec; 237</literallayout> 238 239<literallayout > 240typedef struct _TransientShellClassRec { 241 CoreClassPart core_class; 242 CompositeClassPart composite_class; 243 ShellClassPart shell_class; 244 WMShellClassPart wm_shell_class; 245 VendorShellClassPart vendor_shell_class; 246 TransientShellClassPart transient_shell_class; 247} TransientShellClassRec; 248</literallayout> 249 250<literallayout > 251typedef struct _TopLevelShellClassRec { 252 CoreClassPart core_class; 253 CompositeClassPart composite_class; 254 ShellClassPart shell_class; 255 WMShellClassPart wm_shell_class; 256 VendorShellClassPart vendor_shell_class; 257 TopLevelShellClassPart top_level_shell_class; 258} TopLevelShellClassRec; 259</literallayout> 260 261<literallayout > 262typedef struct _ApplicationShellClassRec { 263 CoreClassPart core_class; 264 CompositeClassPart composite_class; 265 ShellClassPart shell_class; 266 WMShellClassPart wm_shell_class; 267 VendorShellClassPart vendor_shell_class; 268 TopLevelShellClassPart top_level_shell_class; 269 ApplicationShellClassPart application_shell_class; 270} ApplicationShellClassRec; 271</literallayout> 272 273<literallayout > 274typedef struct _SessionShellClassRec { 275 CoreClassPart core_class; 276 CompositeClassPart composite_class; 277 ShellClassPart shell_class; 278 WMShellClassPart wm_shell_class; 279 VendorShellClassPart vendor_shell_class; 280 TopLevelShellClassPart top_level_shell_class; 281 ApplicationShellClassPart application_shell_class; 282 SessionShellClassPart session_shell_class; 283} SessionShellClassRec; 284</literallayout> 285 286<para> 287The single occurrences of the class records and pointers for creating 288instances of shells are: 289</para> 290 291<literallayout > 292extern ShellClassRec shellClassRec; 293extern OverrideShellClassRec overrideShellClassRec; 294extern WMShellClassRec wmShellClassRec; 295extern VendorShellClassRec vendorShellClassRec; 296extern TransientShellClassRec transientShellClassRec; 297extern TopLevelShellClassRec topLevelShellClassRec; 298extern ApplicationShellClassRec applicationShellClassRec; 299extern SessionShellClassRec sessionShellClassRec; 300extern WidgetClass shellWidgetClass; 301extern WidgetClass overrideShellWidgetClass; 302extern WidgetClass wmShellWidgetClass; 303extern WidgetClass vendorShellWidgetClass; 304extern WidgetClass transientShellWidgetClass; 305extern WidgetClass topLevelShellWidgetClass; 306extern WidgetClass applicationShellWidgetClass; 307extern WidgetClass sessionShellWidgetClass; 308</literallayout> 309 310<para> 311The following opaque types and opaque variables are defined 312for generic operations on widgets whose class is a subclass of 313Shell. 314</para> 315 316<informaltable frame='topbot'> 317 <?dbfo keep-together="auto" ?> 318 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 319 <colspec colwidth='1.0*' colname='c1'/> 320 <colspec colwidth='1.0*' colname='c2'/> 321 <thead> 322 <row rowsep='1'> 323 <entry>Types</entry> 324 <entry>Variables</entry> 325 </row> 326 </thead> 327 <tbody> 328 <row> 329 <entry><emphasis role='strong'>ShellWidget</emphasis></entry> 330 <entry><emphasis role='strong'>shellWidgetClass</emphasis></entry> 331 </row> 332 <row> 333 <entry><emphasis role='strong'>OverrideShellWidget</emphasis></entry> 334 <entry><emphasis role='strong'>overrideShellWidgetClass</emphasis></entry> 335 </row> 336 <row> 337 <entry><emphasis role='strong'>WMShellWidget</emphasis></entry> 338 <entry><emphasis role='strong'>wmShellWidgetClass</emphasis></entry> 339 </row> 340 <row> 341 <entry><emphasis role='strong'>VendorShellWidget</emphasis></entry> 342 <entry><emphasis role='strong'>vendorShellWidgetClass</emphasis></entry> 343 </row> 344 <row> 345 <entry><emphasis role='strong'>TransientShellWidget</emphasis></entry> 346 <entry><emphasis role='strong'>transientShellWidgetClass</emphasis></entry> 347 </row> 348 <row> 349 <entry><emphasis role='strong'>TopLevelShellWidget</emphasis></entry> 350 <entry><emphasis role='strong'>topLevelShellWidgetClass</emphasis></entry> 351 </row> 352 <row> 353 <entry><emphasis role='strong'>ApplicationShellWidget</emphasis></entry> 354 <entry><emphasis role='strong'>applicationShellWidgetClass</emphasis></entry> 355 </row> 356 <row> 357 <entry><emphasis role='strong'>SessionShellWidget</emphasis></entry> 358 <entry><emphasis role='strong'>sessionShellWidgetClass</emphasis></entry> 359 </row> 360 <row> 361 <entry><emphasis role='strong'>ShellWidgetClass</emphasis></entry> 362 <entry></entry> 363 </row> 364 <row> 365 <entry><emphasis role='strong'>OverrideShellWidgetClass</emphasis></entry> 366 <entry></entry> 367 </row> 368 <row> 369 <entry><emphasis role='strong'>WMShellWidgetClass</emphasis></entry> 370 <entry></entry> 371 </row> 372 <row> 373 <entry><emphasis role='strong'>VendorShellWidgetClass</emphasis></entry> 374 <entry></entry> 375 </row> 376 <row> 377 <entry><emphasis role='strong'>TransientShellWidgetClass</emphasis></entry> 378 <entry></entry> 379 </row> 380 <row> 381 <entry><emphasis role='strong'>TopLevelShellWidgetClass</emphasis></entry> 382 <entry></entry> 383 </row> 384 <row> 385 <entry><emphasis role='strong'>ApplicationShellWidgetClass</emphasis></entry> 386 <entry></entry> 387 </row> 388 <row> 389 <entry><emphasis role='strong'>SessionShellWidgetClass</emphasis></entry> 390 <entry></entry> 391 </row> 392 </tbody> 393 </tgroup> 394</informaltable> 395 396<para> 397The declarations for all Intrinsics-defined shells except 398VendorShell appear in 399<function>Shell.h</function> 400and 401<function>ShellP.h</function>. 402VendorShell has separate public and private .h files which are included by 403<function>Shell.h</function> 404and 405<function>ShellP.h</function>. 406</para> 407 408<para> 409<function>Shell.h</function> 410uses incomplete structure definitions to ensure that the 411compiler catches attempts to access private data in any of the Shell 412instance or class data structures. 413</para> 414 415<para> 416The symbolic constant for the 417<function>ShellClassExtension</function> 418version identifier is 419<function>XtShellExtensionVersion</function> 420(see <xref linkend='Class_Extension_Records' />). 421</para> 422 423<para> 424The root_geometry_manager procedure acts as 425the parent geometry manager for geometry requests made by shell 426widgets. When a shell widget calls either 427<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/> 428or 429<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>, 430the root_geometry_manager procedure is invoked to 431negotiate the new geometry with the window manager. If the window 432manager permits the new geometry, the root_geometry_manager 433procedure should 434return 435<function>XtGeometryYes</function>; 436if the window manager denies the geometry 437request or does not change the window geometry within some timeout 438interval (equal to <emphasis remap='I'>wm_timeout</emphasis> in the case of WMShells), the 439root_geometry_manager procedure should return 440<function>XtGeometryNo</function>. 441If the window manager makes some alternative geometry change, the 442root_geometry_manager procedure may return either 443<function>XtGeometryNo</function> 444and handle the new geometry as a resize or 445<function>XtGeometryAlmost</function> 446in anticipation that the shell will accept the compromise. If the 447compromise is not accepted, the new size must then be handled as a 448resize. Subclasses of 449Shell 450that wish to provide their own 451root_geometry_manager procedures are strongly encouraged to use enveloping to 452invoke their superclass's root_geometry_manager procedure under most 453situations, as the window manager interaction may be very complex. 454</para> 455 456<para> 457If no 458<function>ShellClassPart</function> 459extension record is declared with <emphasis remap='I'>record_type</emphasis> 460equal to 461<emphasis role='strong'>NULLQUARK</emphasis>, 462then 463<function>XtInheritRootGeometryManager</function> 464is assumed. 465</para> 466</sect2> 467 468<sect2 id="ShellPart_Definition"> 469<title>ShellPart Definition</title> 470<para> 471The various shell widgets have the following additional instance 472fields defined in 473their widget records: 474</para> 475 476<literallayout > 477typedef struct { 478 String geometry; 479 XtCreatePopupChildProc create_popup_child_proc; 480 XtGrabKind grab_kind; 481 Boolean spring_loaded; 482 Boolean popped_up; 483 Boolean allow_shell_resize; 484 Boolean client_specified; 485 Boolean save_under; 486 Boolean override_redirect; 487 XtCallbackList popup_callback; 488 XtCallbackList popdown_callback; 489 Visual * visual; 490} ShellPart; 491</literallayout> 492 493<literallayout > 494typedef struct { 495 int empty; 496} OverrideShellPart; 497</literallayout> 498 499<literallayout > 500typedef struct { 501 String title; 502 int wm_timeout; 503 Boolean wait_for_wm; 504 Boolean transient; 505 Boolean urgency; 506 Widget client_leader; 507 String window_role; 508 struct _OldXSizeHints { 509 long flags; 510 int x, y; 511 int width, height; 512 int min_width, min_height; 513 int max_width, max_height; 514 int width_inc, height_inc; 515 struct { 516 int x; 517 int y; 518 } min_aspect, max_aspect; 519 } size_hints; 520 XWMHints wm_hints; 521 int base_width, base_height, win_gravity; 522 Atom title_encoding; 523} WMShellPart; 524</literallayout> 525 526<literallayout > 527typedef struct { 528 int vendor_specific; 529} VendorShellPart; 530</literallayout> 531 532<literallayout > 533typedef struct { 534 Widget transient_for; 535} TransientShellPart; 536typedef struct { 537 String icon_name; 538 Boolean iconic; 539 Atom icon_name_encoding; 540} TopLevelShellPart; 541</literallayout> 542 543<literallayout > 544typedef struct { 545 char * class; 546 XrmClass xrm_class; 547 int argc; 548 char ** argv; 549} ApplicationShellPart; 550</literallayout> 551 552<literallayout > 553typedef struct { 554 SmcConn connection; 555 String session_id; 556 String * restart_command; 557 String * clone_command; 558 String * discard_command; 559 String * resign_command; 560 String * shutdown_command; 561 String * environment; 562 String current_dir; 563 String program_path; 564 unsigned char restart_style; 565 Boolean join_session; 566 XtCallbackList save_callbacks; 567 XtCallbackList interact_callbacks; 568 XtCallbackList cancel_callbacks; 569 XtCallbackList save_complete_callbacks; 570 XtCallbackList die_callbacks; 571 XtCallbackList error_callbacks; 572} SessionShellPart; 573</literallayout> 574 575<para> 576The full shell widget instance record definitions are: 577</para> 578 579<literallayout > 580typedef struct { 581 CorePart core; 582 CompositePart composite; 583 ShellPart shell; 584} ShellRec, *ShellWidget; 585</literallayout> 586 587<literallayout > 588typedef struct { 589 CorePart core; 590 CompositePart composite; 591 ShellPart shell; 592 OverrideShellPart override; 593} OverrideShellRec, *OverrideShellWidget; 594</literallayout> 595 596<literallayout > 597typedef struct { 598 CorePart core; 599 CompositePart composite; 600 ShellPart shell; 601 WMShellPart wm; 602} WMShellRec, *WMShellWidget; 603</literallayout> 604 605<literallayout > 606typedef struct { 607 CorePart core; 608 CompositePart composite; 609 ShellPart shell; 610 WMShellPart wm; 611 VendorShellPart vendor; 612} VendorShellRec, *VendorShellWidget; 613</literallayout> 614 615<literallayout > 616typedef struct { 617 CorePart core; 618 CompositePart composite; 619 ShellPart shell; 620 WMShellPart wm; 621 VendorShellPart vendor; 622 TransientShellPart transient; 623} TransientShellRec, *TransientShellWidget; 624</literallayout> 625 626<literallayout > 627typedef struct { 628 CorePart core; 629 CompositePart composite; 630 ShellPart shell; 631 WMShellPart wm; 632 VendorShellPart vendor; 633 TopLevelShellPart topLevel; 634} TopLevelShellRec, *TopLevelShellWidget; 635</literallayout> 636 637<literallayout > 638typedef struct { 639 CorePart core; 640 CompositePart composite; 641 ShellPart shell; 642 WMShellPart wm; 643 VendorShellPart vendor; 644 TopLevelShellPart topLevel; 645 ApplicationShellPart application; 646} ApplicationShellRec, *ApplicationShellWidget; 647</literallayout> 648 649<literallayout > 650typedef struct { 651 CorePart core; 652 CompositePart composite; 653 ShellPart shell; 654 WMShellPart wm; 655 VendorShellPart vendor; 656 TopLevelShellPart topLevel; 657 ApplicationShellPart application; 658 SessionShellPart session; 659} SessionShellRec, *SessionShellWidget; 660</literallayout> 661 662</sect2> 663 664<sect2 id="Shell_Resources"> 665<title>Shell Resources</title> 666<para> 667The resource names, classes, and representation types specified in 668the 669<function>shellClassRec</function> 670resource list are: 671</para> 672 673<informaltable frame='topbot'> 674 <?dbfo keep-together="always" ?> 675 <tgroup cols='3' align='left' rowsep='0' colsep='0'> 676 <colspec colwidth='1.0*' colname='c1'/> 677 <colspec colwidth='1.0*' colname='c2'/> 678 <colspec colwidth='1.0*' colname='c3'/> 679 <thead> 680 <row rowsep='1'> 681 <entry>Name</entry> 682 <entry>Class</entry> 683 <entry>Representation</entry> 684 </row> 685 </thead> 686 <tbody> 687 <row> 688 <entry>XtNallowShellResize</entry> 689 <entry>XtCAllowShellResize</entry> 690 <entry>XtRBoolean</entry> 691 </row> 692 <row> 693 <entry>XtNcreatePopupChildProc</entry> 694 <entry>XtCCreatePopupChildProc</entry> 695 <entry>XtRFunction</entry> 696 </row> 697 <row> 698 <entry>XtNgeometry</entry> 699 <entry>XtCGeometry</entry> 700 <entry>XtRString</entry> 701 </row> 702 <row> 703 <entry>XtNoverrideRedirect</entry> 704 <entry>XtCOverrideRedirect</entry> 705 <entry>XtRBoolean</entry> 706 </row> 707 <row> 708 <entry>XtNpopdownCallback</entry> 709 <entry>XtCCallback</entry> 710 <entry>XtRCallback</entry> 711 </row> 712 <row> 713 <entry>XtNpopupCallback</entry> 714 <entry>XtCCallback</entry> 715 <entry>XtRCallback</entry> 716 </row> 717 <row> 718 <entry>XtNsaveUnder</entry> 719 <entry>XtCSaveUnder</entry> 720 <entry>XtRBoolean</entry> 721 </row> 722 <row> 723 <entry>XtNvisual</entry> 724 <entry>XtCVisual</entry> 725 <entry>XtRVisual</entry> 726 </row> 727 </tbody> 728 </tgroup> 729</informaltable> 730 731<para> 732OverrideShell 733declares no additional resources beyond those defined by 734Shell. 735</para> 736 737<para> 738The resource names, classes, and representation types specified in 739the 740<function>wmShellClassRec</function> 741resource list are: 742</para> 743 744<informaltable frame='topbot'> 745 <?dbfo keep-together="always" ?> 746 <tgroup cols='3' align='left' rowsep='0' colsep='0'> 747 <colspec colwidth='1.0*' colname='c1'/> 748 <colspec colwidth='1.0*' colname='c2'/> 749 <colspec colwidth='1.0*' colname='c3'/> 750 <thead> 751 <row rowsep='1'> 752 <entry>Name</entry> 753 <entry>Class</entry> 754 <entry>Representation</entry> 755 </row> 756 </thead> 757 <tbody> 758 <row> 759 <entry>XtNbaseHeight</entry> 760 <entry>XtCBaseHeight</entry> 761 <entry>XtRInt</entry> 762 </row> 763 <row> 764 <entry>XtNbaseWidth</entry> 765 <entry>XtCBaseWidth</entry> 766 <entry>XtRInt</entry> 767 </row> 768 <row> 769 <entry>XtNclientLeader</entry> 770 <entry>XtCClientLeader</entry> 771 <entry>XtRWidget</entry> 772 </row> 773 <row> 774 <entry>XtNheightInc</entry> 775 <entry>XtCHeightInc</entry> 776 <entry>XtRInt</entry> 777 </row> 778 <row> 779 <entry>XtNiconMask</entry> 780 <entry>XtCIconMask</entry> 781 <entry>XtRBitmap</entry> 782 </row> 783 <row> 784 <entry>XtNiconPixmap</entry> 785 <entry>XtCIconPixmap</entry> 786 <entry>XtRBitmap</entry> 787 </row> 788 <row> 789 <entry>XtNiconWindow</entry> 790 <entry>XtCIconWindow</entry> 791 <entry>XtRWindow</entry> 792 </row> 793 <row> 794 <entry>XtNiconX</entry> 795 <entry>XtCIconX</entry> 796 <entry>XtRInt</entry> 797 </row> 798 <row> 799 <entry>XtNiconY</entry> 800 <entry>XtCIconY</entry> 801 <entry>XtRInt</entry> 802 </row> 803 <row> 804 <entry>XtNinitialState</entry> 805 <entry>XtCInitialState</entry> 806 <entry>XtRInitialState</entry> 807 </row> 808 <row> 809 <entry>XtNinput</entry> 810 <entry>XtCInput</entry> 811 <entry>XtRBool</entry> 812 </row> 813 <row> 814 <entry>XtNmaxAspectX</entry> 815 <entry>XtCMaxAspectX</entry> 816 <entry>XtRInt</entry> 817 </row> 818 <row> 819 <entry>XtNmaxAspectY</entry> 820 <entry>XtCMaxAspectY</entry> 821 <entry>XtRInt</entry> 822 </row> 823 <row> 824 <entry>XtNmaxHeight</entry> 825 <entry>XtCMaxHeight</entry> 826 <entry>XtRInt</entry> 827 </row> 828 <row> 829 <entry>XtNmaxWidth</entry> 830 <entry>XtCMaxWidth</entry> 831 <entry>XtRInt</entry> 832 </row> 833 <row> 834 <entry>XtNminAspectX</entry> 835 <entry>XtCMinAspectX</entry> 836 <entry>XtRInt</entry> 837 </row> 838 <row> 839 <entry>XtNminAspectY</entry> 840 <entry>XtCMinAspectY</entry> 841 <entry>XtRInt</entry> 842 </row> 843 <row> 844 <entry>XtNminHeight</entry> 845 <entry>XtCMinHeight</entry> 846 <entry>XtRInt</entry> 847 </row> 848 <row> 849 <entry>XtNminWidth</entry> 850 <entry>XtCMinWidth</entry> 851 <entry>XtRInt</entry> 852 </row> 853 <row> 854 <entry>XtNtitle</entry> 855 <entry>XtCTitle</entry> 856 <entry>XtRString</entry> 857 </row> 858 <row> 859 <entry>XtNtitleEncoding</entry> 860 <entry>XtCTitleEncoding</entry> 861 <entry>XtRAtom</entry> 862 </row> 863 <row> 864 <entry>XtNtransient</entry> 865 <entry>XtCTransient</entry> 866 <entry>XtRBoolean</entry> 867 </row> 868 <row> 869 <entry>XtNwaitforwm, XtNwaitForWm</entry> 870 <entry>XtCWaitforwm, XtCWaitForWm</entry> 871 <entry>XtRBoolean</entry> 872 </row> 873 <row> 874 <entry>XtNwidthInc</entry> 875 <entry>XtCWidthInc</entry> 876 <entry>XtRInt</entry> 877 </row> 878 <row> 879 <entry>XtNwindowRole</entry> 880 <entry>XtCWindowRole</entry> 881 <entry>XtRString</entry> 882 </row> 883 <row> 884 <entry>XtNwinGravity</entry> 885 <entry>XtCWinGravity</entry> 886 <entry>XtRGravity</entry> 887 </row> 888 <row> 889 <entry>XtNwindowGroup</entry> 890 <entry>XtCWindowGroup</entry> 891 <entry>XtRWindow</entry> 892 </row> 893 <row> 894 <entry>XtNwmTimeout</entry> 895 <entry>XtCWmTimeout</entry> 896 <entry>XtRInt</entry> 897 </row> 898 <row> 899 <entry>XtNurgency</entry> 900 <entry>XtCUrgency</entry> 901 <entry>XtRBoolean</entry> 902 </row> 903 <row> 904 <entry>_</entry> 905 </row> 906 </tbody> 907 </tgroup> 908</informaltable> 909 910<para> 911The class resource list for 912VendorShell 913is implementation-defined. 914</para> 915 916<para> 917The resource names, classes, and representation types that are specified in the 918<function>transient\%ShellClassRec</function> 919resource list are: 920</para> 921 922<informaltable frame='topbot'> 923 <?dbfo keep-together="always" ?> 924 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 925 <colspec colwidth='1.0*' colname='c1'/> 926 <colspec colwidth='1.0*' colname='c2'/> 927 <colspec colwidth='1.0*' colname='c3'/> 928 <thead> 929 <row rowsep='1'> 930 <entry>Name</entry> 931 <entry>Class</entry> 932 <entry>Representation</entry> 933 </row> 934 </thead> 935 <tbody> 936 <row> 937 <entry>XtNtransientFor</entry> 938 <entry>XtCTransientFor</entry> 939 <entry>XtRWidget</entry> 940 </row> 941 </tbody> 942 </tgroup> 943</informaltable> 944 945<para> 946The resource names, classes, and representation types that are specified in the 947<function>topLevelShellClassRec</function> 948resource list are: 949</para> 950 951<informaltable frame='topbot'> 952 <?dbfo keep-together="always" ?> 953 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 954 <colspec colwidth='1.0*' colname='c1'/> 955 <colspec colwidth='1.0*' colname='c2'/> 956 <colspec colwidth='1.0*' colname='c3'/> 957 <thead> 958 <row rowsep='1'> 959 <entry>Name</entry> 960 <entry>Class</entry> 961 <entry>Representation</entry> 962 </row> 963 </thead> 964 <tbody> 965 <row> 966 <entry>XtNiconName</entry> 967 <entry>XtCIconName</entry> 968 <entry>XtRString</entry> 969 </row> 970 <row> 971 <entry>XtNiconNameEncoding</entry> 972 <entry>XtCIconNameEncoding</entry> 973 <entry>XtRAtom</entry> 974 </row> 975 <row> 976 <entry>XtNiconic</entry> 977 <entry>XtCIconic</entry> 978 <entry>XtRBoolean</entry> 979 </row> 980 </tbody> 981 </tgroup> 982</informaltable> 983 984<para> 985The resource names, classes, and representation types that are specified in the 986<function>application\%ShellClassRec</function> 987resource list are: 988</para> 989 990<informaltable frame='topbot'> 991 <?dbfo keep-together="always" ?> 992 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 993 <colspec colwidth='1.0*' colname='c1'/> 994 <colspec colwidth='1.0*' colname='c2'/> 995 <colspec colwidth='1.0*' colname='c3'/> 996 <thead> 997 <row rowsep='1'> 998 <entry>Name</entry> 999 <entry>Class</entry> 1000 <entry>Representation</entry> 1001 </row> 1002 </thead> 1003 <tbody> 1004 <row> 1005 <entry>XtNargc</entry> 1006 <entry>XtCArgc</entry> 1007 <entry>XtRInt</entry> 1008 </row> 1009 <row> 1010 <entry>XtNargv</entry> 1011 <entry>XtCArgv</entry> 1012 <entry>XtRStringArray</entry> 1013 </row> 1014 </tbody> 1015 </tgroup> 1016</informaltable> 1017 1018<para> 1019The resource names, classes, and representation types that are specified 1020in the 1021<function>sessionShellClassRec</function> 1022resource list are: 1023</para> 1024 1025<informaltable frame='topbot'> 1026 <?dbfo keep-together="always" ?> 1027 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1028 <colspec colwidth='1.0*' colname='c1'/> 1029 <colspec colwidth='1.0*' colname='c2'/> 1030 <colspec colwidth='1.0*' colname='c3'/> 1031 <thead> 1032 <row rowsep='1'> 1033 <entry>Name</entry> 1034 <entry>Class</entry> 1035 <entry>Representation</entry> 1036 </row> 1037 </thead> 1038 <tbody> 1039 <row> 1040 <entry>XtNcancelCallback</entry> 1041 <entry>XtCCallback</entry> 1042 <entry>XtRCallback</entry> 1043 </row> 1044 <row> 1045 <entry>XtNcloneCommand</entry> 1046 <entry>XtCCloneCommand</entry> 1047 <entry>XtRCommandArgArray</entry> 1048 </row> 1049 <row> 1050 <entry>XtNconnection</entry> 1051 <entry>XtCConnection</entry> 1052 <entry>XtRSmcConn</entry> 1053 </row> 1054 <row> 1055 <entry>XtNcurrentDirectory</entry> 1056 <entry>XtCCurrentDirectory</entry> 1057 <entry>XtRDirectoryString</entry> 1058 </row> 1059 <row> 1060 <entry>XtNdieCallback</entry> 1061 <entry>XtCCallback</entry> 1062 <entry>XtRCallback</entry> 1063 </row> 1064 <row> 1065 <entry>XtNdiscardCommand</entry> 1066 <entry>XtCDiscardCommand</entry> 1067 <entry>XtRCommandArgArray</entry> 1068 </row> 1069 <row> 1070 <entry>XtNenvironment</entry> 1071 <entry>XtCEnvironment</entry> 1072 <entry>XtREnvironmentArray</entry> 1073 </row> 1074 <row> 1075 <entry>XtNerrorCallback</entry> 1076 <entry>XtCCallback</entry> 1077 <entry>XtRCallback</entry> 1078 </row> 1079 <row> 1080 <entry>XtNinteractCallback</entry> 1081 <entry>XtCCallback</entry> 1082 <entry>XtRCallback</entry> 1083 </row> 1084 <row> 1085 <entry>XtNjoinSession</entry> 1086 <entry>XtCJoinSession</entry> 1087 <entry>XtRBoolean</entry> 1088 </row> 1089 <row> 1090 <entry>XtNprogramPath</entry> 1091 <entry>XtCProgramPath</entry> 1092 <entry>XtRString</entry> 1093 </row> 1094 <row> 1095 <entry>XtNresignCommand</entry> 1096 <entry>XtCResignCommand</entry> 1097 <entry>XtRCommandArgArray</entry> 1098 </row> 1099 <row> 1100 <entry>XtNrestartCommand</entry> 1101 <entry>XtCRestartCommand</entry> 1102 <entry>XtRCommandArgArray</entry> 1103 </row> 1104 <row> 1105 <entry>XtNrestartStyle</entry> 1106 <entry>XtCRestartStyle</entry> 1107 <entry>XtRRestartStyle</entry> 1108 </row> 1109 <row> 1110 <entry>XtNsaveCallback</entry> 1111 <entry>XtCCallback</entry> 1112 <entry>XtRCallback</entry> 1113 </row> 1114 <row> 1115 <entry>XtNsaveCompleteCallback</entry> 1116 <entry>XtCCallback</entry> 1117 <entry>XtRCallback</entry> 1118 </row> 1119 <row> 1120 <entry>XtNsessionID</entry> 1121 <entry>XtCSessionID</entry> 1122 <entry>XtRString</entry> 1123 </row> 1124 <row> 1125 <entry>XtNshutdownCommand</entry> 1126 <entry>XtCShutdownCommand</entry> 1127 <entry>XtRCommandArgArray</entry> 1128 </row> 1129 </tbody> 1130 </tgroup> 1131</informaltable> 1132 1133</sect2> 1134 1135<sect2 id="ShellPart_Default_Values"> 1136<title>ShellPart Default Values</title> 1137<para> 1138The default values for fields common to all classes of public shells 1139(filled in by the 1140Shell 1141resource lists and the 1142Shell 1143initialize procedures) are: 1144</para> 1145 1146<informaltable frame='topbot'> 1147 <?dbfo keep-together="always" ?> 1148 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1149 <colspec colwidth='1.0*' colname='c1'/> 1150 <colspec colwidth='1.0*' colname='c2'/> 1151 <thead> 1152 <row rowsep='1'> 1153 <entry>Field</entry> 1154 <entry>Default Value</entry> 1155 </row> 1156 </thead> 1157 <tbody> 1158 <row> 1159 <entry>geometry</entry> 1160 <entry>NULL</entry> 1161 </row> 1162 <row> 1163 <entry>create_popup_child_proc</entry> 1164 <entry>NULL</entry> 1165 </row> 1166 <row> 1167 <entry>grab_kind</entry> 1168 <entry>(none)</entry> 1169 </row> 1170 <row> 1171 <entry>spring_loaded</entry> 1172 <entry>(none)</entry> 1173 </row> 1174 <row> 1175 <entry>popped_up</entry> 1176 <entry><function>False</function></entry> 1177 </row> 1178 <row> 1179 <entry>allow_shell_resize</entry> 1180 <entry><function>False</function></entry> 1181 </row> 1182 <row> 1183 <entry>client_specified</entry> 1184 <entry>(internal)</entry> 1185 </row> 1186 <row> 1187 <entry>save_under</entry> 1188 <entry><function>True</function> 1189 for OverrideShell and TransientShell, 1190 <emphasis role='strong'>False</emphasis> 1191 otherwise</entry> 1192 </row> 1193 <row> 1194 <entry>override_redirect</entry> 1195 <entry><function>True</function> 1196 for OverrideShell, 1197 <function>False</function> 1198 otherwise</entry> 1199 </row> 1200 <row> 1201 <entry>popup_callback</entry> 1202 <entry>NULL</entry> 1203 </row> 1204 <row> 1205 <entry>popdown_callback</entry> 1206 <entry>NULL</entry> 1207 </row> 1208 <row> 1209 <entry>visual</entry> 1210 <entry><function>CopyFromParent</function></entry> 1211 </row> 1212 </tbody> 1213 </tgroup> 1214</informaltable> 1215 1216<para> 1217The <emphasis remap='I'>geometry</emphasis> field specifies the size and position 1218and is usually given only on a command line or in a defaults file. 1219If the <emphasis remap='I'>geometry</emphasis> field is non-NULL when 1220a widget of class WMShell 1221is realized, the geometry specification is parsed using 1222<function>XWMGeometry</function> 1223with a default geometry 1224string constructed from the values of <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, 1225<emphasis remap='I'>height</emphasis>, <emphasis remap='I'>width_inc</emphasis>, 1226and <emphasis remap='I'>height_inc</emphasis> and the size and position flags in the window manager 1227size hints are set. If the geometry specifies an x or y position, 1228then 1229<function>USPosition</function> 1230is set. If the geometry specifies a width or height, then 1231<function>USSize</function> 1232is set. Any fields in the geometry specification 1233override the corresponding values in the 1234Core <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> fields. 1235If <emphasis remap='I'>geometry</emphasis> is NULL or contains only a partial specification, then the 1236Core <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> fields are used and 1237<function>PPosition</function> 1238and 1239<function>PSize</function> 1240are set as appropriate. 1241The geometry string is not copied by any of the Intrinsics 1242Shell classes; a client specifying the string in an arglist 1243or varargs list must ensure 1244that the value remains valid until the shell widget is realized. 1245For further information on the geometry string, see 1246<olink targetdoc='libX11' targetptr='Parsing_the_Window_Geometry' /> 1247in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>. 1248</para> 1249 1250<para> 1251The <emphasis remap='I'>create_popup_child_proc</emphasis> procedure is called by the 1252<xref linkend='XtPopup' xrefstyle='select: title'/> 1253procedure and may remain NULL. 1254The <emphasis remap='I'>grab_kind</emphasis>, <emphasis remap='I'>spring_loaded</emphasis>, 1255and <emphasis remap='I'>popped_up</emphasis> fields maintain widget 1256state information as described under 1257<xref linkend='XtPopup' xrefstyle='select: title'/>, 1258<xref linkend='XtMenuPopup' xrefstyle='select: title'/>, 1259<xref linkend='XtPopdown' xrefstyle='select: title'/>, 1260and 1261<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>. 1262The <emphasis remap='I'>allow_shell_resize</emphasis> field controls whether the widget contained 1263by the shell is allowed to try to resize itself. 1264If allow_shell_resize is 1265<function>False</function>, 1266any geometry requests made by the child will always return 1267<function>XtGeometryNo</function> 1268without interacting with the window manager. 1269Setting <emphasis remap='I'>save_under</emphasis> 1270<function>True</function> 1271instructs the server to attempt 1272to save the contents of windows obscured by the shell when it is mapped 1273and to restore those contents automatically when the shell is unmapped. 1274It is useful for pop-up menus. 1275Setting <emphasis remap='I'>override_redirect</emphasis> 1276<function>True</function> 1277determines 1278whether the window manager can intercede when the shell window 1279is mapped. 1280For further information on override_redirect, 1281see <olink targetdoc='libX11' targetptr='Window_Attributes' /> in 1282<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink> 1283and 1284<olink targetdoc='icccm' targetptr='Pop_up_Windows' /> and 1285<olink targetdoc='icccm' targetptr='Redirection_of_Operations' /> in the 1286<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink>. 1287The pop-up and pop-down callbacks are called during 1288<xref linkend='XtPopup' xrefstyle='select: title'/> 1289and 1290<xref linkend='XtPopdown' xrefstyle='select: title'/>. 1291The default value of the <emphasis remap='I'>visual</emphasis> resource is the symbolic value 1292<function>CopyFromParent</function>. 1293The Intrinsics do not need to query the parent's visual type when the 1294default value is used; if a client using 1295<xref linkend='XtGetValues' xrefstyle='select: title'/> 1296to examine the visual type receives the value 1297<function>CopyFromParent</function>, 1298it must then use 1299<function>XGetWindowAttributes</function> 1300if it needs the actual visual type. 1301</para> 1302 1303<para> 1304The default values for Shell fields in 1305WMShell 1306and its subclasses are: 1307</para> 1308 1309<informaltable frame='topbot'> 1310 <?dbfo keep-together="auto" ?> 1311 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1312 <colspec colwidth='1.0*' colname='c1'/> 1313 <colspec colwidth='1.0*' colname='c2'/> 1314 <thead> 1315 <row rowsep='1'> 1316 <entry>Field</entry> 1317 <entry>Default Value</entry> 1318 </row> 1319 </thead> 1320 <tbody> 1321 <row> 1322 <entry>title</entry> 1323 <entry>Icon name, if specified, otherwise the application's name</entry> 1324 </row> 1325 <row> 1326 <entry>wm_timeout</entry> 1327 <entry>Five seconds, in units of milliseconds</entry> 1328 </row> 1329 <row> 1330 <entry>wait_for_wm</entry> 1331 <entry><function>True</function></entry> 1332 </row> 1333 <row> 1334 <entry>transient</entry> 1335 <entry><function>True</function> 1336 for TransientShell, 1337 <function>False</function> 1338 otherwise</entry> 1339 </row> 1340 <row> 1341 <entry>urgency</entry> 1342 <entry><function>False</function></entry> 1343 </row> 1344 <row> 1345 <entry>client_leader</entry> 1346 <entry>NULL</entry> 1347 </row> 1348 <row> 1349 <entry>window_role</entry> 1350 <entry>NULL</entry> 1351 </row> 1352 <row> 1353 <entry>min_width</entry> 1354 <entry><function>XtUnspecifiedShellInt</function></entry> 1355 </row> 1356 <row> 1357 <entry>min_height</entry> 1358 <entry><function>XtUnspecifiedShellInt</function></entry> 1359 </row> 1360 <row> 1361 <entry>max_width</entry> 1362 <entry><function>XtUnspecifiedShellInt</function></entry> 1363 </row> 1364 <row> 1365 <entry>max_height</entry> 1366 <entry><function>XtUnspecifiedShellInt</function></entry> 1367 </row> 1368 <row> 1369 <entry>width_inc</entry> 1370 <entry><function>XtUnspecifiedShellInt</function></entry> 1371 </row> 1372 <row> 1373 <entry>height_inc</entry> 1374 <entry><function>XtUnspecifiedShellInt</function></entry> 1375 </row> 1376 <row> 1377 <entry>min_aspect_x</entry> 1378 <entry><function>XtUnspecifiedShellInt</function></entry> 1379 </row> 1380 <row> 1381 <entry>min_aspect_y</entry> 1382 <entry><function>XtUnspecifiedShellInt</function></entry> 1383 </row> 1384 <row> 1385 <entry>max_aspect_x</entry> 1386 <entry><function>XtUnspecifiedShellInt</function></entry> 1387 </row> 1388 <row> 1389 <entry>max_aspect_y</entry> 1390 <entry><function>XtUnspecifiedShellInt</function></entry> 1391 </row> 1392 <row> 1393 <entry>input</entry> 1394 <entry><function>False</function></entry> 1395 </row> 1396 <row> 1397 <entry>initial_state</entry> 1398 <entry>Normal</entry> 1399 </row> 1400 <row> 1401 <entry>icon_pixmap</entry> 1402 <entry>None</entry> 1403 </row> 1404 <row> 1405 <entry>icon_window</entry> 1406 <entry>None</entry> 1407 </row> 1408 <row> 1409 <entry>icon_x</entry> 1410 <entry><function>XtUnspecifiedShellInt</function></entry> 1411 </row> 1412 <row> 1413 <entry>icon_y</entry> 1414 <entry><function>XtUnspecifiedShellInt</function></entry> 1415 </row> 1416 <row> 1417 <entry>icon_mask</entry> 1418 <entry>None</entry> 1419 </row> 1420 <row> 1421 <entry>window_group</entry> 1422 <entry><function>XtUnspecifiedWindow</function></entry> 1423 </row> 1424 <row> 1425 <entry>base_width</entry> 1426 <entry><function>XtUnspecifiedShellInt</function></entry> 1427 </row> 1428 <row> 1429 <entry>base_height</entry> 1430 <entry><function>XtUnspecifiedShellInt</function></entry> 1431 </row> 1432 <row> 1433 <entry>win_gravity</entry> 1434 <entry><function>XtUnspecifiedShellInt</function></entry> 1435 </row> 1436 <row> 1437 <entry>title_encoding</entry> 1438 <entry>See text</entry> 1439 </row> 1440 </tbody> 1441 </tgroup> 1442</informaltable> 1443 1444<para> 1445The <emphasis remap='I'>title</emphasis> and 1446<emphasis remap='I'>title_encoding</emphasis> fields are stored in the 1447<emphasis role='strong'>WM_NAME</emphasis> 1448property on the shell's window by the WMShell realize procedure. 1449If the <emphasis remap='I'>title_encoding</emphasis> field is 1450<function>None</function>, 1451the <emphasis remap='I'>title</emphasis> string is assumed to be in the encoding of the current 1452locale and the encoding of the 1453<emphasis role='strong'>WM_NAME</emphasis> 1454property is set to 1455<function>XStdICCTextStyle</function>. 1456If a language procedure has not been set 1457the default value of <emphasis remap='I'>title_encoding</emphasis> is 1458<emphasis role='strong'>XA_STRING</emphasis>, otherwise the default value is 1459<function>None</function>. 1460The <emphasis remap='I'>wm_timeout</emphasis> field specifies, in milliseconds, 1461the amount of time a shell is to wait for 1462confirmation of a geometry request to the window manager. 1463If none comes back within that time, 1464the shell assumes the window manager is not functioning properly 1465and sets <emphasis remap='I'>wait_for_wm</emphasis> to 1466<function>False</function> 1467(later events may reset this value). 1468When <emphasis remap='I'>wait_for_wm</emphasis> is 1469<function>False</function>, 1470the shell does not wait for a response, but relies on asynchronous 1471notification. 1472If <emphasis remap='I'>transient</emphasis> is 1473<function>True</function>, 1474the 1475<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis> 1476property 1477will be stored on the shell window with a value as specified below. 1478The interpretation of this property is specific to the window manager 1479under which the application is run; see the 1480<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink> 1481for more details. 1482</para> 1483 1484<para> 1485The realize and set_values procedures of WMShell store the 1486<emphasis role='strong'>WM_CLIENT_LEADER</emphasis> 1487property on the shell window. 1488When <emphasis remap='I'>client_leader</emphasis> is not NULL and the client leader widget is 1489realized, the property will be created with the value of the window of the 1490client leader widget. 1491When <emphasis remap='I'>client_leader</emphasis> is NULL and the shell widget has a NULL parent, 1492the widget's window is used as the value of the 1493property. 1494When <emphasis remap='I'>client_leader</emphasis> is NULL and the shell widget has a non-NULL parent, 1495a search is made for the closest shell ancestor 1496with a non-NULL <emphasis remap='I'>client_leader</emphasis>, 1497and if none is found the shell ancestor with a NULL parent is the result. 1498If the resulting widget is realized, the property is created 1499with the value of the widget's window. 1500</para> 1501 1502<para> 1503When the value of <emphasis remap='I'>window_role</emphasis> is not NULL, the 1504realize and set_values procedures store the 1505<emphasis role='strong'>WM_WINDOW_ROLE</emphasis> 1506property on the shell's window with the value of the resource. 1507</para> 1508 1509<para> 1510All other resources specify fields in the window manager hints 1511and the window manager size hints. 1512The realize and set_values procedures of 1513WMShell 1514set the corresponding flag bits in the 1515hints if any of the fields contain nondefault values. In addition, if 1516a flag bit is set that refers to a field with the value 1517<function>XtUnspecifiedShellInt</function>, 1518the value of the field is modified as follows: 1519</para> 1520 1521<informaltable frame='topbot'> 1522 <?dbfo keep-together="always" ?> 1523 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1524 <colspec colwidth='1.0*' colname='c1'/> 1525 <colspec colwidth='1.0*' colname='c2'/> 1526 <thead> 1527 <row rowsep='1'> 1528 <entry>Field</entry> 1529 <entry>Replacement</entry> 1530 </row> 1531 </thead> 1532 <tbody> 1533 <row> 1534 <entry>base_width, base_height</entry> 1535 <entry>0</entry> 1536 </row> 1537 <row> 1538 <entry>width_inc, height_inc</entry> 1539 <entry>1</entry> 1540 </row> 1541 <row> 1542 <entry>max_width, max_height</entry> 1543 <entry>32767</entry> 1544 </row> 1545 <row> 1546 <entry>min_width, min_height</entry> 1547 <entry>1</entry> 1548 </row> 1549 <row> 1550 <entry>min_aspect_x, min_aspect_y</entry> 1551 <entry>-1</entry> 1552 </row> 1553 <row> 1554 <entry>max_aspect_x, max_aspect_y</entry> 1555 <entry>-1</entry> 1556 </row> 1557 <row> 1558 <entry>icon_x, icon_y</entry> 1559 <entry>-1</entry> 1560 </row> 1561 <row> 1562 <entry>win_gravity</entry> 1563 <entry>Value returned by 1564 <function>XWMGeometry</function> 1565 if called, 1566 else <function>NorthWestGravity</function></entry> 1567 </row> 1568 </tbody> 1569 </tgroup> 1570</informaltable> 1571 1572<para> 1573If the shell widget has a non-NULL parent, then the 1574realize and set_values procedures replace the value 1575<function>XtUnspecifiedWindow</function> 1576in the <emphasis remap='I'>window_group</emphasis> field with the window id of the root widget 1577of the widget tree if the 1578root widget is realized. The symbolic constant 1579<function>XtUnspecifiedWindowGroup</function> 1580may be used to indicate that the <emphasis remap='I'>window_group</emphasis> hint flag bit is not 1581to be set. If <emphasis remap='I'>transient</emphasis> is 1582<function>True</function>, 1583the shell's class is not a subclass of 1584TransientShell, 1585and <emphasis remap='I'>window_group</emphasis> is not 1586<function>XtUnspecifiedWindowGroup</function>, 1587the WMShell realize and set_values procedures then store the 1588<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis> 1589property with the value of <emphasis remap='I'>window_group</emphasis>. 1590</para> 1591 1592<para> 1593Transient 1594shells have the following additional resource: 1595</para> 1596 1597<informaltable frame='topbot'> 1598 <?dbfo keep-together="always" ?> 1599 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1600 <colspec colwidth='1.0*' colname='c1'/> 1601 <colspec colwidth='1.0*' colname='c2'/> 1602 <thead> 1603 <row rowsep='1'> 1604 <entry>Field</entry> 1605 <entry>Replacement</entry> 1606 </row> 1607 </thead> 1608 <tbody> 1609 <row> 1610 <entry>transient_for</entry> 1611 <entry>NULL</entry> 1612 </row> 1613 </tbody> 1614 </tgroup> 1615</informaltable> 1616 1617<para> 1618The realize and set_values procedures of 1619TransientShell 1620store the 1621<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis> 1622property on the shell window if <emphasis remap='I'>transient</emphasis> is 1623<function>True</function>. 1624If <emphasis remap='I'>transient_for</emphasis> is non-NULL and the widget specified by 1625<emphasis remap='I'>transient_for</emphasis> is realized, then its window is used as the value of the 1626<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis> 1627property; otherwise, the value of <emphasis remap='I'>window_group</emphasis> is used. 1628</para> 1629 1630<para> 1631<function>TopLevel</function> 1632shells have the the following additional resources: 1633</para> 1634 1635 1636<informaltable frame='topbot'> 1637 <?dbfo keep-together="always" ?> 1638 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1639 <colspec colwidth='1.0*' colname='c1'/> 1640 <colspec colwidth='1.0*' colname='c2'/> 1641 <thead> 1642 <row rowsep='1'> 1643 <entry>Field</entry> 1644 <entry>Default Value</entry> 1645 </row> 1646 </thead> 1647 <tbody> 1648 <row> 1649 <entry>icon_name</entry> 1650 <entry>Shell widget's name</entry> 1651 </row> 1652 <row> 1653 <entry>iconic</entry> 1654 <entry><emphasis role='strong'>False</emphasis></entry> 1655 </row> 1656 <row> 1657 <entry>icon_name_encoding</entry> 1658 <entry>See text</entry> 1659 </row> 1660 </tbody> 1661 </tgroup> 1662</informaltable> 1663 1664<para> 1665The <emphasis remap='I'>icon_name</emphasis> 1666and <emphasis remap='I'>icon_name_encoding</emphasis> fields are stored in the 1667<emphasis role='strong'>WM_ICON_NAME</emphasis> 1668property on the shell's window by the TopLevelShell realize 1669procedure. 1670If the <emphasis remap='I'>icon_name_encoding</emphasis> field is 1671<function>None</function>, 1672the <emphasis remap='I'>icon_name</emphasis> string is assumed to be in the encoding of the 1673current locale and the encoding of the 1674<emphasis role='strong'>WM_ICON_NAME</emphasis> 1675property is set to 1676<function>XStdICCTextStyle</function>. 1677If a language procedure has not been set, 1678the default value of <emphasis remap='I'>icon_name_encoding</emphasis> is 1679<emphasis role='strong'>XA_STRING</emphasis>, otherwise the default value is 1680<function>None</function>. 1681The <emphasis remap='I'>iconic</emphasis> field may be used by a client to request 1682that the window manager iconify or deiconify the shell; the 1683TopLevelShell 1684set_values procedure will send the appropriate 1685<emphasis role='strong'>WM_CHANGE_STATE</emphasis> 1686message (as specified by the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>) 1687if this resource is changed from 1688<function>False</function> 1689to 1690<function>True</function> 1691and will call 1692<xref linkend='XtPopup' xrefstyle='select: title'/> 1693specifying <emphasis remap='I'>grab_kind</emphasis> as 1694<function>XtGrabNone</function> 1695if <emphasis remap='I'>iconic</emphasis> is changed from 1696<function>True</function> 1697to 1698<function>False</function>. 1699The XtNiconic resource is also an alternative way to set 1700the XtNinitialState resource 1701to indicate that a shell should be initially displayed as an icon; the 1702TopLevelShell 1703initialize procedure will set <emphasis remap='I'>initial_state</emphasis> to 1704<function>IconicState</function> 1705if <emphasis remap='I'>iconic</emphasis> is 1706<function>True</function>. 1707</para> 1708 1709<para> 1710Application 1711shells have the following additional resources: 1712</para> 1713 1714<informaltable frame='topbot'> 1715 <?dbfo keep-together="always" ?> 1716 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1717 <colspec colwidth='1.0*' colname='c1'/> 1718 <colspec colwidth='1.0*' colname='c2'/> 1719 <thead> 1720 <row rowsep='1'> 1721 <entry>Field</entry> 1722 <entry>Default Value</entry> 1723 </row> 1724 </thead> 1725 <tbody> 1726 <row> 1727 <entry>argc</entry> 1728 <entry>0</entry> 1729 </row> 1730 <row> 1731 <entry>argv</entry> 1732 <entry>NULL</entry> 1733 </row> 1734 </tbody> 1735 </tgroup> 1736</informaltable> 1737 1738<para> 1739The <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> fields are used to initialize 1740the standard property 1741<emphasis role='strong'>WM_COMMAND</emphasis>. See the 1742<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink> 1743for more information. 1744</para> 1745 1746<para> 1747The default values for the SessionShell instance fields, 1748which are filled in from the resource lists and by the 1749initialize procedure, are 1750</para> 1751 1752<informaltable frame='topbot'> 1753 <?dbfo keep-together="always" ?> 1754 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1755 <colspec colwidth='1.0*' colname='c1'/> 1756 <colspec colwidth='1.0*' colname='c2'/> 1757 <thead> 1758 <row rowsep='1'> 1759 <entry>Field</entry> 1760 <entry>Default Value</entry> 1761 </row> 1762 </thead> 1763 <tbody> 1764 <row> 1765 <entry>cancel_callbacks</entry> 1766 <entry>NULL</entry> 1767 </row> 1768 <row> 1769 <entry>clone_command</entry> 1770 <entry>See text</entry> 1771 </row> 1772 <row> 1773 <entry>connection</entry> 1774 <entry>NULL</entry> 1775 </row> 1776 <row> 1777 <entry>current_dir</entry> 1778 <entry>NULL</entry> 1779 </row> 1780 <row> 1781 <entry>die_callbacks</entry> 1782 <entry>NULL</entry> 1783 </row> 1784 <row> 1785 <entry>discard_command</entry> 1786 <entry>NULL</entry> 1787 </row> 1788 <row> 1789 <entry>environment</entry> 1790 <entry>NULL</entry> 1791 </row> 1792 <row> 1793 <entry>error_callbacks</entry> 1794 <entry>NULL</entry> 1795 </row> 1796 <row> 1797 <entry>interact_callbacks</entry> 1798 <entry>NULL</entry> 1799 </row> 1800 <row> 1801 <entry>join_session</entry> 1802 <entry><emphasis role='strong'>True</emphasis></entry> 1803 </row> 1804 <row> 1805 <entry>program_path</entry> 1806 <entry>NULL</entry> 1807 </row> 1808 <row> 1809 <entry>resign_command</entry> 1810 <entry>NULL</entry> 1811 </row> 1812 <row> 1813 <entry>restart_command</entry> 1814 <entry>See text</entry> 1815 </row> 1816 <row> 1817 <entry>restart_style</entry> 1818 <entry><emphasis role='strong'>SmRestartIfRunning</emphasis></entry> 1819 </row> 1820 <row> 1821 <entry>save_callbacks</entry> 1822 <entry>NULL</entry> 1823 </row> 1824 <row> 1825 <entry>save_complete_callbacks</entry> 1826 <entry>NULL</entry> 1827 </row> 1828 <row> 1829 <entry>session_id</entry> 1830 <entry>NULL</entry> 1831 </row> 1832 <row> 1833 <entry>shutdown_command</entry> 1834 <entry>NULL</entry> 1835 </row> 1836 </tbody> 1837 </tgroup> 1838</informaltable> 1839 1840<para> 1841The <emphasis remap='I'>connection</emphasis> field contains the session connection object or NULL 1842if a session connection is not being managed by this widget. 1843</para> 1844 1845<para> 1846The <emphasis remap='I'>session_id</emphasis> is an identification assigned to the session 1847participant by the session manager. 1848The <emphasis remap='I'>session_id</emphasis> will be passed to the session 1849manager as the client identifier of the previous session. 1850When a connection is established with the session manager, 1851the client id assigned by the session manager is stored 1852in the <emphasis remap='I'>session_id</emphasis> field. 1853When not NULL, the <emphasis remap='I'>session_id</emphasis> of the Session shell widget that 1854is at the root of the widget tree of the client leader widget will be 1855used to create the 1856<emphasis role='strong'>SM_CLIENT_ID</emphasis> 1857property on the client leader's window. 1858</para> 1859 1860<para> 1861If <emphasis remap='I'>join_session</emphasis> is 1862<function>False</function>, 1863the widget will not attempt to establish a 1864connection to the session manager at shell creation time. 1865See <xref linkend='Joining_a_Session' /> and 1866<xref linkend='Resigning_from_a_Session' /> 1867for more information on the functionality of this resource. 1868</para> 1869 1870<para> 1871The <emphasis remap='I'>restart_command</emphasis>, <emphasis remap='I'>clone_command</emphasis>, <emphasis remap='I'>discard_command</emphasis>, 1872<emphasis remap='I'>resign_command</emphasis>, <emphasis remap='I'>shutdown_command</emphasis>, <emphasis remap='I'>environment</emphasis>, 1873<emphasis remap='I'>current_dir</emphasis>, <emphasis remap='I'>program_path</emphasis>, and 1874<emphasis remap='I'>restart_style</emphasis> fields contain standard session properties. 1875</para> 1876 1877<para> 1878When a session connection is established or newly managed by the shell, 1879the shell initialize and set_values methods check the values of the 1880<emphasis remap='I'>restart_command</emphasis>, 1881<emphasis remap='I'>clone_command</emphasis>, 1882and <emphasis remap='I'>program_path</emphasis> 1883resources. At that time, if <emphasis remap='I'>restart_command</emphasis> is NULL, the value 1884of the <emphasis remap='I'>argv</emphasis> resource will be copied to <emphasis remap='I'>restart_command</emphasis>. 1885Whether or not <emphasis remap='I'>restart_command</emphasis> was NULL, 1886if "<emphasis>-xtsessionID</emphasis>" "<emphasis><session id></emphasis>" does not 1887already appear in the <emphasis remap='I'>restart_command</emphasis>, it will be added by the 1888initialize and set_values methods at the beginning of the command arguments; 1889if the "<emphasis>-xtsessionID</emphasis>" argument already appears with an incorrect 1890<emphasis>session id</emphasis> in the following argument, that argument 1891will be replaced with the current <emphasis>session id</emphasis>. 1892</para> 1893 1894<para> 1895After this, the shell initialize and set_values procedures check the 1896<emphasis remap='I'>clone_command</emphasis>. If <emphasis remap='I'>clone_command</emphasis> is NULL, 1897<emphasis remap='I'>restart_command</emphasis> will be copied to <emphasis remap='I'>clone_command</emphasis>, 1898except the "<emphasis>-xtsessionID</emphasis>" and following argument will not be copied. 1899</para> 1900 1901<para> 1902Finally, the shell initialize and set_values procedures check the 1903<emphasis remap='I'>program_path</emphasis>. If <emphasis remap='I'>program_path</emphasis> is NULL, the 1904first element of <emphasis remap='I'>restart_command</emphasis> is copied to <emphasis remap='I'>program_path</emphasis>. 1905</para> 1906 1907<para> 1908The possible values of <emphasis remap='I'>restart_style</emphasis> are 1909<function>SmRestartIfRunning</function>, 1910<function>SmRestartAnyway</function>, 1911<function>SmRestartImmediately</function>, 1912and 1913<function>SmRestartNever</function>. 1914A resource converter is registered for this resource; 1915for the strings that it recognizes, 1916see <xref linkend='Predefined_Resource_Converters' />. 1917</para> 1918 1919<para> 1920The resource type EnvironmentArray is a NULL-terminated array of 1921pointers to strings; 1922each string has the format "name=value". 1923The `=' character may not appear in the name, 1924and the string is terminated by a null character. 1925</para> 1926</sect2> 1927</sect1> 1928 1929<sect1 id="Session_Participation"> 1930<title>Session Participation</title> 1931<para> 1932Applications can participate in a user's session, exchanging messages 1933with the session manager as described in the 1934<emphasis>X Session Management Protocol</emphasis> and the 1935<emphasis remap='I'>X Session Management Library</emphasis>. 1936</para> 1937 1938<para> 1939When a widget of 1940<function>sessionShellWidgetClass</function> 1941or a subclass is created, the widget provides support for the application 1942as a session participant and continues to provide support until the 1943widget is destroyed. 1944</para> 1945 1946<sect2 id="Joining_a_Session"> 1947<title>Joining a Session</title> 1948<para> 1949When a Session shell is created, 1950if <emphasis remap='I'>connection</emphasis> is NULL, 1951and if <emphasis remap='I'>join_session</emphasis> is 1952<function>True</function>, 1953and if <emphasis remap='I'>argv</emphasis> or <emphasis remap='I'>restart_command</emphasis> is not NULL, 1954and if in POSIX environments the 1955<emphasis role='strong'>SESSION_MANAGER</emphasis> 1956environment variable is defined, 1957the shell will attempt to establish a new connection with the session manager. 1958</para> 1959 1960<para> 1961To transfer management of an existing session connection from an 1962application to the shell at widget creation time, pass the existing 1963session connection ID as the <emphasis remap='I'>connection</emphasis> resource value 1964when creating the Session shell, 1965and if the other creation-time conditions on session participation are met, 1966the widget will maintain the connection with the session manager. 1967The application must ensure that only one 1968Session shell manages the connection. 1969</para> 1970 1971<para> 1972In the Session shell set_values procedure, 1973if <emphasis remap='I'>join_session</emphasis> changes from 1974<function>False</function> 1975to 1976<function>True</function> 1977and <emphasis remap='I'>connection</emphasis> is NULL and when in POSIX environments the 1978<emphasis role='strong'>SESSION_MANAGER</emphasis> 1979environment variable is defined, 1980the shell will attempt to open a connection to the session manager. 1981If <emphasis remap='I'>connection</emphasis> changes from NULL to non-NULL, the 1982Session shell 1983will take over management of that session connection and will set 1984<emphasis remap='I'>join_session</emphasis> to 1985<function>True</function>. 1986If <emphasis remap='I'>join_session</emphasis> changes from 1987<function>False</function> 1988to 1989<function>True</function> 1990and <emphasis remap='I'>connection</emphasis> is not NULL, the 1991Session shell will take over management of the session connection. 1992</para> 1993 1994<para> 1995When a successful connection has been established, <emphasis remap='I'>connection</emphasis> 1996contains the session connection ID for the session participant. 1997When the shell begins to manage the connection, it will call 1998<xref linkend='XtAppAddInput' xrefstyle='select: title'/> 1999to register the handler which watches for protocol messages 2000from the session manager. 2001When the attempt to connect fails, a warning message is issued 2002and <emphasis remap='I'>connection</emphasis> is set to NULL. 2003</para> 2004 2005<para> 2006While the connection is being managed, if a 2007<function>SaveYourself</function>, 2008<function>SaveYourselfPhase2</function>, 2009<function>Interact</function>, 2010<function>ShutdownCancelled</function>, 2011<function>SaveComplete</function>, 2012or 2013<function>Die</function> 2014message is received from the session manager, the Session shell will 2015call out to application callback procedures registered 2016on the respective callback list of the Session shell and will 2017send 2018<function>SaveYourselfPhase2Request</function>, 2019<function>InteractRequest</function>, 2020<function>InteractDone</function>, 2021<function>SaveYourselfDone</function>, 2022and 2023<function>ConnectionClosed</function> 2024messages as appropriate. 2025Initially, all of the client's session properties are undefined. 2026When any of the session property resource values are defined or change, 2027the Session shell initialize and set_values procedures 2028will update the client's session property value by a 2029<function>SetProperties</function> 2030or a 2031<function>DeleteProperties</function> 2032message, as appropriate. 2033The session ProcessID and UserID properties are always set by the shell 2034when it is possible to determine the value of these properties. 2035</para> 2036</sect2> 2037 2038<sect2 id="Saving_Application_State"> 2039<title>Saving Application State</title> 2040<para> 2041The session manager instigates an application checkpoint by sending a 2042<function>SaveYourself</function> 2043request. 2044Applications are responsible for saving their state in response to the 2045request. 2046</para> 2047 2048<para> 2049When the 2050<function>SaveYourself</function> 2051request arrives, the procedures registered on the 2052Session shell's save callback list are called. 2053If the application does not register any save callback procedures on 2054the save callback list, the shell will report to the session manager 2055that the application failed to save its state. 2056Each procedure on the save callback list receives a token 2057in the <emphasis remap='I'>call_data</emphasis> parameter. 2058</para> 2059 2060<para> 2061The checkpoint token in the <emphasis remap='I'>call_data</emphasis> parameter is of type 2062<function>XtCheckpointToken</function>. 2063</para> 2064 2065<literallayout > 2066typedef struct { 2067 int save_type; 2068 int interact_style; 2069 Boolean shutdown; 2070 Boolean fast; 2071 Boolean cancel_shutdown 2072 int phase; 2073 int interact_dialog_type; /* return */ 2074 Boolean request_cancel; /* return */ 2075 Boolean request_next_phase; /* return */ 2076 Boolean save_success; /* return */ 2077} XtCheckpointTokenRec, *XtCheckpointToken; 2078</literallayout> 2079 2080<para> 2081The <emphasis remap='I'>save_type</emphasis>, <emphasis remap='I'>interact_style</emphasis>, <emphasis remap='I'>shutdown</emphasis>, and <emphasis remap='I'>fast</emphasis> 2082fields of the token contain the parameters of the 2083<function>SaveYourself</function> 2084message. 2085The possible values of <emphasis remap='I'>save_type</emphasis> are 2086<function>SmSaveLocal</function>, 2087<function>SmSaveGlobal</function>, 2088and 2089<function>SmSaveBoth</function>; 2090these indicate the type of information to be saved. 2091The possible values of <emphasis remap='I'>interact_style</emphasis> are 2092<function>SmInteractStyleNone</function>, 2093<function>SmInteractStyleErrors</function>, 2094and 2095<function>SmInteractStyleAny</function>; 2096these indicate whether user interaction would be permitted 2097and, if so, what kind of interaction. 2098If <emphasis remap='I'>shutdown</emphasis> is 2099<function>True</function>, 2100the checkpoint is being performed in preparation for the end of the session. 2101If <emphasis remap='I'>fast</emphasis> is 2102<function>True</function>, 2103the client should perform the checkpoint as quickly as possible. 2104If <emphasis remap='I'>cancel_shutdown</emphasis> is 2105<function>True</function>, 2106a 2107<function>ShutdownCancelled</function> 2108message has been received for the current save operation. 2109(See <xref linkend='Resigning_from_a_Session' />.) 2110The <emphasis remap='I'>phase</emphasis> is used by manager clients, such as a window manager, 2111to distinguish between the first and second phase of a save operation. 2112The <emphasis remap='I'>phase</emphasis> will be either 1 or 2. 2113The remaining fields in the checkpoint token structure are provided for 2114the application to communicate with the shell. 2115</para> 2116 2117<para> 2118Upon entry to the first application save callback procedure, the return 2119fields in the token have the following initial values: 2120<emphasis remap='I'>interact_dialog_type</emphasis> is 2121<function>SmDialogNormal</function>; 2122<emphasis remap='I'>request_cancel</emphasis> is 2123<function>False</function>; 2124<emphasis remap='I'>request_next_phase</emphasis> is 2125<function>False</function>; 2126and <emphasis remap='I'>save_success</emphasis> is 2127<function>True</function>. 2128When a token is returned with any of the four return fields containing 2129a noninitial value, and when the field is applicable, subsequent tokens 2130passed to the application during the current save operation 2131will always contain the noninitial value. 2132</para> 2133 2134<para> 2135The purpose of the token's <emphasis remap='I'>save_success</emphasis> field is to 2136indicate the outcome of the entire operation to the 2137session manager and ultimately, to the user. 2138Returning 2139<function>False</function> 2140indicates some portion of the application state 2141could not be successfully saved. If any token is returned 2142to the shell with <emphasis remap='I'>save_success</emphasis> 2143<function>False</function>, 2144tokens subsequently received 2145by the application for the current save operation will show 2146<emphasis remap='I'>save_success</emphasis> as 2147<function>False</function>. 2148When the shell sends the final status of the checkpoint to the 2149session manager, it will indicate failure to save application state 2150if any token was returned with <emphasis remap='I'>save_success</emphasis> 2151<function>False</function>. 2152</para> 2153 2154<para> 2155Session participants that manage and save the state of other clients 2156should structure their save or interact callbacks to 2157set <emphasis remap='I'>request_next_phase</emphasis> to 2158<function>True</function> 2159when phase is 1, which will cause the shell to send the 2160<function>SaveYourselfPhase2Request</function> 2161when the first phase is complete. When the 2162<function>SaveYourselfPhase2</function> 2163message is received, the shell will invoke the save callbacks a 2164second time with <emphasis remap='I'>phase</emphasis> equal to 2. 2165Manager clients should save the state of other clients 2166when the callbacks are invoked the second time and <emphasis remap='I'>phase</emphasis> equal to 2. 2167</para> 2168 2169<para> 2170The application may request additional tokens while a checkpoint is under way, 2171and these additional tokens must be returned by an explicit call. 2172</para> 2173 2174<para> 2175To request an additional token for a save callback response that has a 2176deferred outcome, use 2177<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>. 2178</para> 2179 2180<funcsynopsis id='XtSessionGetToken'> 2181<funcprototype> 2182<funcdef>XtCheckpointToken <function>XtSessionGetToken</function></funcdef> 2183 <paramdef>Widget <parameter>widget</parameter></paramdef> 2184</funcprototype> 2185</funcsynopsis> 2186 2187<variablelist> 2188 <varlistentry> 2189 <term> 2190 <emphasis remap='I'>widget</emphasis> 2191 </term> 2192 <listitem> 2193 <para> 2194Specifies the Session shell widget which manages session participation. 2195 </para> 2196 </listitem> 2197 </varlistentry> 2198</variablelist> 2199 2200 2201<para> 2202The 2203<xref linkend='XtSessionGetToken' xrefstyle='select: title'/> 2204function will return NULL if no checkpoint operation is currently under way. 2205</para> 2206 2207<para> 2208To indicate the completion of checkpoint processing including user 2209interaction, the application must signal the Session shell 2210by returning all tokens. 2211(See <xref linkend='Interacting_with_the_User_during_a_Checkpoint' /> and 2212<xref linkend='Completing_a_Save' />). 2213To return a token, use 2214<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>. 2215</para> 2216 2217<funcsynopsis id='XtSessionReturnToken'> 2218<funcprototype> 2219<funcdef>void <function>XtSessionReturnToken</function></funcdef> 2220 <paramdef>XtCheckpointToken <parameter>token</parameter></paramdef> 2221</funcprototype> 2222</funcsynopsis> 2223 2224<variablelist> 2225 <varlistentry> 2226 <term> 2227 <emphasis remap='I'>token</emphasis> 2228 </term> 2229 <listitem> 2230 <para> 2231Specifies a token that was received as the <emphasis remap='I'>call_data</emphasis> by a procedure 2232on the interact callback list or a token that was received by a call to 2233<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>. 2234 </para> 2235 </listitem> 2236 </varlistentry> 2237</variablelist> 2238 2239 2240<para> 2241Tokens passed as <emphasis remap='I'>call_data</emphasis> to save callbacks are implicitly 2242returned when the save callback procedure returns. 2243A save callback procedure should not call 2244<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/> 2245on the token passed in its <emphasis remap='I'>call_data</emphasis>. 2246</para> 2247 2248<sect3 id="Requesting_Interaction"> 2249<title>Requesting Interaction</title> 2250<para> 2251When the token <emphasis remap='I'>interact_style</emphasis> allows user interaction, 2252the application may 2253interact with the user during the checkpoint, but must wait for permission 2254to interact. 2255Applications request permission to interact with the user during the 2256checkpointing operation by registering a procedure on the Session 2257shell's interact callback list. When all save callback procedures have 2258returned, and each time a token that was granted by a call to 2259<xref linkend='XtSessionGetToken' xrefstyle='select: title'/> 2260is returned, the Session shell examines the interact callback list. 2261If interaction is permitted and the interact callback list is not empty, 2262the shell will send an 2263<function>InteractRequest</function> 2264to the session manager when an interact request is not already outstanding 2265for the application. 2266</para> 2267 2268<para> 2269The type of interaction dialog that will be requested is specified by 2270the <emphasis remap='I'>interact_dialog_type</emphasis> field in the checkpoint token. 2271The possible values for <emphasis remap='I'>interact_dialog_type</emphasis> are 2272<function>SmDialogError</function> 2273and 2274<function>SmDialogNormal</function>. 2275If a token is returned with <emphasis remap='I'>interact_dialog_type</emphasis> containing 2276<function>SmDialogError</function>, 2277the interact request and any subsequent interact requests will be for 2278an error dialog; otherwise, the request will be for a normal dialog with 2279the user. 2280</para> 2281 2282<para> 2283When a token is returned with <emphasis remap='I'>save_success</emphasis> 2284<function>False</function> 2285or <emphasis remap='I'>interact_dialog_type</emphasis> 2286<function>SmDialogError</function>, 2287tokens subsequently passed to callbacks during the same active 2288<function>SaveYourself</function> 2289response will reflect these changed values, indicating that 2290an error condition has occurred during the checkpoint. 2291</para> 2292 2293<para> 2294The <emphasis remap='I'>request_cancel</emphasis> field is a return value for interact callbacks only. 2295Upon return from a procedure on the save callback list, the value 2296of the token's <emphasis remap='I'>request_cancel</emphasis> field is not examined by the shell. 2297This is also true of tokens received through a call to 2298<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>. 2299</para> 2300</sect3> 2301 2302<sect3 id="Interacting_with_the_User_during_a_Checkpoint"> 2303<title>Interacting with the User during a Checkpoint</title> 2304<para> 2305When the session manager grants the application's request for user interaction, 2306the Session shell receives an 2307<function>Interact</function> 2308message. 2309The procedures registered on the interact callback list are executed, 2310but not as if executing a typical callback list. 2311These procedures are individually executed in 2312sequence, with a checkpoint token functioning as the sequencing mechanism. 2313Each step in the sequence begins by removing a procedure 2314from the interact callback list 2315and executing it with a token passed in the <emphasis remap='I'>call_data</emphasis>. 2316The interact callback will typically pop up a dialog box and return. 2317When the user interaction and associated application checkpointing has 2318completed, the application must return the token by calling 2319<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>. 2320Returning the token completes the current step and triggers the next step 2321in the sequence. 2322</para> 2323 2324<para> 2325During interaction the client may request cancellation of a shutdown. 2326When a token passed as <emphasis remap='I'>call_data</emphasis> to an interact procedure is returned, 2327if <emphasis remap='I'>shutdown</emphasis> is 2328<function>True</function> 2329and <emphasis remap='I'>cancel_shutdown</emphasis> is 2330<function>False</function>, 2331<emphasis remap='I'>request_cancel</emphasis> indicates whether the 2332application requests that the pending shutdown be cancelled. 2333If <emphasis remap='I'>request_cancel</emphasis> is 2334<function>True</function>, 2335the field will also be 2336<function>True</function> 2337in any tokens subsequently granted during the checkpoint operation. 2338When a token is returned requesting cancellation of 2339the session shutdown, pending interact procedures will still be 2340called by the Session shell. 2341When all interact procedures have been removed from the interact callback 2342list, executed, and the final interact token returned to the shell, an 2343<function>InteractDone</function> 2344message is sent to the session manager, indicating whether 2345a pending session shutdown is requested to be cancelled. 2346</para> 2347</sect3> 2348 2349<sect3 id="Responding_to_a_Shutdown_Cancellation"> 2350<title>Responding to a Shutdown Cancellation</title> 2351<para> 2352Callbacks registered on the cancel callback list are invoked when the 2353Session shell processes a 2354<function>ShutdownCancelled</function> 2355message from the session manager. This may occur during the 2356processing of save callbacks, while waiting for interact permission, 2357during user interaction, or after the save operation is complete and 2358the application is expecting a 2359<function>SaveComplete</function> 2360or a 2361<function>Die</function> 2362message. 2363The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL. 2364</para> 2365 2366<para> 2367When the shell notices that a pending shutdown has been cancelled, 2368the token <emphasis remap='I'>cancel_shutdown</emphasis> field will be 2369<function>True</function> 2370in tokens subsequently given to the application. 2371</para> 2372 2373<para> 2374Receiving notice of a shutdown cancellation does not cancel the 2375pending execution of save callbacks or interact callbacks. 2376After the cancel callbacks execute, if <emphasis remap='I'>interact_style</emphasis> is not 2377<function>SmInteractStyleNone</function> 2378and the interact list is not empty, 2379the procedures on the interact callback list will be executed 2380and passed a token with <emphasis remap='I'>interact_style</emphasis> 2381<function>SmInteractStyleNone</function>. 2382The application should not interact with the user, and the Session shell 2383will not send an 2384<function>InteractDone</function> 2385message. 2386</para> 2387</sect3> 2388 2389<sect3 id="Completing_a_Save"> 2390<title>Completing a Save</title> 2391<para> 2392When there is no user interaction, the shell regards the application 2393as having finished saving state when all callback procedures 2394on the save callback list have returned, and any additional tokens 2395passed out by 2396<xref linkend='XtSessionGetToken' xrefstyle='select: title'/> 2397have been returned by corresponding calls to 2398<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>. 2399If the save operation involved user interaction, 2400the above completion conditions apply, and in addition, all requests for 2401interaction have been granted or cancelled, 2402and all tokens passed to interact callbacks have been returned 2403through calls to 2404<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>. 2405If the save operation involved a manager client that requested the 2406second phase, the above conditions apply to both the first and second 2407phase of the save operation. 2408</para> 2409 2410<para> 2411When the application has finished saving state, 2412the Session shell will report the result to the session manager by 2413sending the 2414<function>SaveYourselfDone</function> 2415message. 2416If the session is continuing, the shell will receive the 2417<function>SaveComplete</function> 2418message when all applications have completed saving state. 2419This message indicates that applications may again allow changes 2420to their state. The shell will execute the save_complete callbacks. 2421The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL. 2422</para> 2423</sect3> 2424</sect2> 2425 2426<sect2 id="Responding_to_a_Shutdown"> 2427<title>Responding to a Shutdown</title> 2428<para> 2429Callbacks registered on the die callback list are invoked when the 2430session manager sends a 2431<function>Die</function> 2432message. 2433The callbacks on this list should do whatever is appropriate to quit 2434the application. 2435Before executing procedures on the die callback list, 2436the Session shell will close the connection to the session manager 2437and will remove the handler that watches for protocol messages. 2438The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL. 2439</para> 2440</sect2> 2441 2442<sect2 id="Resigning_from_a_Session"> 2443<title>Resigning from a Session</title> 2444<para> 2445When the Session shell widget is destroyed, the destroy method will 2446close the connection to the session manager by sending a 2447<function>ConnectionClosed</function> 2448protocol message and will remove the input callback 2449that was watching for session protocol messages. 2450</para> 2451 2452<para> 2453When 2454<xref linkend='XtSetValues' xrefstyle='select: title'/> 2455is used to set <emphasis remap='I'>join_session</emphasis> to 2456<function>False</function>, 2457the set_values method of the Session shell will close the 2458connection to the session manager if one exists by sending a 2459<function>ConnectionClosed</function> 2460message, and <emphasis remap='I'>connection</emphasis> will be set to NULL. 2461</para> 2462 2463<para> 2464Applications that exit in response to user actions and that do not 2465wait for phase 2 destroy to complete on 2466the Session shell should set <emphasis remap='I'>join_session</emphasis> to 2467<function>False</function> 2468before exiting. 2469</para> 2470 2471<para> 2472When 2473<xref linkend='XtSetValues' xrefstyle='select: title'/> 2474is used to set <emphasis remap='I'>connection</emphasis> to NULL, 2475the Session shell will stop managing the connection, if one exists. 2476However, that session connection will not be closed. 2477</para> 2478 2479<para> 2480Applications that wish to ensure continuation of a session connection 2481beyond the destruction of the shell should first retrieve the 2482<emphasis remap='I'>connection</emphasis> resource value, 2483then set the <emphasis remap='I'>connection</emphasis> resource to NULL, 2484and then they may safely destroy the widget without losing control 2485of the session connection. 2486</para> 2487 2488<para> 2489The error callback list will be called if an unrecoverable 2490communications error occurs while the shell is managing the connection. 2491The shell will close the connection, set <emphasis remap='I'>connection</emphasis> to NULL, 2492remove the input callback, and 2493call the procedures registered on the error callback list. 2494The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL. 2495</para> 2496</sect2> 2497</sect1> 2498</chapter> 2499