'\" t

...\" VirtBind.sgm /main/12 1996/09/08 21:43:15 rws $

.de P!

.fl

\!!1 setgray

.fl

\\&.\"

.fl

\!!0 setgray

.fl			\" force out current output buffer

\!!save /psv exch def currentpoint translate 0 0 moveto

\!!/showpage{}def

.fl			\" prolog

.sy sed -e 's/^/!/' \\$1\" bring in postscript file

\!!psv restore

.

.de pF

.ie     ?\\*(f1?? .ds f1 \\n(.f

.el .ie ?\\*(f2?? .ds f2 \\n(.f

.el .ie ?\\*(f3?? .ds f3 \\n(.f

.el .ie ?\\*(f4?? .ds f4 \\n(.f

.el .tm ? font overflow

.ft \\$1

..

.de fP

.ie     !?\\*(f4?? \{\

.	ft \\*(f4

.	ds f4\"

'	br \}

.el .ie !?\\*(f3?? \{\

.	ft \\*(f3

.	ds f3\"

'	br \}

.el .ie !?\\*(f2?? \{\

.	ft \\*(f2

.	ds f2\"

'	br \}

.el .ie !?\\*(f1?? \{\

.	ft \\*(f1

.	ds f1\"

'	br \}

.el .tm ? font underflow

..

.ds f1\"

.ds f2\"

.ds f3\"

.ds f4\"

.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 

.TH "VirtualBindings" "library call"

.SH "NAME"

\fBVirtualBindings\fP \(em Bindings for virtual mouse and key events

.iX "VirtualBindings"

.iX "default bindings" "VirtualBindings"

.SH "DESCRIPTION"

.PP

The Motif reference pages describe key translations in terms of

\fIvirtual bindings\fP, based on those described in the \fIMotif Style Guide\fP\&.

.SS "Bindings for osf Keysyms"

.PP

Keysym strings that begin with \fB<osf>\fP are not part of the X server\&'s

keyboard mapping\&.

Instead, these keysyms are produced on the client side at run time\&.

They are interpreted by the routine \fBXmTranslateKey\fP, and

are used by the translation manager when the server delivers an actual

key event\&.

For each application, a mapping is maintained between \fB<osf>\fP keysyms and

keysyms that correspond to actual keys\&.

This mapping is based on information obtained at application startup

from one of the following sources, listed in order of precedence:

.IP "   \(bu" 6

The \fBXmNdefaultVirtualBindings\fP resource from Display\&.

.IP "   \(bu" 6

A property on the root window, which can be set by \fBmwm\fP on startup,

or by the \fBxmbind\fP client, or on prior startup of a Motif

application\&.

.IP "   \(bu" 6

The file \fB\&.motifbind\fP in the user\&'s home directory\&.

.IP "   \(bu" 6

A set of bindings based on the vendor string and optionally the vendor

release of the X server\&.

Motif searches for these bindings in the following steps:

.RS

.IP "   0." 6

If the file \fBxmbind\&.alias\fP exists in the user\&'s home directory,

Motif searches this file for a pathname associated with the vendor

string or with the vendor string and vendor release\&.

If it finds such a pathname and if that file exists, Motif loads the

bindings contained in that file\&.

.IP "   1." 6

If it has found no bindings, Motif next looks for the file

\fBxmbind\&.alias\fP in the directory specified by the environment

variable \fBXMBINDDIR\fP, if \fBXMBINDDIR\fP is set, or in the directory

\fB/usr/lib/Xm/bindings\fP if \fBXMBINDDIR\fP is not set\&.

If this file exists Motif searches it for a pathname associated with the

vendor string or with the vendor string and vendor release\&.

If it finds such a pathname and if that file exists, Motif loads the

bindings contained in that file\&.

.IP "   2." 6

If it still has found no bindings, Motif loads a set of hard-coded

fallback bindings\&.

.RE

.PP

The \fBxmbind\&.alias\fP file contains zero or more lines of the following form:

.PP

.nf

\f(CW"\fIvendor_string\fP[ \fIvendor_release\fP]"    \fIbindings_file\fP\fR

.fi

.PP

.PP

where \fIvendor_string\fP is the X server vendor name as returned by the

X client \fBxdpyinfo\fP or the Xlib function \fBXServerVendor\fP, and

must appear in double quotes\&.

If \fIvendor_release\fP is included, it is the X server vendor release

number as returned by the X client \fBxdpyinfo\fP or the Xlib function

\fBXVendorRelease\fP, and must also be contained within the double

quotes separated by one space from \fIvendor_string\fP\&.

The \fIvendor_release\fP argument is provided to allow support

of changes in keyboard

hardware from a vendor, assuming that the vendor increments the release

number to flag such changes\&.

Alternatively, the vendor may simply use a unique vendor string for each

different keyboard\&.

.PP

The \fIbindings_file\fP argument is the pathname of

the file containing the bindings

themselves\&.

It can be a relative or absolute pathname\&.

If it it is a relative pathname, it is relative to the location of the

\fBxmbind\&.alias\fP file\&.

.PP

Comment lines in the \fBxmbind\&.alias\fP file begin with ! (exclamation

point)\&.

.PP

The bindings found in either the \fB\&.motifbind\fP file or the vendor

mapping are placed in a property on the root window\&.

This property is used to determine the bindings for subsequent Motif

applications\&.

.PP

On startup \fBmwm\fP attempts to load the file \fB\&.motifbind\fP in the

user\&'s home directory\&.

If this is unsuccessful, it loads the vendor bindings as described

previously\&.

It places the bindings it loads in a property on the root window for use

by subsequent Motif applications\&.

.PP

The \fBxmbind\fP function loads bindings

from a file if that file is specified on the

command line\&.

If no file is specified on the command line, it attempts to load the

file \fB\&.motifbind\fP in the user\&'s home directory\&.

If this fails, it loads the vendor bindings as described previously\&.

It places the bindings it loads in a property on the root window for use

by subsequent Motif applications\&.

.PP

The format of the specification for mapping \fB<osf>\fP keysyms to

actual keysyms is similar to that of a specification for an event

translation\&. (See below) The syntax is specified (and below) here in

EBNF notation using the following conventions:

.PP

.nf

\f(CW[\fIa\fP]    Means either nothing or \fIa\fP

{\fIa\fP}    Means zero or more occurrences of \fIa\fP

(\fIa\fP|\fIb\fP)    Means either \fIa\fP or \fIb\fP\&.\fR

.fi

.PP

.PP

Terminals are enclosed in double quotation marks\&.

.PP

The syntax of an \fB<osf>\fP keysym binding specification is as follows:

.PP

.nf

\f(CWbinding_spec    =       {line "\en"} [line]

line            =       virtual_keysym ":" list_of_key_event

list_of_key_event=      key_event { "," key_event}

key_event       =       {modifier_name} "<Key>" actual_keysym

virtual_keysym  =       keysym

actual_keysym   =       keysym

keysym          =       A valid X11 keysym name that is

                        mapped by \fBXStringToKeysym\fP\fR

.fi

.PP

.PP

As with event translations, more specific event descriptions must

precede less specific descriptions\&.

For example, an event description for a key with a modifier must precede

a description for the same key without the same modifier\&.

.PP

Following is an example of a specification for the

\fBdefaultVirtualBindings\fP resource in a resource file:

.PP

.nf

\f(CW*defaultVirtualBindings: \e

        osfBackSpace:       <Key>BackSpace       \en\e

        osfInsert:       <Key>InsertChar      \en\e

        osfDelete:       <Key>DeleteChar      \en\e

\&.\&.\&.

        osfLeft:       <Key>left, Ctrl<Key>H\fR

.fi

.PP

.PP

The format of a \fB\&.motifbind\fP file or of a file containing vendor

bindings is the same, except that the binding specification for each

keysym is placed on a separate line\&.

The previous example specification appears as follows in a

\fB\&.motifbind\fP or vendor bindings file:

.PP

.nf

\f(CWosfBackSpace:       <Key>BackSpace

osfInsert:       <Key>InsertChar

osfDelete:       <Key>DeleteChar

\&.\&.\&.

osfLeft:       <Key>left, Ctrl<Key>H\fR

.fi

.PP

.PP

The following table lists the fixed fallback default bindings for

\fB<osf>\fP keysyms\&.

.TS

tab(?) box;

c s

l| l.

T{

\fBFallback Default Bindings for osf Keysyms\fP

T}

\fB<osf Keysym>\fP?\fBFallback Default Binding\fP

_?_?

\fB<osfActivate>\fP\fB:\fP?\fB<Key>KP_Enter\fP, \fB<Key>Execute\fP

_?_?

\fB<osfAddMode>\fP\fB:\fP?\fBShift<Key>F8\fP

_?_?

\fB<osfBackSpace>\fP\fB:\fP?\fB<Key>\fP\fBBackSpace\fP

_?_?

\fB<osfBeginLine>\fP\fB:\fP?\fB<Key>Home\fP, \fB<Key>Begin\fP

_?_?

\fB<osfCancel>\fP\fB:\fP?\fB<Key>Escape\fP, \fB<Key>Cancel\fP

_?_?

\fB<osfClear>\fP\fB:\fP?\fB<Key>\fP\fBClear\fP

_?_?

\fB<osfCopy>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfCut>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfDelete>\fP\fB:\fP?\fB<Key>\fP\fBDelete\fP

_?_?

\fB<osfDeselectAll>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfDown>\fP\fB:\fP?\fB<Key>\fP\fBDown\fP

_?_?

\fB<osfEndLine>\fP\fB:\fP?\fB<Key>\fP\fBEnd\fP

_?_?

\fB<osfHelp>\fP\fB:\fP?\fB<Key>F1\fP, \fB<Key>Help\fP

_?_?

\fB<osfInsert>\fP\fB:\fP?\fB<Key>\fP\fBInsert\fP

_?_?

\fB<osfLeft>\fP\fB:\fP?\fB<Key>\fP\fBLeft\fP

_?_?

\fB<osfLeftLine>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfMenu>\fP\fB:\fP?\fBShift\fP\fB<Key>F10\fP, \fB<Key>Menu\fP

_?_?

\fB<osfMenuBar>\fP\fB:\fP?\fB<Key>F10\fP, \fBShift<Key>\fP\fBMenu\fP

_?_?

\fB<osfNextMinor>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfPageDown>\fP\fB:\fP?\fB<Key>\fP\fBNext\fP

_?_?

\fB<osfPageLeft>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfPageRight>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfPageUp>\fP\fB:\fP?\fB<Key>\fP\fBPrior\fP

_?_?

\fB<osfPaste>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfPrimaryPaste>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfPriorMinor>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfReselect>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfRestore>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfRight>\fP\fB:\fP?\fB<Key>\fP\fBRight\fP

_?_?

\fB<osfRightLine>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfSelect>\fP\fB:\fP?\fB<Key>\fP\fBSelect\fP

_?_?

\fB<osfSelectAll>\fP\fB:\fP?\fIunbound\fP

_?_?

\fB<osfSwitchDirection>\fP\fB:\fP?\fBAlt<Key>Return\fP, \fBAlt<Key>KP_Enter\fP

_?_?

\fB<osfUndo>\fP\fB:\fP?\fB<Key>\fP\fBUndo\fP

_?_?

\fB<osfUp>\fP\fB:\fP?\fB<Key>\fP\fBUp\fP

_?_?

.TE

.SS "Changes in the Handling of Shifted Keys"

.PP

In conjunction with MIT X11R5 Patch 24, this version of Motif

introduces a change in the way that keys involving the <Shift>

modifier are processed\&. This change allows the numeric keypad to be

used to generate numbers using the standard X mechanisms\&. Since the

default behavior is now to honor the xmodmap keymap bindings,

translations and virtual key bindings that use <Shift> may behave

differently\&. A common symptom is that unshifted keypad and function

keys (with or without other modifiers) produce the expected results,

but shifted ones do not\&.

.PP

To obtain the old behavior you can remove the shifted interpretation

from problematic keys using the \fBxmodmap\fP utility\&. Each entry in

a \fBxmodmap\fP keymap table contains up to four keysym bindings\&. The

second and fourth keysyms are for shifted keys\&. If an expression

contains only two keysyms, simply remove the second keysym\&. If

an entry contains three or more keysyms, replace the second keysym

with \fBNoSymbol\fP and remove the fourth keysym\&.

.SS "Action Translations"

.PP

The translation table syntax used by Motif is completely specified

in the X11R5 Toolkit Intrinsics Documentation\&. For the complete syntax

description, and for general instructions about writing or modifying a

translation table, please refer to this document\&. A brief summary of the

translation table format, however, is included below\&.

.PP

The syntax is defined as in the binding syntax specification above\&.

Informal descriptions are contained in angle brackets (<>)\&.

.PP

.nf

\f(CWTranslationTable=       [ directive ] { production }

directive       =       ( "#replace" | "#override" | "#augment") "\en"

production      =       lhs ":" rhs "\en"

lhs             =       ( event | keyseq) {"," ( event | keyseq) }

keyseq          =       """ keychar { keychar } """

keychar         =       ( "^" | "$" | "\e\e") <ISO Latin 1 character>

event           =       [ modifier_list ] "<" event_type ">" [ count ] {detail}

modifier_list   =       ( ["!"][":"] { modifier } | "None")

modifier        =       [ "~" ] ( "@" <keysym> | <name from table below>)

count           =       "(" <positive integer> [ "+" ] ")"

rhs             =       { action_name "(" [params] ")" }

params          =       string { "," string }\fR

.fi

.PP

The \fIstring\fP field need not be quoted unless it includes a space

or tab character, or any comma, newline, or parenthesis\&. The entire

list of string values making up the \fIparams\fP field will ba passed

to the named action routine\&.

.PP

The \fIdetails\fP field may be used to specify a keysym that will

identify a particular key event\&. For example, \fB<Key>\fP is the name

of a type of event, but it must be modified by the \fIdetails\fP field

to name a specific event, such as \fB<Key>\fP\fBA\fP\&.

.PP

\fBModifier Names\fP

The modifier list, which may be empty, consists of a list of modifier

keys that must be pressed with the key sequence\&. The modifier keys

may abbreviated with single letters, as in the following list of the

familiar modifiers:

.IP "s" 10

Shift

.IP "c\ or\ ^" 10

Ctrl (Control)

.IP "m\ or\ $" 10

Meta

.IP "a" 10

Alt

.PP

Other modifiers are available, such as "Mod5" and "Button2\&." These

have no abbreviation (although the "Button" modifiers may be

abbreviated in combination with events, as outlined below)\&. If a

modifier list has no entries, and is not "None", it means the position

of the modifier keys is irrelevant\&. If modifiers are listed, the

designated keys must be in the specified position, but the unlisted

modifier keys are irrelevant\&. If the list begins with an exclamation

point (!), however, the unlisted modifiers may not be asserted\&. In

addition, if a modifier name is preceded by a tilde (~), the

corresponding key must \fInot\fP be pressed\&.

.PP

If a modifier list begins with a colon (:), X tries to use the

standard modifiers (Shift and Lock), if present, to map the key event

code into a recognized keysym\&.

.PP

Event Types

These are a few of the recognized event types\&.

.IP "Key or KeyDown" 10

A keyboard key was pressed\&.

.IP "KeyUp" 10

A keyboard key was released\&.

.IP "BtnDown" 10

A mouse button was pressed\&.

.IP "BtnUp" 10

A mouse button was released\&.

.IP "Motion" 10

The mouse pointer moved\&.

.IP "Enter" 10

The pointer entered the widget\&'s window\&.

.IP "Leave" 10

The pointer left the widget\&'s window\&.

.IP "FocusIn" 10

The widget has received focus\&.

.IP "FocusOut" 10

The widget has lost focus\&.

.PP

There are some event abbreviations available\&. For example,

\fB<Btn1Motion>\fP is actually a "Motion" event, modified with the

"Button1" modifier (\fBButton1<Motion>\fP)\&. Similarly, \fB<Btn3Up>\fP

is actually a "BtnUp" event with the "Button3" modifier\&. These

abbreviations are used extensively in the Motif translation

tables\&.

.SH "RELATED"

.PP

\fBxmbind\fP(1)

...\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:16