../various
| X11
| 8bit characters
| xmodmap
, latin1 keysyms
, compose sequences
| app resources, xterm
| xmon
| xev
| mem footprints
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 | <empty line>
Comment = ``!'' {<any character except null or newline>}
IncludeFile = ``#'' WhiteSpace ``include'' WhiteSpace FileName WhiteSpace
FileName = <valid filename for operating system>
ResourceSpec = WhiteSpace ResourceName WhiteSpace ``:'' WhiteSpace Value
ResourceName = [Binding] {Component Binding} ComponentName
Binding = ``.'' | ``*''
WhiteSpace = {<space> | <horizontal tab>}
Component = ``?'' | ComponentName
ComponentName = NameChar {NameChar}
NameChar = ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-''
Value = {<any character except null or unescaped newline>}
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 = [ ``^'' | ``$'' | ``\'' ] <ISO Latin 1 character>
event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail}
modifier_list = ( [``!''] [``:''] {modifier} ) | ``None''
modifier = [``~''] modifier_name
count = (``1'' | ``2'' | ``3'' | ``4'' | ...)
modifier_name = ``@'' <keysym> | <see ModifierNames table below>
event_type = <see Event Types table below>
detail = <event specific details>
rhs = { name ``('' [params] ``)'' }
name = namechar { namechar }
namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' }
params = string {``,'' string}
string = quoted_string | unquoted_string
quoted_string = ``"'' {<Latin 1 character> | escape_char} [``\\'' ] ``"''
escape_char = ``\"''
unquoted_string = {<Latin 1 character except space, tab, ``,'', ``\n'', ``)''>}
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, ``:<Key>a'' is distinct
from ``:<Key>A'', and ``:Shift<Key>A'' is distinct from
``:<Key>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, ``<Key>A'' and
``<Key>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 <event> detail
Any modifiers: <event> detail
Only these modifiers: ! mod1 mod2 <event> detail
These modifiers and any others:mod1 mod2 <event> 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
``@'' <keysym> 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,
<Key>A.
For the PropertyNotify, SelectionClear, SelectionRequest,
SelectionNotify, and ClientMessage events the detail field
is specified as an atom name; for example,
<Message>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
<X11/keysymdef.h> 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 = ``@'' <keysym> | <see canonical modifier names below>
event_type = <see canonical event types below>
detail = <event-specific details>
rhs = { name ``('' [params] ``)'' }
name = namechar { namechar }
namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' }
params = string {``,'' string}
string = quoted_string
quoted_string = ``"'' {<Latin 1 character> | 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 <Btn1Down> : twas()\n\
<Btn1Down> : brillig()
o For double-click on Button1 Up with Shift, use this
specification:
Shift<Btn1Up>(2) : and()
This is equivalent to the following line with appropri-
ate timers set between events:
Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down>,Shift<Btn1Up> : and()
o For double-click on Button1 Down with Shift, use this
specification:
Shift<Btn1Down>(2) : the()
This is equivalent to the following line with appropri-
ate timers set between events:
Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down> : the()
o Mouse motion is always discarded when it occurs
between events in a table where no motion event is
specified:
<Btn1Down>,<Btn1Up> : 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:
<Btn1Down>,<Btn1Up> : toves()\n\
<Btn1Up> : 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 <Btn1Down>, Shift Meta<Btn1Up>: 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 <Btn1Up>(2+) : and()
o To indicate EnterNotify with any modifiers, use this
specification:
<Enter> : gimble()
o To indicate EnterNotify with no modifiers, use this
specification:
None <Enter> : in()
o To indicate EnterNotify with Button1 Down and Button2
Up and ``don't care'' about the other modifiers, use
this specification:
Button1 ~Button2 <Enter> : the()
o To indicate EnterNotify with Button1 down and Button2
down exclusively, use this specification:
! Button1 Button2 <Enter> : 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