From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH04.xml | 2498 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2498 insertions(+) create mode 100644 libXt/specs/CH04.xml (limited to 'libXt/specs/CH04.xml') diff --git a/libXt/specs/CH04.xml b/libXt/specs/CH04.xml new file mode 100644 index 000000000..d01fe6eae --- /dev/null +++ b/libXt/specs/CH04.xml @@ -0,0 +1,2498 @@ + +Shell Widgets + + +Shell widgets hold an application's top-level widgets to allow them to +communicate with the window manager and session manager. +Shells have been designed to be as nearly invisible as possible. +Clients have to create them, +but they should never have to worry about their sizes. + + + +If a shell widget is resized from the outside (typically by a window manager), +the shell widget also resizes its managed child widget automatically. +Similarly, if the shell's child widget needs to change size, +it can make a geometry request to the shell, +and the shell negotiates the size change with the outer environment. +Clients should never attempt to change the size of their shells directly. + + +The five types of public shells are: + + + OverrideShell + + + Used for shell windows that completely bypass the window manager + (for example, pop-up menu shells). + + + + + TransientShell + + Used for shell windows that have the + WM_TRANSIENT_FOR + property set. The effect of this property is dependent upon the + window manager being used. + + + + + TopLevelShell + + Used for normal top-level windows + (for example, any additional top-level widgets an application needs). + + + + + ApplicationShell + + Formerly used for the single main top-level window that + the window manager identifies as an application instance and + made obsolete by SessionShell. + + + + + SessionShell + + + Used for the single main top-level window that + the window manager identifies as an application instance and + that interacts with the session manager. + + + + + + +Shell Widget Definitions + +Widgets negotiate their size and position with their parent widget, +that is, the widget that directly contains them. +Widgets at the top of the hierarchy do not have parent widgets. +Instead, they must deal with the outside world. +To provide for this, +each top-level widget is encapsulated in a special widget, called a +shell widget. + + + +Shell +widgets, whose class is a subclass of the +Composite class, +encapsulate other widgets and can allow a widget to avoid the +geometry clipping imposed by the parent-child window relationship. +They also can provide a layer of communication with the window manager. + + +The eight different types of shells are: + + + Shell + + The base class for shell widgets; provides the + fields needed for all types of shells. Shell + is a direct subclass of + compositeWidgetClass. + + + + + OverrideShell + + A subclass of Shell; used for shell windows that completely + bypass the window manager. + + + + WMShell + + A subclass of Shell; contains fields needed by the + common window manager protocol. + + + + VendorShell + + A subclass of WMShell; contains fields used by + vendor-specific window managers. + + + + + TransientShell + + A subclass of VendorShell; used for shell windows that + desire the WM_TRANSIENT_FOR + property. + + + + TopLevelShell + + A subclass of VendorShell; used for normal top-level windows. + + + + + ApplicationShell + + A subclass of TopLevelShell; may be used for an application's additional + root windows. + + + + SessionShell + + A subclass of ApplicationShell; used for an application's + main root window. + + + + + +Note that the classes +Shell, +WMShell, +and +VendorShell +are internal and should not be instantiated or subclassed. +Only +OverrrideShell, +TransientShell, +TopLevelShell, +ApplicationShell, +and +SessionShell +are intended for public use. + + + +ShellClassPart Definitions + +Only the Shell +class has additional class fields, which are all contained in the +ShellClassExtensionRec. +None of the other Shell classes have any additional class fields: + + + +typedef struct { + XtPointer extension; +} ShellClassPart, OverrideShellClassPart, +WMShellClassPart, VendorShellClassPart, TransientShellClassPart, +TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart; + + +The full Shell class record definitions are: + + +typedef struct _ShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; +} ShellClassRec; + + + +typedef struct { + XtPointer next_extension; See + XrmQuark record_type; See + long version; See + Cardinal record_size; See + XtGeometryHandler root_geometry_manager; See below +} ShellClassExtensionRec, *ShellClassExtension; + + + +typedef struct _OverrideShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + OverrideShellClassPart override_shell_class; +} OverrideShellClassRec; + + + +typedef struct _WMShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; +} WMShellClassRec; + + + +typedef struct _VendorShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; +} VendorShellClassRec; + + + +typedef struct _TransientShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; + TransientShellClassPart transient_shell_class; +} TransientShellClassRec; + + + +typedef struct _TopLevelShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; + TopLevelShellClassPart top_level_shell_class; +} TopLevelShellClassRec; + + + +typedef struct _ApplicationShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; + TopLevelShellClassPart top_level_shell_class; + ApplicationShellClassPart application_shell_class; +} ApplicationShellClassRec; + + + +typedef struct _SessionShellClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ShellClassPart shell_class; + WMShellClassPart wm_shell_class; + VendorShellClassPart vendor_shell_class; + TopLevelShellClassPart top_level_shell_class; + ApplicationShellClassPart application_shell_class; + SessionShellClassPart session_shell_class; +} SessionShellClassRec; + + + +The single occurrences of the class records and pointers for creating +instances of shells are: + + + +extern ShellClassRec shellClassRec; +extern OverrideShellClassRec overrideShellClassRec; +extern WMShellClassRec wmShellClassRec; +extern VendorShellClassRec vendorShellClassRec; +extern TransientShellClassRec transientShellClassRec; +extern TopLevelShellClassRec topLevelShellClassRec; +extern ApplicationShellClassRec applicationShellClassRec; +extern SessionShellClassRec sessionShellClassRec; +extern WidgetClass shellWidgetClass; +extern WidgetClass overrideShellWidgetClass; +extern WidgetClass wmShellWidgetClass; +extern WidgetClass vendorShellWidgetClass; +extern WidgetClass transientShellWidgetClass; +extern WidgetClass topLevelShellWidgetClass; +extern WidgetClass applicationShellWidgetClass; +extern WidgetClass sessionShellWidgetClass; + + + +The following opaque types and opaque variables are defined +for generic operations on widgets whose class is a subclass of +Shell. + + + + + + + + + + Types + Variables + + + + + ShellWidget + shellWidgetClass + + + OverrideShellWidget + overrideShellWidgetClass + + + WMShellWidget + wmShellWidgetClass + + + VendorShellWidget + vendorShellWidgetClass + + + TransientShellWidget + transientShellWidgetClass + + + TopLevelShellWidget + topLevelShellWidgetClass + + + ApplicationShellWidget + applicationShellWidgetClass + + + SessionShellWidget + sessionShellWidgetClass + + + ShellWidgetClass + + + + OverrideShellWidgetClass + + + + WMShellWidgetClass + + + + VendorShellWidgetClass + + + + TransientShellWidgetClass + + + + TopLevelShellWidgetClass + + + + ApplicationShellWidgetClass + + + + SessionShellWidgetClass + + + + + + + +The declarations for all Intrinsics-defined shells except +VendorShell appear in +Shell.h +and +ShellP.h. +VendorShell has separate public and private .h files which are included by +Shell.h +and +ShellP.h. + + + +Shell.h +uses incomplete structure definitions to ensure that the +compiler catches attempts to access private data in any of the Shell +instance or class data structures. + + + +The symbolic constant for the +ShellClassExtension +version identifier is +XtShellExtensionVersion +(see ). + + + +The root_geometry_manager procedure acts as +the parent geometry manager for geometry requests made by shell +widgets. When a shell widget calls either + +or +, +the root_geometry_manager procedure is invoked to +negotiate the new geometry with the window manager. If the window +manager permits the new geometry, the root_geometry_manager +procedure should +return +XtGeometryYes; +if the window manager denies the geometry +request or does not change the window geometry within some timeout +interval (equal to wm_timeout in the case of WMShells), the +root_geometry_manager procedure should return +XtGeometryNo. +If the window manager makes some alternative geometry change, the +root_geometry_manager procedure may return either +XtGeometryNo +and handle the new geometry as a resize or +XtGeometryAlmost +in anticipation that the shell will accept the compromise. If the +compromise is not accepted, the new size must then be handled as a +resize. Subclasses of +Shell +that wish to provide their own +root_geometry_manager procedures are strongly encouraged to use enveloping to +invoke their superclass's root_geometry_manager procedure under most +situations, as the window manager interaction may be very complex. + + + +If no +ShellClassPart +extension record is declared with record_type +equal to +NULLQUARK, +then +XtInheritRootGeometryManager +is assumed. + + + + +ShellPart Definition + +The various shell widgets have the following additional instance +fields defined in +their widget records: + + + +typedef struct { + String geometry; + XtCreatePopupChildProc create_popup_child_proc; + XtGrabKind grab_kind; + Boolean spring_loaded; + Boolean popped_up; + Boolean allow_shell_resize; + Boolean client_specified; + Boolean save_under; + Boolean override_redirect; + XtCallbackList popup_callback; + XtCallbackList popdown_callback; + Visual * visual; +} ShellPart; + + + +typedef struct { + int empty; +} OverrideShellPart; + + + +typedef struct { + String title; + int wm_timeout; + Boolean wait_for_wm; + Boolean transient; + Boolean urgency; + Widget client_leader; + String window_role; + struct _OldXSizeHints { + long flags; + int x, y; + int width, height; + int min_width, min_height; + int max_width, max_height; + int width_inc, height_inc; + struct { + int x; + int y; + } min_aspect, max_aspect; + } size_hints; + XWMHints wm_hints; + int base_width, base_height, win_gravity; + Atom title_encoding; +} WMShellPart; + + + +typedef struct { + int vendor_specific; +} VendorShellPart; + + + +typedef struct { + Widget transient_for; +} TransientShellPart; +typedef struct { + String icon_name; + Boolean iconic; + Atom icon_name_encoding; +} TopLevelShellPart; + + + +typedef struct { + char * class; + XrmClass xrm_class; + int argc; + char ** argv; +} ApplicationShellPart; + + + +typedef struct { + SmcConn connection; + String session_id; + String * restart_command; + String * clone_command; + String * discard_command; + String * resign_command; + String * shutdown_command; + String * environment; + String current_dir; + String program_path; + unsigned char restart_style; + Boolean join_session; + XtCallbackList save_callbacks; + XtCallbackList interact_callbacks; + XtCallbackList cancel_callbacks; + XtCallbackList save_complete_callbacks; + XtCallbackList die_callbacks; + XtCallbackList error_callbacks; +} SessionShellPart; + + + +The full shell widget instance record definitions are: + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; +} ShellRec, *ShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + OverrideShellPart override; +} OverrideShellRec, *OverrideShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; +} WMShellRec, *WMShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; +} VendorShellRec, *VendorShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TransientShellPart transient; +} TransientShellRec, *TransientShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; +} TopLevelShellRec, *TopLevelShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; + ApplicationShellPart application; +} ApplicationShellRec, *ApplicationShellWidget; + + + +typedef struct { + CorePart core; + CompositePart composite; + ShellPart shell; + WMShellPart wm; + VendorShellPart vendor; + TopLevelShellPart topLevel; + ApplicationShellPart application; + SessionShellPart session; +} SessionShellRec, *SessionShellWidget; + + + + + +Shell Resources + +The resource names, classes, and representation types specified in +the +shellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNallowShellResize + XtCAllowShellResize + XtRBoolean + + + XtNcreatePopupChildProc + XtCCreatePopupChildProc + XtRFunction + + + XtNgeometry + XtCGeometry + XtRString + + + XtNoverrideRedirect + XtCOverrideRedirect + XtRBoolean + + + XtNpopdownCallback + XtCCallback + XtRCallback + + + XtNpopupCallback + XtCCallback + XtRCallback + + + XtNsaveUnder + XtCSaveUnder + XtRBoolean + + + XtNvisual + XtCVisual + XtRVisual + + + + + + +OverrideShell +declares no additional resources beyond those defined by +Shell. + + + +The resource names, classes, and representation types specified in +the +wmShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNbaseHeight + XtCBaseHeight + XtRInt + + + XtNbaseWidth + XtCBaseWidth + XtRInt + + + XtNclientLeader + XtCClientLeader + XtRWidget + + + XtNheightInc + XtCHeightInc + XtRInt + + + XtNiconMask + XtCIconMask + XtRBitmap + + + XtNiconPixmap + XtCIconPixmap + XtRBitmap + + + XtNiconWindow + XtCIconWindow + XtRWindow + + + XtNiconX + XtCIconX + XtRInt + + + XtNiconY + XtCIconY + XtRInt + + + XtNinitialState + XtCInitialState + XtRInitialState + + + XtNinput + XtCInput + XtRBool + + + XtNmaxAspectX + XtCMaxAspectX + XtRInt + + + XtNmaxAspectY + XtCMaxAspectY + XtRInt + + + XtNmaxHeight + XtCMaxHeight + XtRInt + + + XtNmaxWidth + XtCMaxWidth + XtRInt + + + XtNminAspectX + XtCMinAspectX + XtRInt + + + XtNminAspectY + XtCMinAspectY + XtRInt + + + XtNminHeight + XtCMinHeight + XtRInt + + + XtNminWidth + XtCMinWidth + XtRInt + + + XtNtitle + XtCTitle + XtRString + + + XtNtitleEncoding + XtCTitleEncoding + XtRAtom + + + XtNtransient + XtCTransient + XtRBoolean + + + XtNwaitforwm, XtNwaitForWm + XtCWaitforwm, XtCWaitForWm + XtRBoolean + + + XtNwidthInc + XtCWidthInc + XtRInt + + + XtNwindowRole + XtCWindowRole + XtRString + + + XtNwinGravity + XtCWinGravity + XtRGravity + + + XtNwindowGroup + XtCWindowGroup + XtRWindow + + + XtNwmTimeout + XtCWmTimeout + XtRInt + + + XtNurgency + XtCUrgency + XtRBoolean + + + _ + + + + + + +The class resource list for +VendorShell +is implementation-defined. + + + +The resource names, classes, and representation types that are specified in the +transient\%ShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNtransientFor + XtCTransientFor + XtRWidget + + + + + + +The resource names, classes, and representation types that are specified in the +topLevelShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNiconName + XtCIconName + XtRString + + + XtNiconNameEncoding + XtCIconNameEncoding + XtRAtom + + + XtNiconic + XtCIconic + XtRBoolean + + + + + + +The resource names, classes, and representation types that are specified in the +application\%ShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNargc + XtCArgc + XtRInt + + + XtNargv + XtCArgv + XtRStringArray + + + + + + +The resource names, classes, and representation types that are specified +in the +sessionShellClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNcancelCallback + XtCCallback + XtRCallback + + + XtNcloneCommand + XtCCloneCommand + XtRCommandArgArray + + + XtNconnection + XtCConnection + XtRSmcConn + + + XtNcurrentDirectory + XtCCurrentDirectory + XtRDirectoryString + + + XtNdieCallback + XtCCallback + XtRCallback + + + XtNdiscardCommand + XtCDiscardCommand + XtRCommandArgArray + + + XtNenvironment + XtCEnvironment + XtREnvironmentArray + + + XtNerrorCallback + XtCCallback + XtRCallback + + + XtNinteractCallback + XtCCallback + XtRCallback + + + XtNjoinSession + XtCJoinSession + XtRBoolean + + + XtNprogramPath + XtCProgramPath + XtRString + + + XtNresignCommand + XtCResignCommand + XtRCommandArgArray + + + XtNrestartCommand + XtCRestartCommand + XtRCommandArgArray + + + XtNrestartStyle + XtCRestartStyle + XtRRestartStyle + + + XtNsaveCallback + XtCCallback + XtRCallback + + + XtNsaveCompleteCallback + XtCCallback + XtRCallback + + + XtNsessionID + XtCSessionID + XtRString + + + XtNshutdownCommand + XtCShutdownCommand + XtRCommandArgArray + + + + + + + + +ShellPart Default Values + +The default values for fields common to all classes of public shells +(filled in by the +Shell +resource lists and the +Shell +initialize procedures) are: + + + + + + + + + + Field + Default Value + + + + + geometry + NULL + + + create_popup_child_proc + NULL + + + grab_kind + (none) + + + spring_loaded + (none) + + + popped_up + False + + + allow_shell_resize + False + + + client_specified + (internal) + + + save_under + True + for OverrideShell and TransientShell, + False + otherwise + + + override_redirect + True + for OverrideShell, + False + otherwise + + + popup_callback + NULL + + + popdown_callback + NULL + + + visual + CopyFromParent + + + + + + +The geometry field specifies the size and position +and is usually given only on a command line or in a defaults file. +If the geometry field is non-NULL when +a widget of class WMShell +is realized, the geometry specification is parsed using +XWMGeometry +with a default geometry +string constructed from the values of x, y, width, +height, width_inc, +and height_inc and the size and position flags in the window manager +size hints are set. If the geometry specifies an x or y position, +then +USPosition +is set. If the geometry specifies a width or height, then +USSize +is set. Any fields in the geometry specification +override the corresponding values in the +Core x, y, width, and height fields. +If geometry is NULL or contains only a partial specification, then the +Core x, y, width, and height fields are used and +PPosition +and +PSize +are set as appropriate. +The geometry string is not copied by any of the Intrinsics +Shell classes; a client specifying the string in an arglist +or varargs list must ensure +that the value remains valid until the shell widget is realized. +For further information on the geometry string, see + +in Xlib — C Language X Interface. + + + +The create_popup_child_proc procedure is called by the + +procedure and may remain NULL. +The grab_kind, spring_loaded, +and popped_up fields maintain widget +state information as described under +, +, +, +and +. +The allow_shell_resize field controls whether the widget contained +by the shell is allowed to try to resize itself. +If allow_shell_resize is +False, +any geometry requests made by the child will always return +XtGeometryNo +without interacting with the window manager. +Setting save_under +True +instructs the server to attempt +to save the contents of windows obscured by the shell when it is mapped +and to restore those contents automatically when the shell is unmapped. +It is useful for pop-up menus. +Setting override_redirect +True +determines +whether the window manager can intercede when the shell window +is mapped. +For further information on override_redirect, +see in +Xlib — C Language X Interface +and + and + in the +Inter-Client Communication Conventions Manual. +The pop-up and pop-down callbacks are called during + +and +. +The default value of the visual resource is the symbolic value +CopyFromParent. +The Intrinsics do not need to query the parent's visual type when the +default value is used; if a client using + +to examine the visual type receives the value +CopyFromParent, +it must then use +XGetWindowAttributes +if it needs the actual visual type. + + + +The default values for Shell fields in +WMShell +and its subclasses are: + + + + + + + + + + Field + Default Value + + + + + title + Icon name, if specified, otherwise the application's name + + + wm_timeout + Five seconds, in units of milliseconds + + + wait_for_wm + True + + + transient + True + for TransientShell, + False + otherwise + + + urgency + False + + + client_leader + NULL + + + window_role + NULL + + + min_width + XtUnspecifiedShellInt + + + min_height + XtUnspecifiedShellInt + + + max_width + XtUnspecifiedShellInt + + + max_height + XtUnspecifiedShellInt + + + width_inc + XtUnspecifiedShellInt + + + height_inc + XtUnspecifiedShellInt + + + min_aspect_x + XtUnspecifiedShellInt + + + min_aspect_y + XtUnspecifiedShellInt + + + max_aspect_x + XtUnspecifiedShellInt + + + max_aspect_y + XtUnspecifiedShellInt + + + input + False + + + initial_state + Normal + + + icon_pixmap + None + + + icon_window + None + + + icon_x + XtUnspecifiedShellInt + + + icon_y + XtUnspecifiedShellInt + + + icon_mask + None + + + window_group + XtUnspecifiedWindow + + + base_width + XtUnspecifiedShellInt + + + base_height + XtUnspecifiedShellInt + + + win_gravity + XtUnspecifiedShellInt + + + title_encoding + See text + + + + + + +The title and +title_encoding fields are stored in the +WM_NAME +property on the shell's window by the WMShell realize procedure. +If the title_encoding field is +None, +the title string is assumed to be in the encoding of the current +locale and the encoding of the +WM_NAME +property is set to +XStdICCTextStyle. +If a language procedure has not been set +the default value of title_encoding is +XA_STRING, otherwise the default value is +None. +The wm_timeout field specifies, in milliseconds, +the amount of time a shell is to wait for +confirmation of a geometry request to the window manager. +If none comes back within that time, +the shell assumes the window manager is not functioning properly +and sets wait_for_wm to +False +(later events may reset this value). +When wait_for_wm is +False, +the shell does not wait for a response, but relies on asynchronous +notification. +If transient is +True, +the +WM_TRANSIENT_FOR +property +will be stored on the shell window with a value as specified below. +The interpretation of this property is specific to the window manager +under which the application is run; see the +Inter-Client Communication Conventions Manual +for more details. + + + +The realize and set_values procedures of WMShell store the +WM_CLIENT_LEADER +property on the shell window. +When client_leader is not NULL and the client leader widget is +realized, the property will be created with the value of the window of the +client leader widget. +When client_leader is NULL and the shell widget has a NULL parent, +the widget's window is used as the value of the +property. +When client_leader is NULL and the shell widget has a non-NULL parent, +a search is made for the closest shell ancestor +with a non-NULL client_leader, +and if none is found the shell ancestor with a NULL parent is the result. +If the resulting widget is realized, the property is created +with the value of the widget's window. + + + +When the value of window_role is not NULL, the +realize and set_values procedures store the +WM_WINDOW_ROLE +property on the shell's window with the value of the resource. + + + +All other resources specify fields in the window manager hints +and the window manager size hints. +The realize and set_values procedures of +WMShell +set the corresponding flag bits in the +hints if any of the fields contain nondefault values. In addition, if +a flag bit is set that refers to a field with the value +XtUnspecifiedShellInt, +the value of the field is modified as follows: + + + + + + + + + + Field + Replacement + + + + + base_width, base_height + 0 + + + width_inc, height_inc + 1 + + + max_width, max_height + 32767 + + + min_width, min_height + 1 + + + min_aspect_x, min_aspect_y + -1 + + + max_aspect_x, max_aspect_y + -1 + + + icon_x, icon_y + -1 + + + win_gravity + Value returned by + XWMGeometry + if called, + else NorthWestGravity + + + + + + +If the shell widget has a non-NULL parent, then the +realize and set_values procedures replace the value +XtUnspecifiedWindow +in the window_group field with the window id of the root widget +of the widget tree if the +root widget is realized. The symbolic constant +XtUnspecifiedWindowGroup +may be used to indicate that the window_group hint flag bit is not +to be set. If transient is +True, +the shell's class is not a subclass of +TransientShell, +and window_group is not +XtUnspecifiedWindowGroup, +the WMShell realize and set_values procedures then store the +WM_TRANSIENT_FOR +property with the value of window_group. + + + +Transient +shells have the following additional resource: + + + + + + + + + + Field + Replacement + + + + + transient_for + NULL + + + + + + +The realize and set_values procedures of +TransientShell +store the +WM_TRANSIENT_FOR +property on the shell window if transient is +True. +If transient_for is non-NULL and the widget specified by +transient_for is realized, then its window is used as the value of the +WM_TRANSIENT_FOR +property; otherwise, the value of window_group is used. + + + +TopLevel +shells have the the following additional resources: + + + + + + + + + + + Field + Default Value + + + + + icon_name + Shell widget's name + + + iconic + False + + + icon_name_encoding + See text + + + + + + +The icon_name +and icon_name_encoding fields are stored in the +WM_ICON_NAME +property on the shell's window by the TopLevelShell realize +procedure. +If the icon_name_encoding field is +None, +the icon_name string is assumed to be in the encoding of the +current locale and the encoding of the +WM_ICON_NAME +property is set to +XStdICCTextStyle. +If a language procedure has not been set, +the default value of icon_name_encoding is +XA_STRING, otherwise the default value is +None. +The iconic field may be used by a client to request +that the window manager iconify or deiconify the shell; the +TopLevelShell +set_values procedure will send the appropriate +WM_CHANGE_STATE +message (as specified by the Inter-Client Communication Conventions Manual) +if this resource is changed from +False +to +True +and will call + +specifying grab_kind as +XtGrabNone +if iconic is changed from +True +to +False. +The XtNiconic resource is also an alternative way to set +the XtNinitialState resource +to indicate that a shell should be initially displayed as an icon; the +TopLevelShell +initialize procedure will set initial_state to +IconicState +if iconic is +True. + + + +Application +shells have the following additional resources: + + + + + + + + + + Field + Default Value + + + + + argc + 0 + + + argv + NULL + + + + + + +The argc and argv fields are used to initialize +the standard property +WM_COMMAND. See the +Inter-Client Communication Conventions Manual +for more information. + + + +The default values for the SessionShell instance fields, +which are filled in from the resource lists and by the +initialize procedure, are + + + + + + + + + + Field + Default Value + + + + + cancel_callbacks + NULL + + + clone_command + See text + + + connection + NULL + + + current_dir + NULL + + + die_callbacks + NULL + + + discard_command + NULL + + + environment + NULL + + + error_callbacks + NULL + + + interact_callbacks + NULL + + + join_session + True + + + program_path + NULL + + + resign_command + NULL + + + restart_command + See text + + + restart_style + SmRestartIfRunning + + + save_callbacks + NULL + + + save_complete_callbacks + NULL + + + session_id + NULL + + + shutdown_command + NULL + + + + + + +The connection field contains the session connection object or NULL +if a session connection is not being managed by this widget. + + + +The session_id is an identification assigned to the session +participant by the session manager. +The session_id will be passed to the session +manager as the client identifier of the previous session. +When a connection is established with the session manager, +the client id assigned by the session manager is stored +in the session_id field. +When not NULL, the session_id of the Session shell widget that +is at the root of the widget tree of the client leader widget will be +used to create the +SM_CLIENT_ID +property on the client leader's window. + + + +If join_session is +False, +the widget will not attempt to establish a +connection to the session manager at shell creation time. +See and + +for more information on the functionality of this resource. + + + +The restart_command, clone_command, discard_command, +resign_command, shutdown_command, environment, +current_dir, program_path, and +restart_style fields contain standard session properties. + + + +When a session connection is established or newly managed by the shell, +the shell initialize and set_values methods check the values of the +restart_command, +clone_command, +and program_path +resources. At that time, if restart_command is NULL, the value +of the argv resource will be copied to restart_command. +Whether or not restart_command was NULL, +if "-xtsessionID" "<session id>" does not +already appear in the restart_command, it will be added by the +initialize and set_values methods at the beginning of the command arguments; +if the "-xtsessionID" argument already appears with an incorrect +session id in the following argument, that argument +will be replaced with the current session id. + + + +After this, the shell initialize and set_values procedures check the +clone_command. If clone_command is NULL, +restart_command will be copied to clone_command, +except the "-xtsessionID" and following argument will not be copied. + + + +Finally, the shell initialize and set_values procedures check the +program_path. If program_path is NULL, the +first element of restart_command is copied to program_path. + + + +The possible values of restart_style are +SmRestartIfRunning, +SmRestartAnyway, +SmRestartImmediately, +and +SmRestartNever. +A resource converter is registered for this resource; +for the strings that it recognizes, +see . + + + +The resource type EnvironmentArray is a NULL-terminated array of +pointers to strings; +each string has the format "name=value". +The `=' character may not appear in the name, +and the string is terminated by a null character. + + + + + +Session Participation + +Applications can participate in a user's session, exchanging messages +with the session manager as described in the +X Session Management Protocol and the +X Session Management Library. + + + +When a widget of +sessionShellWidgetClass +or a subclass is created, the widget provides support for the application +as a session participant and continues to provide support until the +widget is destroyed. + + + +Joining a Session + +When a Session shell is created, +if connection is NULL, +and if join_session is +True, +and if argv or restart_command is not NULL, +and if in POSIX environments the +SESSION_MANAGER +environment variable is defined, +the shell will attempt to establish a new connection with the session manager. + + + +To transfer management of an existing session connection from an +application to the shell at widget creation time, pass the existing +session connection ID as the connection resource value +when creating the Session shell, +and if the other creation-time conditions on session participation are met, +the widget will maintain the connection with the session manager. +The application must ensure that only one +Session shell manages the connection. + + + +In the Session shell set_values procedure, +if join_session changes from +False +to +True +and connection is NULL and when in POSIX environments the +SESSION_MANAGER +environment variable is defined, +the shell will attempt to open a connection to the session manager. +If connection changes from NULL to non-NULL, the +Session shell +will take over management of that session connection and will set +join_session to +True. +If join_session changes from +False +to +True +and connection is not NULL, the +Session shell will take over management of the session connection. + + + +When a successful connection has been established, connection +contains the session connection ID for the session participant. +When the shell begins to manage the connection, it will call + +to register the handler which watches for protocol messages +from the session manager. +When the attempt to connect fails, a warning message is issued +and connection is set to NULL. + + + +While the connection is being managed, if a +SaveYourself, +SaveYourselfPhase2, +Interact, +ShutdownCancelled, +SaveComplete, +or +Die +message is received from the session manager, the Session shell will +call out to application callback procedures registered +on the respective callback list of the Session shell and will +send +SaveYourselfPhase2Request, +InteractRequest, +InteractDone, +SaveYourselfDone, +and +ConnectionClosed +messages as appropriate. +Initially, all of the client's session properties are undefined. +When any of the session property resource values are defined or change, +the Session shell initialize and set_values procedures +will update the client's session property value by a +SetProperties +or a +DeleteProperties +message, as appropriate. +The session ProcessID and UserID properties are always set by the shell +when it is possible to determine the value of these properties. + + + + +Saving Application State + +The session manager instigates an application checkpoint by sending a +SaveYourself +request. +Applications are responsible for saving their state in response to the +request. + + + +When the +SaveYourself +request arrives, the procedures registered on the +Session shell's save callback list are called. +If the application does not register any save callback procedures on +the save callback list, the shell will report to the session manager +that the application failed to save its state. +Each procedure on the save callback list receives a token +in the call_data parameter. + + + +The checkpoint token in the call_data parameter is of type +XtCheckpointToken. + + + +typedef struct { + int save_type; + int interact_style; + Boolean shutdown; + Boolean fast; + Boolean cancel_shutdown + int phase; + int interact_dialog_type; /* return */ + Boolean request_cancel; /* return */ + Boolean request_next_phase; /* return */ + Boolean save_success; /* return */ +} XtCheckpointTokenRec, *XtCheckpointToken; + + + +The save_type, interact_style, shutdown, and fast +fields of the token contain the parameters of the +SaveYourself +message. +The possible values of save_type are +SmSaveLocal, +SmSaveGlobal, +and +SmSaveBoth; +these indicate the type of information to be saved. +The possible values of interact_style are +SmInteractStyleNone, +SmInteractStyleErrors, +and +SmInteractStyleAny; +these indicate whether user interaction would be permitted +and, if so, what kind of interaction. +If shutdown is +True, +the checkpoint is being performed in preparation for the end of the session. +If fast is +True, +the client should perform the checkpoint as quickly as possible. +If cancel_shutdown is +True, +a +ShutdownCancelled +message has been received for the current save operation. +(See .) +The phase is used by manager clients, such as a window manager, +to distinguish between the first and second phase of a save operation. +The phase will be either 1 or 2. +The remaining fields in the checkpoint token structure are provided for +the application to communicate with the shell. + + + +Upon entry to the first application save callback procedure, the return +fields in the token have the following initial values: +interact_dialog_type is +SmDialogNormal; +request_cancel is +False; +request_next_phase is +False; +and save_success is +True. +When a token is returned with any of the four return fields containing +a noninitial value, and when the field is applicable, subsequent tokens +passed to the application during the current save operation +will always contain the noninitial value. + + + +The purpose of the token's save_success field is to +indicate the outcome of the entire operation to the +session manager and ultimately, to the user. +Returning +False +indicates some portion of the application state +could not be successfully saved. If any token is returned +to the shell with save_success +False, +tokens subsequently received +by the application for the current save operation will show +save_success as +False. +When the shell sends the final status of the checkpoint to the +session manager, it will indicate failure to save application state +if any token was returned with save_success +False. + + + +Session participants that manage and save the state of other clients +should structure their save or interact callbacks to +set request_next_phase to +True +when phase is 1, which will cause the shell to send the +SaveYourselfPhase2Request +when the first phase is complete. When the +SaveYourselfPhase2 +message is received, the shell will invoke the save callbacks a +second time with phase equal to 2. +Manager clients should save the state of other clients +when the callbacks are invoked the second time and phase equal to 2. + + + +The application may request additional tokens while a checkpoint is under way, +and these additional tokens must be returned by an explicit call. + + + +To request an additional token for a save callback response that has a +deferred outcome, use +. + + + + +XtCheckpointToken XtSessionGetToken + Widget widget + + + + + + + widget + + + +Specifies the Session shell widget which manages session participation. + + + + + + + +The + +function will return NULL if no checkpoint operation is currently under way. + + + +To indicate the completion of checkpoint processing including user +interaction, the application must signal the Session shell +by returning all tokens. +(See and +). +To return a token, use +. + + + + +void XtSessionReturnToken + XtCheckpointToken token + + + + + + + token + + + +Specifies a token that was received as the call_data by a procedure +on the interact callback list or a token that was received by a call to +. + + + + + + + +Tokens passed as call_data to save callbacks are implicitly +returned when the save callback procedure returns. +A save callback procedure should not call + +on the token passed in its call_data. + + + +Requesting Interaction + +When the token interact_style allows user interaction, +the application may +interact with the user during the checkpoint, but must wait for permission +to interact. +Applications request permission to interact with the user during the +checkpointing operation by registering a procedure on the Session +shell's interact callback list. When all save callback procedures have +returned, and each time a token that was granted by a call to + +is returned, the Session shell examines the interact callback list. +If interaction is permitted and the interact callback list is not empty, +the shell will send an +InteractRequest +to the session manager when an interact request is not already outstanding +for the application. + + + +The type of interaction dialog that will be requested is specified by +the interact_dialog_type field in the checkpoint token. +The possible values for interact_dialog_type are +SmDialogError +and +SmDialogNormal. +If a token is returned with interact_dialog_type containing +SmDialogError, +the interact request and any subsequent interact requests will be for +an error dialog; otherwise, the request will be for a normal dialog with +the user. + + + +When a token is returned with save_success +False +or interact_dialog_type +SmDialogError, +tokens subsequently passed to callbacks during the same active +SaveYourself +response will reflect these changed values, indicating that +an error condition has occurred during the checkpoint. + + + +The request_cancel field is a return value for interact callbacks only. +Upon return from a procedure on the save callback list, the value +of the token's request_cancel field is not examined by the shell. +This is also true of tokens received through a call to +. + + + + +Interacting with the User during a Checkpoint + +When the session manager grants the application's request for user interaction, +the Session shell receives an +Interact +message. +The procedures registered on the interact callback list are executed, +but not as if executing a typical callback list. +These procedures are individually executed in +sequence, with a checkpoint token functioning as the sequencing mechanism. +Each step in the sequence begins by removing a procedure +from the interact callback list +and executing it with a token passed in the call_data. +The interact callback will typically pop up a dialog box and return. +When the user interaction and associated application checkpointing has +completed, the application must return the token by calling +. +Returning the token completes the current step and triggers the next step +in the sequence. + + + +During interaction the client may request cancellation of a shutdown. +When a token passed as call_data to an interact procedure is returned, +if shutdown is +True +and cancel_shutdown is +False, +request_cancel indicates whether the +application requests that the pending shutdown be cancelled. +If request_cancel is +True, +the field will also be +True +in any tokens subsequently granted during the checkpoint operation. +When a token is returned requesting cancellation of +the session shutdown, pending interact procedures will still be +called by the Session shell. +When all interact procedures have been removed from the interact callback +list, executed, and the final interact token returned to the shell, an +InteractDone +message is sent to the session manager, indicating whether +a pending session shutdown is requested to be cancelled. + + + + +Responding to a Shutdown Cancellation + +Callbacks registered on the cancel callback list are invoked when the +Session shell processes a +ShutdownCancelled +message from the session manager. This may occur during the +processing of save callbacks, while waiting for interact permission, +during user interaction, or after the save operation is complete and +the application is expecting a +SaveComplete +or a +Die +message. +The call_data for these callbacks is NULL. + + + +When the shell notices that a pending shutdown has been cancelled, +the token cancel_shutdown field will be +True +in tokens subsequently given to the application. + + + +Receiving notice of a shutdown cancellation does not cancel the +pending execution of save callbacks or interact callbacks. +After the cancel callbacks execute, if interact_style is not +SmInteractStyleNone +and the interact list is not empty, +the procedures on the interact callback list will be executed +and passed a token with interact_style +SmInteractStyleNone. +The application should not interact with the user, and the Session shell +will not send an +InteractDone +message. + + + + +Completing a Save + +When there is no user interaction, the shell regards the application +as having finished saving state when all callback procedures +on the save callback list have returned, and any additional tokens +passed out by + +have been returned by corresponding calls to +. +If the save operation involved user interaction, +the above completion conditions apply, and in addition, all requests for +interaction have been granted or cancelled, +and all tokens passed to interact callbacks have been returned +through calls to +. +If the save operation involved a manager client that requested the +second phase, the above conditions apply to both the first and second +phase of the save operation. + + + +When the application has finished saving state, +the Session shell will report the result to the session manager by +sending the +SaveYourselfDone +message. +If the session is continuing, the shell will receive the +SaveComplete +message when all applications have completed saving state. +This message indicates that applications may again allow changes +to their state. The shell will execute the save_complete callbacks. +The call_data for these callbacks is NULL. + + + + + +Responding to a Shutdown + +Callbacks registered on the die callback list are invoked when the +session manager sends a +Die +message. +The callbacks on this list should do whatever is appropriate to quit +the application. +Before executing procedures on the die callback list, +the Session shell will close the connection to the session manager +and will remove the handler that watches for protocol messages. +The call_data for these callbacks is NULL. + + + + +Resigning from a Session + +When the Session shell widget is destroyed, the destroy method will +close the connection to the session manager by sending a +ConnectionClosed +protocol message and will remove the input callback +that was watching for session protocol messages. + + + +When + +is used to set join_session to +False, +the set_values method of the Session shell will close the +connection to the session manager if one exists by sending a +ConnectionClosed +message, and connection will be set to NULL. + + + +Applications that exit in response to user actions and that do not +wait for phase 2 destroy to complete on +the Session shell should set join_session to +False +before exiting. + + + +When + +is used to set connection to NULL, +the Session shell will stop managing the connection, if one exists. +However, that session connection will not be closed. + + + +Applications that wish to ensure continuation of a session connection +beyond the destruction of the shell should first retrieve the +connection resource value, +then set the connection resource to NULL, +and then they may safely destroy the widget without losing control +of the session connection. + + + +The error callback list will be called if an unrecoverable +communications error occurs while the shell is managing the connection. +The shell will close the connection, set connection to NULL, +remove the input callback, and +call the procedures registered on the error callback list. +The call_data for these callbacks is NULL. + + + + -- cgit v1.2.3