1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> 3 4<chapter id='Shell_Widgets'> 5<title>Shell Widgets</title> 6 7<para> 8Shell widgets hold an application's top-level widgets to allow them to 9communicate with the window manager and session manager. 10Shells have been designed to be as nearly invisible as possible. 11Clients have to create them, 12but they should never have to worry about their sizes. 13</para> 14 15<para> 16If a shell widget is resized from the outside (typically by a window manager), 17the shell widget also resizes its managed child widget automatically. 18Similarly, if the shell's child widget needs to change size, 19it can make a geometry request to the shell, 20and the shell negotiates the size change with the outer environment. 21Clients should never attempt to change the size of their shells directly. 22</para> 23 24<para>The five types of public shells are:</para> 25<variablelist> 26 <varlistentry> 27 <term>OverrideShell</term> 28 <listitem> 29 <para> 30 Used for shell windows that completely bypass the window manager 31 (for example, pop-up menu shells). 32 </para> 33 </listitem> 34 </varlistentry> 35 <varlistentry> 36 <term>TransientShell</term> 37 <listitem> 38 <para>Used for shell windows that have the 39 <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis> 40 property set. The effect of this property is dependent upon the 41 window manager being used. 42 </para> 43 </listitem> 44 </varlistentry> 45 <varlistentry> 46 <term>TopLevelShell</term> 47 <listitem> 48 <para>Used for normal top-level windows 49 (for example, any additional top-level widgets an application needs). 50 </para> 51 </listitem> 52 </varlistentry> 53 <varlistentry> 54 <term>ApplicationShell</term> 55 <listitem> 56 <para>Formerly used for the single main top-level window that 57 the window manager identifies as an application instance and 58 made obsolete by SessionShell. 59 </para> 60 </listitem> 61 </varlistentry> 62 <varlistentry> 63 <term>SessionShell</term> 64 <listitem> 65 <para> 66 Used for the single main top-level window that 67 the window manager identifies as an application instance and 68 that interacts with the session manager. 69 </para> 70 </listitem> 71 </varlistentry> 72</variablelist> 73 74<sect1 id="Shell_Widget_Definitions"> 75<title>Shell Widget Definitions</title> 76<para> 77Widgets negotiate their size and position with their parent widget, 78that is, the widget that directly contains them. 79Widgets at the top of the hierarchy do not have parent widgets. 80Instead, they must deal with the outside world. 81To provide for this, 82each top-level widget is encapsulated in a special widget, called a 83shell widget. 84</para> 85 86<para> 87Shell 88widgets, whose class is a subclass of the 89Composite class, 90encapsulate other widgets and can allow a widget to avoid the 91geometry clipping imposed by the parent-child window relationship. 92They also can provide a layer of communication with the window manager. 93</para> 94 95<para>The eight different types of shells are:</para> 96<variablelist> 97 <varlistentry> 98 <term>Shell</term> 99 <listitem> 100 <para>The base class for shell widgets; provides the 101 fields needed for all types of shells. Shell 102 is a direct subclass of 103 <emphasis role='strong'>compositeWidgetClass</emphasis>. 104 </para> 105 </listitem> 106 </varlistentry> 107 <varlistentry> 108 <term>OverrideShell</term> 109 <listitem> 110 <para>A subclass of Shell; used for shell windows that completely 111 bypass the window manager.</para> 112 </listitem> 113 </varlistentry> 114 <varlistentry> 115 <term>WMShell</term> 116 <listitem> 117 <para>A subclass of Shell; contains fields needed by the 118 common window manager protocol.</para> 119 </listitem> 120 </varlistentry> 121 <varlistentry> 122 <term>VendorShell</term> 123 <listitem> 124 <para>A subclass of WMShell; contains fields used by 125 vendor-specific window managers. 126 </para> 127 </listitem> 128 </varlistentry> 129 <varlistentry> 130 <term>TransientShell</term> 131 <listitem> 132 <para>A subclass of VendorShell; used for shell windows that 133 desire the <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis> 134 property.</para> 135 </listitem> 136 </varlistentry> 137 <varlistentry> 138 <term>TopLevelShell</term> 139 <listitem> 140 <para>A subclass of VendorShell; used for normal top-level windows. 141 </para> 142 </listitem> 143 </varlistentry> 144 <varlistentry> 145 <term>ApplicationShell</term> 146 <listitem> 147 <para>A subclass of TopLevelShell; may be used for an application's additional 148 root windows.</para> 149 </listitem> 150 </varlistentry> 151 <varlistentry> 152 <term>SessionShell</term> 153 <listitem> 154 <para>A subclass of ApplicationShell; used for an application's 155 main root window.</para> 156 </listitem> 157 </varlistentry> 158</variablelist> 159 160<para> 161Note that the classes 162Shell, 163WMShell, 164and 165VendorShell 166are internal and should not be instantiated or subclassed. 167Only 168OverrrideShell, 169TransientShell, 170TopLevelShell, 171ApplicationShell, 172and 173SessionShell 174are intended for public use. 175</para> 176 177<sect2 id="ShellClassPart_Definitions"> 178<title>ShellClassPart Definitions</title> 179<para> 180Only the Shell 181class has additional class fields, which are all contained in the 182<function>ShellClassExtensionRec</function>. 183None of the other Shell classes have any additional class fields: 184</para> 185 186<programlisting> 187typedef struct { 188 XtPointer extension; 189} ShellClassPart, OverrideShellClassPart, 190WMShellClassPart, VendorShellClassPart, TransientShellClassPart, 191TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart; 192</programlisting> 193 194<para>The full Shell class record definitions are:</para> 195 196<programlisting> 197typedef struct _ShellClassRec { 198 CoreClassPart core_class; 199 CompositeClassPart composite_class; 200 ShellClassPart shell_class; 201} ShellClassRec; 202</programlisting> 203 204<programlisting> 205typedef struct { <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation> 206 XtPointer next_extension; 207 XrmQuark record_type; 208 long version; 209 Cardinal record_size; 210 XtGeometryHandler root_geometry_manager; See below 211} ShellClassExtensionRec, *ShellClassExtension; 212</programlisting> 213 214<programlisting> 215typedef struct _OverrideShellClassRec { 216 CoreClassPart core_class; 217 CompositeClassPart composite_class; 218 ShellClassPart shell_class; 219 OverrideShellClassPart override_shell_class; 220} OverrideShellClassRec; 221</programlisting> 222 223<programlisting> 224typedef struct _WMShellClassRec { 225 CoreClassPart core_class; 226 CompositeClassPart composite_class; 227 ShellClassPart shell_class; 228 WMShellClassPart wm_shell_class; 229} WMShellClassRec; 230</programlisting> 231 232<programlisting> 233typedef struct _VendorShellClassRec { 234 CoreClassPart core_class; 235 CompositeClassPart composite_class; 236 ShellClassPart shell_class; 237 WMShellClassPart wm_shell_class; 238 VendorShellClassPart vendor_shell_class; 239} VendorShellClassRec; 240</programlisting> 241 242<programlisting> 243typedef struct _TransientShellClassRec { 244 CoreClassPart core_class; 245 CompositeClassPart composite_class; 246 ShellClassPart shell_class; 247 WMShellClassPart wm_shell_class; 248 VendorShellClassPart vendor_shell_class; 249 TransientShellClassPart transient_shell_class; 250} TransientShellClassRec; 251</programlisting> 252 253<programlisting> 254typedef struct _TopLevelShellClassRec { 255 CoreClassPart core_class; 256 CompositeClassPart composite_class; 257 ShellClassPart shell_class; 258 WMShellClassPart wm_shell_class; 259 VendorShellClassPart vendor_shell_class; 260 TopLevelShellClassPart top_level_shell_class; 261} TopLevelShellClassRec; 262</programlisting> 263 264<programlisting> 265typedef struct _ApplicationShellClassRec { 266 CoreClassPart core_class; 267 CompositeClassPart composite_class; 268 ShellClassPart shell_class; 269 WMShellClassPart wm_shell_class; 270 VendorShellClassPart vendor_shell_class; 271 TopLevelShellClassPart top_level_shell_class; 272 ApplicationShellClassPart application_shell_class; 273} ApplicationShellClassRec; 274</programlisting> 275 276<programlisting> 277typedef struct _SessionShellClassRec { 278 CoreClassPart core_class; 279 CompositeClassPart composite_class; 280 ShellClassPart shell_class; 281 WMShellClassPart wm_shell_class; 282 VendorShellClassPart vendor_shell_class; 283 TopLevelShellClassPart top_level_shell_class; 284 ApplicationShellClassPart application_shell_class; 285 SessionShellClassPart session_shell_class; 286} SessionShellClassRec; 287</programlisting> 288 289<para> 290The single occurrences of the class records and pointers for creating 291instances of shells are: 292</para> 293 294<programlisting> 295extern ShellClassRec shellClassRec; 296extern OverrideShellClassRec overrideShellClassRec; 297extern WMShellClassRec wmShellClassRec; 298extern VendorShellClassRec vendorShellClassRec; 299extern TransientShellClassRec transientShellClassRec; 300extern TopLevelShellClassRec topLevelShellClassRec; 301extern ApplicationShellClassRec applicationShellClassRec; 302extern SessionShellClassRec sessionShellClassRec; 303extern WidgetClass shellWidgetClass; 304extern WidgetClass overrideShellWidgetClass; 305extern WidgetClass wmShellWidgetClass; 306extern WidgetClass vendorShellWidgetClass; 307extern WidgetClass transientShellWidgetClass; 308extern WidgetClass topLevelShellWidgetClass; 309extern WidgetClass applicationShellWidgetClass; 310extern WidgetClass sessionShellWidgetClass; 311</programlisting> 312 313<para> 314The following opaque types and opaque variables are defined 315for generic operations on widgets whose class is a subclass of 316Shell. 317</para> 318 319<informaltable frame='topbot'> 320 <?dbfo keep-together="auto" ?> 321 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 322 <colspec colwidth='1.0*' colname='c1'/> 323 <colspec colwidth='1.0*' colname='c2'/> 324 <thead> 325 <row rowsep='1'> 326 <entry>Types</entry> 327 <entry>Variables</entry> 328 </row> 329 </thead> 330 <tbody> 331 <row> 332 <entry><emphasis role='strong'>ShellWidget</emphasis></entry> 333 <entry><emphasis role='strong'>shellWidgetClass</emphasis></entry> 334 </row> 335 <row> 336 <entry><emphasis role='strong'>OverrideShellWidget</emphasis></entry> 337 <entry><emphasis role='strong'>overrideShellWidgetClass</emphasis></entry> 338 </row> 339 <row> 340 <entry><emphasis role='strong'>WMShellWidget</emphasis></entry> 341 <entry><emphasis role='strong'>wmShellWidgetClass</emphasis></entry> 342 </row> 343 <row> 344 <entry><emphasis role='strong'>VendorShellWidget</emphasis></entry> 345 <entry><emphasis role='strong'>vendorShellWidgetClass</emphasis></entry> 346 </row> 347 <row> 348 <entry><emphasis role='strong'>TransientShellWidget</emphasis></entry> 349 <entry><emphasis role='strong'>transientShellWidgetClass</emphasis></entry> 350 </row> 351 <row> 352 <entry><emphasis role='strong'>TopLevelShellWidget</emphasis></entry> 353 <entry><emphasis role='strong'>topLevelShellWidgetClass</emphasis></entry> 354 </row> 355 <row> 356 <entry><emphasis role='strong'>ApplicationShellWidget</emphasis></entry> 357 <entry><emphasis role='strong'>applicationShellWidgetClass</emphasis></entry> 358 </row> 359 <row> 360 <entry><emphasis role='strong'>SessionShellWidget</emphasis></entry> 361 <entry><emphasis role='strong'>sessionShellWidgetClass</emphasis></entry> 362 </row> 363 <row> 364 <entry><emphasis role='strong'>ShellWidgetClass</emphasis></entry> 365 <entry></entry> 366 </row> 367 <row> 368 <entry><emphasis role='strong'>OverrideShellWidgetClass</emphasis></entry> 369 <entry></entry> 370 </row> 371 <row> 372 <entry><emphasis role='strong'>WMShellWidgetClass</emphasis></entry> 373 <entry></entry> 374 </row> 375 <row> 376 <entry><emphasis role='strong'>VendorShellWidgetClass</emphasis></entry> 377 <entry></entry> 378 </row> 379 <row> 380 <entry><emphasis role='strong'>TransientShellWidgetClass</emphasis></entry> 381 <entry></entry> 382 </row> 383 <row> 384 <entry><emphasis role='strong'>TopLevelShellWidgetClass</emphasis></entry> 385 <entry></entry> 386 </row> 387 <row> 388 <entry><emphasis role='strong'>ApplicationShellWidgetClass</emphasis></entry> 389 <entry></entry> 390 </row> 391 <row> 392 <entry><emphasis role='strong'>SessionShellWidgetClass</emphasis></entry> 393 <entry></entry> 394 </row> 395 </tbody> 396 </tgroup> 397</informaltable> 398 399<para> 400The declarations for all Intrinsics-defined shells except 401VendorShell appear in 402<filename class="headerfile">Shell.h</filename> 403and 404<filename class="headerfile">ShellP.h</filename>. 405VendorShell has separate public and private .h files which are included by 406<filename class="headerfile">Shell.h</filename> 407and 408<filename class="headerfile">ShellP.h</filename>. 409</para> 410 411<para> 412<filename class="headerfile">Shell.h</filename> 413uses incomplete structure definitions to ensure that the 414compiler catches attempts to access private data in any of the Shell 415instance or class data structures. 416</para> 417 418<para> 419The symbolic constant for the 420<function>ShellClassExtension</function> 421version identifier is 422<function>XtShellExtensionVersion</function> 423(see <xref linkend='Class_Extension_Records' />). 424</para> 425 426<para> 427The root_geometry_manager procedure acts as 428the parent geometry manager for geometry requests made by shell 429widgets. When a shell widget calls either 430<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/> 431or 432<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>, 433the root_geometry_manager procedure is invoked to 434negotiate the new geometry with the window manager. If the window 435manager permits the new geometry, the root_geometry_manager 436procedure should 437return 438<function>XtGeometryYes</function>; 439if the window manager denies the geometry 440request or does not change the window geometry within some timeout 441interval (equal to <emphasis remap='I'>wm_timeout</emphasis> in the case of WMShells), the 442root_geometry_manager procedure should return 443<function>XtGeometryNo</function>. 444If the window manager makes some alternative geometry change, the 445root_geometry_manager procedure may return either 446<function>XtGeometryNo</function> 447and handle the new geometry as a resize or 448<function>XtGeometryAlmost</function> 449in anticipation that the shell will accept the compromise. If the 450compromise is not accepted, the new size must then be handled as a 451resize. Subclasses of 452Shell 453that wish to provide their own 454root_geometry_manager procedures are strongly encouraged to use enveloping to 455invoke their superclass's root_geometry_manager procedure under most 456situations, as the window manager interaction may be very complex. 457</para> 458 459<para> 460If no 461<function>ShellClassPart</function> 462extension record is declared with <emphasis remap='I'>record_type</emphasis> 463equal to 464<emphasis role='strong'>NULLQUARK</emphasis>, 465then 466<function>XtInheritRootGeometryManager</function> 467is assumed. 468</para> 469</sect2> 470 471<sect2 id="ShellPart_Definition"> 472<title>ShellPart Definition</title> 473<para> 474The various shell widgets have the following additional instance 475fields defined in 476their widget records: 477</para> 478 479<programlisting> 480typedef struct { 481 String geometry; 482 XtCreatePopupChildProc create_popup_child_proc; 483 XtGrabKind grab_kind; 484 Boolean spring_loaded; 485 Boolean popped_up; 486 Boolean allow_shell_resize; 487 Boolean client_specified; 488 Boolean save_under; 489 Boolean override_redirect; 490 XtCallbackList popup_callback; 491 XtCallbackList popdown_callback; 492 Visual * visual; 493} ShellPart; 494</programlisting> 495 496<programlisting> 497typedef struct { 498 int empty; 499} OverrideShellPart; 500</programlisting> 501 502<programlisting> 503typedef struct { 504 String title; 505 int wm_timeout; 506 Boolean wait_for_wm; 507 Boolean transient; 508 Boolean urgency; 509 Widget client_leader; 510 String window_role; 511 struct _OldXSizeHints { 512 long flags; 513 int x, y; 514 int width, height; 515 int min_width, min_height; 516 int max_width, max_height; 517 int width_inc, height_inc; 518 struct { 519 int x; 520 int y; 521 } min_aspect, max_aspect; 522 } size_hints; 523 XWMHints wm_hints; 524 int base_width, base_height, win_gravity; 525 Atom title_encoding; 526} WMShellPart; 527</programlisting> 528 529<programlisting> 530typedef struct { 531 int vendor_specific; 532} VendorShellPart; 533</programlisting> 534 535<programlisting> 536typedef struct { 537 Widget transient_for; 538} TransientShellPart; 539typedef struct { 540 String icon_name; 541 Boolean iconic; 542 Atom icon_name_encoding; 543} TopLevelShellPart; 544</programlisting> 545 546<programlisting> 547typedef struct { 548 char * class; 549 XrmClass xrm_class; 550 int argc; 551 char ** argv; 552} ApplicationShellPart; 553</programlisting> 554 555<programlisting> 556typedef struct { 557 SmcConn connection; 558 String session_id; 559 String * restart_command; 560 String * clone_command; 561 String * discard_command; 562 String * resign_command; 563 String * shutdown_command; 564 String * environment; 565 String current_dir; 566 String program_path; 567 unsigned char restart_style; 568 Boolean join_session; 569 XtCallbackList save_callbacks; 570 XtCallbackList interact_callbacks; 571 XtCallbackList cancel_callbacks; 572 XtCallbackList save_complete_callbacks; 573 XtCallbackList die_callbacks; 574 XtCallbackList error_callbacks; 575} SessionShellPart; 576</programlisting> 577 578<para> 579The full shell widget instance record definitions are: 580</para> 581 582<programlisting> 583typedef struct { 584 CorePart core; 585 CompositePart composite; 586 ShellPart shell; 587} ShellRec, *ShellWidget; 588</programlisting> 589 590<programlisting> 591typedef struct { 592 CorePart core; 593 CompositePart composite; 594 ShellPart shell; 595 OverrideShellPart override; 596} OverrideShellRec, *OverrideShellWidget; 597</programlisting> 598 599<programlisting> 600typedef struct { 601 CorePart core; 602 CompositePart composite; 603 ShellPart shell; 604 WMShellPart wm; 605} WMShellRec, *WMShellWidget; 606</programlisting> 607 608<programlisting> 609typedef struct { 610 CorePart core; 611 CompositePart composite; 612 ShellPart shell; 613 WMShellPart wm; 614 VendorShellPart vendor; 615} VendorShellRec, *VendorShellWidget; 616</programlisting> 617 618<programlisting> 619typedef struct { 620 CorePart core; 621 CompositePart composite; 622 ShellPart shell; 623 WMShellPart wm; 624 VendorShellPart vendor; 625 TransientShellPart transient; 626} TransientShellRec, *TransientShellWidget; 627</programlisting> 628 629<programlisting> 630typedef struct { 631 CorePart core; 632 CompositePart composite; 633 ShellPart shell; 634 WMShellPart wm; 635 VendorShellPart vendor; 636 TopLevelShellPart topLevel; 637} TopLevelShellRec, *TopLevelShellWidget; 638</programlisting> 639 640<programlisting> 641typedef struct { 642 CorePart core; 643 CompositePart composite; 644 ShellPart shell; 645 WMShellPart wm; 646 VendorShellPart vendor; 647 TopLevelShellPart topLevel; 648 ApplicationShellPart application; 649} ApplicationShellRec, *ApplicationShellWidget; 650</programlisting> 651 652<programlisting> 653typedef struct { 654 CorePart core; 655 CompositePart composite; 656 ShellPart shell; 657 WMShellPart wm; 658 VendorShellPart vendor; 659 TopLevelShellPart topLevel; 660 ApplicationShellPart application; 661 SessionShellPart session; 662} SessionShellRec, *SessionShellWidget; 663</programlisting> 664 665</sect2> 666 667<sect2 id="Shell_Resources"> 668<title>Shell Resources</title> 669<para> 670The resource names, classes, and representation types specified in 671the 672<function>shellClassRec</function> 673resource list are: 674</para> 675 676<informaltable frame='topbot'> 677 <?dbfo keep-together="always" ?> 678 <tgroup cols='3' align='left' rowsep='0' colsep='0'> 679 <colspec colwidth='1.0*' colname='c1'/> 680 <colspec colwidth='1.0*' colname='c2'/> 681 <colspec colwidth='1.0*' colname='c3'/> 682 <thead> 683 <row rowsep='1'> 684 <entry>Name</entry> 685 <entry>Class</entry> 686 <entry>Representation</entry> 687 </row> 688 </thead> 689 <tbody> 690 <row> 691 <entry>XtNallowShellResize</entry> 692 <entry>XtCAllowShellResize</entry> 693 <entry>XtRBoolean</entry> 694 </row> 695 <row> 696 <entry>XtNcreatePopupChildProc</entry> 697 <entry>XtCCreatePopupChildProc</entry> 698 <entry>XtRFunction</entry> 699 </row> 700 <row> 701 <entry>XtNgeometry</entry> 702 <entry>XtCGeometry</entry> 703 <entry>XtRString</entry> 704 </row> 705 <row> 706 <entry>XtNoverrideRedirect</entry> 707 <entry>XtCOverrideRedirect</entry> 708 <entry>XtRBoolean</entry> 709 </row> 710 <row> 711 <entry>XtNpopdownCallback</entry> 712 <entry>XtCCallback</entry> 713 <entry>XtRCallback</entry> 714 </row> 715 <row> 716 <entry>XtNpopupCallback</entry> 717 <entry>XtCCallback</entry> 718 <entry>XtRCallback</entry> 719 </row> 720 <row> 721 <entry>XtNsaveUnder</entry> 722 <entry>XtCSaveUnder</entry> 723 <entry>XtRBoolean</entry> 724 </row> 725 <row> 726 <entry>XtNvisual</entry> 727 <entry>XtCVisual</entry> 728 <entry>XtRVisual</entry> 729 </row> 730 </tbody> 731 </tgroup> 732</informaltable> 733 734<para> 735OverrideShell 736declares no additional resources beyond those defined by 737Shell. 738</para> 739 740<para> 741The resource names, classes, and representation types specified in 742the 743<function>wmShellClassRec</function> 744resource list are: 745</para> 746 747<informaltable frame='topbot'> 748 <?dbfo keep-together="always" ?> 749 <tgroup cols='3' align='left' rowsep='0' colsep='0'> 750 <colspec colwidth='1.0*' colname='c1'/> 751 <colspec colwidth='1.0*' colname='c2'/> 752 <colspec colwidth='1.0*' colname='c3'/> 753 <thead> 754 <row rowsep='1'> 755 <entry>Name</entry> 756 <entry>Class</entry> 757 <entry>Representation</entry> 758 </row> 759 </thead> 760 <tbody> 761 <row> 762 <entry>XtNbaseHeight</entry> 763 <entry>XtCBaseHeight</entry> 764 <entry>XtRInt</entry> 765 </row> 766 <row> 767 <entry>XtNbaseWidth</entry> 768 <entry>XtCBaseWidth</entry> 769 <entry>XtRInt</entry> 770 </row> 771 <row> 772 <entry>XtNclientLeader</entry> 773 <entry>XtCClientLeader</entry> 774 <entry>XtRWidget</entry> 775 </row> 776 <row> 777 <entry>XtNheightInc</entry> 778 <entry>XtCHeightInc</entry> 779 <entry>XtRInt</entry> 780 </row> 781 <row> 782 <entry>XtNiconMask</entry> 783 <entry>XtCIconMask</entry> 784 <entry>XtRBitmap</entry> 785 </row> 786 <row> 787 <entry>XtNiconPixmap</entry> 788 <entry>XtCIconPixmap</entry> 789 <entry>XtRBitmap</entry> 790 </row> 791 <row> 792 <entry>XtNiconWindow</entry> 793 <entry>XtCIconWindow</entry> 794 <entry>XtRWindow</entry> 795 </row> 796 <row> 797 <entry>XtNiconX</entry> 798 <entry>XtCIconX</entry> 799 <entry>XtRInt</entry> 800 </row> 801 <row> 802 <entry>XtNiconY</entry> 803 <entry>XtCIconY</entry> 804 <entry>XtRInt</entry> 805 </row> 806 <row> 807 <entry>XtNinitialState</entry> 808 <entry>XtCInitialState</entry> 809 <entry>XtRInitialState</entry> 810 </row> 811 <row> 812 <entry>XtNinput</entry> 813 <entry>XtCInput</entry> 814 <entry>XtRBool</entry> 815 </row> 816 <row> 817 <entry>XtNmaxAspectX</entry> 818 <entry>XtCMaxAspectX</entry> 819 <entry>XtRInt</entry> 820 </row> 821 <row> 822 <entry>XtNmaxAspectY</entry> 823 <entry>XtCMaxAspectY</entry> 824 <entry>XtRInt</entry> 825 </row> 826 <row> 827 <entry>XtNmaxHeight</entry> 828 <entry>XtCMaxHeight</entry> 829 <entry>XtRInt</entry> 830 </row> 831 <row> 832 <entry>XtNmaxWidth</entry> 833 <entry>XtCMaxWidth</entry> 834 <entry>XtRInt</entry> 835 </row> 836 <row> 837 <entry>XtNminAspectX</entry> 838 <entry>XtCMinAspectX</entry> 839 <entry>XtRInt</entry> 840 </row> 841 <row> 842 <entry>XtNminAspectY</entry> 843 <entry>XtCMinAspectY</entry> 844 <entry>XtRInt</entry> 845 </row> 846 <row> 847 <entry>XtNminHeight</entry> 848 <entry>XtCMinHeight</entry> 849 <entry>XtRInt</entry> 850 </row> 851 <row> 852 <entry>XtNminWidth</entry> 853 <entry>XtCMinWidth</entry> 854 <entry>XtRInt</entry> 855 </row> 856 <row> 857 <entry>XtNtitle</entry> 858 <entry>XtCTitle</entry> 859 <entry>XtRString</entry> 860 </row> 861 <row> 862 <entry>XtNtitleEncoding</entry> 863 <entry>XtCTitleEncoding</entry> 864 <entry>XtRAtom</entry> 865 </row> 866 <row> 867 <entry>XtNtransient</entry> 868 <entry>XtCTransient</entry> 869 <entry>XtRBoolean</entry> 870 </row> 871 <row> 872 <entry>XtNwaitforwm, XtNwaitForWm</entry> 873 <entry>XtCWaitforwm, XtCWaitForWm</entry> 874 <entry>XtRBoolean</entry> 875 </row> 876 <row> 877 <entry>XtNwidthInc</entry> 878 <entry>XtCWidthInc</entry> 879 <entry>XtRInt</entry> 880 </row> 881 <row> 882 <entry>XtNwindowRole</entry> 883 <entry>XtCWindowRole</entry> 884 <entry>XtRString</entry> 885 </row> 886 <row> 887 <entry>XtNwinGravity</entry> 888 <entry>XtCWinGravity</entry> 889 <entry>XtRGravity</entry> 890 </row> 891 <row> 892 <entry>XtNwindowGroup</entry> 893 <entry>XtCWindowGroup</entry> 894 <entry>XtRWindow</entry> 895 </row> 896 <row> 897 <entry>XtNwmTimeout</entry> 898 <entry>XtCWmTimeout</entry> 899 <entry>XtRInt</entry> 900 </row> 901 <row> 902 <entry>XtNurgency</entry> 903 <entry>XtCUrgency</entry> 904 <entry>XtRBoolean</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>transientShellClassRec</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>applicationShellClassRec</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' >Parsing the Window Geometry</olink> 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' >Window Attributes</olink> in 1282<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink> 1283and 1284<olink targetdoc='icccm' targetptr='Pop_up_Windows'>Pop-up Windows</olink> and 1285<olink targetdoc='icccm' targetptr='Redirection_of_Operations'>Redirection of Operations</olink> 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<programlisting> 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</programlisting> 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