X Toolkit Intrinsics - C Language Interface X Window System X Version 11, Release 6.4 First Revision - April, 1994 [...] Chapter 2 Widget Instantiation [...] 2.3. Loading the Resource Database The XtDisplayInitialize function first determines the language string to be used for the specified display. It then creates a resource database for the default screen of the display by combining the following sources in order, with the entries in the first named source having highest precedence: o Application command line (argc, argv). o Per-host user environment resource file on the local host. o Per-screen resource specifications from the server. o Per-display resource specifications from the server or from the user preference file on the local host. o Application-specific user resource file on the local host. o Application-specific class resource file on the local host. When the resource database for a particular screen on the display is needed (either internally, or when XtScreenData- base is called), it is created in the following manner using the sources listed above in the same order: o A temporary database, the ``server resource data- base'', is created from the string returned by XResour- ceManagerString or, if XResourceManagerString returns NULL, the contents of a resource file in the user's home directory. On POSIX-based systems, the usual name for this user preference resource file is $HOME/.Xdefaults. o If a language procedure has been set, XtDisplayIni- tialize first searches the command line for the option ``-xnlLanguage'', or for a -xrm option that specifies the xnlLanguage/XnlLanguage resource, as specified by Section 2.4. If such a resource is found, the value is assumed to be entirely in XPCS, the X Portable Charac- ter Set. If neither option is specified on the command line, XtDisplayInitialize queries the server resource database (which is assumed to be entirely in XPCS) for the resource name.xnlLanguage, class Class.XnlLanguage where name and Class are the application_name and application_class specified to XtDisplayInitialize. The language procedure is then invoked with the resource value if found, else the empty string. The string returned from the language procedure is saved for all future references in the Intrinsics that require the per-display language string. o The screen resource database is initialized by parsing the command line in the manner specified by Section 2.4. o If a language procedure has not been set, the initial database is then queried for the resource name.xnlLanguage, class Class.XnlLanguage as specified above. If this database query fails, the server resource database is queried; if this query also fails, the language is determined from the environment; on POSIX-based systems, this is done by retrieving the value of the LANG environment variable. If no language string is found, the empty string is used. This language string is saved for all future references in the Intrinsics that require the per-display language string. o After determining the language string, the user's environment resource file is then merged into the ini- tial resource database if the file exists. This file is user-, host-, and process-specific and is expected to contain user preferences that are to override those specifications in the per-display and per-screen resources. On POSIX-based systems, the user's environ- ment resource file name is specified by the value of the XENVIRONMENT environment variable. If this environment variable does not exist, the user's home directory is searched for a file named .Xdefaults-host, where host is the host name of the machine on which the application is running. o The per-screen resource specifications are then merged into the screen resource database, if they exist. These specifications are the string returned by XScreenResourceString for the respective screen and are owned entirely by the user. o Next, the server resource database created earlier is merged into the screen resource database. The server property, and corresponding user preference file, are owned and constructed entirely by the user. o The application-specific user resource file from the local host is then merged into the screen resource database. This file contains user customizations and is stored in a directory owned by the user. Either the user or the application or both can store resource specifications in the file. Each should be prepared to find and respect entries made by the other. The file name is found by calling XrmSetDatabase with the current screen resource database, after preserving the original display-associated database, then calling XtResolvePathname with the parameters (display, NULL, NULL, NULL, path, NULL, 0, NULL), where path is defined in an operating-system-specific way. On POSIX-based systems, path is defined to be the value of the environment variable XUSERFILESEARCHPATH if this is defined. If XUSERFILESEARCHPATH is not defined, an implementation-dependent default value is used. This default value is constrained in the following manner: - If the environment variable XAPPLRESDIR is not defined, the default XUSERFILESEARCHPATH must con- tain at least six entries. These entries must con- tain $HOME as the directory prefix, plus the follow- ing substitutions: 1. %C, %N, %L or %C, %N, %l, %t, %c 2. %C, %N, %l 3. %C, %N 4. %N, %L or %N, %l, %t, %c 5. %N, %l 6. %N The order of these six entries within the path must be as given above. The order and use of substitu- tions within a given entry are implementation- dependent. - If XAPPLRESDIR is defined, the default XUSER- FILESEARCHPATH must contain at least seven entries. These entries must contain the following directory prefixes and substitutions: 1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c 2. $XAPPLRESDIR with %C, %N, %l 3. $XAPPLRESDIR with %C, %N 4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c 5. $XAPPLRESDIR with %N, %l 6. $XAPPLRESDIR with %N 7. $HOME with %N The order of these seven entries within the path must be as given above. The order and use of sub- stitutions within a given entry are implementation- dependent. o Last, the application-specific class resource file from the local host is merged into the screen resource database. This file is owned by the application and is usually installed in a system directory when the appli- cation is installed. It may contain sitewide customi- zations specified by the system manager. The name of the application class resource file is found by calling XtResolvePathname with the parameters (display, ``app- defaults'', NULL, NULL, NULL, NULL, 0, NULL). This file is expected to be provided by the developer of the application and may be required for the application to function properly. A simple application that wants to be assured of having a minimal set of resources in the absence of its class resource file can declare fallback resource specifications with XtAppSetFallbackResources. Note that the customization substitution string is retrieved dynamically by XtResolvePathname so that the resolved file name of the application class resource file can be affected by any of the earlier sources for the screen resource database, even though the contents of the class resource file have lowest precedence. After calling XtResolvePathname, the original display- associated database is restored. To obtain the resource database for a particular screen, use XtScreenDatabase. __ | XrmDatabase XtScreenDatabase(screen) Screen *screen; screen Specifies the screen whose resource database is to be returned. |__ The XtScreenDatabase function returns the fully merged resource database as specified above, associated with the specified screen. If the specified screen does not belong to a Display initialized by XtDisplayInitialize, the results are undefined. To obtain the default resource database associated with a particular display, use XtDatabase. __ | XrmDatabase XtDatabase(display) Display *display; display Specifies the display. |__ The XtDatabase function is equivalent to XrmGetDatabase. It returns the database associated with the specified display, or NULL if a database has not been set. To specify a default set of resource values that will be used to initialize the resource database if no application- specific class resource file is found (the last of the six sources listed above), use XtAppSetFallbackResources. __ | void XtAppSetFallbackResources(app_context, specification_list) XtAppContext app_context; String *specification_list; app_context Specifies the application context in which the fallback specifications will be used. specification_list Specifies a NULL-terminated list of resource specifications to preload the database, or NULL. |__ Each entry in specification_list points to a string in the format of XrmPutLineResource. Following a call to XtAppSet- FallbackResources, when a resource database is being created for a particular screen and the Intrinsics are not able to find or read an application-specific class resource file according to the rules given above and if specification_list is not NULL, the resource specifications in specification_list will be merged into the screen resource database in place of the application-specific class resource file. XtAppSetFallbackResources is not required to copy specification_list; the caller must ensure that the contents of the list and of the strings addressed by the list remain valid until all displays are initialized or until XtAppSet- FallbackResources is called again. The value NULL for specification_list removes any previous fallback resource specification for the application context. The intended use for fallback resources is to provide a minimal number of resources that will make the application usable (or at least terminate with helpful diagnostic messages) when some prob- lem exists in finding and loading the application defaults file. 2.4. Parsing the Command Line The XtOpenDisplay function first parses the command line for the following options: -display Specifies the display name for XOpenDisplay. -name Sets the resource name prefix, which overrides the application name passed to XtOpenDisplay. -xnllanguage Specifies the initial language string for estab- lishing locale and for finding application class resource files. XtDisplayInitialize has a table of standard command line options that are passed to XrmParseCommand for adding resources to the resource database, and it takes as a param- eter additional application-specific resource abbreviations. The format of this table is described in Section 15.9 in Xlib - C Language X Interface. __ | typedef enum { XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ XrmoptionIsArg, /* Value is the option string itself */ XrmoptionStickyArg, /* Value is characters immediately following option */ XrmoptionSepArg, /* Value is next argument in argv */ XrmoptionResArg, /* Use the next argument as input to XrmPutLineResource*/ XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ XrmoptionSkipNArgs, /* Ignore this option and the next */ /* OptionDescRec.value arguments in argv */ XrmoptionSkipLine /* Ignore this option and the rest of argv */ } XrmOptionKind; typedef struct { char *option; /* Option name in argv */ char *specifier; /* Resource name (without application name) */ XrmOptionKind argKind;/* Location of the resource value */ XPointer value; /* Value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; |__ The standard table contains the following entries: ______________________________________________________________________ Option String Resource Name Argument Kind Resource Value ______________________________________________________________________ -background *background SepArg next argument -bd *borderColor SepArg next argument -bg *background SepArg next argument -borderwidth .borderWidth SepArg next argument -bordercolor *borderColor SepArg next argument -bw .borderWidth SepArg next argument -display .display SepArg next argument -fg *foreground SepArg next argument -fn *font SepArg next argument -font *font SepArg next argument -foreground *foreground SepArg next argument -geometry .geometry SepArg next argument -iconic .iconic NoArg ``true'' -name .name SepArg next argument -reverse .reverseVideo NoArg ``on'' -rv .reverseVideo NoArg ``on'' +rv .reverseVideo NoArg ``off'' -selectionTimeout .selectionTimeout SepArg next argument -synchronous .synchronous NoArg ``on'' +synchronous .synchronous NoArg ``off'' -title .title SepArg next argument -xnllanguage .xnlLanguage SepArg next argument -xrm next argument ResArg next argument -xtsessionID .sessionID SepArg next argument ______________________________________________________________________ Note that any unique abbreviation for an option name in the standard table or in the application table is accepted. If reverseVideo is True, the values of XtDefaultForeground and XtDefaultBackground are exchanged for all screens on the Display. The value of the synchronous resource specifies whether or not Xlib is put into synchronous mode. If a value is found in the resource database during display initialization, XtDisplayInitialize makes a call to XSynchronize for all display connections currently open in the application con- text. Therefore, when multiple displays are initialized in the same application context, the most recent value speci- fied for the synchronous resource is used for all displays in the application context. The value of the selectionTimeout resource applies to all displays opened in the same application context. When mul- tiple displays are initialized in the same application con- text, the most recent value specified is used for all displays in the application context. The -xrm option provides a method of setting any resource in an application. The next argument should be a quoted string identical in format to a line in the user resource file. For example, to give a red background to all command buttons in an application named xmh, you can start it up as xmh -xrm 'xmh*Command.background: red' When it parses the command line, XtDisplayInitialize merges the application option table with the standard option table before calling the Xlib XrmParseCommand function. An entry in the application table with the same name as an entry in the standard table overrides the standard table entry. If an option name is a prefix of another option name, both names are kept in the merged table. The Intrinsics reserve all option names beginning with the characters ``-xt'' for future standard uses. [...] Appendix A Resource File Format A resource file contains text representing the default resource values for an application or set of applications. The format of resource files is defined by Xlib - C Language X Interface and is reproduced here for convenience only. The format of a resource specification is ResourceLine = Comment | IncludeFile | ResourceSpec | Comment = ``!'' {} IncludeFile = ``#'' WhiteSpace ``include'' WhiteSpace FileName WhiteSpace FileName = ResourceSpec = WhiteSpace ResourceName WhiteSpace ``:'' WhiteSpace Value ResourceName = [Binding] {Component Binding} ComponentName Binding = ``.'' | ``*'' WhiteSpace = { | } Component = ``?'' | ComponentName ComponentName = NameChar {NameChar} NameChar = ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' Value = {} Elements separated by vertical bar (|) are alternatives. Curly braces ({...}) indicate zero or more repetitions of the enclosed elements. Square brackets ([...]) indicate that the enclosed element is optional. Quotes (``...'') are used around literal characters. If the last character on a line is a backslash (\), that line is assumed to continue on the next line. To allow a Value to begin with whitespace, the two-character sequence ``\space'' (backslash followed by space) is recog- nized and replaced by a space character, and the two- character sequence ``\tab'' (backslash followed by horizon- tal tab) is recognized and replaced by a horizontal tab character. To allow a Value to contain embedded newline characters, the two-character sequence ``\n'' is recognized and replaced by a newline character. To allow a Value to be broken across multiple lines in a text file, the two-character sequence ``\newline'' (backslash followed by newline) is recognized and removed from the value. To allow a Value to contain arbitrary character codes, the four-character sequence ``\nnn'', where each n is a digit character in the range of ``0''-``7'', is recognized and replaced with a single byte that contains the octal value specified by the sequence. Finally, the two-character sequence ``\\'' is recognized and replaced with a single backslash. [...] Appendix B Translation Table Syntax Notation Syntax is specified in EBNF notation with the following con- ventions: [ a ] Means either nothing or ``a'' { a } Means zero or more occurrences of ``a'' ( a | b ) Means either ``a'' or ``b'' \n Is the newline character All terminals are enclosed in double quotation marks (`` ''). Informal descriptions are enclosed in angle brackets (< >). Syntax The syntax of a translation table is translationTable = [ directive ] { production } directive = ( ``#replace'' | ``#override'' | ``#augment'' ) ``\n'' production = lhs ``:'' rhs ``\n'' lhs = ( event | keyseq ) { ``,'' (event | keyseq) } keyseq = ``"'' keychar {keychar} ``"'' keychar = [ ``^'' | ``$'' | ``\'' ] event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail} modifier_list = ( [``!''] [``:''] {modifier} ) | ``None'' modifier = [``~''] modifier_name count = (``1'' | ``2'' | ``3'' | ``4'' | ...) modifier_name = ``@'' | event_type = detail = rhs = { name ``('' [params] ``)'' } name = namechar { namechar } namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } params = string {``,'' string} string = quoted_string | unquoted_string quoted_string = ``"'' { | escape_char} [``\\'' ] ``"'' escape_char = ``\"'' unquoted_string = {} The params field is parsed into a list of String values that will be passed to the named action procedure. A quoted string may contain an embedded quotation mark if the quota- tion mark is preceded by a single backslash (\). The three-character sequence ``\\"'' is interpreted as ``single backslash followed by end-of-string''. Modifier Names The modifier field is used to specify standard X keyboard and button modifier mask bits. Modifiers are legal on event types KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, EnterNotify, LeaveNotify, and their abbrevia- tions. An error is generated when a translation table that contains modifiers for any other events is parsed. o If the modifier list has no entries and is not ``None'', it means ``don't care'' on all modifiers. o If an exclamation point (!) is specified at the begin- ning of the modifier list, it means that the listed modifiers must be in the correct state and no other modifiers can be asserted. o If any modifiers are specified and an exclamation point (!) is not specified, it means that the listed modifiers must be in the correct state and ``don't care'' about any other modifiers. o If a modifier is preceded by a tilde (~), it means that that modifier must not be asserted. o If ``None'' is specified, it means no modifiers can be asserted. o If a colon (:) is specified at the beginning of the modifier list, it directs the Intrinsics to apply any standard modifiers in the event to map the event key- code into a KeySym. The default standard modifiers are Shift and Lock, with the interpretation as defined in X Window System Protocol, Section 5. The resulting KeySym must exactly match the specified KeySym, and the nonstandard modifiers in the event must match the modifier list. For example, ``:a'' is distinct from ``:A'', and ``:ShiftA'' is distinct from ``:A''. o If both an exclamation point (!) and a colon (:) are specified at the beginning of the modifier list, it means that the listed modifiers must be in the correct state and that no other modifiers except the standard modifiers can be asserted. Any standard modifiers in the event are applied as for colon (:) above. o If a colon (:) is not specified, no standard modifiers are applied. Then, for example, ``A'' and ``a'' are equivalent. In key sequences, a circumflex (^) is an abbreviation for the Control modifier, a dollar sign ($) is an abbreviation for Meta, and a backslash (\) can be used to quote any char- acter, in particular a double quote ("), a circumflex (^), a dollar sign ($), and another backslash (\). Briefly: No modifiers: None detail Any modifiers: detail Only these modifiers: ! mod1 mod2 detail These modifiers and any others:mod1 mod2 detail The use of ``None'' for a modifier list is identical to the use of an exclamation point with no modifers. __________________________________________________________ Modifier Abbreviation Meaning __________________________________________________________ Ctrl c Control modifier bit Shift s Shift modifier bit Lock l Lock modifier bit Meta m Meta key modifier Hyper h Hyper key modifier Super su Super key modifier Alt a Alt key modifier Mod1 Mod1 modifier bit Mod2 Mod2 modifier bit Mod3 Mod3 modifier bit Mod4 Mod4 modifier bit Mod5 Mod5 modifier bit Button1 Button1 modifier bit Button2 Button2 modifier bit Button3 Button3 modifier bit Button4 Button4 modifier bit Button5 Button5 modifier bit None No modifiers Any Any modifier combination __________________________________________________________ A key modifier is any modifier bit one of whose correspond- ing KeyCodes contains the corresponding left or right KeySym. For example, ``m'' or ``Meta'' means any modifier bit mapping to a KeyCode whose KeySym list contains XK_Meta_L or XK_Meta_R. Note that this interpretation is for each display, not global or even for each application context. The Control, Shift, and Lock modifier names refer explicitly to the corresponding modifier bits; there is no additional interpretation of KeySyms for these modifiers. Because it is possible to associate arbitrary KeySyms with modifiers, the set of key modifiers is extensible. The ``@'' syntax means any modifier bit whose corresponding KeyCode contains the specified KeySym name. A modifier_list/KeySym combination in a translation matches a modifiers/KeyCode combination in an event in the following ways: 1. If a colon (:) is used, the Intrinsics call the display's XtKeyProc with the KeyCode and modifiers. To match, (modifiers & ~modifiers_return) must equal modifier_list, and keysym_return must equal the given KeySym. 2. If (:) is not used, the Intrinsics mask off all don't- care bits from the modifiers. This value must be equal to modifier_list. Then, for each possible combination of don't-care modifiers in the modifier list, the Intrinsics call the display's XtKeyProc with the Key- Code and that combination ORed with the cared-about modifier bits from the event. Keysym_return must match the KeySym in the translation. Event Types The event-type field describes XEvent types. In addition to the standard Xlib symbolic event type names, the following event type synonyms are defined: ________________________________________________ Type Meaning ________________________________________________ Key KeyPress KeyDown KeyPress KeyUp KeyRelease BtnDown ButtonPress BtnUp ButtonRelease Motion MotionNotify PtrMoved MotionNotify MouseMoved MotionNotify Enter EnterNotify EnterWindow EnterNotify Leave LeaveNotify LeaveWindow LeaveNotify FocusIn FocusIn FocusOut FocusOut Keymap KeymapNotify Expose Expose GrExp GraphicsExpose NoExp NoExpose Visible VisibilityNotify Create CreateNotify Destroy DestroyNotify Unmap UnmapNotify Map MapNotify MapReq MapRequest Reparent ReparentNotify Configure ConfigureNotify ConfigureReq ConfigureRequest Grav GravityNotify ResReq ResizeRequest Circ CirculateNotify CircReq CirculateRequest Prop PropertyNotify SelClr SelectionClear SelReq SelectionRequest Select SelectionNotify Clrmap ColormapNotify Message ClientMessage Mapping MappingNotify ________________________________________________ The supported abbreviations are: _________________________________________________________ Abbreviation Event Type Including _________________________________________________________ Ctrl KeyPress with Control modifier Meta KeyPress with Meta modifier Shift KeyPress with Shift modifier Btn1Down ButtonPress with Button1 detail Btn1Up Button- with Button1 detail Release Btn2Down ButtonPress with Button2 detail Btn2Up Button- with Button2 detail Release Btn3Down ButtonPress with Button3 detail Btn3Up Button- with Button3 detail Release Btn4Down ButtonPress with Button4 detail Btn4Up Button- with Button4 detail Release Btn5Down ButtonPress with Button5 detail Btn5Up Button- with Button5 detail Release BtnMotion MotionNotify with any button modifier Btn1Motion MotionNotify with Button1 modifier Btn2Motion MotionNotify with Button2 modifier Btn3Motion MotionNotify with Button3 modifier Btn4Motion MotionNotify with Button4 modifier Btn5Motion MotionNotify with Button5 modifier _________________________________________________________ The detail field is event-specific and normally corresponds to the detail field of the corresponding event as described by X Window System Protocol, Section 11. The detail field is supported for the following event types: _____________________________________________________ Event Event Field _____________________________________________________ KeyPress KeySym from event detail (keycode) KeyRelease KeySym from event detail (keycode) ButtonPress button from event detail ButtonRelease button from event detail MotionNotify event detail EnterNotify event mode LeaveNotify event mode FocusIn event mode FocusOut event mode PropertyNotify atom SelectionClear selection SelectionRequest selection SelectionNotify selection ClientMessage type MappingNotify request _____________________________________________________ If the event type is KeyPress or KeyRelease, the detail field specifies a KeySym name in standard format which is matched against the event as described above, for example, A. For the PropertyNotify, SelectionClear, SelectionRequest, SelectionNotify, and ClientMessage events the detail field is specified as an atom name; for example, WM_PROTOCOLS. For the MotionNotify, EnterNotify, LeaveNotify, FocusIn, FocusOut, and MappingNotify events, either the symbolic constants as defined by X Window System Protocol, Section 11, or the numeric values may be speci- fied. If no detail field is specified, then any value in the event detail is accepted as a match. A KeySym can be specified as any of the standard KeySym names, a hexadecimal number prefixed with ``0x'' or ``0X'', an octal number prefixed with ``0'', or a decimal number. A KeySym expressed as a single digit is interpreted as the corresponding Latin 1 KeySym, for example, ``0'' is the KeySym XK_0. Other single character KeySyms are treated as literal constants from Latin 1, for example, ``!'' is treated as 0x21. Standard KeySym names are as defined in with the ``XK_'' prefix removed. Canonical Representation Every translation table has a unique, canonical text representation. This representation is passed to a widget's display_accelerator procedure to describe the accelerators installed on that widget. The canonical representation of a translation table is (see also ``Syntax'') translationTable = { production } production = lhs ``:'' rhs ``\n'' lhs = event { ``,'' event } event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail} modifier_list = [``!''] [``:''] {modifier} modifier = [``~''] modifier_name count = (``1'' | ``2'' | ``3'' | ``4'' | ...) modifier_name = ``@'' | event_type = detail = rhs = { name ``('' [params] ``)'' } name = namechar { namechar } namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } params = string {``,'' string} string = quoted_string quoted_string = ``"'' { | escape_char} [``\\'' ] ``"'' escape_char = ``\"'' The canonical modifier names are Ctrl Mod1 Button1 Shift Mod2 Button2 Lock Mod3 Button3 Mod4 Button4 Mod5 Button5 The canonical event types are KeyPress KeyRelease ButtonPress ButtonRelease MotionNotify EnterNotify LeaveNotify FocusIn FocusOut KeymapNotify Expose GraphicsExpose, NoExpose VisibilityNotify CreateNotify DestroyNotify UnmapNotify MapNotify MapRequest ReparentNotify ConfigureNotify ConfigureRequest GravityNotify ResizeRequest CirculateNotify CirculateRequest PropertyNotify SelectionClear SelectionRequest SelectionNotify ColormapNotify ClientMessage Examples o Always put more specific events in the table before more general ones: Shift : twas()\n\ : brillig() o For double-click on Button1 Up with Shift, use this specification: Shift(2) : and() This is equivalent to the following line with appropri- ate timers set between events: Shift,Shift,Shift,Shift : and() o For double-click on Button1 Down with Shift, use this specification: Shift(2) : the() This is equivalent to the following line with appropri- ate timers set between events: Shift,Shift,Shift : the() o Mouse motion is always discarded when it occurs between events in a table where no motion event is specified: , : slithy() This is taken, even if the pointer moves a bit between the down and up events. Similarly, any motion event specified in a translation matches any number of motion events. If the motion event causes an action procedure to be invoked, the procedure is invoked after each motion event. o If an event sequence consists of a sequence of events that is also a noninitial subsequence of another trans- lation, it is not taken if it occurs in the context of the longer sequence. This occurs mostly in sequences like the following: , : toves()\n\ : did() The second translation is taken only if the button release is not preceded by a button press or if there are intervening events between the press and the release. Be particularly aware of this when using the repeat notation, above, with buttons and keys, because their expansion includes additional events; and when specifying motion events, because they are implicitly included between any two other events. In particular, pointer motion and double-click translations cannot coexist in the same translation table. o For single click on Button1 Up with Shift and Meta, use this specification: Shift Meta , Shift Meta: gyre() o For multiple clicks greater or equal to a minimum number, a plus sign (+) may be appended to the final (rightmost) count in an event sequence. The actions will be invoked on the count-th click and each subse- quent one arriving within the multi-click time inter- val. For example: Shift (2+) : and() o To indicate EnterNotify with any modifiers, use this specification: : gimble() o To indicate EnterNotify with no modifiers, use this specification: None : in() o To indicate EnterNotify with Button1 Down and Button2 Up and ``don't care'' about the other modifiers, use this specification: Button1 ~Button2 : the() o To indicate EnterNotify with Button1 down and Button2 down exclusively, use this specification: ! Button1 Button2 : wabe() You do not need to use a tilde (~) with an exclamation point (!). [...] Table of Contents Acknowledgments ....................................... ix About This Manual ..................................... xii Chapter 1 - Intrinsics and Widgets .................... 1 1.1. Intrinsics ....................................... 1 1.2. Languages ........................................ 1 1.3. Procedures and Macros ............................ 2 1.4. Widgets .......................................... 2 1.4.1. Core Widgets ................................... 3 1.4.1.1. CoreClassPart Structure ...................... 4 1.4.1.2. CorePart Structure ........................... 5 1.4.1.3. Core Resources ............................... 7 1.4.1.4. CorePart Default Values ...................... 7 1.4.2. Composite Widgets .............................. 8 1.4.2.1. CompositeClassPart Structure ................. 8 1.4.2.2. CompositePart Structure ...................... 10 1.4.2.3. Composite Resources .......................... 11 1.4.2.4. CompositePart Default Values ................. 11 1.4.3. Constraint Widgets ............................. 11 1.4.3.1. ConstraintClassPart Structure ................ 11 1.4.3.2. ConstraintPart Structure ..................... 13 1.4.3.3. Constraint Resources ......................... 14 1.5. Implementation-Specific Types .................... 14 1.6. Widget Classing .................................. 15 1.6.1. Widget Naming Conventions ...................... 16 1.6.2. Widget Subclassing in Public .h Files .......... 17 1.6.3. Widget Subclassing in Private .h Files ......... 19 1.6.4. Widget Subclassing in .c Files ................. 21 1.6.5. Widget Class and Superclass Look Up ............ 24 1.6.6. Widget Subclass Verification ................... 25 1.6.7. Superclass Chaining ............................ 26 1.6.8. Class Initialization: class_initialize and class_part_initialize Procedures ...................... 28 1.6.9. Initializing a Widget Class .................... 30 1.6.10. Inheritance of Superclass Operations .......... 30 1.6.11. Invocation of Superclass Operations ........... 32 1.6.12. Class Extension Records ....................... 33 Chapter 2 - Widget Instantiation ...................... 36 2.1. Initializing the X Toolkit ....................... 37 2.2. Establishing the Locale .......................... 43 2.3. Loading the Resource Database .................... 45 2.4. Parsing the Command Line ......................... 50 2.5. Creating Widgets ................................. 53 2.5.1. Creating and Merging Argument Lists ............ 54 2.5.2. Creating a Widget Instance ..................... 57 2.5.3. Creating an Application Shell Instance ......... 60 2.5.4. Convenience Procedure to Initialize an Appli- cation ................................................ 63 2.5.5. Widget Instance Allocation: The allocate Pro- cedure ................................................ 66 2.5.6. Widget Instance Initialization: The initial- ize Procedure ......................................... 69 2.5.7. Constraint Instance Initialization: The Con- straintClassPart initialize Procedure ................. 72 2.5.8. Nonwidget Data Initialization: The initialize_hook Procedure ............................. 72 2.6. Realizing Widgets ................................ 73 2.6.1. Widget Instance Window Creation: The realize Procedure ............................................. 75 2.6.2. Window Creation Convenience Routine ............ 77 2.7. Obtaining Window Information from a Widget ....... 78 2.7.1. Unrealizing Widgets ............................ 81 2.8. Destroying Widgets ............................... 81 2.8.1. Adding and Removing Destroy Callbacks .......... 83 2.8.2. Dynamic Data Deallocation: The destroy Pro- cedure ................................................ 84 2.8.3. Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure ................. 85 2.8.4. Widget Instance Deallocation: The deallocate Procedure ............................................. 85 2.9. Exiting from an Application ...................... 86 Chapter 3 - Composite Widgets and Their Children ...... 87 3.1. Addition of Children to a Composite Widget: The insert_child Procedure ................................ 88 3.2. Insertion Order of Children: The insert_position Procedure ............................. 89 3.3. Deletion of Children: The delete_child Pro- cedure ................................................ 90 3.4. Adding and Removing Children from the Managed Set ................................................... 91 3.4.1. Managing Children .............................. 91 3.4.2. Unmanaging Children ............................ 94 3.4.3. Bundling Changes to the Managed Set ............ 95 3.4.4. Determining if a Widget Is Managed ............. 98 3.5. Controlling When Widgets Get Mapped .............. 99 3.6. Constrained Composite Widgets .................... 100 Chapter 4 - Shell Widgets ............................. 103 4.1. Shell Widget Definitions ......................... 103 4.1.1. ShellClassPart Definitions ..................... 104 4.1.2. ShellPart Definition ........................... 108 4.1.3. Shell Resources ................................ 112 4.1.4. ShellPart Default Values ....................... 114 4.2. Session Participation ............................ 121 4.2.1. Joining a Session .............................. 121 4.2.2. Saving Application State ....................... 122 4.2.2.1. Requesting Interaction ....................... 125 4.2.2.2. Interacting with the User during a Check- point ................................................. 126 4.2.2.3. Responding to a Shutdown Cancellation ........ 126 4.2.2.4. Completing a Save ............................ 127 4.2.3. Responding to a Shutdown ....................... 127 4.2.4. Resigning from a Session ....................... 128 Chapter 5 - Pop-Up Widgets ............................ 129 5.1. Pop-Up Widget Types .............................. 129 5.2. Creating a Pop-Up Shell .......................... 130 5.3. Creating Pop-Up Children ......................... 132 5.4. Mapping a Pop-Up Widget .......................... 133 5.5. Unmapping a Pop-Up Widget ........................ 137 Chapter 6 - Geometry Management ....................... 141 6.1. Initiating Geometry Changes ...................... 141 6.2. General Geometry Manager Requests ................ 142 6.3. Resize Requests .................................. 145 6.4. Potential Geometry Changes ....................... 146 6.5. Child Geometry Management: The geometry_manager Procedure ............................................. 147 6.6. Widget Placement and Sizing ...................... 149 6.7. Preferred Geometry ............................... 152 6.8. Size Change Management: The resize Procedure Chapter 7 - Event Management .......................... 156 7.1. Adding and Deleting Additional Event Sources 7.1.1. Adding and Removing Input Sources .............. 157 7.1.2. Adding and Removing Blocking Notifications 7.1.3. Adding and Removing Timeouts ................... 160 7.1.4. Adding and Removing Signal Callbacks ........... 162 7.2. Constraining Events to a Cascade of Widgets ...... 164 7.2.1. Requesting Key and Button Grabs ................ 166 7.3. Focusing Events on a Child ....................... 172 7.3.1. Events for Drawables That Are Not a Widget's Window ................................................ 174 7.4. Querying Event Sources ........................... 176 7.5. Dispatching Events ............................... 177 7.6. The Application Input Loop ....................... 179 7.7. Setting and Checking the Sensitivity State of a Widget ................................................ 180 7.8. Adding Background Work Procedures ................ 182 7.9. X Event Filters .................................. 183 7.9.1. Pointer Motion Compression ..................... 183 7.9.2. Enter/Leave Compression ........................ 183 7.9.3. Exposure Compression ........................... 184 7.10. Widget Exposure and Visibility .................. 186 7.10.1. Redisplay of a Widget: The expose Procedure 7.10.2. Widget Visibility ............................. 187 7.11. X Event Handlers ................................ 188 7.11.1. Event Handlers That Select Events ............. 189 7.11.2. Event Handlers That Do Not Select Events ...... 191 7.11.3. Current Event Mask ............................ 194 7.11.4. Event Handlers for X11 Protocol Extensions 7.12. Using the Intrinsics in a Multi-Threaded Environment ........................................... 202 7.12.1. Initializing a Multi-Threaded Intrinsics Application ........................................... 202 7.12.2. Locking X Toolkit Data Structures ............. 202 7.12.2.1. Locking the Application Context ............. 203 7.12.2.2. Locking the Process ......................... 204 7.12.3. Event Management in a Multi-Threaded Environment ........................................... 205 Chapter 8 - Callbacks ................................. 207 8.1. Using Callback Procedure and Callback List Definitions ........................................... 207 8.2. Identifying Callback Lists ....................... 208 8.3. Adding Callback Procedures ....................... 209 8.4. Removing Callback Procedures ..................... 210 8.5. Executing Callback Procedures .................... 211 8.6. Checking the Status of a Callback List ........... 213 Chapter 9 - Resource Management ....................... 214 9.1. Resource Lists ................................... 214 9.2. Byte Offset Calculations ......................... 220 9.3. Superclass-to-Subclass Chaining of Resource Lists ................................................. 221 9.4. Subresources ..................................... 222 9.5. Obtaining Application Resources .................. 224 9.6. Resource Conversions ............................. 226 9.6.1. Predefined Resource Converters ................. 227 9.6.2. New Resource Converters ........................ 230 9.6.3. Issuing Conversion Warnings .................... 235 9.6.4. Registering a New Resource Converter ........... 236 9.6.5. Resource Converter Invocation .................. 241 9.7. Reading and Writing Widget State ................. 246 9.7.1. Obtaining Widget State ......................... 246 9.7.1.1. Widget Subpart Resource Data: The get_values_hook Procedure ............................. 249 9.7.1.2. Widget Subpart State ......................... 249 9.7.2. Setting Widget State ........................... 251 9.7.2.1. Widget State: The set_values Procedure ....... 253 9.7.2.2. Widget State: The set_values_almost Pro- cedure ................................................ 256 9.7.2.3. Widget State: The ConstraintClassPart set_values Procedure .................................. 257 9.7.2.4. Widget Subpart State ......................... 257 9.7.2.5. Widget Subpart Resource Data: The set_values_hook Procedure ............................. 259 Chapter 10 - Translation Management ................... 261 10.1. Action Tables ................................... 261 10.1.1. Action Table Registration ..................... 263 10.1.2. Action Names to Procedure Translations ........ 264 10.1.3. Action Hook Registration ...................... 264 10.2. Translation Tables .............................. 266 10.2.1. Event Sequences ............................... 267 10.2.2. Action Sequences .............................. 267 10.2.3. Multi-Click Time .............................. 268 10.3. Translation Table Management .................... 269 10.4. Using Accelerators .............................. 272 10.5. KeyCode-to-KeySym Conversions ................... 275 10.6. Obtaining a KeySym in an Action Procedure ....... 279 10.7. KeySym-to-KeyCode Conversions ................... 280 10.8. Registering Button and Key Grabs for Actions 10.9. Invoking Actions Directly ....................... 283 10.10. Obtaining a Widget's Action List ............... 284 Chapter 11 - Utility Functions ........................ 285 11.1. Determining the Number of Elements in an Array 11.2. Translating Strings to Widget Instances ......... 286 11.3. Managing Memory Usage ........................... 287 11.4. Sharing Graphics Contexts ....................... 290 11.5. Managing Selections ............................. 292 11.5.1. Setting and Getting the Selection Timeout Value ................................................. 293 11.5.2. Using Atomic Transfers ........................ 293 11.5.2.1. Atomic Transfer Procedures .................. 294 11.5.2.2. Getting the Selection Value ................. 298 11.5.2.3. Setting the Selection Owner ................. 300 11.5.3. Using Incremental Transfers ................... 302 11.5.3.1. Incremental Transfer Procedures ............. 303 11.5.3.2. Getting the Selection Value Incrementally 11.5.3.3. Setting the Selection Owner for Incremen- tal Transfers ......................................... 310 11.5.4. Setting and Retrieving Selection Target Parameters ............................................ 312 11.5.5. Generating MULTIPLE Requests .................. 315 11.5.6. Auxiliary Selection Properties ................ 316 11.5.7. Retrieving the Most Recent Timestamp .......... 317 11.5.8. Retrieving the Most Recent Event .............. 318 11.6. Merging Exposure Events into a Region ........... 318 11.7. Translating Widget Coordinates .................. 319 11.8. Translating a Window to a Widget ................ 320 11.9. Handling Errors ................................. 320 11.10. Setting WM_COLORMAP_WINDOWS .................... 328 11.11. Finding File Names ............................. 329 11.12. Hooks for External Agents ...................... 334 11.12.1. Hook Object Resources ........................ 335 11.12.2. Querying Open Displays ....................... 341 Chapter 12 - Nonwidget Objects ........................ 343 12.1. Data Structures ................................. 343 12.2. Object Objects .................................. 343 12.2.1. ObjectClassPart Structure ..................... 343 12.2.2. ObjectPart Structure .......................... 345 12.2.3. Object Resources .............................. 346 12.2.4. ObjectPart Default Values ..................... 347 12.2.5. Object Arguments to Intrinsics Routines ....... 347 12.2.6. Use of Objects ................................ 348 12.3. Rectangle Objects ............................... 348 12.3.1. RectObjClassPart Structure .................... 349 12.3.2. RectObjPart Structure ......................... 350 12.3.3. RectObj Resources ............................. 351 12.3.4. RectObjPart Default Values .................... 352 12.3.5. Widget Arguments to Intrinsics Routines ....... 352 12.3.6. Use of Rectangle Objects ...................... 352 12.4. Undeclared Class ................................ 354 12.5. Widget Arguments to Intrinsics Routines ......... 354 Chapter 13 - Evolution of the Intrinsics .............. 357 13.1. Determining Specification Revision Level ........ 357 13.2. Release 3 to Release 4 Compatibility ............ 357 13.2.1. Additional Arguments .......................... 358 13.2.2. set_values_almost Procedures .................. 358 13.2.3. Query Geometry ................................ 358 13.2.4. unrealizeCallback Callback List ............... 359 13.2.5. Subclasses of WMShell ......................... 359 13.2.6. Resource Type Converters ...................... 359 13.2.7. KeySym Case Conversion Procedure .............. 360 13.2.8. Nonwidget Objects ............................. 360 13.3. Release 4 to Release 5 Compatibility ............ 360 13.3.1. baseTranslations Resource ..................... 361 13.3.2. Resource File Search Path ..................... 361 13.3.3. Customization Resource ........................ 361 13.3.4. Per-Screen Resource Database .................. 362 13.3.5. Internationalization of Applications .......... 362 13.3.6. Permanently Allocated Strings ................. 363 13.3.7. Arguments to Existing Functions ............... 363 13.4. Release 5 to Release 6 Compatibility ............ 363 13.4.1. Widget Internals .............................. 364 13.4.2. General Application Development ............... 364 13.4.3. Communication with Window and Session Managers .............................................. 365 13.4.4. Geometry Management ........................... 365 13.4.5. Event Management .............................. 365 13.4.6. Resource Management ........................... 366 13.4.7. Translation Management ........................ 367 13.4.8. Selections .................................... 367 13.4.9. External Agent Hooks .......................... 367 Appendix A - Resource File Format ..................... 368 Appendix B - Translation Table Syntax ................. 370 Appendix C - Compatibility Functions .................. 380 Appendix D - Intrinsics Error Messages ................ 399 Appendix E - Defined Strings .......................... 407 Appendix F - Resource Configuration Management ........ 417 Index ................................................. 419