diff --git a/distrib/sets/lists/xshare/mi b/distrib/sets/lists/xshare/mi index 972cdd987..ab9208c85 100644 --- a/distrib/sets/lists/xshare/mi +++ b/distrib/sets/lists/xshare/mi @@ -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 diff --git a/doc/xorg-docs/Makefile.bsd-wrapper b/doc/xorg-docs/Makefile.bsd-wrapper index 075b2b6c0..f1a5b1091 100644 --- a/doc/xorg-docs/Makefile.bsd-wrapper +++ b/doc/xorg-docs/Makefile.bsd-wrapper @@ -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} diff --git a/doc/xorg-docs/general/input/XKB-Config.7 b/doc/xorg-docs/general/input/XKB-Config.7 new file mode 100644 index 000000000..44979185d --- /dev/null +++ b/doc/xorg-docs/general/input/XKB-Config.7 @@ -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 diff --git a/doc/xorg-docs/general/input/XKB-Enhancing.7 b/doc/xorg-docs/general/input/XKB-Enhancing.7 new file mode 100644 index 000000000..8b6b076ef --- /dev/null +++ b/doc/xorg-docs/general/input/XKB-Enhancing.7 @@ -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 + (stands for space bar) or +.It +names which express some relative positioning on a keyboard, for +example (an exclamation mark on US keyboards), on +the right there are keys , +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. + 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 +, , +, and + keys but it differs from number of shift +levels of . +.Pp +Note that the 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 + 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 and expects that a set +of +.Ql 'map[]=' +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 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[]=' . +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 ; +.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 .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 .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 diff --git a/doc/xorg-docs/general/input/defs.ent b/doc/xorg-docs/general/input/defs.ent new file mode 100644 index 000000000..30b1911cd --- /dev/null +++ b/doc/xorg-docs/general/input/defs.ent @@ -0,0 +1 @@ + diff --git a/lib/libXext/Makefile.bsd-wrapper b/lib/libXext/Makefile.bsd-wrapper index 1ea416086..fead1acfa 100644 --- a/lib/libXext/Makefile.bsd-wrapper +++ b/lib/libXext/Makefile.bsd-wrapper @@ -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 diff --git a/lib/libXext/specs/defs.ent b/lib/libXext/specs/defs.ent new file mode 100644 index 000000000..30b1911cd --- /dev/null +++ b/lib/libXext/specs/defs.ent @@ -0,0 +1 @@ + diff --git a/lib/libXext/specs/shapelib.3 b/lib/libXext/specs/shapelib.3 new file mode 100644 index 000000000..b2f50ee6b --- /dev/null +++ b/lib/libXext/specs/shapelib.3 @@ -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. diff --git a/lib/libXext/specs/synclib.3 b/lib/libXext/specs/synclib.3 new file mode 100644 index 000000000..77c51ffca --- /dev/null +++ b/lib/libXext/specs/synclib.3 @@ -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 . +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. diff --git a/lib/libXext/specs/xtest1.3 b/lib/libXext/specs/xtest1.3 new file mode 100644 index 000000000..33723c0cb --- /dev/null +++ b/lib/libXext/specs/xtest1.3 @@ -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 'xReq'. +.It +The names of the protocol request minor type codes follow the Xlib convention +of 'X_'. +.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. diff --git a/lib/libXmu/Makefile.bsd-wrapper b/lib/libXmu/Makefile.bsd-wrapper index a3eafde5f..a1fcce2c1 100644 --- a/lib/libXmu/Makefile.bsd-wrapper +++ b/lib/libXmu/Makefile.bsd-wrapper @@ -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 diff --git a/lib/libXmu/doc/Xmu.3 b/lib/libXmu/doc/Xmu.3 new file mode 100644 index 000000000..99413b7d2 --- /dev/null +++ b/lib/libXmu/doc/Xmu.3 @@ -0,0 +1,2780 @@ +.\" automatically generated with docbook2mdoc Xmu.xml +.Dd $Mdocdate: May 10 2019 $ +.Dt XMU 3 +.Os +.Sh NAME +.Nm xmu +.Nd Xmu and Xmuu Library API Reference +.Sh ABSTRACT +\(lqDon't ask.\(rq +.Sh INTRODUCTION +The Xmu Library is a collection of miscellaneous (some might say random) +utility functions that have been useful in building various applications +and widgets. +This library is required by the Athena Widgets. +.Pp +Starting in XFree86 4.1.0, and incorporated into X11R6.7 and later releases, +a subset of the functions that do not rely on the Athena Widgets (libXaw) +or X Toolkit Instrinsics (libXt) are provided in a second library, libXmuu. +.Pp +Programs using either of these libraries are encouraged to determine the +correct compiler and linker options via the +.Ql xmu +or +.Ql xmuu +module names for +.Nm pkg-config , +such as: +.Bd -literal +cc -c xapplication.c `pkg-config --cflags xmu` +cc -o xapplication xapplication.o `pkg-config --libs xmu` +.Ed +.Sh ATOM FUNCTIONS +To use the functions and macros defined in this section, you should include +the header file +.Pf < Pa X11/Xmu/Atoms.h Ns > +and link against the libXmu library. +.Pp +.Fo XA_ATOM_PAIR +.Fa d +.Fc +.Fo XA_CHARACTER_POSITION +.Fa d +.Fc +.Fo XA_CLASS +.Fa d +.Fc +.Fo XA_CLIENT_WINDOW +.Fa d +.Fc +.Fo XA_CLIPBOARD +.Fa d +.Fc +.Fo XA_COMPOUND_TEXT +.Fa d +.Fc +.Fo XA_DECNET_ADDRESS +.Fa d +.Fc +.Fo XA_DELETE +.Fa d +.Fc +.Fo XA_FILENAME +.Fa d +.Fc +.Fo XA_HOSTNAME +.Fa d +.Fc +.Fo XA_IP_ADDRESS +.Fa d +.Fc +.Fo XA_LENGTH +.Fa d +.Fc +.Fo XA_LIST_LENGTH +.Fa d +.Fc +.Fo XA_NAME +.Fa d +.Fc +.Fo XA_NET_ADDRESS +.Fa d +.Fc +.Fo XA_NULL +.Fa d +.Fc +.Fo XA_OWNER_OS +.Fa d +.Fc +.Fo XA_SPAN +.Fa d +.Fc +.Fo XA_TARGETS +.Fa d +.Fc +.Fo XA_TEXT +.Fa d +.Fc +.Fo XA_TIMESTAMP +.Fa d +.Fc +.Fo XA_USER +.Fa d +.Fc +.Fo XA_UTF8_STRING +.Fa d +.Fc +.Pp +These macros take a display as argument and return an +.Vt Atom . +The name of the +atom is obtained from the macro name by removing the leading characters +.Pf \(lq Ql XA_ Ns \(rq . +The +.Vt Atom +value is cached, such that subsequent requests do not cause +another round-trip to the server. +.Pp +.Ft AtomPtr +.Fo XmuMakeAtom +.Fa "const char * name" +.Fc +.Bl -tag -width Ds +.It Fa name +specifies the atom name +.El +.Pp +This function creates and initializes an opaque object, an +.Vt AtomPtr , +for an +.Vt Atom +with the +given name. +.Sx XmuInternAtom +can be used to cache the Atom value for one or more displays. +.Pp +.Ft char +.Fo "* XmuNameOfAtom" +.Fa "AtomPtr atom_ptr" +.Fc +.Bl -tag -width Ds +.It Fa atom_ptr +specifies the AtomPtr +.El +.Pp +The function returns the name of an AtomPtr. +.Pp +.Ft Atom +.Fo XmuInternAtom +.Fa "Display * dpy" +.Fa "AtomPtr atom_ptr" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa atom_ptr +specifies the AtomPtr +.El +.Pp +This function returns the +.Vt Atom +for an +.Vt AtomPtr . +The +.Vt Atom +is cached, +such that subsequent requests do not cause another round-trip to the server. +.Pp +.Ft char +.Fo "* XmuGetAtomName" +.Fa "Display * dpy" +.Fa "Atom atom" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa atom +specifies the atom whose name is desired +.El +.Pp +This function returns the name of an +.Vt Atom . +The result is cached, such that subsequent +requests do not cause another round-trip to the server. +.Pp +.Ft void +.Fo XmuInternStrings +.Fa "Display * dpy" +.Fa "String * names" +.Fa "Cardinal count" +.Fa "Atom * atoms" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa names +specifies the strings to intern +.It Fa count +specifies the number of strings +.It Fa atoms +returns the list of Atom values +.El +.Pp +This function converts a list of atom names into +.Vt Atom +values. +The results are cached, such +that subsequent requests do not cause further round-trips to the server. +The caller is responsible for preallocating the array pointed at by atoms. +.Sh ERROR HANDLER FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/Error.h Ns > +and link against the libXmu or libXmuu library. +.Pp +.Ft int +.Fo XmuPrintDefaultErrorMessage +.Fa "Display * dpy" +.Fa "XErrorEvent * event" +.Fa "FILE * fp" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa event +specifies the error +.It Fa fp +specifies where to print the error message +.El +.Pp +This function prints an error message, equivalent to Xlib's default error +message for protocol errors. +It returns a non-zero value +if the caller should consider exiting, otherwise it returns 0. +This function can be used when you need to +write your own error handler, but need to print out an error from within +that handler. +.Pp +.Ft int +.Fo XmuSimpleErrorHandler +.Fa "Display * dpy" +.Fa "XErrorEvent * errorp" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa errorp +specifies the error +.El +.Pp +This function ignores errors for +.Er BadWindow +errors for +.Lk libX11 XQueryTree +.Pq XQueryTree +and +.Lk libX11 XGetWindowAttributes +.Pq XGetWindowAttributes , +and ignores +.Er BadDrawable +errors for +.Lk libX11 XGetGeometry +.Pq XGetGeometry ; +it returns 0 in those cases. +Otherwise, it prints the default error message, +and returns a non-zero value if the caller should consider exiting, +and 0 if the caller should not exit. +.Sh SYSTEM UTILITY FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/SysUtil.h Ns > +and link against the libXmu or libXmuu library. +.Pp +.Ft int +.Fo XmuGetHostname +.Fa "char * buf" +.Fa "int maxlen" +.Fc +.Bl -tag -width Ds +.It Fa buf +returns the host name +.It Fa maxlen +specifies the length of +.Fa buf +.El +.Pp +This function stores the null terminated name of the local host in +.Fa buf , +and +returns length of the name. +This function hides operating system differences, +such as whether to call +.Fn gethostname +or +.Fn uname . +.Pp +.Ft int +.Fo XmuSnprintf +.Fa "char * str" +.Fa "int size" +.Fa ... +.Fc +.Bl -tag -width Ds +.It Fa str +string to write output to +.It Fa size +specifies the size of +.Fa str +.El +.Pp +This function was provided as a portable implementation of +.Fn snprintf +before all platforms could be +relied on to provide their own. +It is now deprecated in favor of +calling +.Fn snprintf +directly and should only be used +in software that needs to continue to support non-Unix98 compliant platforms. +.Sh WINDOW UTILITY FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/WinUtil.h Ns > +\&. +To use +.Fn XmuClientWindow , +you may link against either the +libXmu or libXmuu libraries. +The other functions in this section require +linking against the libXmu library. +.Pp +.Ft Screen +.Fo "* XmuScreenOfWindow" +.Fa "Display * dpy" +.Fa "Window w" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa w +specifies the window +.El +.Pp +This function returns the +.Vt Screen +on which the specified window was created. +.Pp +.Ft Window +.Fo XmuClientWindow +.Fa "Display * dpy" +.Fa "Window win" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa win +specifies the window +.El +.Pp +This function finds a window, at or below the specified window, which has a +.Fa WM_STATE +property. +If such a window is found, it is +returned, otherwise the +argument window is returned. +.Pp +.Ft Bool +.Fo XmuUpdateMapHints +.Fa "Display * dpy" +.Fa "Window w" +.Fa "XSizeHints * hints" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa win +specifies the window +.It Fa hints +specifies the new hints, or +.Dv NULL +.El +.Pp +This function clears the +.Dv PPosition +and +.Dv PSize +flags and sets the +.Dv USPosition +and +.Dv USSize +flags in the hints structure, and then stores the hints for the +window using +.Lk libX11 XSetWMNormalHints +.Pq XSetWMNormalHints +and returns +.Dv True . +If +.Dv NULL +is passed for the +hints structure, then the current hints are read back from the window using +.Lk libX11 XGetWMNormalHints +.Pq XGetWMNormalHints +and are used instead, and +.Dv True +is returned; otherwise +.Dv False +is returned. +.Sh CURSOR UTILITY FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/CurUtil.h Ns > +and link against the libXmu or libXmuu library. +.Pp +.Ft int +.Fo XmuCursorNameToIndex +.Fa "const char * name" +.Fc +.Bl -tag -width Ds +.It Fa name +specifies the name of the cursor +.El +.Pp +This function takes the name of a standard cursor and returns its index +in the standard cursor font. +The cursor names are formed by removing the +.Pf \(lq Ql XC_ Ns \(rq +prefix from the cursor defines listed in +Appendix B of the Xlib +manual. +.Sh GRAPHICS FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/Drawing.h Ns > +and link against the libXmu library. +.Pp +.Ft void +.Fo XmuDrawRoundedRectangle +.Fa "Display * dpy" +.Fa "Drawable draw" +.Fa "GC gc" +.Fa "int x" +.Fa "int y" +.Fa "int w" +.Fa "int h" +.Fa "int ew" +.Fa "int eh" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa draw +specifies the drawable +.It Fa gc +specifies the GC +.It Fa x +specifies the upper left x coordinate +.It Fa y +specifies the upper left y coordinate +.It Fa w +specifies the rectangle width +.It Fa h +specifies the rectangle height +.It Fa ew +specifies the corner width +.It Fa eh +specifies the corner height +.El +.Pp +This function draws a rounded rectangle, where x, y, w, h are the dimensions +of the overall rectangle, and ew and eh are the sizes of a bounding box that +the corners are drawn inside of; ew should be no more than half of w, and eh +should be no more than half of h. The current GC line attributes control +all attributes of the line. +.Pp +.Ft void +.Fo XmuFillRoundedRectangle +.Fa "Display * dpy" +.Fa "Drawable draw" +.Fa "GC gc" +.Fa "int x" +.Fa "int y" +.Fa "int w" +.Fa "int h" +.Fa "int ew" +.Fa "int eh" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa draw +specifies the drawable +.It Fa gc +specifies the GC +.It Fa x +specifies the upper left x coordinate +.It Fa y +specifies the upper left y coordinate +.It Fa w +specifies the rectangle width +.It Fa h +specifies the rectangle height +.It Fa ew +specifies the corner width +.It Fa eh +specifies the corner height +.El +.Pp +This function draws a filled rounded rectangle, where x, y, w, h are the +dimensions of the overall rectangle, and ew and eh are the sizes of a +bounding box that the corners are drawn inside of; ew should be no more than +half of w, and eh should be no more than half of h. The current GC fill +settings control all attributes of the fill contents. +.Pp +.Fo XmuDrawLogo +.Fa "Display * dpy" +.Fa "Drawable drawable" +.Fa "GC gcFore" +.Fa "GC gcBack" +.Fa "int x" +.Fa "int y" +.Fa "unsigned int width" +.Fa "unsigned int height" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa drawable +specifies the drawable +.It Fa gcFore +specifies the foreground GC +.It Fa gcBack +specifies the background GC +.It Fa x +specifies the upper left x coordinate +.It Fa y +specifies the upper left y coordinate +.It Fa width +specifies the logo width +.It Fa height +specifies the logo height +.El +.Pp +This function draws the \(lqofficial\(rq X Window System logo +.Pf ( Sx xlogo ) . +The bounding box +of the logo in the drawable is given by x, y, width, and height. +The logo +itself is filled using gcFore, and the rest of the rectangle is filled using +gcBack. +.Pp +.Sy The X Logo +.Bd -ragged -offset indent +[image: xlogo.svg] +.Ed +.Pp +.Ft Pixmap +.Fo XmuCreateStippledPixmap +.Fa "Screen * screen" +.Fa "Pixel fore" +.Fa "Pixel back" +.Fa "unsigned int depth" +.Fc +.Bl -tag -width Ds +.It Fa screen +specifies the screen the pixmap is created on +.It Fa fore +specifies the foreground pixel value +.It Fa back +specifies the background pixel value +.It Fa depth +specifies the depth of the pixmap +.El +.Pp +This function creates a two pixel by one pixel stippled pixmap of specified +depth on the specified screen. +The pixmap is cached so that multiple +requests share the same pixmap. +The pixmap should be freed with +.Fn XmuReleaseStippledPixmap +to maintain correct reference counts. +.Pp +.Ft void +.Fo XmuReleaseStippledPixmap +.Fa "Screen * screen" +.Fa "Pixmap pixmap" +.Fc +.Bl -tag -width Ds +.It Fa screen +specifies the screen the pixmap was created on +.It Fa pixmap +specifies the pixmap to free +.El +.Pp +This function frees a pixmap created with +.Fn XmuCreateStippledPixmap . +.Pp +.Ft int +.Fo XmuReadBitmapData +.Fa "FILE * fstream" +.Fa "unsigned int * width" +.Fa "unsigned int * height" +.Fa "unsigned char ** datap" +.Fa "int * x_hot" +.Fa "int * y_hot" +.Fc +.Bl -tag -width Ds +.It Fa fstream +specifies the stream to read from +.It Fa width +returns the width of the bitmap +.It Fa height +returns the height of the bitmap +.It Fa datap +returns the parsed bitmap data +.It Fa x_hot +returns the x coordinate of the hotspot +.It Fa y_hot +returns the y coordinate of the hotspot +.El +.Pp +This function reads a standard bitmap file description from the specified +stream, and returns the parsed data in a format suitable for passing to +.Lk libX11 XCreateBitmapFromData +.Pq XCreateBitmapFromData . +The return value of the function has the same +interpretation as the return value for +.Lk libX11 XReadBitmapFile +.Pq XReadBitmapFile . +.Pp +.Ft int +.Fo XmuReadBitmapDataFromFile +.Fa "const char * filename" +.Fa "unsigned int * width" +.Fa "unsigned int * height" +.Fa "unsigned char ** datap" +.Fa "int * x_hot" +.Fa "int * y_hot" +.Fc +.Bl -tag -width Ds +.It Fa fstream +specifies the file to read from +.It Fa width +returns the width of the bitmap +.It Fa height +returns the height of the bitmap +.It Fa datap +returns the parsed bitmap data +.It Fa x_hot +returns the x coordinate of the hotspot +.It Fa y_hot +returns the y coordinate of the hotspot +.El +.Pp +This function reads a standard bitmap file description from the specified +file, and returns the parsed data in a format suitable for passing to +.Lk libX11 XCreateBitmapFromData +.Pq XCreateBitmapFromData . +The return value of the function has the same +interpretation as the return value for +.Lk libX11 XReadBitmapFile +.Pq XReadBitmapFile . +.Pp +.Ft Pixmap +.Fo XmuLocateBitmapFile +.Fa "Screen * screen" +.Fa "const char * name" +.Fa "char * srcname" +.Fa "int srcnamelen" +.Fa "int * widthp" +.Fa "int * heightp" +.Fa "int * xhotp" +.Fa "int * yhotp" +.Fc +.Bl -tag -width Ds +.It Fa screen +specifies the screen the pixmap is created on +.It Fa name +specifies the file to read from +.It Fa srcname +returns the full filename of the bitmap +.It Fa srcnamelen +specifies the length of the srcname buffer +.It Fa width +returns the width of the bitmap +.It Fa height +returns the height of the bitmap +.It Fa xhotp +returns the x coordinate of the hotspot +.It Fa yhotp +returns the y coordinate of the hotspot +.El +.Pp +This function reads a file in standard bitmap file format, using +.Lk libX11 XReadBitmapFile +.Pq XReadBitmapFile , +and returns the created bitmap. +The filename may be +absolute, or relative to the global resource named +.Sy bitmapFilePath +with class +BitmapFilePath. +If the resource is not defined, the default value is the +build symbol BITMAPDIR, which is typically +.Pf \(dq Pa /usr/include/X11/bitmaps Ns \(dq. +If +.Fa srcnamelen +is greater than zero and +.Fa srcname +is not +.Dv NULL , +the null terminated filename will be copied into +.Fa srcname . +The size and hotspot of the bitmap are +also returned. +.Pp +.Ft Pixmap +.Fo XmuCreatePixmapFromBitmap +.Fa "Display * dpy" +.Fa "Drawable d" +.Fa "Pixmap bitmap" +.Fa "unsigned int width" +.Fa "unsigned int height" +.Fa "unsigned int depth" +.Fa "unsigned long fore" +.Fa "unsigned long back" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa screen +specifies the screen the pixmap is created on +.It Fa bitmap +specifies the bitmap source +.It Fa width +specifies the width of the pixmap +.It Fa height +specifies the height of the pixmap +.It Fa depth +specifies the depth of the pixmap +.It Fa fore +specifies the foreground pixel value +.It Fa back +specifies the background pixel value +.El +.Pp +This function creates a pixmap of the specified width, height, and depth, on +the same screen as the specified drawable, and then performs an +.Lk libX11 XCopyPlane +.Pq XCopyPlane +from the specified bitmap to the pixmap, +using the specified foreground and background pixel values. +The created pixmap is returned. +.Sh SELECTION FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/StdSel.h Ns > +and link against the libXmu library. +.Pp +.Ft Boolean +.Fo XmuConvertStandardSelection +.Fa "Widget w" +.Fa "Time time" +.Fa "Atom * selection" +.Fa "Atom * target" +.Fa "Atom * type" +.Fa "XPointer value" +.Fa "unsigned long * length" +.Fa "int * format" +.Fc +.Bl -tag -width Ds +.It Fa w +specifies the widget which currently owns the selection +.It Fa time +specifies the time at which the selection was established +.It Fa selection +this argument is ignored +.It Fa target +specifies the target type of the selection +.It Fa type +returns the property type of the converted value +.It Fa value +returns the converted value +.It Fa length +returns the number of elements in the converted value +.It Fa format +returns the size in bits of the elements +.El +.Pp +This function converts the following standard selections: CLASS, +CLIENT_WINDOW, DECNET_ADDRESS, HOSTNAME, IP_ADDRESS, NAME, OWNER_OS, +TARGETS, TIMESTAMP, and USER. +It returns +.Dv True +if the conversion was successful, else it returns +.Dv False . +.Sh TYPE CONVERTER FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/Converters.h Ns > +and link against the libXmu library. +.Pp +.Ft void +.Fo XmuCvtFunctionToCallback +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +this argument is ignored +.It Fa num_args +this argument is ignored +.It Fa fromVal +the function to convert +.It Fa toVal +the place to store the converted value +.El +.Pp +This function converts a callback procedure to a callback list containing +that procedure, with +.Dv NULL +closure data. +To use this converter, include the +following in your widget's ClassInitialize procedure: +.Bd -literal +XtAddConverter(XtRCallProc, XtRCallback, XmuCvtFunctionToCallback, NULL, 0); +.Ed +.Pp +.Ft void +.Fo XmuCvtStringToBackingStore +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +this argument is ignored +.It Fa num_args +this argument must be a pointer to a Cardinal containing the value 0 +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.El +.Pp +This function converts a string to a backing-store integer as defined in +.Pf < Pa X11/X.h Ns > . +The string "notUseful" converts to +.Dv NotUseful , +"whenMapped" converts to +.Dv WhenMapped , +and "always" converts to +.Dv Always . +The string "default" converts to the value +.Dv Always ++ +.Dv WhenMapped ++ +.Dv NotUseful . +The case of the string does not matter. +To use this converter, include the following +in your widget's ClassInitialize procedure: +.Bd -literal +XtAddConverter(XtRString, XtRBackingStore, XmuCvtStringToBackingStore, NULL, 0); +.Ed +.Pp +.Ft void +.Fo XmuCvtStringToBitmap +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +the sole argument specifies the Screen on which to create the bitmap +.It Fa num_args +must be the value 1 +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.El +.Pp +This function creates a bitmap (a Pixmap of depth one) suitable for window +manager icons. +The string argument is the name of a file in standard bitmap +file format. +For the possible filename specifications, see +.Fn XmuLocateBitmapFile +.Pq Sx XmuLocateBitmapFile . +To use this converter, include the following in your widget's +ClassInitialize procedure: +.Bd -literal +static XtConvertArgRec screenConvertArg[] = { + {XtBaseOffset, (XtPointer)XtOffset(Widget, core.screen), sizeof(Screen *)} +}; +XtAddConverter(XtRString, XtRBitmap, XmuCvtStringToBitmap, + screenConvertArg, XtNumber(screenConvertArg)); +.Ed +.Pp +.Ft Boolean +.Fo XmuCvtStringToColorCursor +.Fa "Display * dpy" +.Fa "XrmValuePtr args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fa "XtPointer * data" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the display to use for conversion warnings +.It Fa args +specifies the required conversion arguments +.It Fa num_args +specifies the number of required conversion arguments, which is 4 +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.It Fa data +this argument is ignored +.El +.Pp +This function converts a string to a +.Vt Cursor +with the foreground and background pixels specified by the conversion +arguments. +The string can either be a +standard cursor name formed by removing the +.Ql \(lqXC_\(rq +prefix from any of the +cursor defines listed in Appendix B of the Xlib Manual, a font name and +glyph index in decimal of the form "FONT fontname index [[font] index]", +or a bitmap filename acceptable to +.Fn XmuLocateBitmapFile +.Pq Sx XmuLocateBitmapFile . +To use this converter, include +the following in the widget ClassInitialize procedure: +.Bd -literal +static XtConvertArgRec colorCursorConvertArgs[] = { + {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.screen), + sizeof(Screen *)}, + {XtResourceString, (XtPointer) XtNpointerColor, sizeof(Pixel)}, + {XtResourceString, (XtPointer) XtNpointerColorBackground, sizeof(Pixel)}, + {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.colormap), + sizeof(Colormap)} +}; +XtSetTypeConverter(XtRString, XtRColorCursor, XmuCvtStringToColorCursor, + colorCursorConvertArgs, XtNumber(colorCursorConvertArgs), + XtCacheByDisplay, NULL); +.Ed +.Pp +The widget must recognize XtNpointerColor and XtNpointerColorBackground as +resources, or specify other appropriate foreground and background resources. +The widget's Realize and SetValues methods must cause the converter to be +invoked with the appropriate arguments when one of the foreground, +background, or cursor resources has changed, or when the window is created, +and must assign the cursor to the window of the widget. +.Pp +.Ft void +.Fo XmuCvtStringToCursor +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +specifies the required conversion argument, the screen +.It Fa num_args +specifies the number of required conversion arguments, which is 1 +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.El +.Pp +This function converts a string to a +.Vt Cursor . +The string can either be a +standard cursor name formed by removing the +.Ql \(lqXC_\(rq +prefix from any of the +cursor defines listed in Appendix B of the Xlib Manual, a font name and +glyph index in decimal of the form "FONT fontname index [[font] index]", or +a bitmap filename acceptable to +.Fn XmuLocateBitmapFile +.Pq Sx XmuLocateBitmapFile . +To use this converter, include +the following in your widget's ClassInitialize procedure: +.Bd -literal +static XtConvertArgRec screenConvertArg[] = { + {XtBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.screen), sizeof(Screen *)} +}; +XtAddConverter(XtRString, XtRCursor, XmuCvtStringToCursor, + screenConvertArg, XtNumber(screenConvertArg)); +.Ed +.Pp +.Ft void +.Fo XmuCvtStringToGravity +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +this argument is ignored +.It Fa num_args +this argument must be a pointer to a Cardinal containing the value 0 +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.El +.Pp +This function converts a string to an +.Vt XtGravity +enumeration value. +The string "forget" and a +.Dv NULL +value convert to +.Dv ForgetGravity , +"NorthWestGravity" converts to +.Dv NorthWestGravity , +the strings "NorthGravity" and "top" convert to +.Dv NorthGravity , +"NorthEastGravity" converts to +.Dv NorthEastGravity , +the strings "West" and "left" convert to +.Dv WestGravity , +"CenterGravity" converts to +.Dv CenterGravity , +"EastGravity" and "right" convert to +.Dv EastGravity , +"SouthWestGravity" converts to +.Dv SouthWestGravity , +"SouthGravity" and "bottom" convert to +.Dv SouthGravity , +"SouthEastGravity" converts to +.Dv SouthEastGravity , +"StaticGravity" converts to +.Dv StaticGravity , +and "UnmapGravity" converts to +.Dv UnmapGravity . +The case of the string does not matter. +To use this converter, include +the following in your widget's class initialize procedure: +.Bd -literal +XtAddConverter(XtRString, XtRGravity, XmuCvtStringToGravity, NULL, 0); +.Ed +.Pp +.Ft void +.Fo XmuCvtStringToJustify +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +this argument is ignored +.It Fa num_args +this argument is ignored +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.El +.Pp +This function converts a string to an +.Vt XtJustify +enumeration value. +The string "left" converts to +.Dv XtJustifyLeft , +"center" converts to +.Dv XtJustifyCenter , +and "right" converts to +.Dv XtJustifyRight . +The case of the string does not matter. +To use this converter, +include the following in your widget's ClassInitialize procedure: +.Bd -literal +XtAddConverter(XtRString, XtRJustify, XmuCvtStringToJustify, NULL, 0); +.Ed +.Pp +.Ft void +.Fo XmuCvtStringToLong +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +this argument is ignored +.It Fa num_args +this argument must be a pointer to a Cardinal containing 0 +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.El +.Pp +This function converts a string to an integer of type long. +It parses the +string using +.Fn sscanf +with a format of "%ld". To use this converter, include +the following in your widget's ClassInitialize procedure: +.Bd -literal +XtAddConverter(XtRString, XtRLong, XmuCvtStringToLong, NULL, 0); +.Ed +.Pp +.Ft void +.Fo XmuCvtStringToOrientation +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +this argument is ignored +.It Fa num_args +this argument is ignored +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.El +.Pp +This function converts a string to an +.Vt XtOrientation +enumeration value. +The string "horizontal" converts to +.Dv XtorientHorizontal +and "vertical" converts to +.Dv XtorientVertical . +The case of the string does not matter. +To use this converter, +include the following in your widget's ClassInitialize procedure: +.Bd -literal +XtAddConverter(XtRString, XtROrientation, XmuCvtStringToOrientation, NULL, 0); +.Ed +.Pp +.Ft Boolean +.Fo XmuCvtStringToShapeStyle +.Fa "Display * dpy" +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fa "XtPointer * data" +.Fc +.Bl -tag -width Ds +.It Fa dpy +the display to use for conversion warnings +.It Fa args +this argument is ignored +.It Fa num_args +this argument is ignored +.It Fa fromVal +the value to convert from +.It Fa toVal +the place to store the converted value +.It Fa data +this argument is ignored +.El +.Pp +This function converts a string to an integer shape style. +The string +"rectangle" converts to +.Dv XmuShapeRectangle , +"oval" converts to +.Dv XmuShapeOval , +"ellipse" converts to +.Dv XmuShapeEllipse , +and "roundedRectangle" converts to +.Dv XmuShapeRoundedRectangle . +The case of the string does not matter. +To use this converter, +include the following in your widget's ClassInitialize procedure: +.Bd -literal +XtSetTypeConverter(XtRString, XtRShapeStyle, XmuCvtStringToShapeStyle, + NULL, 0, XtCacheNone, NULL); +.Ed +.Pp +.Ft Boolean +.Fo XmuReshapeWidget +.Fa "Widget w" +.Fa "int shape_style" +.Fa "int corner_width" +.Fa "int corner_height" +.Fc +.Bl -tag -width Ds +.It Fa w +specifies the widget to reshape +.It Fa shape_style +specifies the new shape +.It Fa corner_width +specifies the width of the rounded rectangle corner +.It Fa corner_height +specified the height of the rounded rectangle corner +.El +.Pp +This function reshapes the specified widget, using the Shape extension, to a +rectangle, oval, ellipse, or rounded rectangle, as specified by shape_style +( +.Dv XmuShapeRectangle , +.Dv XmuShapeOval , +.Dv XmuShapeEllipse , +and +.Dv XmuShapeRoundedRectangle , +respectively). +The shape is bounded by the outside edges of the rectangular extents of the +widget. +If the shape is a rounded rectangle, corner_width and corner_height +specify the size of the bounding box that the corners are drawn inside of +(see +.Fn XmuFillRoundedRectangle +.Pq Sx XmuFillRoundedRectangle ) ; +otherwise, corner_width and corner_height are ignored. +The origin of the widget within its parent remains unchanged. +.Pp +.Ft void +.Fo XmuCvtStringToWidget +.Fa "XrmValue * args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fc +.Bl -tag -width Ds +.It Fa args +the sole argument is the parent Widget +.It Fa num_args +this argument must be 1 +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.El +.Pp +This function converts a string to an immediate child widget of the parent +widget passed as an argument. +Note that this converter only works for +child widgets that have already been created; there is no lazy evaluation. +The string is first compared against the +names of the normal and popup children, and if a match is found the +corresponding child is returned. +If no match is found, the string is +compared against the classes of the normal and popup children, and if a +match is found the corresponding child is returned. +The case of the string +is significant. +To use this converter, include the following in your +widget's ClassInitialize procedure: +.Bd -literal +static XtConvertArgRec parentCvtArg[] = { + {XtBaseOffset, (XtPointer)XtOffset(Widget, core.parent), sizeof(Widget)}, +}; +XtAddConverter(XtRString, XtRWidget, XmuCvtStringToWidget, + parentCvtArg, XtNumber(parentCvtArg)); +.Ed +.Pp +.Ft Boolean +.Fo XmuNewCvtStringToWidget +.Fa "Display * dpy" +.Fa "XrmValuePtr args" +.Fa "Cardinal * num_args" +.Fa "XrmValuePtr fromVal" +.Fa "XrmValuePtr toVal" +.Fa "XtPointer * data" +.Fc +.Bl -tag -width Ds +.It Fa dpy +the display to use for conversion warnings +.It Fa args +the sole argument is the parent Widget +.It Fa num_args +this argument must be a pointer to a Cardinal containing the value 1 +.It Fa fromVal +specifies the string to convert +.It Fa toVal +returns the converted value +.It Fa data +this argument is ignored +.El +.Pp +This converter is identical in functionality to +.Fn XmuCvtStringToWidget +.Pq Sx XmuCvtStringToWidget , +except +that it is a new-style converter, allowing the specification of a cache type +at the time of registration. +Most widgets will not cache the conversion results, as the application may +dynamically create and destroy widgets, which would cause cached values to +become illegal. +To use this converter, include the following in the widget's +class initialize procedure: +.Bd -literal +static XtConvertArgRec parentCvtArg[] = { + {XtWidgetBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.parent), + sizeof(Widget)} +}; +XtSetTypeConverter(XtRString, XtRWidget, XmuNewCvtStringToWidget, + parentCvtArg, XtNumber(parentCvtArg), XtCacheNone, NULL); +.Ed +.Sh CHARACTER SET FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/CharSet.h Ns > +and link against the libXmu or libXmuu library. +.Pp +.Sy Warning +.Pp +The functions in this section are +.Em deprecated +because they don't work in most locales now supported by X11; most platforms +provide alternatives in their system libraries. +.Pp +.Ft void +.Fo XmuCopyISOLatin1Lowered +.Fa "char * dst" +.Fa "const char * src" +.Fc +.Bl -tag -width Ds +.It Fa dst +returns the string copy +.It Fa src +specifies the string to copy +.El +.Pp +This function copies a null terminated string from src to dst (including the +null), changing all Latin-1 uppercase letters to lowercase. +The string is +assumed to be encoded using ISO 8859-1. +.Pp +Note that like +.Fn strcpy +the caller is responsible for +ensuring the size of +.Fa dst +is at least as large as the +size of +.Fa src . +.Pp +.Ft void +.Fo XmuNCopyISOLatin1Lowered +.Fa "char * dst" +.Fa "const char * src" +.Fa "int size" +.Fc +.Bl -tag -width Ds +.It Fa dst +returns the string copy +.It Fa src +specifies the string to copy +.It Fa size +maximum number of characters (including the null terminator) to write to dst +.El +.Pp +This function copies up to +.Ql Fa size +- 1 +characters of a null terminated string from +.Fa src +to +.Fa dst , +and terminates it with a null, +changing all Latin-1 uppercase letters to lowercase. +The string is +assumed to be encoded using ISO 8859-1. +.Pp +.Ft void +.Fo XmuCopyISOLatin1Uppered +.Fa "char * dst" +.Fa "const char * src" +.Fc +.Bl -tag -width Ds +.It Fa dst +returns the string copy +.It Fa src +specifies the string to copy +.El +.Pp +This function copies a null terminated string from src to dst (including the +null), changing all Latin-1 lowercase letters to uppercase. +The string is +assumed to be encoded using ISO 8859-1. +.Pp +Note that like +.Fn strcpy +the caller is responsible for +ensuring the size of +.Fa dst +is at least as large as the +size of +.Fa src . +.Pp +.Ft void +.Fo XmuNCopyISOLatin1Uppered +.Fa "char * dst" +.Fa "const char * src" +.Fa "int size" +.Fc +.Bl -tag -width Ds +.It Fa dst +returns the string copy +.It Fa src +specifies the string to copy +.It Fa size +maximum number of characters (including the null terminator) to write to dst +.El +.Pp +This function copies up to +.Ql Fa size +- 1 +characters of a null terminated string from +.Fa src +to +.Fa dst , +and terminates it with a null, +changing all Latin-1 lowercase letters to uppercase. +The string is +assumed to be encoded using ISO 8859-1. +.Pp +.Ft int +.Fo XmuCompareISOLatin1 +.Fa "const char * first" +.Fa "const char * second" +.Fc +.Bl -tag -width Ds +.It Fa first +specifies a string to compare +.It Fa second +specifies a string to compare +.El +.Pp +This function compares two null terminated Latin-1 strings, ignoring case +differences, and returns an integer greater than, equal to, or less than 0, +according to whether first is lexicographically greater than, equal to, or +less than second. +The two strings are assumed to be encoded using ISO +8859-1. +.Sh KEYBOARD EVENT TRANSLATION FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/Lookup.h Ns > +\&. +and link against the libXmu library. +.Pp +.Sy Warning +.Pp +The functions in this section are +.Em deprecated +because they don't work +in most locales now supported by X11; the function +.Lk libX11 XmbLookupString +.Pq XmbLookupString +provides a better alternative. +.Pp +.Ft int +.Fo XmuLookupLatin1 +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is identical to +.Lk libX11 XLookupString +.Pq XLookupString , +and exists only for naming symmetry with other functions. +.Pp +.Ft int +.Fo XmuLookupLatin2 +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to an Latin-2 (ISO 8859-2) string, or to an ASCII control string. +.Pp +.Ft int +.Fo XmuLookupLatin3 +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to an Latin-3 (ISO 8859-3) string, or to an ASCII control string. +.Pp +.Ft int +.Fo XmuLookupLatin4 +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to an Latin-4 (ISO 8859-4) string, or to an ASCII control string. +.Pp +.Ft int +.Fo XmuLookupKana +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to a string in an encoding consisting of Latin-1 (ISO 8859-1) and ASCII +control in the Graphics Left half (values 0 to 127), and Katakana in the +Graphics Right half (values 128 to 255), using the values from JIS +X201-1976. +.Pp +.Ft int +.Fo XmuLookupJISX0201 +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to a string in the JIS X0201-1976 encoding, including ASCII control. +.Pp +.Ft int +.Fo XmuLookupArabic +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to a Latin/Arabic (ISO 8859-6) string, or to an ASCII control string. +.Pp +.Ft int +.Fo XmuLookupCyrillic +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to a Latin/Cyrillic (ISO 8859-5) string, or to an ASCII control string. +.Pp +.Ft int +.Fo XmuLookupGreek +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to a Latin/Greek (ISO 8859-7) string, or to an ASCII control string. +.Pp +.Ft int +.Fo XmuLookupHebrew +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event +to a Latin/Hebrew (ISO 8859-8) string, or to an ASCII control string. +.Pp +.Ft int +.Fo XmuLookupAPL +.Fa "XKeyEvent * event" +.Fa "unsigned char * buffer" +.Fa "int nbytes" +.Fa "KeySym * keysym" +.Fa "XComposeStatus * status" +.Fc +.Bl -tag -width Ds +.It Fa event +specifies the key event +.It Fa buffer +returns the translated characters +.It Fa nbytes +specifies the length of the buffer +.It Fa keysym +returns the computed KeySym, or None +.It Fa status +specifies or returns the compose state +.El +.Pp +This function is similar to +.Lk libX11 XLookupString +.Pq XLookupString , +except that it maps a key event to an APL string. +.Sh COMPOUND TEXT FUNCTIONS +The functions defined in this section are for parsing Compound Text strings, +decomposing them into individual segments. +Definitions needed to use these +routines are in the include file +.Pf < Pa X11/Xmu/Xct.h Ns > +and link against the libXmu library. +.Pp +.Sy Warning +.Pp +The functions in this section are +.Em deprecated +because they shift the +burden for recently introduced locale encodings to the application. +The +use of the +.Dv UTF8_STRING +text encoding provides a better alternative. +.Pp +A Compound Text string is represented as the following type: +.Bd -literal + typedef unsigned char *XctString; +.Ed +.Pp +.Ft XctData +.Fo XctCreate +.Fa "const XctString string" +.Fa "int length" +.Fa "XctFlags flags" +.Fc +.Bl -tag -width Ds +.It Fa string +the Compound Text string +.It Fa length +the number of bytes in string +.It Fa flags +parsing control flags +.El +.Pp +This function creates an +.Vt XctData +structure for parsing a Compound Text +string. +The string need not be null terminated. +The following flags are +defined to control parsing of the string: +.Bl -tag -width Ds +.It Dv XctSingleSetSegments +This means that returned segments should contain +characters from only one set (C0, C1, GL, GR). When this is requested, +.Dv XctSegment +is never returned by +.Fn XctNextItem , +instead +.Dv XctC0Segment , +.Dv XctC1Segment , +.Dv XctGlSegment , +and +.Dv XctGRSegment +are returned. +C0 and C1 +segments are always returned as singleton characters. +.It Dv XctProvideExtensions +This means that if the Compound Text string is from a +higher version than this code is implemented to, then syntactically correct +but unknown control sequences should be returned as +.Dv XctExtension +items by +.Fn XctNextItem . +If this flag is not set, and the Compound Text string version +indicates that extensions cannot be ignored, then each unknown control +sequence will be reported as an +.Dv XctError . +.It Dv XctAcceptC0Extensions +This means that if the Compound Text string is from +a higher version than this code is implemented to, then unknown C0 +characters should be treated as if they were legal, and returned as C0 +characters (regardless of how +.Dv XctProvideExtensions +is set) by +.Fn XctNextItem . +If this flag is not set, then all unknown C0 characters are treated +according to +.Dv XctProvideExtensions . +.It Dv XctAcceptC1Extensions +This means that if the Compound Text string is from +a higher version than this code is implemented to, then unknown C1 +characters should be treated as if they were legal, and returned as C1 +characters (regardless of how +.Dv XctProvideExtensions +is set) by +.Fn XctNextItem . +If this flag is not set, then all unknown C1 characters are treated +according to +.Dv XctProvideExtensions . +.It Dv XctHideDirection +This means that horizontal direction changes should be +reported as +.Dv XctHorizontal +items by +.Fn XctNextItem . +If this flag is not set, +then direction changes are not returned as items, but the current direction +is still maintained and reported for other items. +The current direction is +given as an enumeration, with the values +.Dv XctUnspecified , +.Dv XctLeftToRight , +and +.Dv XctRightToLeft . +.It Dv XctFreeString +This means that +.Fn XctFree +should free the Compound Text string that is passed to +.Fn XctCreate . +If this flag is not set, the string is not freed. +.It Dv XctShiftMultiGRToGL +This means that +.Fn XctNextItem +should translate GR +segments on-the-fly into GL segments for the GR sets: GB2312.1980-1, +JISX0208.1983-1, and KSC5601.1987-1. +.El +.Pp +.Ft void +.Fo XctReset +.Fa "XctData data" +.Fc +.Bl -tag -width Ds +.It Fa data +specifies the Compound Text structure +.El +.Pp +This function resets the +.Vt XctData +structure to reparse the Compound Text string from the beginning. +.Pp +.Ft XctResult +.Fo XctNextItem +.Fa "XctData data" +.Fc +.Bl -tag -width Ds +.It Fa data +specifies the Compound Text structure +.El +.Pp +This function parses the next \(lqitem\(rq from the Compound Text string. +The +return value indicates what kind of item is returned. +The item itself, its +length, and the current contextual state, are reported as components of the +.Vt XctData +structure. +.Vt XctResult +is an enumeration, with the following values: +.Bl -tag -width Ds +.It Dv XctSegment +the item contains some mixture of C0, GL, GR, and C1 characters. +.It Dv XctC0Segment +the item contains only C0 characters. +.It Dv XctGLSegment +the item contains only GL characters. +.It Dv XctC1Segment +the item contains only C1 characters. +.It Dv XctGRSegment +the item contains only GR characters. +.It Dv XctExtendedSegment +the item contains an extended segment. +.It Dv XctExtension +the item is an unknown extension control sequence. +.It Dv XctHorizontal +the item indicates a change in horizontal direction or +depth. +The new direction and depth are recorded in the +.Vt XctData +structure. +.It Dv XctEndOfText +The end of the Compound Text string has been reached. +.It Dv XctError +the string contains a syntactic or semantic error; no further +parsing should be performed. +.El +.Pp +The following state values are stored in the +.Vt XctData +structure: +.Bd -literal + XctString item; /* the action item */ + unsigned item_length; /* length of item in bytes */ + int char_size; /* the number of bytes per character in + * item, with zero meaning variable */ + char *encoding; /* the XLFD encoding name for item */ + XctHDirection horizontal; /* the direction of item */ + unsigned horz_depth; /* the current direction nesting depth */ + char *GL; /* the "{I} F" string for the current GL */ + char *GL_encoding; /* the XLFD encoding name for the current GL */ + int GL_set_size; /* 94 or 96 */ + int GL_char_size; /* the number of bytes per GL character */ + char *GR; /* the "{I} F" string for the current GR */ + char *GR_encoding; /* the XLFD encoding name for the current GR */ + int GR_set_size; /* 94 or 96 */ + int GR_char_size; /* number of bytes per GR character */ + char *GLGR_encoding; /* the XLFD encoding name for the current + * GL+GR, if known */ +.Ed +.Pp +.Ft void +.Fo XctFree +.Fa "XctData data" +.Fc +.Bl -tag -width Ds +.It Fa data +specifies the Compound Text structure +.El +.Pp +This function frees all data associated with the +.Vt XctData +structure. +.Sh CLOSEDISPLAY HOOK FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/CloseHook.h Ns > +and link against the libXmu library. +.Pp +.Ft CloseHook +.Fo XmuAddCloseDisplayHook +.Fa "Display * dpy" +.Fa "int ( *func )(Display *, XPointer)" +.Fa "XPointer arg" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa func +specifies the function to call at display close +.It Fa arg +specifies arbitrary data to pass to +.Fa func +.El +.Pp +This function adds a callback for the given display. +When the display is +closed, the given function will be called with the given display and +argument as: +.Bd -literal + (*func)(dpy, arg) +.Ed +.Pp +The function is declared to return an int even though the value is ignored, +because some compilers used to have problems with functions returning void. +.Pp +This routine returns +.Dv NULL +if it was unable to add the +callback, otherwise it +returns an opaque handle that can be used to remove or lookup the callback. +.Pp +.Ft Bool +.Fo XmuRemoveCloseDisplayHook +.Fa "Display * dpy" +.Fa "CloseHook handle" +.Fa "int ( *func )(Display *, XPointer)" +.Fa "XPointer arg" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa handle +specifies the callback by id, or +.Dv NULL +.It Fn func +specifies the callback by function +.It Fa arg +specifies the function data to match +.El +.Pp +This function deletes a callback that has been added with +.Fn XmuAddCloseDisplayHook . +If handle is not +.Dv NULL , +it specifies the callback to +remove, and the func and arg parameters are ignored. +If handle is +.Dv NULL , +the +first callback found to match the specified func and arg will be removed. +Returns +.Dv True +if a callback was removed, else returns +.Dv False . +.Pp +.Ft Bool +.Fo XmuLookupCloseDisplayHook +.Fa "Display * dpy" +.Fa "CloseHook handle" +.Fa "int ( *func )(Display *, XPointer)" +.Fa "XPointer arg" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa handle +specifies the callback by id, or +.Dv NULL +.It Fn func +specifies the callback by function +.It Fa arg +specifies the function data to match +.El +.Pp +This function determines if a callback is installed. +If handle is not +.Dv NULL , +it specifies the callback to look for, and the func and arg parameters are +ignored. +If handle is +.Dv NULL , +the function will look for +any callback for the +specified func and arg. +Returns +.Dv True +if a matching callback exists, else returns +.Dv False . +.Sh DISPLAY QUEUE FUNCTIONS +To use the functions and types defined in this section, you should include the +header file +.Pf < Pa X11/Xmu/DisplayQue.h Ns > +and link against the libXmu library. +.Pa DisplayQue.h +defines the following +types: +.Bd -literal +typedef int (*XmuCloseDisplayQueueProc)(XmuDisplayQueue *queue, + XmuDisplayQueueEntry *entry); +typedef int (*XmuFreeDisplayQueueProc)(XmuDisplayQueue *queue); +typedef struct _XmuDisplayQueueEntry { + struct _XmuDisplayQueueEntry *prev, *next; + Display *display; + CloseHook closehook; + XPointer data; +} XmuDisplayQueueEntry; +typedef struct _XmuDisplayQueue { + int nentries; + XmuDisplayQueueEntry *head, *tail; + XmuCloseDisplayQueueProc closefunc; + XmuFreeDisplayQueueProc freefunc; + XPointer data; +} XmuDisplayQueue; +.Ed +.Pp +.Ft XmuDisplayQueue +.Fo "* XmuDQCreate" +.Fa "XmuCloseDisplayQueueProc closefunc" +.Fa "XmuFreeDisplayQueueProc freefunc" +.Fa "XPointer data" +.Fc +.Bl -tag -width Ds +.It Fa closefunc +specifies the close function +.It Fa freefunc +specifies the free function +.It Fa data +specifies private data for the functions +.El +.Pp +This function creates and returns an empty +.Vt XmuDisplayQueue +(which is really just a set of displays, but is called a queue for +historical reasons). The queue is initially empty, but displays +can be added using +.Fn XmuAddDisplay . +The data value is simply stored in the queue for use by the closefunc +and freefunc callbacks. +Whenever a display in the queue is closed using +.Fn XCloseDisplay , +the +.Fa closefunc +(if +.Pf non- Dv NULL ) +is called with the queue and the display's +.Fn XmuDisplayQueueEntry +as follows: +.Bd -literal + (*closefunc)(queue, entry) +.Ed +.Pp +The +.Fa freefunc +(if +.Pf non- Dv NULL ) +is called whenever the last +display in the +queue is closed, as follows: +.Bd -literal + (*freefunc)(queue) +.Ed +.Pp +The application is responsible for actually freeing the queue, by calling +.Fn XmuDQDestroy . +.Pp +.Ft XmuDisplayQueueEntry +.Fo "* XmuDQAddDisplay" +.Fa "XmuDisplayQueue * q" +.Fa "Display * dpy" +.Fa "XPointer data" +.Fc +.Bl -tag -width Ds +.It Fa q +specifies the queue +.It Fa dpy +specifies the display to add +.It Fa data +specifies private data for the free function +.El +.Pp +This function adds the specified display to the queue. +If successful, +the queue entry is returned, otherwise +.Dv NULL +is returned. +The data value is simply stored in the queue entry for use by the +queue's freefunc callback. +This function does not attempt to prevent +duplicate entries in the queue; the caller should use +.Fn XmuDQLookupDisplay +to determine if a display has already been added to a queue. +.Pp +.Ft XmuDisplayQueueEntry +.Fo "* XmuDQLookupDisplay" +.Fa "XmuDisplayQueue * q" +.Fa "Display * dpy" +.Fc +.Bl -tag -width Ds +.It Fa q +specifies the queue +.It Fa dpy +specifies the display to lookup +.El +.Pp +This function returns the queue entry for the specified display, or +.Dv NULL +if +the display is not in the queue. +.Pp +.Fo XmuDQNDisplays +.Fa q +.Fc +This macro returns the number of displays in the specified queue. +.Pp +.Ft Bool +.Fo XmuDQRemoveDisplay +.Fa "XmuDisplayQueue * q" +.Fa "Display * dpy" +.Fc +.Bl -tag -width Ds +.It Fa q +specifies the queue +.It Fa dpy +specifies the display to remove +.El +.Pp +This function removes the specified display from the specified queue. +No callbacks are performed. +If the display is not found in the queue, +.Dv False +is returned, otherwise +.Dv True +is returned. +.Pp +.Ft Bool +.Fo XmuDQDestroy +.Fa "XmuDisplayQueue * q" +.Fa "Bool docallbacks" +.Fc +.Bl -tag -width Ds +.It Fa q +specifies the queue to destroy +.It Fa docallbacks +specifies whether close functions should be called +.El +.Pp +This function releases all memory associated with the specified queue. +If docallbacks is +.Dv True , +then the queue's closefunc callback (if +.Pf non- Dv NULL ) +is first called +for each display in the queue, even though +.Fn XCloseDisplay +is not called on the display. +.Sh TOOLKIT CONVENIENCE FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/Initer.h Ns > +and link against the libXmu library. +.Pp +.Ft void +.Fo XmuAddInitializer +.Fa "void ( *func )(XtAppContext, XPointer)" +.Fa "XPointer data" +.Fc +.Bl -tag -width Ds +.It Fa func +specifies the procedure to register +.It Fa data +specifies private data for the procedure +.El +.Pp +This function registers a procedure, to be invoked the first time +.Fn XmuCallInitializers +is called on a given application context. +The procedure +is called with the application context and the specified data: +.Bd -literal + (*func)(app_con, data) +.Ed +.Pp +.Ft void +.Fo XmuCallInitializers +.Fa "XtAppContext app_con" +.Fc +.Bl -tag -width Ds +.It Fa app_con +specifies the application context to initialize +.El +.Pp +This function calls each of the procedures that have been registered with +.Fn XmuAddInitializer , +if this is the first time the application context has been passed to +.Fn XmuCallInitializers . +Otherwise, this function does nothing. +.Sh STANDARD COLORMAP FUNCTIONS +To use the functions defined in this section, you should include the header +file +.Pf < Pa X11/Xmu/StdCmap.h Ns > +and link against the libXmu library. +.Pp +.Ft Status +.Fo XmuAllStandardColormaps +.Fa "Display * dpy" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.El +.Pp +To create all of the appropriate standard colormaps for every visual of +every screen on a given display, use +.Fn XmuAllStandardColormaps . +.Pp +This function defines and retains as permanent resources all standard +colormaps which are meaningful for the visuals of each screen of the +display. +It returns 0 on failure, non-zero on success. +If the property of +any standard colormap is already defined, this function will redefine it. +.Pp +This function is intended to be used by window managers or a special client +at the start of a session. +.Pp +The standard colormaps of a screen are defined by properties associated with +the screen's root window. +The property names of standard colormaps are +predefined, and each property name except +.Fa RGB_DEFAULT_MAP +may describe at +most one colormap. +.Pp +The standard colormaps are: +.Fa RGB_BEST_MAP , +.Fa RGB_RED_MAP , +.Fa RGB_GREEN_MAP , +.Fa RGB_BLUE_MAP , +.Fa RGB_DEFAULT_MAP , +and +.Fa RGB_GRAY_MAP . +Therefore a screen may +have at most 6 standard colormap properties defined. +.Pp +A standard colormap is associated with a particular visual of the screen. +A +screen may have multiple visuals defined, including visuals of the same +class at different depths. +Note that a visual id might be repeated for more +than one depth, so the visual id and the depth of a visual identify the +visual. +The characteristics of the visual will determine which standard +colormaps are meaningful under that visual, and will determine how the +standard colormap is defined. +Because a standard colormap is associated +with a specific visual, there must be a method of determining which visuals +take precedence in defining standard colormaps. +.Pp +The method used here is: for the visual of greatest depth, define all +standard colormaps meaningful to that visual class, according to this order +of (descending) precedence: +.Dv DirectColor ; +.Dv PseudoColor ; +.Dv TrueColor +and +.Dv GrayScale ; +and finally +.Dv StaticColor +and +.Dv StaticGray . +.Pp +This function allows success, on a per screen basis. +For example, if a map +on screen 1 fails, the maps on screen 0, created earlier, will remain. +However, none on screen 1 will remain. +If a map on screen 0 fails, none +will remain. +.Pp +See +.Fn XmuVisualStandardColormaps +.Pq Sx XmuVisualStandardColormaps +for which standard colormaps are meaningful under these classes of visuals. +.Pp +.Ft Status +.Fo XmuVisualStandardColormaps +.Fa "Display * dpy" +.Fa "int screen" +.Fa "VisualID visualid" +.Fa "unsigned int depth" +.Fa "Bool replace" +.Fa "Bool retain" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa screen +specifies the screen of the display +.It Fa visualid +specifies the visual type +.It Fa depth +specifies the visual depth +.It Fa replace +specifies whether or not to replace +.It Fa retain +specifies whether or not to retain +.El +.Pp +To create all of the appropriate standard colormaps for a given visual on a +given screen, use +.Fn XmuVisualStandardColormaps . +.Pp +This function defines all appropriate standard colormap properties for the +given visual. +If replace is +.Dv True , +any previous definition will be removed. +If retain is +.Dv True , +new properties will be retained for the duration of the +server session. +This function returns 0 on failure, non-zero on success. +On failure, no new properties will be defined, but old ones may have been +removed if replace was +.Dv True . +.Pp +Not all standard colormaps are meaningful to all visual classes. +This +routine will check and define the following properties for the following +classes, provided that the size of the colormap is not too small. +For +.Dv DirectColor +and +.Dv PseudoColor : +.Fa RGB_DEFAULT_MAP , +.Fa RGB_BEST_MAP , +.Fa RGB_RED_MAP , +.Fa RGB_GREEN_MAP , +.Fa RGB_BLUE_MAP , +and +.Fa RGB_GRAY_MAP . +For +.Dv TrueColor +and +.Dv StaticColor : +.Fa RGB_BEST_MAP . +For +.Dv GrayScale +and +.Dv StaticGray : +.Fa RGB_GRAY_MAP . +.Pp +.Ft Status +.Fo XmuLookupStandardColormap +.Fa "Display * dpy" +.Fa "int screen" +.Fa "VisualID visualid" +.Fa "unsigned int depth" +.Fa "Atom property" +.Fa "Bool replace" +.Fa "Bool retain" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa screen +specifies the screen of the display +.It Fa visualid +specifies the visual type +.It Fa depth +specifies the visual depth +.It Fa property +specifies the standard colormap property +.It Fa replace +specifies whether or not to replace +.It Fa retain +specifies whether or not to retain +.El +.Pp +To create a standard colormap if one does not currently exist, or replace +the currently existing standard colormap, use +.Fn XmuLookupStandardColormap . +.Pp +Given a screen, a visual, and a property, this function will determine the +best allocation for the property under the specified visual, and determine +the whether to create a new colormap or to use the default colormap of the +screen. +.Pp +If replace is True, any previous definition of the property will be +replaced. +If retain is True, the property and the colormap will be made +permanent for the duration of the server session. +However, pre-existing +property definitions which are not replaced cannot be made permanent by a +call to this function; a request to retain resources pertains to newly +created resources. +.Pp +This function returns 0 on failure, non-zero on success. +A request to +create a standard colormap upon a visual which cannot support such a map is +considered a failure. +An example of this would be requesting any standard +colormap property on a monochrome visual, or, requesting an +.Fa RGB_BEST_MAP +on +a display whose colormap size is 16. +.Pp +.Ft Status +.Fo XmuGetColormapAllocation +.Fa "XVisualInfo * vinfo" +.Fa "Atom property" +.Fa "unsigned long * red_max" +.Fa "unsigned long * green_max" +.Fa "unsigned long * blue_max" +.Fc +.Bl -tag -width Ds +.It Fa vinfo +specifies visual information for a chosen visual +.It Fa property +specifies one of the standard colormap property names +.It Fa red_max +returns maximum red value +.It Fa green_max +returns maximum green value +.It Fa blue_max +returns maximum blue value +.El +.Pp +To determine the best allocation of reds, greens, and blues in a standard +colormap, use +.Fn XmuGetColormapAllocation . +.Pp +.Fn XmuGetColormapAllocation +returns 0 on failure, non-zero on success. +It is +assumed that the visual is appropriate for the colormap property. +.Pp +.Ft XStandardColormap +.Fo "* XmuStandardColormap" +.Fa "Display * dpy" +.Fa "int screen" +.Fa "VisualID visualid" +.Fa "unsigned int depth" +.Fa "Atom property" +.Fa "Colormap cmap" +.Fa "unsigned long red_max" +.Fa "unsigned long green_max" +.Fa "unsigned long blue_max" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa screen +specifies the screen of the display +.It Fa visualid +specifies the visual type +.It Fa depth +specifies the visual depth +.It Fa property +specifies the standard colormap property +.It Fa cmap +specifies the colormap ID, or None +.It Fa red_max +specifies the red allocation +.It Fa green_max +specifies the green allocation +.It Fa blue_max +specifies the blue allocation +.El +.Pp +To create any one standard colormap, use +.Fn XmuStandardColormap . +.Pp +This function creates a standard colormap for the given screen, visualid, +and visual depth, with the given red, green, and blue maximum values, with +the given standard property name. +Upon success, it returns a pointer to an +.Fn XStandardColormap +structure which describes the newly created colormap. +Upon failure, it returns +.Dv NULL . +If cmap is the default colormap of the screen, the standard colormap +will be defined on the default colormap; otherwise a new colormap is created. +.Pp +Resources created by this function are not made permanent; that is the +caller's responsibility. +.Pp +.Ft Status +.Fo XmuCreateColormap +.Fa "Display * dpy" +.Fa "XStandardColormap * colormap" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection under which the map is created +.It Fa colormap +specifies the map to be created +.El +.Pp +To create any one colormap which is described by an +.Vt XStandardColormap +structure, use +.Fn XmuCreateColormap . +.Pp +This function returns 0 on failure, and non-zero on success. +The base_pixel +of the colormap is set on success. +Resources created by this function are +not made permanent. +No argument error checking is provided; use at your own +risk. +.Pp +All colormaps are created with read-only allocations, with the exception of +read-only allocations of colors which fail +to return the expected pixel value, and these are individually defined as +read/write allocations. +This is done so that all the cells defined in the +colormap are contiguous, for use in image processing. +This typically +happens with White and Black in the default map. +.Pp +Colormaps of static visuals are considered to be successfully created if the +map of the static visual matches the definition given in the standard +colormap structure. +.Pp +.Ft void +.Fo XmuDeleteStandardColormap +.Fa "Display * dpy" +.Fa "Screen * screen" +.Fa "Atom property" +.Fc +.Bl -tag -width Ds +.It Fa dpy +specifies the connection to the X server +.It Fa screen +specifies the screen of the display +.It Fa property +specifies the standard colormap property +.El +.Pp +To remove any standard colormap property, use +.Fn XmuDeleteStandardColormap . +This function will remove the specified property from the specified screen, +releasing any resources used by the colormap(s) of the property, if +possible. +.Sh WIDGET DESCRIPTION FUNCTIONS +The functions defined in this section are for building a description of +the structure of and resources associated with a hierarchy of widget classes. +This package is typically used by applications that wish to manipulate the +widget set itself. +.Pp +The definitions needed to use these interfaces are in the header file +.Pf < Pa X11/Xmu/WidgetNode.h Ns > +\&. +To call these functions, you need to link against the libXmu library. +The following function must be called before any of the others described +below: +.Ft void +.Fo XmuWnInitializeNodes +.Fa "XmuWidgetNode * node_array" +.Fa "int num_nodes" +.Fc +.Bl -tag -width Ds +.It Fa node_array +specifies a list of widget classes, in alphabetical order +.It Fa num_nodes +specifies the number of widget classes in the node array +.El +.Pp +To determine the resources provided by a widget class or classes, use +.Ft void +.Fo XmuWnFetchResources +.Fa "XmuWidgetNode * node" +.Fa "Widget toplevel" +.Fa "XmuWidgetNode * top_node" +.Fc +.Bl -tag -width Ds +.It Fa node +specifies the widget class for which resources should be obtained. +.It Fa toplevel +specifies the widget that should be used for creating an instance of +.Fa node +from which resources are extracted. +This is typically the value returned +by +.Lk libXaw XtAppInitialize +.Pq XtAppInitialize . +.It Fa top_node +specifies the ancestor of +.Fa node +that should be +treated as the root +of the widget inheritance tree (used in determining which ancestor contributed +which resources). +.El +.Pp +Each widget class inherits the resources of its parent. +To count the number +of resources contributed by a particular widget class, use: +.Ft int +.Fo XmuWnCountOwnedResources +.Fa "XmuWidgetNode * node" +.Fa "XmuWidgetNode * owner_node" +.Fa "Bool constraints" +.Fc +.Bl -tag -width Ds +.It Fa node +specifies the widget class whose resources are being examined. +.It Fa owner_node +specifies the widget class of the ancestor of +.Fa node +whose contributions +are being counted. +.It Fa constraints +specifies whether or not to count constraint resources or normal resources. +.El +.Pp +This routine returns the number of resources contributed (or +\(lqowned\(rq) by +the specified widget class. +.Pp +.Ft XmuWidgetNode +.Fo "* XmuWnNameToNode" +.Fa "XmuWidgetNode * node_list" +.Fa "int num_nodes" +.Fa "char * name" +.Fc +.Bl -tag -width Ds +.It Fa node_list +specifies a list of widget nodes +.It Fa num_nodes +specifies the number of nodes in the list +.It Fa name +specifies the name of the widget class in the node list to search for +.El +.Pp +This function returns the WidgetNode in the list that matches the given +widget name or widget class name. +If no match is found, it returns +.Dv NULL . +.Sh PARTICIPATION IN THE EDITRES PROTOCOL +To participate in the editres protocol, applications which are not based +on the Athena widget set should include the header file +.Pf < Pa X11/Xmu/Editres.h Ns > +and link against the libXmu library. +.Pp +To participate in the editres protocol, Xt applications which do not rely +on the Athena widget set should register the editres protocol handler on +each shell widget in the application, specifying an event mask of 0, +nonmaskable events, and client data as +.Dv NULL : +.Bd -literal +XtAddEventHandler(shell, (EventMask) 0, True, _XEditResCheckMessages, NULL); +.Ed +.Sh AUTHORS +.An -nosplit +X Version 11, Release 6 +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 +.Em X Window System +is a trademark of The Open Group. diff --git a/lib/libXmu/doc/defs.ent b/lib/libXmu/doc/defs.ent new file mode 100644 index 000000000..30b1911cd --- /dev/null +++ b/lib/libXmu/doc/defs.ent @@ -0,0 +1 @@ + diff --git a/lib/libxtrans/Makefile.bsd-wrapper b/lib/libxtrans/Makefile.bsd-wrapper index 7a2f49896..fc74c9de1 100644 --- a/lib/libxtrans/Makefile.bsd-wrapper +++ b/lib/libxtrans/Makefile.bsd-wrapper @@ -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 diff --git a/lib/libxtrans/doc/defs.ent b/lib/libxtrans/doc/defs.ent new file mode 100644 index 000000000..30b1911cd --- /dev/null +++ b/lib/libxtrans/doc/defs.ent @@ -0,0 +1 @@ + diff --git a/lib/libxtrans/doc/xtrans.3 b/lib/libxtrans/doc/xtrans.3 new file mode 100644 index 000000000..3c569e4f8 --- /dev/null +++ b/lib/libxtrans/doc/xtrans.3 @@ -0,0 +1,1277 @@ +.\" automatically generated with docbook2mdoc xtrans.xml +.Dd $Mdocdate: May 10 2019 $ +.Dt XTRANS 3 +.Os +.Sh NAME +.Nm xtrans +.Nd X Transport Interface +.Sh THE X TRANSPORT INTERFACE +Designed by Stuart Anderson (NCR) with help from Ralph Mor (X Consortium) +.Pp +.Sy Note +.Pp +This documentation does not completely match the implementation in R6 +(as a result of some late changes made in the code). Specifically, support +was added for font server cloning, and conditional compliation was introduced +for client vs. server code. +.Sh PURPOSES AND GOALS +The X Transport Interface is intended to combine all system and +transport specific code into a single place in the source tree. +This API +should be used by all libraries, clients and servers of the X Window System. +Use of this API should allow the addition of new types of transports and +support for new platforms without making any changes to the source except +in the X Transport Interface code. +.Pp +This interface should solve the problem of multiple +.Ql #ifdef TRANSPORT +and +.Ql #ifdef PLATFORM +statements scattered throughout the source tree. +.Pp +This interface should provide enough functionality to support all +types of protocols, including connection oriented protocols such as X11 and +FS, and connection-less oriented protocols such as XDMCP. +.Sh OVERVIEW OF THE INTERFACE +The interface provides an API for use by applications. +The functions in +this API perform work that is common to all transports and systems, such +as parsing an address into a host and port number. +The functions in this +API call transport specific functions that are contained in a table whose +contents are defined at compile time. +This table contains an entry for each +type of transport. +Each entry is a record containing mostly pointers to +function that implements the interface for the given transport. +.Pp +This API does not provide an abstraction for +.Fn select +or +.Fn poll . +These functions are themselves transport independent, so an additional +interface is not needed for these functions. +It is also unclear how such +an interface would affect performance. +.Sh DEFINITION OF ADDRESS SPECIFICATION FORMAT +Addresses are specified in the following syntax, +.Bd -literal +.Ar protocol Ns Pf / Ar host : Ns Ar port +.Ed +.Pp +where +.Ar protocol +specifies a protocol family +or an alias for a protocol family. +A definition of common protocol +families is given in a later section. +.Pp +The +.Ar host +part specifies the name of a host or other +transport dependent entity that could be interpreted as a Network Service Access Point +(NSAP). +.Pp +The +.Ar port +part specifies the name of a Transport Service +Access Point (TSAP). The format of the TSAP is defined by the underlying transport +implementation, but it is represented using a string format when it is +part of an address. +.Sh INTERNAL DATA STRUCTURES +There are two major data structures associated with the transport +independent portion of this interface. +Additional data structures +may be used internally by each transport. +.Ss Xtransport +Each transport supported has an entry in the transport table. +The transport +table is an array of Xtransport records. +Each record contains all the entry +points for a single transport. +This record is defined as: +.Bd -literal +typedef struct _Xtransport { + const char *TransName; + int flags; + XtransConnInfo (*OpenCOTSClient)( + struct _Xtransport *, /* transport */ + const char *, /* protocol */ + const char *, /* host */ + const char * /* port */ + ); + XtransConnInfo (*OpenCOTSServer)( + struct _Xtransport *, /* transport */ + const char *, /* protocol */ + const char *, /* host */ + const char * /* port */ + ); + XtransConnInfo (*OpenCLTSClient)( + struct _Xtransport *, /* transport */ + const char *, /* protocol */ + const char *, /* host */ + const char * /* port */ + ); + XtransConnInfo (*OpenCLTSServer)( + struct _Xtransport *, /* transport */ + const char *, /* protocol */ + const char *, /* host */ + const char * /* port */ + ); + int (*SetOption)( + XtransConnInfo, /* connection */ + int, /* option */ + int /* arg */ + ); + int (*CreateListener)( + XtransConnInfo, /* connection */ + const char *, /* port */ + int /* flags */ + ); + int (*ResetListener)( + XtransConnInfo /* connection */ + ); + XtransConnInfo (*Accept)( + XtransConnInfo /* connection */ + ); + int (*Connect)( + XtransConnInfo, /* connection */ + const char *, /* host */ + const char * /* port */ + ); + int (*BytesReadable)( + XtransConnInfo, /* connection */ + BytesReadable_t * /* pend */ + ); + int (*Read)( + XtransConnInfo, /* connection */ + char *, /* buf */ + int /* size */ + ); + int (*Write)( + XtransConnInfo, /* connection */ + char *, /* buf */ + int /* size */ + ); + int (*Readv)( + XtransConnInfo, /* connection */ + struct iovec *, /* buf */ + int /* size */ + ); + int (*Writev)( + XtransConnInfo, /* connection */ + struct iovec *, /* buf */ + int /* size */ + ); + int (*Disconnect)( + XtransConnInfo /* connection */ + ); + int (*Close)( + XtransConnInfo /* connection */ + ); +} Xtransport; +.Ed +.Pp +The +.Fa flags +field can contain an OR of +the following masks: +.Bl -tag -width Ds +.It Dv TRANS_ALIAS +indicates that this record is providing an alias, and should +not be used to create a listener. +.It Dv TRANS_LOCAL +indicates that this is a +.Dv LOCALCONN +transport. +.It Dv TRANS_ABSTRACT +indicates that a local connection transport uses the abstract socket namespace. +.El +.Pp +Some additional flags may be set in the +.Fa flags +field by the library while it is running: +.Bl -tag -width Ds +.It Dv TRANS_DISABLED +indicates that this transport has been disabled. +.It Dv TRANS_NOLISTEN +indicates that servers should not open new listeners using this transport. +.It Dv TRANS_NOUNLINK +set by a transport backend to indicate that the endpoints for its connection +should not be unlinked. +.El +.Ss XtransConnInfo +Each connection will have an opaque +.Vt XtransConnInfo +transport connection +object allocated for it. +This record contains information specific to the +connection. +The record is defined as: +.Bd -literal +typedef struct _XtransConnInfo *XtransConnInfo; +struct _XtransConnInfo { + struct _Xtransport *transptr; + char *priv; + int flags; + int fd; + int family; + char *addr; + int addrlen; + char *peeraddr; + int peeraddrlen; +}; +.Ed +.Sh EXPOSED TRANSPORT INDEPENDENT API +This API is included in each library and server that uses it. +The API may +be used by the library, but it is not added to the public API for that +library. +This interface is simply an implementation facilitator. +This API +contains a low level set of core primitives, and a few utility functions +that are built on top of the primitives. +The utility functions exist to +provide a more familiar interface that can be used to port existing code. +.Pp +A macro is defined in Xtrans.h for TRANS(func) that creates a unique function +name depending on where the code is compiled. +For example, when built for +Xlib, +.Fn TRANS(OpenCOTSClient) +becomes +.Fn _X11TransOpenCOTSClient . +.Pp +All failures are considered fatal, and the connection should be closed +and re-established if desired. +In most cases, however, the value of +errno will be available for debugging purposes. +.Ss Core Interface API +.Bl -bullet +.It +.Ft XtransConnInfo +.Fo TRANS(OpenCOTSClient) +.Fa "const char * address" +.Fc +.Pp +This function creates a Connection-Oriented Transport that is +suitable for use by a client. +The parameter +.Fa address +contains the full address of the server to which this endpoint will be +connected. +This function returns an opaque transport connection object on +success, or +.Dv NULL +on failure. +.It +.Ft XtransConnInfo +.Fo TRANS(OpenCOTSServer) +.Fa "const char * address" +.Fc +.Pp +This function creates a Connection-Oriented Transport that is suitable +for use by a server. +The parameter +.Fa address +contains the +full address to which this server will be bound. +This function returns an +opaque transport connection object on success, or +.Dv NULL +on failure. +.It +.Ft XtransConnInfo +.Fo TRANS(OpenCLTSClient) +.Fa "const char * address" +.Fc +.Pp +This function creates a Connection-Less Transport that is suitable for +use by a client. +The parameter +.Fa address +contains the +full address of the server to which this endpoint will be connected. +This +function returns an opaque transport connection object on success, or +.Dv NULL +on failure. +.It +.Ft XtransConnInfo +.Fo TRANS(OpenCLTSServer) +.Fa "const char * address" +.Fc +.Pp +This function creates a Connection-Less Transport that is suitable for +use by a server. +The parameter +.Fa address +contains the +full address to which this server will be bound. +This function returns an +opaque transport connection object on success, or +.Dv NULL +on failure. +.It +.Ft int +.Fo TRANS(SetOption) +.Fa "XtransConnInfo connection" +.Fa "int option" +.Fa "int arg" +.Fc +.Pp +This function sets transport options, similar to the way +.Fn setsockopt +and +.Fn ioctl +work. +The parameter +.Fa connection +is an endpoint +that was obtained from +.Fn _XTransOpen* +functions. +The parameter +.Fa option +contains the option that will +be set. +The actual values for +.Fa option +are defined in a +later section +.Pq Sx Transport_Option_Definition . +The parameter +.Fa arg +can be used to pass +in an additional value that may be required by some options. +This function returns 0 on success and -1 on failure. +.Pp +.Sy Note +.Pp +Based on current usage, the complimentary function +.Fn TRANS(GetOption) +is not necessary. +.It +.Ft int +.Fo TRANS(CreateListener) +.Fa "XtransConnInfo connection" +.Fa "const char * port" +.Fa "int flags" +.Fc +.Pp +This function sets up the server endpoint for listening. +The parameter +.Fa connection +is an endpoint that was obtained from +.Fn TRANS(OpenCOTSServer) +or +.Fn TRANS(OpenCLTSServer) . +The parameter +.Fa port +specifies the port to which this endpoint +should be bound for listening. +If port is +.Dv NULL , +then the transport may attempt to allocate any available TSAP for this +connection. +If the transport cannot support this, then this function will +return a failure. +The +.Fa flags +parameter can be set +to +.Dv ADDR_IN_USE_ALLOWED +to allow the call to the underlying +binding function to fail with a +.Er EADDRINUSE +error +without causing the +.Fn TRANS(CreateListener) +function itself to fail. +This function return 0 on success and -1 on failure. +.It +.Ft int +.Fo TRANS(ResetListener) +.Fa "XtransConnInfo connection" +.Fc +.Pp +When a server is restarted, certain listen ports may need to be reset. +For example, unix domain needs to check that the file used for +communication has not been deleted. +If it has, it must be recreated. +The parameter +.Fa connection +is an opened and bound +endpoint that was obtained from +.Fn TRANS(OpenCOTSServer) +and passed to +.Fn TRANS(CreateListener) . +This function will return one of the following values: +.Dv TRANS_RESET_NOOP , +.Dv TRANS_RESET_NEW_FD , +or +.Dv TRANS_RESET_FAILURE . +.It +.Ft XtransConnInfo +.Fo TRANS(Accept) +.Fa "XtransConnInfo connection" +.Fc +.Pp +Once a connection indication is received, this function can be called to +accept the connection. +The parameter +.Fa connection +is +an opened and bound endpoint that was obtained from +.Fn TRANS(OpenCOTSServer) +and passed to +.Fn TRANS(CreateListener) . +This function will return a +new opaque transport connection object upon success, +.Dv NULL +otherwise. +.It +.Ft int +.Fo TRANS(Connect) +.Fa "XtransConnInfo connection" +.Fa "const char * address" +.Fc +.Pp +This function creates a connection to a server. +The parameter +.Fa connection +is an endpoint that was obtained +from +.Fn TRANS(OpenCOTSClient) . +The parameter +.Fa address +specifies the TSAP to which this endpoint +should connect. +If the protocol is included in the address, it will be +ignored. +This function returns 0 on success and -1 on failure. +.It +.Ft int +.Fo TRANS(BytesReadable) +.Fa "XtransConnInfo connection" +.Fa "BytesReadable_t * pend" +.Fc +.Pp +This function provides the same functionality as the +.Fn BytesReadable +macro. +.It +.Ft int +.Fo TRANS(Read) +.Fa "XtransConnInfo connection" +.Fa "char * buf" +.Fa "int size" +.Fc +.Pp +This function will return the number of bytes requested on a COTS +connection, and will return the minimum of the number bytes requested or +the size of the incoming packet on a CLTS connection. +.It +.Ft int +.Fo TRANS(Write) +.Fa "XtransConnInfo connection" +.Fa "char * buf" +.Fa "int size" +.Fc +.Pp +This function will write the requested number of bytes on a COTS +connection, and will send a packet of the requested size on a CLTS connection. +.It +.Ft int +.Fo TRANS(Readv) +.Fa "XtransConnInfo connection" +.Fa "struct iovec * buf" +.Fa "int size" +.Fc +.Pp +Similar to +.Fn TRANS(Read) . +.It +.Ft int +.Fo TRANS(Writev) +.Fa "XtransConnInfo connection" +.Fa "struct iovec * buf" +.Fa "int size" +.Fc +.Pp +Similar to +.Fn TRANS(Write) . +.It +.Ft int +.Fo TRANS(Disconnect) +.Fa "XtransConnInfo connection" +.Fc +.Pp +This function is used when an orderly disconnect is desired. +This function +breaks the connection on the transport. +It is similar to the socket function +.Fn shutdown . +.It +.Ft int +.Fo TRANS(Close) +.Fa "XtransConnInfo connection" +.Fc +.Pp +This function closes the transport, unbinds it, and frees all resources that +was associated with the transport. +If a +.Fn TRANS(Disconnect) +call was not made on the connection, a disorderly disconnect may occur. +.It +.Ft int +.Fo TRANS(IsLocal) +.Fa "XtransConnInfo connection" +.Fc +.Pp +Returns TRUE if it is a local transport. +.It +.Ft int +.Fo TRANS(GetMyAddr) +.Fa "XtransConnInfo connection" +.Fa "int * familyp" +.Fa "int * addrlenp" +.Fa "Xtransaddr ** addrp" +.Fc +.Pp +This function is similar to +.Fn getsockname . +This function will allocate space for the address, so it must be freed by +the caller. +Not all transports will have a valid address until a connection +is established. +This function should not be used until the connection is +established with +.Fn Connect +or +.Fn Accept . +.It +.Ft int +.Fo TRANS(GetPeerAddr) +.Fa "XtransConnInfo connection" +.Fa "int * familyp" +.Fa "int * addrlenp" +.Fa "Xtransaddr ** addrp" +.Fc +.Pp +This function is similar to +.Fn getpeername . +This function will allocate space for the address, so it must be freed by +the caller. +Not all transports will have a valid address until a connection +is established. +This function should not be used until the connection is +established with +.Fn Connect +or +.Fn Accept . +.It +.Ft int +.Fo TRANS(GetConnectionNumber) +.Fa "XtransConnInfo connection" +.Fc +.Pp +Returns the file descriptor associated with this transport. +.It +.Ft int +.Fo TRANS(MakeAllCOTSServerListeners) +.Fa "const char * port" +.Fa "int * partial_ret" +.Fa "int * count_ret" +.Fa "XtransConnInfo ** connections_ret" +.Fc +.Pp +This function should be used by most servers. +It will try to establish +a COTS server endpoint for each transport listed in the transport table. +.Fa partial_ret +will be set to +.Dv True +if +only a partial network could be created. +.Fa count_ret +is +the number of transports returned, and +.Fa connections_ret +is the list of transports. +.It +.Ft int +.Fo TRANS(MakeAllCLTSServerListeners) +.Fa "const char * port" +.Fa "int * partial_ret" +.Fa "int * count_ret" +.Fa "XtransConnInfo ** connections_ret" +.Fc +.Pp +This function should be used by most servers. +It will try to establish a +CLTS server endpoint for each transport listed in the transport table. +.Fa partial_ret +will be set to +.Dv True +if +only a partial network could be created. +.Fa count_ret +is +the number of transports returned, and +.Fa connections_ret +is the list of transports. +.El +.Ss Utility API +This section describes a few useful functions that have been implemented on +top of the Core Interface API. +These functions are being provided as a +convenience. +.Bl -bullet +.It +.Ft int +.Fo TRANS(ConvertAddress) +.Fa "int * familyp" +.Fa "int * addrlenp" +.Fa "Xtransaddr * addrp" +.Fc +.Pp +This function converts a sockaddr based address to an X authorization based +address (ie +.Dv AF_INET , +.Dv AF_UNIX +to the X +protocol definition (ie +.Dv FamilyInternet , +.Dv FamilyLocal ) ) . +.El +.Sh TRANSPORT OPTION DEFINITION +The following options are defined for the +.Fn TRANS(SetOption) +.Pq Sx TRANSSetOption +function. +If an OS or transport does not support any of these options, +then it will silently ignore the option. +.Bl -bullet +.It +.Dv TRANS_NONBLOCKING +.Pp +This option controls the blocking mode of the connection. +If the argument +is set to 1, then the connection will be set to blocking. +If the argument +is set to 0, then the connection will be set to non- blocking. +.It +.Dv TRANS_CLOSEONEXEC +.Pp +This option determines what will happen to the connection when an exec is +encountered. +If the argument is set to 1, then the connection will be +closed when an exec occurs. +If the argument is set to 0, then the +connection will not be closed when an exec occurs. +.El +.Sh HIDDEN TRANSPORT DEPENDENT API +The hidden transport dependent functions are placed in the Xtransport record. +These function are similar to the Exposed Transport Independent API, but +some of the parameters and return values are slightly different. +Stuff like +the +.Ql #ifdef SUNSYSV +should be handled inside these functions. +.Bl -bullet +.It +.Ft XtransConnInfo +.Fo "* OpenCOTSClient" +.Fa "struct _Xtransport * thistrans" +.Fa "const char * protocol" +.Fa "const char * host" +.Fa "const char * port" +.Fc +.Pp +This function creates a Connection-Oriented Transport. +The parameter +.Fa thistrans +points to an Xtransport entry in the +transport table. +The parameters +.Fa protocol , +.Fa host , +and +.Fa port , +point to +strings containing the corresponding parts of the address that was passed into +.Fn TRANS(OpenCOTSClient) +.Pq Sx TRANSOpenCOTSClient . +This function must allocate and initialize the contents of the XtransConnInfo +structure that is returned by this function. +This function will open the +transport, and bind it into the transport namespace if applicable. +The local +address portion of the XtransConnInfo structure will also be filled in by +this function. +.It +.Ft XtransConnInfo +.Fo "* OpenCOTSServer" +.Fa "struct _Xtransport * thistrans" +.Fa "const char * protocol" +.Fa "const char * host" +.Fa "const char * port" +.Fc +.Pp +This function creates a Connection-Oriented Transport. +The parameter +.Fa thistrans +points to an Xtransport entry in the +transport table. +The parameters +.Fa protocol , +.Fa host , +and +.Fa port +point to +strings containing the corresponding parts of the address that was passed into +.Fn TRANS(OpenCOTSServer) +.Pq Sx TRANSOpenCOTSServer . +This function must allocate and initialize the contents of the +XtransConnInfo structure that is returned by this function. +This function +will open the transport. +.It +.Ft XtransConnInfo +.Fo "* OpenCLTSClient" +.Fa "struct _Xtransport * thistrans" +.Fa "const char * protocol" +.Fa "const char * host" +.Fa "const char * port" +.Fc +.Pp +This function creates a Connection-Less Transport. +The parameter +.Fa thistrans +points to an Xtransport entry in the +transport table. +The parameters +.Fa protocol , +.Fa host , +and +.Fa port +point to strings +containing the corresponding parts of the address that was passed into +.Fn TRANS(OpenCLTSClient) +.Pq Sx TRANSOpenCLTSClient . +This function must allocate and initialize the contents of the XtransConnInfo +structure that is returned by this function. +This function will open the +transport, and bind it into the transport namespace if applicable. +The +local address portion of the XtransConnInfo structure will also be filled +in by this function. +.It +.Ft XtransConnInfo +.Fo "* OpenCLTSServer" +.Fa "struct _Xtransport * thistrans" +.Fa "const char * protocol" +.Fa "const char * host" +.Fa "const char * port" +.Fc +.Pp +This function creates a Connection-Less Transport. +The parameter +.Fa thistrans +points to an Xtransport entry in the +transport table. +The parameters +.Fa protocol , +.Fa host , +and +.Fa port +point to strings +containing the corresponding parts of the address that was passed into +.Fn TRANS(OpenCLTSServer) +.Pq Sx TRANSOpenCLTSServer . +This function must allocate and initialize the contents of the +XtransConnInfo structure that is returned by this function. +This +function will open the transport. +.It +.Ft int +.Fo SetOption +.Fa "struct _Xtransport * thistrans" +.Fa "int option" +.Fa "int arg" +.Fc +.Pp +This function provides a transport dependent way of implementing the +options defined by the X Transport Interface. +In the current prototype, +this function is not being used, because all of the options defined so far +are transport independent. +This function will have to be used if a radically +different transport type is added, or a transport dependent option is defined. +.It +.Ft int +.Fo CreateListener +.Fa "struct _Xtransport * thistrans" +.Fa "const char *port" +.Fa "int flags" +.Fc +.Pp +This function takes a transport endpoint opened for a server, and sets it +up to listen for incoming connection requests. +The parameter +.Fa port +contains the port portion of the address that was passed to the Open function. +The parameter +.Fa flags +should be set to +.Dv ADDR_IN_USE_ALLOWED +if the underlying transport endpoint +may be already bound and this should not be considered +as an error. +Otherwise flags should be set to 0. This is used by IPv6 code, +where the same socket can be bound to both an IPv6 address and then to a +IPv4 address. +This function will bind the transport into the transport +name space if applicable, and fill in the local address portion of the +XtransConnInfo structure. +The transport endpoint will then be set to +listen for incoming connection requests. +.It +.Ft int +.Fo ResetListener +.Fa "struct _Xtransport * thistrans" +.Fc +.Pp +This function resets the transport for listening. +.It +.Ft XtransConnInfo +.Fo Accept +.Fa "struct _Xtransport * thistrans" +.Fc +.Pp +This function creates a new transport endpoint as a result of an +incoming connection request. +The parameter +.Fa thistrans +is the endpoint +that was opened for listening by the server. +The new endpoint is +opened and bound into the transport’s namespace. +A XtransConnInfo +structure describing the new endpoint is returned from this function +.It +.Ft int +.Fo Connect +.Fa "struct _Xtransport * thistrans" +.Fa "const char * host" +.Fa "const char * port" +.Fc +.Pp +This function establishes a connection to a server. +The parameters +.Fa host +and +.Fa port +describe the server to which the connection should be +established. +The connection will be established so that +.Fn Read +and +.Fn Write +call can be made. +.It +.Ft int +.Fo BytesReadable +.Fa "struct _Xtransport * thistrans" +.Fa "BytesReadable_t * pend" +.Fc +.Pp +This function replaces the +.Fn BytesReadable +macro. +This allows each transport to have its own mechanism for determining +how much data is ready to be read. +.It +.Ft int +.Fo Read +.Fa "struct _Xtransport * thistrans" +.Fa "char * buf" +.Fa "int size" +.Fc +.Pp +This function reads +.Fa size +bytes into +.Fa buf +from the connection. +.It +.Ft int +.Fo Write +.Fa "struct _Xtransport * thistrans" +.Fa "char * buf" +.Fa "int size" +.Fc +.Pp +This function writes +.Fa size +bytes from +.Fa buf +to the connection. +.It +.Ft int +.Fo Readv +.Fa "struct _Xtransport * thistrans" +.Fa "struct iovec * buf" +.Fa "int size" +.Fc +.Pp +This function performs a +.Fn readv +on the connection. +.It +.Ft int +.Fo Writev +.Fa "struct _Xtransport * thistrans" +.Fa "struct iovec * buf" +.Fa "int size" +.Fc +.Pp +This function performs a +.Fn writev +on the connection. +.It +.Ft int +.Fo Disconnect +.Fa "struct _Xtransport * thistrans" +.Fc +.Pp +This function initiates an orderly shutdown of a connection. +If a +transport does not distinguish between orderly and disorderly +disconnects, then a call to this function will have no affect. +.It +.Ft int +.Fo Close +.Fa "struct _Xtransport * thistrans" +.Fc +.Pp +This function will break the connection, and close the endpoint. +.El +.Sh CONFIGURATION +The implementation of each transport can be platform specific. +It is expected +that existing connection types such as +.Dv TCPCONN , +.Dv UNIXCONN , +.Dv LOCALCONN , +and +.Dv STREAMSCONN +will be replaced with flags for each +possible transport type. +.Pp +In X11R6, the below flags to enable transport types were set in +.Dv ConnectionFlags +in the +.Pa vendor.cf +or +.Pa site.def +config files. +.Pp +In X11R7 modular releases, these flags are set when running +.Pa configure +scripts which include the +.Fn XTRANS_CONNECTION_FLAGS +macro from +.Pa xtrans.m4 . +.Bl -ohang +.It Table Row +.Bl -dash -compact +.It +.Ql #define +.It +configure flag +.It +Description +.El +.It Table Row +.Bl -dash -compact +.It +.Dv TCPCONN +.It +.Fl -enable-tcp-transport +.It +Enables the INET (IPv4) Domain Socket based transport +.El +.It Table Row +.Bl -dash -compact +.It +.Dv IPv6 +.It +.Fl -enable-ipv6 +.It +Extends +.Dv TCPCONN +to enable IPv6 Socket based transport +.El +.It Table Row +.Bl -dash -compact +.It +.Dv UNIXCONN +.It +.Fl -enable-unix-transport +.It +Enables the UNIX Domain Socket based transport +.El +.It Table Row +.Bl -dash -compact +.It +.Dv STREAMSCONN +.It +.Em Not available in X11R7 +.It +Enables the TLI based transports +.El +.It Table Row +.Bl -dash -compact +.It +.Dv LOCALCONN +.It +.Fl -enable-local-transport +.It +Enables the SYSV Local connection transports +.El +.It Table Row +.Bl -dash -compact +.It +.Dv DNETCONN +.It +.Em Not available in X11R7 +.It +Enables the DECnet transports +.El +.El +.Sh TRANSPORT SPECIFIC DEFINITIONS +.Bl -ohang +.It Table Row +.Bl -dash -compact +.It +Protocol Family +.It +Address Component +.El +.It Table Row +.Bl -dash -compact +.It +protocol +.It +host +.It +port +.El +.It Table Row +.Bl -dash -compact +.It +Internet +.It +inet inet6 tcp udp +.It +name of an internet addressable host +.It +string containing the name of a service or a valid port number. +Example: "xserver0", "7100" +.El +.It Table Row +.Bl -dash -compact +.It +DECnet +.It +decnet +.It +name of a DECnet addressable host +.It +string containing the complete name of the object. +Example: "X$X0" +.El +.It Table Row +.Bl -dash -compact +.It +NETware +.It +ipx +.It +name of a NETware addressable host +.It +Not sure of the specifics yet. +.El +.It Table Row +.Bl -dash -compact +.It +OSI +.It +osi +.It +name of an OSI adressable host. +.It +Not sure of the specifics yet. +.El +.It Table Row +.Bl -dash -compact +.It +Local +.It +local pts named sco isc +.It +(ignored) +.It +String containing the port name, ie "xserver0", "fontserver0". +.El +.El +.Sh IMPLEMENTATION NOTES +This section refers to the prototype implementation that is being developed +concurrently with this document. +This prototype has been able to flush out many +details and problems as the specification was being developed. +.Pp +In X11R6, all of the source code for this interface was located in +.Pa xc/lib/xtrans . +.Pp +In X11R7, all of the source code for this interface is delivered via +the +.Sy lib/libxtrans +modular package from X.Org, +and is installed under +.Pa +.Ar ${prefix} Ns /X11/Xtrans +so that other modules may find it when they build. +.Pp +All functions names in the source are of the format +.Fn TRANS(func) . +The +.Fn TRANS +macro is defined as +.Bd -literal +#define TRANS(func) _PROTOCOLTrans##func +.Ed +.Pp +.Dv PROTOCOL +will be uniquely defined in each directory +where this code is compiled. +.Dv PROTOCOL +will be defined to be the name of the protocol +that is implemented by the library or server, such as X11, FS, and ICE. +.Pp +All libraries and servers that use the X Transport Interface should have a new +file called +.Pa +.Ar TRANSPORT Ns trans.c . +This file will include the transports based on the configuration flags +provided by the +.Pa configure +script. +Below is an +example +.Pa xfstrans.c +for the font server. +.Bd -literal +#include "config.h" +#define FONT_t 1 +#define TRANS_REOPEN 1 +#define TRANS_SERVER 1 +#include +.Ed +.Pp +The source files for this interface are listed below. +.Bl -tag -width Ds +.It Pa Xtrans.h +Function prototypes and defines for the Transport Independent API. +.It Pa Xtransint.h +Used by the interface implementation only. +Contains the internal data structures. +.It Pa Xtranssock.c +Socket implementation of the Transport Dependent API. +.It Pa Xtranstli.c +TLI implementation of the Transport Dependent API. +.It Pa Xtransdnet.c +DECnet implementation of the Transport Dependent API. +.It Pa Xtranslocal.c +Implementation of the Transport Dependent API for SYSV Local connections. +.It Pa Xtrans.c +Exposed Transport Independent API Functions. +.It Pa Xtransutil.c +Collection of Utility functions that use the X Transport Interface. +.El +.Pp +The file +.Pa Xtransint.h +contains much of the transport +related code that was previously in +.Pa Xlibint.h +and +.Pa Xlibnet.h . +This will make the definitions available for all transport users. +This +should also obsolete the equivalent code in other libraries. +.Sh AUTHORS +.An -nosplit +.Sy X Consortium Standard +.Pp +.An -split +.An Stuart Anderson , +NCR Corporation +.An Ralph Mor , +X Consortium +.An Alan Coopersmith , +Oracle Corp. +X Version 11, Release 6 +Version 1.2 +Copyright \(co 1993, 1994 +NCR Corporation - Dayton, Ohio, USA +.Ss Legal Notice +All Rights Reserved +.Pp +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, provided +that the above copyright notice appear in all copies and that both that +copyright notice and this permission notice appear in supporting +documentation, and that the name NCR not be used in advertising +or publicity pertaining to distribution of the software without specific, +written prior permission. +NCR makes no representations about the +suitability of this software for any purpose. +It is provided "as is" +without express or implied warranty. +.Pp +NCR DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN +NO EVENT SHALL NCR BE LIABLE FOR ANY SPECIAL, INDIRECT OR +CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS +OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.Ss Legal Notice +Copyright \(co 1993, 1994, 2002 The Open Group +.Pp +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 +OPEN GROUP 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 Open Group 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 Open Group. +.Pp +X Window System is a trademark of The Open Group, Inc.