Install more manual pages:
* 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:
parent
7b04c9060e
commit
042aae5043
@ -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
|
||||
|
@ -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
239
doc/xorg-docs/general/input/XKB-Config.7
Normal 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
672
doc/xorg-docs/general/input/XKB-Enhancing.7
Normal 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
1
doc/xorg-docs/general/input/defs.ent
Normal file
@ -0,0 +1 @@
|
||||
<!ENTITY fullrelvers "6">
|
@ -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
1
lib/libXext/specs/defs.ent
Normal file
@ -0,0 +1 @@
|
||||
<!ENTITY fullrelvers "6">
|
493
lib/libXext/specs/shapelib.3
Normal file
493
lib/libXext/specs/shapelib.3
Normal 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
740
lib/libXext/specs/synclib.3
Normal 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
586
lib/libXext/specs/xtest1.3
Normal 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.
|
@ -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
2780
lib/libXmu/doc/Xmu.3
Normal file
File diff suppressed because it is too large
Load Diff
1
lib/libXmu/doc/defs.ent
Normal file
1
lib/libXmu/doc/defs.ent
Normal file
@ -0,0 +1 @@
|
||||
<!ENTITY fullrelvers "6">
|
@ -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
1
lib/libxtrans/doc/defs.ent
Normal file
@ -0,0 +1 @@
|
||||
<!ENTITY fullrelvers "6">
|
1277
lib/libxtrans/doc/xtrans.3
Normal file
1277
lib/libxtrans/doc/xtrans.3
Normal file
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user