qbit/xenocara
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Install more manual pages:

Browse Source 
* XKB-Config(7), XKB-Enhancing(7): user-level documentation
for XKB configuration; not perfect, but the best available.
* xtrans(3): a library actively maintained upstream.
* libXmu and libXext: Many libraries are effectively frozen upstream.
According to matthieu@, the documentation of libXmu and libXext
is among the most valuable of those.
Feedback and OK matthieu@.
This commit is contained in:
schwarze 2019-05-10 11:44:39 +00:00
parent 7b04c9060e
commit 042aae5043
16 changed files with 6843 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
distrib/sets/lists/xshare/mi
View File

@ -2106,6 +2106,7 @@
./usr/X11R6/man/man3/XmbufGetVersion.3
./usr/X11R6/man/man3/XmbufGetWindowAttributes.3
./usr/X11R6/man/man3/XmbufQueryExtension.3
./usr/X11R6/man/man3/Xmu.3
./usr/X11R6/man/man3/Xpresent.3
./usr/X11R6/man/man3/Xrandr.3
./usr/X11R6/man/man3/XrmCombineDatabase.3
@ -2973,6 +2974,10 @@
./usr/X11R6/man/man3/gluTessProperty.3
./usr/X11R6/man/man3/gluTessVertex.3
./usr/X11R6/man/man3/gluUnProject.3
./usr/X11R6/man/man3/shapelib.3
./usr/X11R6/man/man3/synclib.3
./usr/X11R6/man/man3/xtest1.3
./usr/X11R6/man/man3/xtrans.3
./usr/X11R6/man/man5/Compose.5
./usr/X11R6/man/man5/XCompose.5
./usr/X11R6/man/man5/cwmrc.5
@ -2980,6 +2985,8 @@
./usr/X11R6/man/man7/Consortium.7
./usr/X11R6/man/man7/Standards.7
./usr/X11R6/man/man7/X.7
./usr/X11R6/man/man7/XKB-Config.7
./usr/X11R6/man/man7/XKB-Enhancing.7
./usr/X11R6/man/man7/XOrgFoundation.7
./usr/X11R6/man/man7/XProjectTeam.7
./usr/X11R6/man/man7/Xsecurity.7

6
doc/xorg-docs/Makefile.bsd-wrapper
View File

@ -1,8 +1,10 @@
# $OpenBSD: Makefile.bsd-wrapper,v 1.5 2019/05/05 23:27:58 schwarze Exp $
# $OpenBSD: Makefile.bsd-wrapper,v 1.6 2019/05/10 11:44:39 schwarze Exp $
CONFIGURE_ARGS += --without-fop --without-xmlto
MDOCS = general/fonts/fonts
MDOCS = general/fonts/fonts \
general/input/XKB-Config \
general/input/XKB-Enhancing
beforeinstall:
.for n in ${MDOCS}

239
doc/xorg-docs/general/input/XKB-Config.7 Normal file
View File

@ -0,0 +1,239 @@
.\" automatically generated with docbook2mdoc XKB-Config.xml
.Dd November 2010
.Dt XKB-CONFIG 7
.Os
.Sh NAME
.Nm XKB-Config
.Nd The XKB Configuration Guide
.Sh ABSTRACT
This document describes how to configure Xorg XKB from a user's point
of view.
It covers basic configuration syntax and gives also a few examples.
.Pp
This version covers Xorg server versions 1.8 and later, used with the
data files from the
.Lk http://www.freedesktop.org/wiki/Software/XKeyboardConfig xkeyboard-config
project.
.Sh OVERVIEW
The XKB configuration is decomposed into a number of components.
Selecting
proper parts and combining them back you can achieve most of the configurations
you might need.
Unless you have a completely atypical keyboard you really don't
need to touch any of the xkb configuration files.
.Pp
Some desktop environments now provide integrated graphical configuration
tools for setting XKB configuration as part of your desktop session.
The
instructions in this document are provided for those without such support,
those who need to configure XKB before the session startup (such as at the
login screen), or those who need to perform more advanced configuration
than those tools provide.
.Sh SELECTING XKB CONFIGURATION
The easiest and the most natural way to specify a keyboard mapping is to use
the
.Ql rules
component.
As its name suggests it describes a number of
general rules to combine all bits and pieces into a valid and useful keyboard
mapping.
All you need to do is to select a suitable rules file and then to
feed it with a few parameters that will adjust the keyboard behaviour to
fulfill your needs.
.Pp
The parameters are:
.Bl -tag -width Ds
.It Fl XkbRules
files of rules to be used for keyboard mapping composition
.It Fl XkbModel
name of the model of your keyboard type
.It Fl XkbLayout
layout(s) you intend to use
.It Fl XkbVariant
variant(s) of the layout you intend to use
.It Fl XkbOptions
extra xkb configuration options
.El
.Pp
The rules file used depends on your system.
The rules files commonly
used with Xorg are provided by the
.Lk http://www.freedesktop.org/wiki/Software/XKeyboardConfig xkeyboard-config
project.
On Linux systems, the
.Pa evdev
rules are most
commonly used, on other systems the
.Pa base
rules
are used.
Some additional rules files exist for historical reasons,
but are no longer widely used.
In general, it's best to simply not
specify the rules file, in order to use the default rules selected
automatically by the X server.
.Pp
For each rules file there is a description file named
.Pa < Ns Ar vendor-rules Ns > . Ns lst ,
for instance
.Pa base.lst
which is located in
the xkb configuration subdirectory
.Pa rules
(for example
.Pa /usr/share/X11/xkb/rules ) .
.Ss Basic Configuration
Let's say you want to configure a PC-style American keyboard with 104
keys as described in
.Pa base.lst .
This can be done
by simply writing several lines from below to a new configuration file
in
.Pa /etc/X11/xorg.conf.d ,
such
as
.Pa /etc/X11/xorg.conf.d/90-custom-kbd.conf .
.Bd -literal
Section "InputClass"
Identifier "keyboard defaults"
MatchIsKeyboard "on"
Option "XkbModel" "pc104"
Option "XkbLayout" "us"
Option "XKbOptions" ""
EndSection
.Ed
.Pp
The values of
.Fl XkbModel
and
.Fl XkbLayout
are
really not surprising.
The
.Fl XkbOptions
has been explicitly set to the empty set of parameters.
The
.Fl XkbVariant
option has been left out.
That means the default variant named
.Ql basic
is loaded.
.Pp
Of course, this can be also done at runtime using the utility
.Nm setxkbmap .
The shell command loading the same keyboard mapping would look like:
.Bd -literal
setxkbmap -model pc104 -layout us -option ""
.Ed
.Pp
The configuration and the shell command would be very analogous
for most other layouts (internationalized mappings).
.Pp
If you wanted to enable the
.Sy Ctrl
.Sy Alt Ns Sy Backspace
sequence to kill
the X server by default, you could create a configuration snippet
.Pa /etc/X11/xorg.conf.d/90-zap.conf
containing:
.Bd -literal
Section "InputClass"
Identifier "keyboard defaults"
MatchIsKeyboard "on"
Option "XKbOptions" "terminate:ctrl_alt_bksp"
EndSection
.Ed
.Pp
This would be equivalent to running the shell command:
.Bd -literal
setxkbmap -option "terminate:ctrl_alt_bksp"
.Ed
.Ss Advanced Configuration
You can use multi-layouts xkb configuration.
What does it mean?
Basically it allows to load up to four different
keyboard layouts at a time.
Each such layout would reside in its
own group.
The groups (unlike complete keyboard remapping) can be
switched very fast from one to another by a combination of keys.
.Pp
Let's say you want to configure your new Logitech cordless desktop
keyboard, you intend to use three different layouts at the same
time - us, czech and german (in this order), and that you are used to
.Sy Alt Ns Sy Shift
combination for switching among them.
.Pp
Then the configuration snippet could look like this:
.Bd -literal
Section "InputClass"
Identifier "Logitech Cordless"
MatchIsKeyboard "on"
Option "XkbModel" "logicordless"
Option "XkbLayout" "us,cz,de"
Option "XKbOptions" "grp:alt_shift_toggle"
EndSection
.Ed
.Pp
Of course, this can be also done at runtime using the utility
.Nm setxkbmap .
The shell command loading the same keyboard mapping would look like:
.Bd -literal
setxkbmap -model logicordless -layout "us,cz,de" \e
-option "grp:alt_shift_toggle"
.Ed
.Ss Even More Advanced Configuration
Okay, let's say you are more demanding.
You do like the example
above but you want it to change a bit.
Let's imagine you want
the czech keyboard mapping to use another variant but basic.
The configuration snippet then changes into:
.Bd -literal
Section "InputClass"
Identifier "Logitech Cordless"
MatchIsKeyboard "on"
Option "XkbModel" "logicordless"
Option "XkbLayout" "us,cz,de"
Option "XkbVariant" ",bksl,"
Option "XKbOptions" "grp:alt_shift_toggle" EndSection
.Ed
.Pp
That seems tricky but it is not.
The logic for settings of variants
is the same as for layouts, that means the first and the third variant
settings are left out (set to
.Ql basic ) ,
the second is set to
.Ql bksl
(a special
variant with an enhanced definition of the backslash key).
.Pp
Analogously, the loading runtime will change to:
.Bd -literal
setxkbmap -model logicordless -layout "us,cz,de" \e
-variant ",bksl," -option "grp:alt_shift_toggle"
.Ed
.Ss Basic Global Options
For a list of available options, with a short description of what they do,
see the section starting with
.Dq Li ! option
in the
.Pa rules/*.lst
files.
.Sh KEYMAP XKB CONFIGURATION
Keymap configuration is the way formerly used to configure xkb.
The
user included a special keymap file which specified the direct xkb
configuration.
This method has been obsoleted by previously described
rules files which are far more flexible and allow simpler and more
intuitive syntax.
It is preserved merely for compatibility reasons and
should be avoided if possible.
.Sh AUTHORS
.An -nosplit
X Version 11, Release 6
.An -split
.An Kamil Toman
.An Ivan U. Pascal

672
doc/xorg-docs/general/input/XKB-Enhancing.7 Normal file
View File

@ -0,0 +1,672 @@
.\" automatically generated with docbook2mdoc XKB-Enhancing.xml
.Dd 25 November 2002
.Dt XKB-ENHANCING 7
.Os
.Sh NAME
.Nm XKB-Enhancing
.Nd How to further enhance XKB configuration
.Sh ABSTRACT
This guide is aimed to relieve one's labour to create a new (internationalized)
keyboard layout.
Unlike other documents this guide accents the keymap developer's point of view.
.Sh OVERVIEW
The developer of a new layout should read the xkb
protocol specification
.Pf ( Lk http://www.x.org/docs/XKB/XKBproto.pdf "The X Keyboard Extension: Protocol Specification" )
at least
to clarify for himself some xkb-specific terms used in this document
and elsewhere in xkb configuration.
Also it shows wise to understand
how the X server and a client digest their keyboard inputs
(with and without xkb).
.Pp
A useful source is also
.Lk http://www.tsu.ru/~pascal/en/xkb "Ivan Pascal's text about xkb configuration"
often referenced throughout this
document.
.Pp
Note that this document covers only enhancements which
are to be made to XFree86 version 4.3 and X11R6.7.0 and above.
.Sh THE BASICS
At the startup (or at later at user's command) X server starts its xkb
keyboard module extension and reads data from a compiled configuration
file.
.Pp
This compiled configuration file is prepared by the
program
.Nm xkbcomp
which behaves altogether as an
ordinary compiler (see
.Ql man xkbcomp ) .
Its input are human readable xkb configuration files which are verified and
then composed into a useful xkb configuration.
Users don't need to mess with
.Nm xkbcomp
themselves, for them it is invisible.
Usually,
it is started upon X server startup.
.Pp
As you probably already know, the xkb configuration consists of five
main modules:
.Bl -tag -width Ds
.It Keycodes
Tables that defines translation from keyboard scan codes into reasonable
symbolic names, maximum, minimum legal keycodes, symbolic aliases and
description of physically present LED-indicators.
The primary sense of
this component is to allow definitions of maps of symbols (see below)
to be independent of physical keyboard scancodes.
There are two main
naming conventions for symbolic names (always four bytes long):
.Bl -bullet
.It
names which express some traditional meaning like
<SPCE> (stands for space bar) or
.It
names which express some relative positioning on a keyboard, for
example <AE01> (an exclamation mark on US keyboards), on
the right there are keys <AE02>, <AE03>
etc.
.El
.It Types
Types describe how the produced key is changed by active modifiers (like
Shift, Control, Alt, ...). There are several predefined types which
cover most of used combinations.
.It Compat
Compatibility component defines internal behaviour of modifiers.
Using
compat component you can assign various actions (elaborately described
in xkb specification) to key events.
This is also the place where
LED-indicators behaviour is defined.
.It Symbols
For i18n purposes, this is the most important table.
It defines what
values (=symbols) are assigned to what keycodes (represented by their
symbolic name, see above). There may be defined more than one value
for each key and then it depends on a key type and on modifiers state
(respective compat component) which value will be the resulting one.
.It Geometry
Geometry files aren't used by xkb itself but they may be used by some
external programs to depict a keyboard image.
.El
.Pp
All these components have the files located in xkb configuration tree
in subdirectories with the same names (usually in
.Pa /usr/lib/X11/xkb ) .
.Sh ENHANCING XKB CONFIGURATION
Most of xkb enhancements concerns a need to define new output symbols
for the some input key events.
In other words, a need to define a new
symbol map (for a new language, standard or just to feel more comfortable
when typing text).
.Pp
What do you need to do?
Generally, you have to define following things:
.Bl -bullet
.It
the map of symbols itself
.It
the rules to allow users to select the new mapping
.It
the description of the new layout
.El
.Pp
First of all, it is good to go through existing layouts and to examine
them if there is something you could easily adjust to fit your needs.
Even if there is nothing similar you may get some ideas about basic
concepts and used tricks.
.Ss Levels And Groups
Since XFree86 4.3.0 and X11R6.7.0 you can use
.Em multi-layout
concept of xkb
configuration.
Though it is still in boundaries of xkb protocol and general ideas, the
keymap designer must obey new rules when creating new maps.
In exchange
we get a more powerful and cleaner configuration system.
.Pp
Remember that it is the application which must decide which symbol
matches which keycode according to effective modifier state.
The X server
itself sends only an input event message to.
Of course, usually
the general interpretation is processed by Xlib, Xaw, Motif, Qt, Gtk
and similar libraries.
The X server only supplies its mapping table
(usually upon an application startup).
.Pp
You can think of the X server's symbol table as of a irregular table where each
keycode has its row and where each combination of modifiers determines exactly
one column.
The resulting cell then gives the proper symbolic value.
Not all
keycodes need to bind different values for different combination of modifiers.
<ENTER> key, for instance, usually doesn't depend on any
modifiers so it its row has only one column defined.
.Pp
Note that in XKB there is no prior assumption that certain modifiers are bound
to certain columns.
By editing proper files (see
.Sx Key_Types )
this mapping can be changed as well.
.Pp
Unlike the original X protocol the XKB approach is far more
flexible.
It is comfortable to add one additional XKB term - group.
You can
think of a group as of a vector of columns per each keycode (naturally the
dimension of this vector may differ for different keycodes). What is it good
for?
The group is not very useful unless you intend to use more than one
logically different set of symbols (like more than one alphabet) defined in a
single mapping table.
But then, the group has a natural meaning - each symbol
set has its own group and changing it means selecting a different one.
XKB approach allows up to four different groups.
The columns inside each group
are called (shift) levels.
The X server knows the current group and reports it
together with modifier set and with a keycode in key events.
.Pp
To sum it up:
.Bl -bullet
.It
for each keycode XKB keyboard map contains up to four one-dimensional
tables - groups (logically different symbol sets)
.It
for each group of a keycode XKB keyboard map contains some columns
- shift levels (values reached by combinations of Shift, Ctrl, Alt, ...
modifiers)
.It
different keycodes can have different number of groups
.It
different groups of one keycode can have different number of shift levels
.It
the current group number is tracked by X server
.El
.Pp
It is clear that if you sanely define levels, groups and sanely bind
modifiers and associated actions you can have simultaneously loaded up to
four different symbol sets where each of them would reside in its own group.
.Pp
The multi-layout concept provides a facility to manipulate xkb groups
and symbol definitions in a way that allows almost arbitrary composition of
predefined symbol tables.
To keep it fully functional you have to:
.Bl -bullet
.It
define all symbols only in the first group
.It
(re)define any modifiers with extra care to avoid strange (anisometric)
behaviour
.El
.Sh DEFINING NEW LAYOUTS
See
.Lk http://www.tsu.ru/~pascal/en/xkb/internals.html "Some Words About XKB internals"
for explanation of used xkb terms and problems
addressed by XKB extension.
.Pp
See
.Lk http://www.tsu.ru/~pascal/en/xkb/gram-common.html "Common notes about XKB configuration files language"
for more precise explanation of
syntax of xkb configuration files.
.Ss Predefined XKB Symbol Sets
If you are about to define some European symbol map extension, you might
want to use on of four predefined latin alphabet layouts.
.Pp
Okay, let's assume you want extend an existing keymap and you want to override
a few keys.
Let's take a simple U.K. keyboard as an example (defined in
.Pa pc/gb ) :
.Bd -literal
partial default alphanumeric_keys
xkb_symbols "basic" {
include "pc/latin"
name[Group1]="Great Britain";
key \[u003C]AE02\[u003E] { [ 2, quotedbl, twosuperior, oneeighth ] };
key \[u003C]AE03\[u003E] { [ 3, sterling, threesuperior, sterling ] };
key \[u003C]AC11\[u003E] { [apostrophe, at, dead_circumflex, dead_caron] };
key \[u003C]TLDE\[u003E] { [ grave, notsign, bar, bar ] };
key \[u003C]BKSL\[u003E] { [numbersign, asciitilde, dead_grave, dead_breve ] };
key \[u003C]RALT\[u003E] { type[Group1]="TWO_LEVEL",
[ ISO_Level3_Shift, Multi_key ] };
modifier_map Mod5 { \[u003C]RALT\[u003E] };
};
.Ed
.Pp
It defines a new layout in
.Ql basic
variant as an extension of common
latin alphabet layout.
The layout (symbol set) name is set to "Great Britain".
Then there are redefinitions of a few keycodes and a modifiers binding.
As you
can see the number of shift levels is the same for
<AE02>, <AE03>,
<AC11>, <TLDE> and
<BKSL> keys but it differs from number of shift
levels of <RALT>.
.Pp
Note that the <RALT> key itself is a binding key for Mod5 and
that it
serves like a shift modifier for LevelThree, together with Shift
as a multi-key.
It is a good habit to respect this rule in a new similar
layout.
.Pp
Okay, you could now define more variants of your new layout besides
.Ql basic
simply by including (augmenting/overriding/...)
the basic
definition and altering what may be needed.
.Ss Key Types
The differences in the number of columns (shift levels) are caused by
a different types of keys (see the types definition in section basics). Most
keycodes have implicitly set the keytype in the included
.Pa pc/latin
file to
.Dq Li FOUR_LEVEL_ALPHABETIC .
The only exception is
<RALT> keycode which is explicitly set
.Dq Li TWO_LEVEL
keytype.
.Pp
All those names refer to pre-defined shift level schemes.
Usually you can
choose a suitable shift level scheme from
.Ql default
types scheme list
in proper xkb component's subdirectory.
.Pp
The most used schemes are:
.Bl -tag -width Ds
.It ONE_LEVEL
The key does not depend on any modifiers.
The symbol from first level
is always chosen.
.It TWO_LEVEL
The key uses a modifier Shift and may have two possible values.
The second level may be chosen by Shift modifier.
If Lock modifier
(usually Caps-lock) applies the symbol is further processed using
system-specific capitalization rules.
If both Shift+Lock modifier apply the
symbol from the second level is taken and capitalization rules are applied
(and usually have no effect).
.It ALPHABETIC
The key uses modifiers Shift and Lock.
It may have two possible
values.
The second level may be chosen by Shift modifier.
When Lock
modifier applies, the symbol from the first level is taken and further
processed using system-specific capitalization rules.
If both Shift+Lock
modifier apply the symbol from the first level is taken and no
capitalization rules applied.
This is often called shift-cancels-caps
behaviour.
.It THREE_LEVEL
Is the same as TWO_LEVEL but it considers an extra modifier -
LevelThree which can be used to gain the symbol value from the third
level.
If both Shift+LevelThree modifiers apply the value from the third
level is also taken.
As in TWO_LEVEL, the Lock modifier doesn't influence
the resulting level.
Only Shift and LevelThree are taken into that
consideration.
If the Lock modifier is active capitalization rules
are applied on the resulting symbol.
.It FOUR_LEVEL
Is the same as THREE_LEVEL but unlike LEVEL_THREE if both Shift+LevelThree
modifiers apply the symbol is taken from the fourth level.
.It FOUR_LEVEL_ALPHABETIC
Is similar to FOUR_LEVEL but also defines shift-cancels-caps behaviour
as in ALPHABETIC.
If Lock+LevelThree apply the symbol from the
third level is taken and the capitalization rules are applied.
If Lock+Shift+LevelThree apply the symbol from the third level is taken
and no capitalization rules are applied.
.It KEYPAD
As the name suggest this scheme is primarily used for numeric keypads.
The scheme considers two modifiers - Shift and NumLock.
If none
of modifiers applies the symbol from the first level is taken.
If either
Shift or NumLock modifiers apply the symbol from the second level is taken.
If both Shift+NumLock modifiers apply the symbol from the first level
is taken.
Again, shift-cancels-caps variant.
.It FOUR_LEVEL_KEYPAD
Is similar to KEYPAD scheme but considers also LevelThree modifier.
If LevelThree modifier applies the symbol from the third level is taken.
If Shift+LevelThree or NumLock+LevelThree apply the symbol from the fourth
level is taken.
If all Shift+NumLock+LevelThree modifiers apply the symbol
from the third level is taken.
This also, shift-cancels-caps variant.
.El
.Pp
Besides that, there are several schemes for special purposes:
.Bl -tag -width Ds
.It PC_BREAK
It is similar to TWO_LEVEL scheme but it considers the Control
modifier rather than Shift.
That means, the symbol from the second level
is chosen by Control rather than by Shift.
.It PC_SYSRQ
It is similar to TWO_LEVEL scheme but it considers the Alt modifier rather
than Shift.
That means, the symbol from the second level
is chosen by Alt rather than by Shift.
.It CTRL+ALT
The key uses modifiers Alt and Control.
It may have two possible
values.
If only one modifier (Alt or Control) applies the symbol
from the first level is chosen.
Only if both Alt+Control modifiers apply
the symbol from the second level is chosen.
.It SHIFT+ALT
The key uses modifiers Shift and Alt.
It may have two possible values.
If only one modifier (Alt or Shift) applies the symbol
from the first level is chosen.
Only if both Alt+Shift modifiers apply
the symbol from the second level is chosen.
.El
.Pp
If needed, special
.Ql caps
schemes may be used.
They redefine the standard behaviour of all
.Ql *ALPHABETIC
types.
The layouts (maps of
symbols) with keys defined in respective types then automatically change
their behaviour accordingly.
Possible redefinitions are:
.Bl -bullet
.It
internal
.It
internal_nocancel
.It
shift
.It
shift_nocancel
.El
.Pp
None of these schemes should be used directly.
They are defined merely
for
.Ql 'caps:'
xkb options (used to globally
change the layouts behaviour).
.Pp
Don't alter any of existing key types.
If you need a different behaviour
create a new one.
.Pp
.Sy More \&On Definitions \&Of Types
.Pp
When the XKB software deals with a separate type description it gets
a complete list of modifiers that should be taken into account from the
.Ql 'modifiers=<list of modifiers>'
list and expects that a set
of
.Ql 'map[<combination of modifiers>]=<list of modifiers>'
instructions that contain the mapping for each combination of modifiers
mentioned in that list.
Modifiers that are not explicitly listed are NOT taken
into account
when the resulting shift level is computed.
If some combination is omitted the program (subroutine) should choose the first
level for this combination (a quite reasonable behavior).
.Pp
Lets consider an example with two modifiers
.Sy ModOne
and
.Sy ModTwo :
.Bd -literal
type "..." {
modifiers = ModOne+ModTwo;
map[None] = Level1;
map[ModOne] = Level2;
};
.Ed
.Pp
In this case the map statements for
.Sy ModTwo
only and
.Sy ModOne+ModTwo
are omitted.
It means that if
the
.Sy ModTwo
is active the subroutine can't found
explicit mapping for such combination an will use
the
.Em default level
i.e. Level1.
.Pp
But in the case the type described as:
.Bd -literal
type "..." {
modifiers = ModOne;
map[None] = Level1;
map[ModOne] = Level2;
};
.Ed
.Pp
the ModTwo will not be taken into account and the resulting level depends on
the ModOne state only.
That means, ModTwo alone produces the Level1 but the
combination ModOne+ModTwo produces the Level2 as well as ModOne alone.
.Pp
What does it mean if the second modifier is the Lock?
It means that in
the first case (the Lock itself is included in the list of modifiers but
combinations with this modifier aren't mentioned in the map statements)
the internal capitalization rules will be applied to the symbol from the first
level.
But in the second case the capitalization will be applied to the symbol
chosen accordingly to the first modifier - and this can be the symbol from the
first as well as from the second level.
.Pp
Usually, all modifiers introduced in
.Ql 'modifiers=<list of modifiers>'
list are used for shift level calculation and then
discarded.
Sometimes this is not desirable.
If you want to use a modifier
for shift level calculation but you don't want to discard it, you may
list in
.Pf ' Ql preserve[<combination of modifiers>]=<list of modifiers>' .
That means, for a given combination all listed modifiers
will be preserved.
If the Lock modifier is preserved then the resulting
symbol is passed to internal capitalization routine regardless whether
it has been used for a shift level calculation or not.
.Pp
Any key type description can use both real and virtual modifiers.
Since real
modifiers always have standard names it is not necessary to explicitly declare
them.
Virtual modifiers can have arbitrary names and can be declared (prior
using them) directly in key type definition:
.Bd -literal
virtual_modifiers <comma-separated list of modifiers> ;
.Ed
.Pp
as seen in for example
.Ql basic ,
.Ql pc
or
.Ql mousekeys
key
type definitions.
.Ss Rules
Once you are finished with your symbol map you need to add it
to rules file.
The rules file describes how all the
five basic keycodes, types, compat, symbols and geometry components
should be composed to give a sensible resulting xkb configuration.
.Pp
The main advantage of rules over formerly used keymaps is a possibility
to simply parameterize (once) fixed patterns of configurations and thus
to elegantly allow substitutions of various local configurations
into predefined templates.
.Pp
A pattern in a rules file (often located in
.Pa /usr/lib/X11/xkb/rules )
can be parameterized with four other arguments:
.Ql Model ,
.Ql Layout ,
.Ql Variant
and
.Ql Options .
For most cases parameters
.Ql model
and
.Ql layout
should
be sufficient for choosing a functional keyboard mapping.
.Pp
The rules file itself is composed of pattern lines and lines with rules.
The
pattern line starts with an exclamation mark
.Pf (' Ql ! Ns ')
and describes how will the xkb interpret the following lines (rules). A sample
rules file looks like this:
.Bd -literal
! model = keycodes
macintosh_old = macintosh
...
* = xorg
! model = symbols
hp = +inet(%m)
microsoftpro = +inet(%m)
geniuscomfy = +inet(%m)
! model layout[1] = symbols
macintosh us = macintosh/us%(v[1])
* * = pc/pc(%m)+pc/%l[1]%(v[1])
! model layout[2] = symbols
macintosh us = +macintosh/us[2]%(v[2]):2
* * = +pc/%l[2]%(v[2]):2
! option = types
caps:internal = +caps(internal)
caps:internal_nocancel = +caps(internal_nocancel)
.Ed
.Pp
Each rule defines what certain combination of values on the left side
of equal sign
.Pf (' Ql = Ns ')
results in.
For
example a (keyboard) model
.Ql macintosh_old
instructs xkb to take definitions of keycodes from
file
.Pa keycodes/macintosh
while the rest
of models (represented by a wild card
.Pf ' Ql * Ns ')
instructs it to take them from file
.Pa keycodes/xorg .
The wild card represents all possible values on the left side which
were not found in any of the previous rules.
The more specialized
(more complete) rules have higher precedence than general ones,
i.e. the more general rules supply reasonable default values.
.Pp
As you can see some lines contain substitution parameters - the parameters
preceded by the percent sign
.Pf (' Ql % Ns ').
The first alphabetical character after the percent sign expands to the
value which has been found on the left side.
For
example
.Ql +%l%(v)
expands
into
.Ql +cz(bksl)
if the respective values
on the left side were
.Ql cz
layout in
its
.Ql bksl
variant.
More, if the layout
resp.
variant parameter is followed by a pair of brackets
.Pf (' Ql [ Ns ',
.Pf ' Ql ] Ns ')
it means that xkb should
.Em place the layout resp. variant into specified xkb group .
If the brackets are omitted the first
group is the default value.
.Pp
So the second block of rules enhances symbol definitions for some particular
keyboard models with extra keys (for internet, multimedia, ...) . Other models
are left intact.
Similarly, the last block overrides some key type definitions,
so the common global behaviour ''shift cancels caps'' or ''shift doesn't cancel
caps'' can be selected.
The rest of rules produces special symbols for each
variant
.Ql us
layout of
.Ql macintosh
keyboard and standard pc
symbols in appropriate variants as a default.
.Ss Descriptive Files of Rules
Now you just need to add a detailed description to
.Pa <rules>.xml
description file so the other users (and external programs which often parse
this file) know what is your work about.
.Pp
.Sy Old Descriptive Files
.Pp
The formerly used descriptive files were named
.Pa <rules>.lst
Its structure is very simple and quite self descriptive but such simplicity
had also some cavities, for example there was no way how to describe local
variants of layouts and there were problems with the localization of
descriptions.
To preserve compatibility with some older programs,
new XML descriptive files can be converted to old format '.lst'.
.Pp
For each parameter of rules file should be described its meaning.
For the rules
file described above the
.Pa .lst
file could look like:
.Bd -literal
! model
pc104 Generic 104-key PC
microsoft Microsoft Natural
pc98 PC-98xx Series
macintosh Original Macintosh
...
! layout
us U.S. English
cz Czech
de German
...
! option
caps:internal uses internal capitalization. Shift cancels Caps
caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
.Ed
.Pp
And that should be it.
Enjoy creating your own xkb mapping.
.Sh AUTHORS
.An -nosplit
X Version 11, Release 6
.An -split
.An Kamil Toman
.An Ivan U. Pascal

1
doc/xorg-docs/general/input/defs.ent Normal file
View File

@ -0,0 +1 @@
<!ENTITY fullrelvers "6">

20
lib/libXext/Makefile.bsd-wrapper
View File

@ -1,7 +1,25 @@
# $OpenBSD: Makefile.bsd-wrapper,v 1.5 2013/08/13 07:07:15 guenther Exp $
# $OpenBSD: Makefile.bsd-wrapper,v 1.6 2019/05/10 11:44:39 schwarze Exp $
CONFIGURE_ARGS= --without-xmlto --without-fop --without-xsltproc
SHARED_LIBS= Xext 13.0
MDOCS = specs/shapelib \
specs/synclib \
specs/xtest1
beforeinstall:
.for n in ${MDOCS}
${INSTALL} ${INSTALL_COPY} -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} \
${.CURDIR}/${n}.3 ${DESTDIR}${MANDIR}3
.endfor
# maintainer target, not used duing build or install
mdoc:
.for n in ${MDOCS}
docbook2mdoc -s 3 ${.CURDIR}/${n}.xml > ${.CURDIR}/${n}.3
.endfor
.PHONY: mdoc
.include <bsd.xorg.mk>

1
lib/libXext/specs/defs.ent Normal file
View File

@ -0,0 +1 @@
<!ENTITY fullrelvers "6">

493
lib/libXext/specs/shapelib.3 Normal file
View File

@ -0,0 +1,493 @@
.\" automatically generated with docbook2mdoc shapelib.xml
.Dd $Mdocdate: May 10 2019 $
.Dt SHAPELIB 3
.Os
.Sh NAME
.Nm shapelib
.Nd X Nonrectangular Window Shape Extension Library
.Sh OVERVIEW
This extension provides arbitrary window and border shapes within
the X11 protocol.
.Pp
The restriction of rectangular windows within the X protocol is a significant
limitation in the implementation of many styles of user interface.
For
example, many transient windows would like to display a
\(lqdrop shadow\(rq to give the illusion of 3 dimensions.
As
another example, some user interface style guides call for buttons with
rounded corners; the full simulation of a nonrectangular shape,
particularly with respect to event distribution and cursor shape, is not
possible within the core X protocol.
As a final example, round clocks
and nonrectangular icons are desirable visual addition to the desktop.
.Pp
This extension provides mechanisms for changing the visible shape of a
window to an arbitrary, possibly disjoint, nonrectangular form.
The intent
of the extension is to supplement the existing semantics, not replace them.
In particular, it is desirable for clients that are unaware of the
extension to still be able to cope reasonably with shaped windows.
For
example, window managers should still be able to negotiate screen
real estate in rectangular pieces.
Toward this end, any shape specified for
a window is clipped by the bounding rectangle for the window as specified by
the window's geometry in the core protocol.
An expected convention would be
that client programs expand their shape to fill the area offered by the
window manager.
.Sh DESCRIPTION
Each window (even with no shapes specified) is defined by two regions: the
.Lk shapelib "bounding region"
.Pq bounding_region
and the
.Lk shapelib "clip region"
.Pq clip_region .
The bounding region is the
area of the parent window that the window will occupy (including border).
The clip region is the subset of the bounding region that is available for
subwindows and graphics.
The area between the bounding region and the
clip region is defined to be the border of the window.
.Pp
A nonshaped window will have a bounding region that is a rectangle spanning
the window, including its border; the clip region will be a rectangle
filling the inside dimensions (not including the border). In this document,
these areas are referred to as the
.Lk shapelib "default bounding region"
.Pq default_bounding_region
and the
.Lk shapelib "default clip region"
.Pq default_clip_region .
For a window with
inside size of
.Em width
by
.Em height
and border width
.Em bwidth ,
the default bounding and clip
regions are the rectangles (relative to the window origin):
.Bd -unfilled
bounding.x = \c
.Pf - Em bwidth
bounding.y = \c
.Pf - Em bwidth
bounding.width = \c
.Em width No + 2 * Em bwidth
bounding.height = \c
.Em height No + 2 * Em bwidth
clip.x = 0
clip.y = 0
clip.width = \c
.Em width
clip.height = \c
.Em height
.Ed
.Pp
This extension allows a client to modify either or both of the bounding or
clip regions by specifying new regions that combine with the default
regions.
These new regions are called the
.Lk shapelib "client bounding region"
.Pq client_bounding_region
and the
.Lk shapelib "client clip region"
.Pq client_clip_region .
They are specified
relative to the origin of the window and are always defined by offsets
relative to the window origin (that is, region adjustments are not
required when the window is moved). Three mechanisms for specifying
regions are provided: a list of rectangles, a bitmap, and an existing
bounding or clip region from a window.
This is modeled on the specification
of regions in graphics contexts in the core protocol and allows a variety
of different uses of the extension.
.Pp
When using an existing window shape as an operand in specifying a new shape,
the client region is used, unless none has been set, in which case the
default region is used instead.
.Pp
The
.Lk shapelib "effective bounding region"
.Pq effective_bounding_region
of a window is
defined to be the intersection of the client bounding region with the default
bounding region.
Any portion of the client bounding region that is not
included in the default bounding region will not be included in the
effective bounding region on the screen.
This means that window managers
(or other geometry managers) used to dealing with rectangular client windows
will be able to constrain the client to a rectangular area of the screen.
.Pp
Construction of the effective bounding region is dynamic; the client bounding
region is not mutated to obtain the effective bounding region.
If a client
bounding region is specified that extends beyond the current default bounding
region, and the window is later enlarged, the effective bounding region will
be enlarged to include more of the client bounding region.
.Pp
The
.Lk shapelib "effective clip region"
.Pq effective_clip_region
of a window is
defined to be the intersection of the client clip region with both the
default clip region and the client bounding region.
Any portion of the
client clip region that is not included in both the default clip region
and the client bounding region will not be included in the effective clip
region on the screen.
.Pp
Construction of the effective clip region is dynamic; the client clip region is
not mutated to obtain the effective clip region.
If a client clip region is
specified that extends beyond the current default clip region and the
window or its bounding region is later enlarged, the effective clip region will
be enlarged to include more of the client clip region if it is included in
the effective bounding region.
.Pp
The border of a window is defined to be the difference between the effective
bounding region and the effective clip region.
If this region is empty, no
border is displayed.
If this region is nonempty, the border is filled
using the border-tile or border-pixel of the window as specified in the core
protocol.
Note that a window with a nonzero border width will never be able
to draw beyond the default clip region of the window.
Also note that a zero
border width does not prevent a window from having a border, since the clip
shape can still be made smaller than the bounding shape.
.Pp
All output to the window and visible regions of any subwindows will be
clipped to the effective clip region.
The server must not retain window
contents beyond the effective bounding region with backing store.
The window's
origin (for graphics operations, background tiling, and subwindow placement)
is not affected by the existence of a bounding region or clip region.
.Pp
Areas that are inside the default bounding region but outside the effective
bounding region are not part of the window; these areas of the screen will
be occupied by other windows.
Input events that occur within the default
bounding region but outside the effective bounding region will be delivered as
if the window was not occluding the event position.
Events that occur in
a nonrectangular border of a window will be delivered to that window, just
as for events that occur in a normal rectangular border.
.Pp
An
.Lk libX11 InputOnly
.Pq glossary:InputOnly_window
window can have its bounding region set, but it is a
.Lk libX11 Match
.Pq BadMatch
error to attempt to set a clip region on an
.Lk libX11 InputOnly
.Pq glossary:InputOnly_window
window or to specify its clip region as a source to a request
in this extension.
.Pp
The server must accept changes to the clip region of a root window, but
the server is permitted to ignore requested changes to the bounding region
of a root window.
If the server accepts bounding region changes, the contents
of the screen outside the bounding region are implementation dependent.
.Sh C LANGUAGE BINDING
The C functions provide direct access to the protocol and add no additional
semantics.
.Pp
The include file for this extension is
.Pf < Dv X11/extensions/shape.h Ns > .
The defined shape kinds are
.Fn ShapeBounding
and
.Fn ShapeClip
The defined region operations are
.Fn ShapeSet
.Fn ShapeUnion
.Fn ShapeIntersect
.Fn ShapeSubtract
and
.Fn ShapeInvert .
.Pp
.Ft Bool
.Fo XShapeQueryExtension
.Fa "Display *display"
.Fa "int *event_base"
.Fa "int *error_base"
.Fc
.Pp
.Fn XShapeQueryExtension
returns
.Fn True
if the specified display supports the SHAPE extension else
.Fn False
If the extension is supported, *event_base is set to the event number for
.Fn ShapeNotify
events and *error_base would be set to the error number for the first error for
this extension.
Because no errors are defined for this version of
the extension, the value returned here is not defined (nor useful).
.Pp
.Ft Status
.Fo XShapeQueryVersion
.Fa "Display *display"
.Fa "int *major_version"
.Fa "int *minor_version"
.Fc
.Pp
If the extension is supported,
.Fn XShapeQueryVersion
sets the major and minor version numbers of the
extension supported by the display and returns a nonzero value.
Otherwise, the arguments are not set and zero is returned.
.Pp
.Fo XShapeCombineRegion
.Fa "Display *display"
.Fa "Window dest"
.Fa "int dest_kind"
.Fa "int x_off"
.Fa "int y_off"
.Fa "int region"
.Fa "int op"
.Fa "REGION *region"
.Fc
.Pp
.Fn XShapeCombineRegion
converts the specified region into a list of rectangles and calls
.Fn XShapeCombineRectangles
.Pp
.Fo XShapeCombineRectangles
.Fa "Display *display"
.Fa "Window dest"
.Fa "int dest_kind"
.Fa "int x_off"
.Fa "int y_off"
.Fa "XRectangle *rectangles"
.Fa "int n_rects"
.Fa "int op"
.Fa "int ordering"
.Fc
.Pp
If the extension is supported,
.Fn XShapeCombineRectangles
performs a
.Fn ShapeRectangles
operation; otherwise, the request is ignored.
.Pp
.Fo XShapeCombineMask
.Fa "Display *display"
.Fa "int dest"
.Fa "int dest_kind"
.Fa "int x_off"
.Fa "int y_off"
.Fa "Pixmap src"
.Fa "int op"
.Fc
.Pp
If the extension is supported,
.Fn XShapeCombineMask
performs a
.Fn ShapeMask
operation; otherwise, the request is ignored.
.Pp
.Fo XShapeCombineShape
.Fa "Display *display"
.Fa "Window dest"
.Fa "int dest_kind"
.Fa "int x_off"
.Fa "int y_off"
.Fa "Window src"
.Fa "int src_kind"
.Fa "int op"
.Fc
.Pp
If the extension is supported,
.Fn XShapeCombineShape
performs a
.Fn ShapeCombine
operation; otherwise, the request is ignored.
.Pp
.Fo XShapeOffsetShape
.Fa display
.Fa dest
.Fa dest_kind
.Fa x_off
.Fa y_off
.Fc
.Pp
If the extension is supported,
.Fn XShapeOffsetShape
performs a
.Fn ShapeOffset
operation; otherwise, the request is ignored.
.Pp
.Ft Status
.Fo XShapeQueryExtents
.Fa "Display *display"
.Fa "Window window"
.Fa "Bool *bounding_shaped"
.Fa "int *x_bounding"
.Fa "int *y_bounding"
.Fa "unsigned int *w_bounding"
.Fa "unsigned int *h_bounding"
.Fa "Bool *clip_shaped"
.Fa "int *x_clip"
.Fa "int *y_clip"
.Fa "unsigned int *w_clip"
.Fa "unsigned int *h_clip"
.Fc
.Pp
If the extension is supported,
.Fn XShapeQueryExtents
sets x_bounding, y_bounding, w_bounding, h_bounding to the extents of the
bounding shape and sets x_clip, y_clip, w_clip, h_clip to the extents of
the clip shape.
For unspecified client regions, the extents of the
corresponding default region are used.
.Pp
If the extension is supported, a nonzero value is returned; otherwise,
zero is returned.
.Pp
.Fo XShapeSelectInput
.Fa "Display *display"
.Fa "Window window"
.Fa "unsigned long mask"
.Fc
.Pp
To make this extension more compatible with other interfaces, although
only one event type can be selected via the extension,
.Fn XShapeSelectInput
provides a general mechanism similar to the standard Xlib binding for
window events.
A mask value has been defined,
.Fn ShapeNotifyMask
that is the only valid bit in mask that may be specified.
The structure for this event is defined as follows:
.Bd -unfilled
typedef struct {
int type; /* of event */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came frome a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* window of event */
int kind; /* ShapeBounding or ShapeClip */
int x, y; /* extents of new region */
unsigned width, height;
Time time; /* server timestamp when region changed */
Bool shaped; /* true if the region exists */
} XShapeEvent;
.Ed
.Pp
.Ft unsigned long
.Fo XShapeInputSelected
.Fa "Display *display"
.Fa "Window window"
.Fc
.Pp
.Fn XShapeInputSelected
returns the current input mask for extension events on the specified
window; the value returned if
.Fn ShapeNotify
is selected for is
.Fn ShapeNotifyMask
otherwise, it returns zero.
If the extension is not supported, it returns zero.
.Pp
.Ft XRectangle
.Fo *XShapeGetRectangles
.Fa "Display *display"
.Fa "Window window"
.Fa "int kind"
.Fa "int *count"
.Fa "int *ordering"
.Fc
.Pp
If the extension is not supported,
.Fn XShapeGetRectangles
returns NULL.
Otherwise, it returns a list of rectangles that describe the
region specified by kind.
.Bl -tag -width Ds
.It Em bounding region
The area of the parent window that this window will occupy.
This area is divided into two parts: the border and the interior.
.It Em clip region
The interior of the window, as a subset of the bounding
region.
This region describes the area that will be painted with the
window background when the window is cleared, will contain all graphics
output to the window, and will clip any subwindows.
.It Em default bounding region
The rectangular area, as described by the core protocol
window size, that covers the interior of the window and its border.
.It Em default clip region
The rectangular area, as described by the core protocol
window size, that covers the interior of the window and excludes the border.
.It Em client bounding region
The region associated with a window that is directly
modified via this extension when specified by
.Fn ShapeBounding
This region is used in conjunction with the default bounding region
to produce the effective bounding region.
.It Em client clip region
The region associated with a window that is directly
modified via this extension when specified by
.Fn ShapeClip
This region is used in conjunction with the default clip region
and the client bounding region to produce the effective clip region.
.It Em effective bounding region
The actual shape of the window on the screen, including
border and interior (but excluding the effects of overlapping windows).
When a window has a client bounding region, the effective bounding region
is the intersection of the default bounding region and the client bounding
region.
Otherwise, the effective bounding region is the same as the
default bounding region.
.It Em effective clip region
The actual shape of the interior of the window on the
screen (excluding the effects of overlapping windows). When a window
has a client clip region or a client bounding region, the effective
clip region is the intersection of the default clip region, the client
clip region (if any) and the client bounding region (if any). Otherwise,
the effective clip region is the same as the default clip region.
.El
.Sh AUTHORS
.An -nosplit
.Sy X Consortium Standard
.Pp
X Version 11, Release 6
Version 1.0
.An -split
.An Keith Packard ,
MIT X Consortium
Copyright \(co 1989X Consortium
.Ss Legal Notice
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files
(the \(lqSoftware\(rq), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and
to permit persons to whom the Software is furnished to do so, subject to
the following conditions:
.Pp
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
.Pp
THE SOFTWARE IS PROVIDED \(lqAS IS\(rq, WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
.Pp
Except as contained in this notice, the name of the X Consortium shall not be
used in advertising or otherwise to promote the sale, use or other dealings
in this Software without prior written authorization from the X Consortium.
.Pp
X Window System is a trademark of The OpenGroup.

740
lib/libXext/specs/synclib.3 Normal file
View File

@ -0,0 +1,740 @@
.\" automatically generated with docbook2mdoc synclib.xml
.Dd $Mdocdate: May 10 2019 $
.Dt SYNCLIB 3
.Os
.Sh NAME
.Nm synclib
.Nd X Synchronization Extension Library
.Sh SYNCHRONIZATION PROTOCOL
The core X protocol makes no guarantees about the relative order of
execution of requests for different clients.
This means that any
synchronization between clients must be done at the client level in an
operating system-dependent and network-dependent manner.
Even if there
was an accepted standard for such synchronization, the use of a network
introduces unpredictable delays between the synchronization of the clients and
the delivery of the resulting requests to the X server.
.Pp
The core X protocol also makes no guarantees about the time at which
requests are executed, which means that all clients with real-time constraints
must implement their timing on the host computer.
Any such timings are
subject to error introduced by delays within the operating system and
network and are inefficient because of the need for round-trip requests that
keep the client and server synchronized.
.Pp
The synchronization extension provides primitives that allow synchronization
between clients to take place entirely within the X server.
This removes any
error introduced by the network and makes it possible to synchronize clients
on different hosts running different operating systems.
This is important for
multimedia applications, where audio, video, and graphics data streams are
being synchronized.
The extension also provides internal timers within the X
server to which client requests can be synchronized.
This allows simple
animation applications to be implemented without any round-trip requests
and makes best use of buffering within the client, network, and server.
.Ss Description
The mechanism used by this extension for synchronization within the X server
is to block the processing of requests from a client until a specific
synchronization condition occurs.
When the condition occurs, the client is
released and processing of requests continues.
Multiple clients may block on
the same condition to give inter-client synchronization.
Alternatively, a single
client may block on a condition such as an animation frame marker.
.Pp
The extension adds
.Fn Counter
and
.Fn Alarm
to the set of resources managed by
the server.
A counter has a 64-bit integer value that may be increased or
decreased by client requests or by the server internally.
A client can
block by sending an
.Fn Await
request that waits until
one of a set of synchronization conditions, called TRIGGERs, becomes TRUE.
.Pp
The
.Fn CreateCounter
request allows a client to create
a
.Fn Counter
that can be changed by explicit
.Fn SetCounter
and
.Fn ChangeCounter
requests.
These can be used to implement synchronization between
different clients.
.Pp
There are some counters, called
.Fn System Counters ,
that are changed by the server internally rather than by client
requests.
The effect of any change to a system counter is not visible
until the server has finished processing the current request.
In other
words, system counters are apparently updated in the gaps between the
execution of requests rather than during the actual execution of a
request.
The extension provides a system counter that advances with the
server time as defined by the core protocol, and it may also provide
counters that advance with the real-world time or that change each
time the CRT screen is refreshed.
Other extensions may provide their own
extension-specific system counters.
.Pp
The extension provides an
.Fn Alarm
mechanism that allows clients to receive an
event on a regular basis when a particular counter is changed.
.Sh C LANGUAGE BINDING
The C routines provide direct access to the protocol and add no additional
semantics.
.Pp
The include file for this extension is <X11/extensions/sync.h>.
Most of the names in the language binding are derived from the protocol
names by prepending XSync to the protocol name and changing the
capitalization.
.Ss C Functions
Most of the following functions generate SYNC protocol requests.
.Pp
.Ft Status
.Fo XSyncQueryExtension
.Fa "Display *dpy"
.Fa "int *event_base_return"
.Fa "int *error_base_return"
.Fc
.Pp
If dpy supports the SYNC extension,
.Fn XSyncQueryExtension
returns True,
sets *event_base_return to the event number for the first SYNC event, and
sets *error_base_return to the error number for the first SYNC error.
If dpy
does not support the SYNC extension, it returns False.
.Pp
.Ft Status
.Fo XSyncInitialize
.Fa "Display *dpy"
.Fa "int *major_version_return"
.Fa "int *minor_version_return"
.Fc
.Pp
.Fn XSyncInitialize
sets *major_version_return and
*minor version return to the major/minor SYNC protocol version supported
by the server.
If the XSync library is compatible with the version
returned by the server, this function returns
.Fn True .
If dpy does not support the SYNC extension, or if there was an error
during communication with the server, or if the server and library protocol
versions are incompatible, this function returns
.Fn False .
The only XSync function that may be called before this function is
XSyncQueryExtension.
If a client violates this rule, the effects of all XSync
calls that it makes are undefined.
.Pp
.Ft XSyncSystemCounter
.Fo "* XSyncListSystemCounters"
.Fa "Display *dpy"
.Fa "int *n_counters_return"
.Fc
.Pp
.Fn XSyncListSystemCounters
returns a pointer to an array
of system counters supported by the display and sets *n_counters_return
to the number of counters in the array.
The array should be freed with
.Fn XSyncFreeSystemCounterList .
If dpy does not support
the SYNC extension, or if there was an error during communication with
the server, or if the server does not support any system counters,
this function returns NULL.
.Pp
XSyncSystemCounter has the following fields:
.Bd -unfilled
char * name; /* null-terminated name of system counter */
XSyncCounter counter; /* counter id of this system counter */
XSyncValue resolution; /* resolution of this system counter */
.Ed
.Pp
.Ft void
.Fo XSyncFreeSystemCounterList
.Fa "XSyncSystemCounter *list"
.Fc
.Pp
.Fn XSyncFreeSystemCounterList
frees the memory
associated with the system counter list returned by
.Fn XSyncListSystemCounters .
.Pp
.Ft XSyncCounter
.Fo XSyncCreateCounter
.Fa "Display *dpy"
.Fa "XSyncValue initial_value"
.Fc
.Pp
.Fn XSyncCreateCounter
creates a counter on the dpy
with the given initial value and returns the counter ID.
It returns
.Fn None
if dpy does not support the SYNC extension.
.Pp
.Ft Status
.Fo XSyncSetCounter
.Fa "Display *dpy"
.Fa "XSyncCounter counter"
.Fa "XSyncValue value"
.Fc
.Pp
.Fn XSyncSetCounter
sets counter to value.
It returns
.Fn False
if dpy does not
support the SYNC extension; otherwise, it returns
.Fn True .
.Pp
.Ft Status
.Fo XSyncChangeCounter
.Fa "Display *dpy"
.Fa "XSyncCounter counter"
.Fa "XSyncValue value"
.Fc
.Pp
.Fn XSyncChangeCounter
adds value to counter.
It returns
.Fn False
if dpy does not support the SYNC extension;
otherwise, it returns
.Fn True .
.Pp
.Ft Status
.Fo XSyncDestroyCounter
.Fa "Display *dpy"
.Fa "XSyncCounter counter"
.Fc
.Pp
.Fn XSyncDestroyCounter
destroys counter.
It returns
.Fn False
if dpy does not support the SYNC extension;
otherwise, it returns
.Fn True .
.Pp
.Ft Status
.Fo XSyncQueryCounter
.Fa "Display *dpy"
.Fa "XSyncCounter counter"
.Fa "XSyncValue *value_return"
.Fc
.Pp
.Fn XSyncQueryCounter
sets *value_return to the current
value of counter.
It returns
.Fn False
if there was an
error during communication with the server or if dpy does not support the
SYNC extension; otherwise, it returns
.Fn True .
.Pp
.Ft Status
.Fo XSyncAwait
.Fa "Display *dpy"
.Fa "XSyncWaitCondition *wait_list"
.Fa "int n_conditions"
.Fc
.Pp
.Fn XSyncAwait
awaits on the conditions in wait_list.
The n_conditions is the number of wait conditions in wait_list.
It
returns
.Fn False
if dpy does not support the SYNC
extension; otherwise, it returns
.Fn True .
The await is
processed asynchronously by the server; this function always returns
immediately after issuing the request.
.Pp
XSyncWaitCondition has the following fields:
.Bd -unfilled
XSyncCounter trigger.counter; /*counter to trigger on */
XSyncValueType trigger.value_type; /*absolute/relative */
XSyncValue trigger.wait_value; /*value to compare counter to */
XSyncTestType trigger.test_type; /*pos/neg comparison/transtion */
XSyncValue event_threshold; /*send event if past threshold */
.Ed
.Pp
.Fn XSyncValueType
can be either
.Fn XSyncAbsolute
or
.Fn XSyncRelative .
.Pp
.Fn XSyncTestType
can be one of
.Fn XSyncPositiveTransition ,
.Fn XSyncNegativeTransition ,
.Fn XSyncPositiveComparison ,
or
.Fn XSyncNegativeComparison .
.Pp
.Ft XSyncAlarm
.Fo XSyncCreateAlarm
.Fa "Display *dpy"
.Fa "unsigned long values_mask"
.Fa "XSyncAlarmAttributes *values`"
.Fc
.Pp
.Fn XSyncCreateAlarm
creates an alarm and returns the
alarm ID.
It returns None if the display does not support the SYNC
extension.
The values_mask and values specify the alarm attributes.
.Pp
.Fn XSyncAlarmAttributes
has the following fields.
The
attribute_mask column specifies the symbol that the caller should OR
into values_mask to indicate that the value for the corresponding
attribute was actually supplied.
Default values are used for all
attributes that do not have their attribute_mask OR’ed into values_mask.
See the protocol description for
.Fn CreateAlarm
for the
defaults.
.Bd -unfilled
type field name attribute_mask
XSyncCounter trigger.counter; XSyncCACounter
XSyncValueType trigger.value_type; XSyncCAValueType
XSyncValue trigger.wait_value; XSyncCAValue
XSyncTestType trigger.test_type; XSyncCATestType
XSyncValue delta; XSyncCADelta
Bool events; XSyncCAEvents
XSyncAlarmState state; client cannot set this
.Ed
.Pp
.Ft Status
.Fo XSyncDestroyAlarm
.Fa "Display *dpy"
.Fa "XSyncAlarm alarm"
.Fc
.Pp
.Fn XSyncDestroyAlarm
destroys alarm.
It returns
.Fn False
if dpy does not support
the SYNC extension; otherwise, it returns
.Fn True .
.Pp
.Ft Status
.Fo XSyncQueryAlarm
.Fa "Display *dpy"
.Fa "XSyncAlarm alarm"
.Fa "XSyncAlarmAttributes *values_return"
.Fc
.Pp
.Fn XSyncQueryAlarm
sets *values_return to the alarm’s
attributes.
It returns
.Fn False
if there was an error
during communication with the server or if dpy does not support the
SYNC extension; otherwise, it returns
.Fn True .
.Pp
.Ft Status
.Fo XSyncChangeAlarm
.Fa "Display *dpy"
.Fa "XSyncAlarm alarm"
.Fa "unsigned long values_mask"
.Fa "XSyncAlarmAttributes *values"
.Fc
.Pp
.Fn XSyncChangeAlarm
changes alarm’s attributes.
The
attributes to change are specified as in
.Fn XSyncCreateAlarm .
It returns
.Fn False
if dpy does not support
the SYNC extension; otherwise, it returns
.Fn True .
.Pp
.Ft Status
.Fo XSyncSetPriority
.Fa "Display *dpy"
.Fa "XID client_resource_id"
.Fa "int priority"
.Fc
.Pp
.Fn XSyncSetPriority
sets the priority of the client
owning client_resource_id to priority.
If client_resource_id is None, it
sets the caller’s priority.
It returns
.Fn False
if dpy does not support the SYNC extension;
otherwise, it returns
.Fn True .
.Pp
.Ft Status
.Fo XSyncGetPriority
.Fa "Display *dpy"
.Fa "XID client_resource_id"
.Fa "int *return_priority"
.Fc
.Pp
.Fn XSyncGetPriority
sets *return_priority to the
priority of the client owning client_resource_id.
If client_resource_id
is None, it sets *return_priority to the caller’s priority.
It returns
.Fn False
if there was an error during communication
with the server or if dpy does not support the SYNC extension; otherwise, it
returns
.Fn True .
.Ss C Macros/Functions
The following procedures manipulate 64-bit values.
They are defined both as
macros and as functions.
By default, the macro form is used.
To use the
function form, #undef the macro name to uncover the function.
.Pp
.Ft void
.Fo XSyncIntToValue
.Fa "XSyncValue *pv"
.Fa "int i"
.Fc
.Pp
Converts i to an
.Fn XSyncValue
and stores it in *pv.
Performs sign extension (*pv will have the same sign as i.)
.Pp
.Ft void
.Fo XSyncIntsToValue
.Fa "XSyncValue *pv"
.Fa "unsigned int low"
.Fa "int high"
.Fc
.Pp
Stores low in the low 32 bits of *pv and high in the high 32 bits of *pv.
.Pp
.Ft Bool
.Fo XSyncValueGreaterThan
.Fa "XSyncValue a"
.Fa "XSyncValue b"
.Fc
.Pp
Returns
.Fn True
if a is greater than b, else returns
.Fn False .
.Pp
.Ft Bool
.Fo XSyncValueLessThan
.Fa "XSyncValue a"
.Fa "XSyncValue b"
.Fc
.Pp
Returns
.Fn True
if a is less than b, else returns
.Fn False .
.Pp
.Ft Bool
.Fo XSyncValueGreaterOrEqual
.Fa "XSyncValue a"
.Fa "XSyncValue b"
.Fc
.Pp
Returns
.Fn True
if a is greater than or equal to b,
else returns
.Fn False .
.Pp
.Ft Bool
.Fo XSyncValueLessOrEqual
.Fa "XSyncValue a"
.Fa "XSyncValue b"
.Fc
.Pp
Returns
.Fn True
if a is less than or equal to b,
else returns
.Fn False .
.Pp
.Ft Bool
.Fo XSyncValueEqual
.Fa "XSyncValue a"
.Fa "XSyncValue b"
.Fc
.Pp
Returns
.Fn True
if a is equal to b,
else returns
.Fn False .
.Pp
.Ft Bool
.Fo XSyncValueIsNegative
.Fa "XSyncValue v"
.Fc
.Pp
Returns
.Fn True
if v is negative,
else returns
.Fn False .
.Pp
.Ft Bool
.Fo XSyncValueIsZero
.Fa "XSyncValue v"
.Fc
.Pp
Returns
.Fn True
if v is zero,
else returns
.Fn False .
.Pp
.Ft Bool
.Fo XSyncValueIsPositive
.Fa "XSyncValue v"
.Fc
.Pp
Returns
.Fn True
if v is positive,
else returns
.Fn False .
.Pp
.Ft unsigned int
.Fo XSyncValueLow32
.Fa "XSyncValue v"
.Fc
.Pp
Returns the low 32 bits of v.
.Pp
.Ft unsigned int
.Fo XSyncValueHigh32
.Fa "XSyncValue v"
.Fc
.Pp
Returns the high 32 bits of v.
.Pp
.Ft void
.Fo XSyncValueAdd
.Fa "XSyncValue *presult"
.Fa "XSyncValue a"
.Fa "XSyncValue b"
.Fa "Bool *poverflow"
.Fc
.Pp
Adds a to b and stores the result in *presult.
If the result could not
fit in 64 bits, *poverflow is set to
.Fn True ,
else it is
set to
.Fn False .
.Pp
.Ft void
.Fo XSyncValueSubtract
.Fa "XSyncValue *presult"
.Fa "XSyncValue a"
.Fa "XSyncValue b"
.Fa "Bool *poverflow"
.Fc
.Pp
Subtracts b from a and stores the result in *presult.
If the result could not
fit in 64 bits, *poverflow is set to
.Fn True ,
else it is
set to
.Fn False .
.Pp
.Ft void
.Fo XSyncMaxValue
.Fa "XSyncValue *pv"
.Fc
.Pp
Sets *pv to the maximum value expressible in 64 bits.
.Pp
.Ft void
.Fo XSyncMinValue
.Fa "XSyncValue *pv"
.Fc
.Pp
Sets *pv to the minimum value expressible in 64 bits.
.Ss Events
Let
.Em event_base
be the value event base return as defined in the function
.Fn XSyncQueryExtension .
.Pp
An
.Fn XSyncCounterNotifyEvent Ns ’s
type field has the value
event_base +
.Fn XSyncCounterNotify .
The fields of this
structure are:
.Bd -unfilled
int type; /* event base + XSyncCounterNotify */
unsigned long serial; /* number of last request processed by server */
Bool send event; /* true if this came from a SendEvent request */
Display * display; /* Display the event was read from */
XSyncCounter counter; /* counter involved in await */
XSyncValue wait_value; /* value being waited for */
XSyncValue counter_value; /* counter value when this event was sent */
Time time; /* milliseconds */
int count; /* how many more events to come */
Bool destroyed; /* True if counter was destroyed */
.Ed
.Pp
An
.Fn XSyncAlarmNotifyEvent Ns ’s
type field has the value
event_base +
.Fn XSyncAlarmNotify .
The fields of
this structure are:
.Bd -unfilled
int type; /* event_base + XSyncAlarmNotify */
unsigned long serial; /* number of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display * display; /*Display the event was read from */
XSyncAlarm alarm; /* alarm that triggered */
XSyncValue counter_value /* value that triggered the alarm */
XSyncValue alarm_value /* test value of trigger in alarm */
Time time; /* milliseconds */
XSyncAlarmState state; /* new state of alarm */
.Ed
.Ss Errors
Let
.Em error_base
be the value
.Em error_base_return
as defined in the function
.Fn XSyncQueryExtension .
.Pp
An
.Fn XSyncAlarmError Ns ’s
error_code field has
.Fn XSyncBadAlarm .
The fields of this structure are:
.Bd -unfilled
int type
Display * display; /* Display the event was read from */
XSyncCounter counter; /* resource id */
unsigned long serial; /* serial number of failed request */
unsigned char error_code; /* error_base + XSyncBadAlarm */
unsigned char request_code; /* Major op-code of failed request */
unsigned char minor_code; /* Minor op-code of failed request */
.Ed
.Pp
An
.Fn XSyncCounterError Ns ’s
error code field has the value
error_base +
.Fn XSyncBadCounter .
The fields of this
structure are:
.Bd -unfilled
int type
Display * display; /* Display the event was read from */
XSyncCounter counter; /* resource id */
unsigned long serial; /* serial number of failed request */
unsigned char error_code; /* error_base + XSyncBadCounter */
unsigned char request_code; /* Major op-code of failed request */
unsigned char minor_code; /* Minor op-code of failed request */
.Ed
.Sh AUTHORS
.An -nosplit
.Sy X Consortium Standard
.Pp
X Version 11, Release 6
Version 3.0
.An -split
.An Tim Glauert ,
Olivetti Research
MultiWorks
.An Dave Carver ,
Digital Equipment Corporation
MIT/Project Athena
.An Jim Gettys ,
Digital Equipment Corporation
Cambridge Research Laboratory
.An David P. Wiggins ,
X Consortium, Inc.
Copyright \(co 1991
Olivetti Research Limited, Cambridge England
Digital Equipment Corporation, Maynard, Massachusetts
.Ss Legal Notice
Permission to use, copy, modify, and distribute this documentation for any
purpose and without fee is hereby granted, provided that the above
copyright notice appear in all copies.
Olivetti, Digital, MIT, and the
X Consortium make no representations about the suitability for any purpose
of the information in this document.
This documentation is provided as
is without express or implied warranty.
.Ss Legal Notice
Copyright \(co 1991 X Consortium, Inc.
.Pp
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files
(the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
.Pp
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
.Pp
THE SOFTWARE IS PROVIDED \(lqAS IS\(rq, WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
.Pp
Except as contained in this notice, the name of the X Consortium shall
not be used in advertising or otherwise to promote the sale, use or other
dealings in this Software without prior written authorization from the
X Consortium.
.Pp
X Window System is a trademark of The OpenGroup.

586
lib/libXext/specs/xtest1.3 Normal file
View File

@ -0,0 +1,586 @@
.\" automatically generated with docbook2mdoc xtest1.xml
.Dd $Mdocdate: May 10 2019 $
.Dt XTEST1 3
.Os
.Sh NAME
.Nm xtest1
.Nd X11 INPUT SYNTHESIS EXTENSION PROPOSAL
.Sh ABSTRACT
This is a proposal for an extension to the X11 server and Xlib.
.Sh INTRODUCTION
This is a proposal for an extension to the X11 server and Xlib.
It provides two capabilities:
.Bl -bullet
.It
It allows a client to generate user input actions in the server without
requiring a user to be present.
.It
It also allows a client to control the
handling of user input actions by the server.
.El
.Pp
The capability
to allow a client to generate user input actions in the server
will be used by some of the X Testing Consortium Xlib tests.
Both capabilities will be used by the X Testing Consortium client exerciser
program.
These capabilities may also be useful in other programs.
.Pp
This extension requires modification to device-dependent code in the
server.
Therefore it is not a 'portable' extension as defined by the
X11 Server Extensions document.
However, the majority of the code
and functionality of this extension will be implementation-independent.
.Sh CONVENTIONS USED IN THIS DOCUMENT
The naming conventions used in the Xlib documentation are followed
with these additions:
.Bl -bullet
.It
The names of all functions defined in this extension begin with 'XTest',
with the first letter of each additional word capitalized.
.It
The names of the protocol request structures follow the Xlib convention
of 'x<name>Req'.
.It
The names of the protocol request minor type codes follow the Xlib convention
of 'X_<name>'.
.It
The names of all other constants defined in this extension begin with 'XTest',
with the rest of the name in upper case letters.
.It
All constants and structures defined in this extension will have their
values specified in the 'xtestext1.h' file (listed in section 5).
.El
.Sh DEFINITION OF TERMS
.Ss Input Actions
Input actions are pointer movements, button presses and releases,
and key presses and releases.
They can be generated by a user or by a client
(using functions in this extension).
.Ss User Input Actions
User input actions are input actions that are generated by the user
moving a pointing device (typically a mouse), pressing and releasing buttons on
the pointing device, and pressing and releasing keys on the keyboard.
.Sh WHAT DOES THIS EXTENSION DO?
Without this extension, user input actions are processed by the server,
and are converted into normal X events that are sent to the
appropriate client or clients.
.Pp
This extension adds the following capabilities:
.Bl -bullet
.It
Input actions may be sent from a client to the server to be
processed just as if the user had physically performed them.
The input actions are provided to the server in the form of X protocol
requests defined by this extension.
The information provided to the server includes what action should be
performed, and how long to delay before processing the action in the server.
.It
User input actions may be diverted to a client before being processed by the
server.
The effect on the server is as if the user had performed no input action.
The user input actions are provided to the client in the form of X events
defined by this extension.
The information provided to the client includes what user input action
occurred and the delay between this user input action and the previous user
input action.
The client may then do anything it wishes with this information.
.It
User input actions may be copied, with one copy going to the server in the
normal way, and the other copy being sent to a client as described above.
.El
.Sh FUNCTIONS IN THIS EXTENSION
.Ss High Level Functions
These functions are built on top of the low level functions described later.
.Pp
.Sy XTestMovePointer
.Pp
.Ft int
.Fo XTestMovePointer
.Fa "Display *display"
.Fa "int device_id"
.Fa "unsigned long delay"
.Fa "int x"
.Fa "int y"
.Fa "unsigned int count"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.It device_id
Specifies which pointer device was supposed to have caused the input action.
This is a provision for future support of multiple (distinguishable) pointer
devices, and should always be set to 0 for now.
.It delay
Specifies the time (in milliseconds) to wait before each movement
of the pointer.
.It x, y
Specifies the x and y coordinates to move the pointer to relative to the
root window for the specified display.
.It count
Specifies the number of 'delay, x, y' triplets contained in the
.Em delay ,
.Em x
and
.Em y
arrays.
.El
.Pp
The
.Fn XTestMovePointer
function creates input actions to be sent to the the server.
The input actions will be accumulated in a request defined by this extension
until the request is full or the XTestFlush function is called.
They will then be sent to the server.
When the input actions are sent to the server, the input actions will cause
the server to think that the pointer was moved to the specified position(s),
with the specified delay before each input action.
.Pp
The
.Fn XTestMovePointer
function will return -1 if there is an error, and 0 otherwise.
.Pp
.Sy XTestPressButton
.Pp
.Ft int
.Fo XTestPressButton
.Fa "Display *display"
.Fa "int device_id"
.Fa "unsigned long delay"
.Fa "unsigned int button_number"
.Fa "unsigned int button_action"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.It device_id
Specifies which button device was supposed to have caused the input action.
This is a provision for future support of multiple (distinguishable) button
devices, and should always be set to 0 for now.
.It delay
Specifies the time (in milliseconds) to wait before the input action.
.It button_number
Specifies which button is being acted upon.
.It button_action
Specifies the action to be performed (one of
.Em XTestPRESS ,
.Em XTestRELEASE ,
or
.Em XTestSTROKE ) .
.El
.Pp
The
.Fn XTestPressButton
function creates input actions to be sent to the the server.
The input actions will be accumulated in a request defined by this extension
until the request is full or the XTestFlush function is called.
They will then be sent to the server.
When the input actions are sent to the server, the input actions will cause
the server to think that the specified button was moved as specified.
.Pp
The
.Fn XTestPressButton
function will return -1 if there is an error, and 0 otherwise.
.Pp
.Sy XTestPressKey
.Pp
.Ft int
.Fo XTestPressKey
.Fa "Display *display"
.Fa "int device_id"
.Fa "unsigned long delay"
.Fa "unsigned int keycode"
.Fa "unsigned int key_action"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.It device_id
Specifies which keyboard device was supposed to have caused the input action.
This is a provision for future support of multiple (distinguishable) keyboard
devices, and should always be set to 0 for now.
.It delay
Specifies the time (in milliseconds) to wait before the input action.
.It keycode
Specifies which keycode is being acted upon.
.It key_action
Specifies the action to be performed (one of
.Em XTestPRESS ,
.Em XTestRELEASE ,
or
.Em XTestSTROKE ) .
.El
.Pp
The
.Fn XTestPressKey
function creates input actions to be sent to the the server.
The input actions will be accumulated in a request defined by this extension
until the request is full or the XTestFlush function is called.
They will then be sent to the server.
When the input actions are sent to the server, the input actions will cause
the server to think that the specified key on the keyboard was moved as
specified.
.Pp
The
.Fn XTestPressKey
function will return -1 if there is an error, and 0 otherwise.
.Pp
.Sy XTestFlush
.Pp
.Ft int
.Fo XTestFlush
.Fa "Display *display"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.El
.Pp
The
.Fn XTestFlush
will send any remaining input actions to the server.
.Pp
The
.Fn XTestFlush
function will return -1 if there is an error, and 0 otherwise.
.Ss Low Level Functions
.Sy XTestGetInput
.Pp
.Ft int
.Fo XTestGetInput
.Fa "Display *display"
.Fa "int action_handling"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.It action_handling
Specifies to the server what to do with the user input actions.
(one of
0,
.Em XTestPACKED_MOTION
or
.Em XTestPACKED_ACTIONS ;
optionally 'or'ed
with
.Em XTestEXCLUSIVE ) .
.El
.Pp
The
.Fn XTestGetInput
function tells the server to begin putting information about user input actions
into events to be sent to the client that called this function.
These events
can be read via the Xlib
.Fn XNextEvent Ns fR
function.
.Pp
The server assigns an event type of
.Em XTestInputActionType
to these events
to distinguish them from other events.
Since the actual value of the event type may vary depending on how many
extensions are included with an X11 implementation,
.Em XTestInputActionType
is a variable that will be
contained in the Xlib
part of this extension.
It may be referenced as follows:
.Pp
extern int XTestInputActionType;
.Bl -bullet
.It
An
.Em action_handling
value of 0 causes the server
to send one user input action in each
.Em XTestInputActionType
event.
This can sometimes cause performance problems.
.It
An
.Em action_handling
value of
.Em XTestPACKED_ACTIONS
causes the server
to pack as many user input actions as possible into a
.Em XTestInputActionType
event.
This is needed if user input actions are happening rapidly (such as
when the user moves the pointer) to keep performance at a reasonable level.
.It
An
.Em action_handling
value of
.Em XTestPACKED_MOTION
causes the server
to pack only user input actions associated with moving the pointer.
This allows the
client to receive button and key motions as they happen without waiting for the
event to fill up, while still keeping performance at a reasonable level.
.It
An
.Em action_handling
value with
.Em XTestEXCLUSIVE
\&'or'ed in
causes the server to send user input actions only to the client.
The effect on the server is as if the user had performed no input actions.
.It
An
.Em action_handling
value without
.Em XTestEXCLUSIVE
causes the server to copy user input actions, sending one copy to the
client, and handling the other copy normally (as it would if this extension
were not installed).
.El
.Pp
There are four types of input actions that are passed from the server
to the client.
They are:
.Bl -tag -width Ds
.It key/button~state~change
This type of input action contains the keycode of the key or button that
changed state;
whether the key or button is up or down,
and the time delay between this input action and the previous input action.
.It pointer~motions
This type of input action contains information about the motion of the
pointer when the pointer has only moved a short distance.
If the pointer has moved a long distance,
the pointer jump input action is used.
.It pointer~jumps
This type of input action contains information about the motion of the
pointer when the pointer has moved a long distance.
.It delays
This type of input action is used when the delay between input actions is too
large to be held in the other input actions.
.El
.Pp
The
.Fn XTestGetInput
function will return -1 if there is an error, and 0 otherwise.
.Pp
An error code of
.Em BadAccess
means that another client
has already requested that user input actions be sent to it.
.Pp
.Sy XTestStopInput
.Pp
.Ft int
.Fo XTestStopInput
.Fa "Display *display"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.El
.Pp
The
.Fn XTestStopInput
function tells the server to stop putting information about user input actions
into events.
The server will process user input actions normally (as it would
if this extension were not in the server).
.Pp
The
.Fn XTestStopInput
function will return -1 if there is an error, and 0 otherwise.
.Pp
An error code of
.Em BadAccess
means that a request
was made to stop input when input has never been started.
.Pp
.Sy XTestFakeInput
.Pp
.Ft int
.Fo XTestFakeInput
.Fa "Display *display"
.Fa "char *action_list_addr"
.Fa "int action_list_size"
.Fa "int ack_flag"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.It action_list_addr
Specifies the address of an list of input actions to be sent to the server.
.It action_list_size
Specifies the size (in bytes) of the list of input actions.
It may be no larger than
.Em XTestMAX_ACTION_LIST_SIZE
bytes.
.It ack_flag
Specifies whether the server needs to send an event to indicate that its
input action buffer is empty (one of
.Em XTestFAKE_ACK_NOT_NEEDED
or
.Em XTestFAKE_ACK_REQUEST ) .
.El
.Pp
The
.Fn XTestFakeInput
function tells the server to take the specified user input actions and process
them as if the user had physically performed them.
.Pp
The server can only accept a limited number of input actions at one
time.
This limit can be determined by the
.Fn XTestQueryInputSize
function
in this extension.
.Pp
The client should set
.Em ack_flag
to
.Em XTestFAKE_ACK_NOT_NEEDED
on calls to
.Em XTestFakeInput
that do not reach this limit.
.Pp
The client should set
.Em ack_flag
to
.Em XTestFAKE_ACK_REQUEST
on the call to
.Em XTestFakeInput
that reaches this limit.
.Pp
When the server sees an
.Em ack_flag
value of
.Em XTestFAKE_ACK_REQUEST
it finishes processing its input action buffer, then sends an event with
type
.Em XTestFakeAckType
to the client.
When the client reads this event, it knows that it is safe to resume
sending input actions to the server.
.Pp
Since the actual value of the event type may vary depending on how many
extensions are included with an X11 implementation,
.Em XTestFakeAckType
is a variable that is contained
in the Xlib part of this extension.
It may be referenced as follows:
.Pp
extern int XTestFakeAckType;
.Pp
There are four types of input actions that are passed from the client
to the server.
They are:
.Bl -tag -width Ds
.It key/button~state~change
This type of input action contains the keycode of the key or button that
is to change state;
whether the key or button is to be up or down,
and the time to delay before changing the state of the key or button.
.It pointer~motions
This type of input action contains information about the motion of the
pointer when the pointer is to be moved a short distance,
and the time to delay before moving the pointer.
If the pointer is to be moved a long distance,
the pointer jump input action must be used.
.It pointer~jumps
This type of input action contains information about the motion of the
pointer when the pointer is to be moved a long distance,
and the time to delay before moving the pointer.
.It delays
This type of input action is used when the delay between input actions is too
large to be held in the other input actions.
.El
.Pp
The
.Fn XTestFakeInput
function will return -1 if there is an error, and 0 otherwise.
.Pp
An error code of \efIBadAccess\efR means that another client has already
sent user input actions to the server, and the server has not finished
processing the user input actions.
.Pp
.Sy XTestQueryInputSize
.Pp
.Ft int
.Fo XTestQueryInputSize
.Fa "Display *display"
.Fa "unsigned long size_return"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.It size_return
Returns the number of input actions that the server's input action buffer can
hold.
.El
.Pp
The
.Fn XTestQueryInputSize
function asks the server to return the number of input actions that it can hold
in its input action buffer in the unsigned long pointed to by \efIsize_return\efR.
.Pp
The
.Fn XTestQueryInputSize
function will return -1 if there is an error, and 0 otherwise.
.Pp
.Sy XTestReset
.Pp
.Ft int
.Fo XTestReset
.Fa "Display *display"
.Fc
.Bl -tag -width Ds
.It display
Specifies the connection to the X server.
.El
.Pp
The
.Fn XTestReset
function tells the server to set everything having to do with this extension
back to its initial state.
After this call the server will act as if this
extension were not installed until one of the extension functions is called by
a client.
This function is not normally needed, but is included in case a
client wishes to clean up the server state, such as after a serious error.
.Pp
The
.Fn XTestReset
function will return -1 if there is an error, and 0 otherwise.
.Sh AUTHORS
.An -nosplit
.Sy X Consortium Standard
.Pp
Version 1.0
.An -split
.An Larry Woestman ,
Member of Technical Staff
Hewlett Packard
Copyright \(co 1993X Consortium
.Ss Legal Notice
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
.Pp
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
.Pp
THE SOFTWARE IS PROVIDED \(lqAS IS\(rq, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE X
CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.Pp
Except as contained in this notice, the name of the X Consortium shall not be
used in advertising or otherwise to promote the sale, use or other dealings in
this Software without prior written authorization from the X Consortium.
.Pp
X Window System is a trademark of The Open Group.

12
lib/libXmu/Makefile.bsd-wrapper
View File

@ -1,7 +1,17 @@
# $OpenBSD: Makefile.bsd-wrapper,v 1.6 2013/08/13 18:52:14 matthieu Exp $
# $OpenBSD: Makefile.bsd-wrapper,v 1.7 2019/05/10 11:44:39 schwarze Exp $
SHARED_LIBS= Xmu 11.0 Xmuu 6.0
CONFIGURE_ARGS+= --without-xsltproc --without-fop --without-xmlto
beforeinstall:
${INSTALL} ${INSTALL_COPY} -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} \
${.CURDIR}/doc/Xmu.3 ${DESTDIR}${MANDIR}3
# maintainer target, not used duing build or install
mdoc:
docbook2mdoc -s 3 ${.CURDIR}/doc/Xmu.xml > ${.CURDIR}/doc/Xmu.3
.PHONY: mdoc
.include <bsd.xorg.mk>

2780
lib/libXmu/doc/Xmu.3 Normal file
View File

File diff suppressed because it is too large Load Diff

1
lib/libXmu/doc/defs.ent Normal file
View File

@ -0,0 +1 @@
<!ENTITY fullrelvers "6">

12
lib/libxtrans/Makefile.bsd-wrapper
View File

@ -1,5 +1,15 @@
# $OpenBSD: Makefile.bsd-wrapper,v 1.3 2012/03/10 18:41:37 matthieu Exp $
# $OpenBSD: Makefile.bsd-wrapper,v 1.4 2019/05/10 11:44:39 schwarze Exp $
CONFIGURE_ARGS += --without-fop --without-xmlto
beforeinstall:
${INSTALL} ${INSTALL_COPY} -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} \
${.CURDIR}/doc/xtrans.3 ${DESTDIR}${MANDIR}3
# maintainer target, not used duing build or install
mdoc:
docbook2mdoc -s 3 ${.CURDIR}/doc/xtrans.xml > ${.CURDIR}/doc/xtrans.3
.PHONY: mdoc
.include <bsd.xorg.mk>

1
lib/libxtrans/doc/defs.ent Normal file
View File

@ -0,0 +1 @@
<!ENTITY fullrelvers "6">

1277
lib/libxtrans/doc/xtrans.3 Normal file
View File

File diff suppressed because it is too large Load Diff