This is /home/user/nico/projekte/gpm/gpm/doc/gpm.info, produced by makeinfo version 4.11 from /home/user/nico/projekte/gpm/gpm/doc/gpm.texinfo. INFO-DIR-SECTION Miscellaneous START-INFO-DIR-ENTRY * Gpm: (gpm). A server wich hands mouse events to non-X programs. END-INFO-DIR-ENTRY This file is a user's and programmer's manual for gpm 1.20.3pre6. Copyright (C) 1994,1995,1998 Alessandro Rubini Copyright (C) 2001-2008 Nico Schottelius Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. This file documents the 1.20.3pre6 release of the "General Purpose Mouse" (gpm) server for the Linux text console (6th of April 2008).  File: gpm.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) gpm *** * Menu: * Overview:: * Server Invocation:: * Gpm Internals:: * The ClientLib:: * Demo Clients:: * Type Index:: * Function Index:: * Variable Index::  File: gpm.info, Node: Overview, Next: Server Invocation, Prev: Top, Up: Top 1 Overview ********** The "gpm" package is a mouse server for the Linux console. It is meant to provide cooked mouse events to text-only applications, such as editors and simple menu-based apps. The daemon is also able to repeat packets in "msc" format to a graphic application. This last feature is meant to override the single-open problem of busmice. The roots of `gpm' come from the `selection-1.5' package, by Andrew Haylett. The first application to support the mouse has been The Midnight Commander, by Miguel de Icaza. `mc-0.11' and later releases offer mouse support if you have the mouse server running on your system. The file `t-mouse.el' provides support for using the mouse from within Emacs. *Note Emacs Support::. As of release 0.96, a default-handler is released with gpm, and can be used to handle Control-Mouse events to draw menus on the screen. The `gpm-root' program, however, needs kernel 1.1.73 or newer. *Note gpm-root::. Release 1.00 has been an incompatible one (is is incompatible with releases older than 0.97), but is compatible with the kernel-level mouse driver (available as `kmouse-?.??.tar.gz' from the mirrors of `ftp://tsx-11.mit.edu'. With 1.0 the high level library is available, together with a demonstration/test program. A small utility to help in detecting your mouse-type is also included. As of release 1.20.0 the default device is removed. Now -m is a must. Release 1.20.1 introduces the must for -t and a specific way to use -m,-t,-o: Now you've got to use -m first, then -t and at last -o. This seems to be more complex, but makes using of multiply mice possible with clean code. * Menu: * Building the Release::  File: gpm.info, Node: Building the Release, Prev: Overview, Up: Overview 1.1 Compiling and Installing ============================ Just say `./configure && make && make install' to your shell. You'll need gpm installed to compile the latest release of The Midnight Commander with mouse support enabled. Binaries are not released with the package because it's safer for you to compile the package by yourself.  File: gpm.info, Node: Server Invocation, Next: Gpm Internals, Prev: Overview, Up: Top 2 Server Invocation ******************* The `gpm' executable is meant to act like a daemon (thus, `gpmd' would be a better name for it). This section is meant to describe the command-line options for `gpm', while its internals are outlined in the next section. *Note Gpm Internals::. Due to restrictions in the `ioctl(TIOCLINUX)' system call, `gpm' must be run by the superuser. The restrictions have been added in the last 1.1 kernels to fix a security hole related to selection and screen dumping. The server can be configured to match the user's taste, and any application using the mouse will inherit the server's attitude. From release 1.02 up to 1.19.2 is was possible for any user logged on the system console to change the mouse _feeling_ using the -q option. This is no longer possible for security reasons. As of 0.97 the server program puts itself in the background. To kill `gpm' you can just reinvoke it with the `-k' cmdline switch, although `killall gpm' can be a better choice. * Menu: * Special Commands:: * Command Line:: * Bugs and Problems:: * Mouse Types::  File: gpm.info, Node: Special Commands, Next: Command Line, Prev: Server Invocation, Up: Server Invocation 2.1 Special Commands ==================== Version 1.10 adds the capability to execute _special_ commands on certain circumstances. Special commands default to rebooting and halting the system, but the user can specify his/her personal choice. The capability to invoke commands using the mouse is a handy one for programmers, because it allows to issue a clean shutdown when the keyboard is locked and no network is available to restore the system to a sane state. Special commands are toggled by triple-clicking the left and right button - an unlikely event during normal mouse usage. The easiest way to triple-click is pressing one of the buttons and triple-click the other one. When special processing is toggled, a message appears on the console (and the speaker beeps twice, if you have a speaker); if the user releases all the buttons and presses one of them again within three seconds, then the special command corresponding to the button is executed. The default special commands are: LEFT BUTTON Reboot the system by signalling the init process MIDDLE BUTTON (IF ANY) Execute `/sbin/shutdown -h now' RIGHT BUTTON Execute `/sbin/shutdown -r now' The `-S' command line switch enables special command processing and allows to change the three special commands. To accept the default commands use `-S ""' (i.e., specify an empty argument). To specify your own commands, use a colon-separated list to specify commands associated to the left, middle and right button. If any of the commands is empty, it is interpreted as `send a signal to the init process'. This particular operation is supported, in addition to executing external commands, because sometimes bad bugs put the system to the impossibility to fork; in these rare case the programmer should be able to shutdown the system anyways, and killing init from a running process is the only way to do it. As an example, `-S ":telinit 1:/sbin/halt"', associates killing init to the left button, going single user to the middle one, and halting the system to the right button. System administrators should obviously be careful about special commands, as gpm runs with superuser permissions. Special commands are best suited for computers whose mouse can be physically accessed only by trusted people.  File: gpm.info, Node: Command Line, Next: Bugs and Problems, Prev: Special Commands, Up: Server Invocation 2.2 Command Line Options ======================== Available command line options are the following: `-a ACCEL' Set the acceleration value used when a single motion event is longer than DELTA (see `-d'). `-A[LIMIT]' Start up with selection pasting disabled. This is intended as a security measure; a plausible attack on a system seems to be to stuff a nasty shell command into the selection buffer (`rm -rf /') including the terminating line break, then all the victim has to do is click the middle mouse button .. As of version 1.17.2, this has developed into a more general aging mechanism; the gpm daemon can disable (_age_) selection pasting automatically after a period of inactivity. To enable this mode just give the optional LIMIT parameter (no space in between !) which is interpreted as the time in seconds for which a selection is considered valid and pastable. As of version 1.15.7, a trivial program called `disable-paste' is provided. The following makes a good addition to `/etc/profile' if you allow multiple users to work on your console. `case $( /usr/bin/tty ) in /dev/tty[0-9]*) /usr/bin/disable-paste ;; esac' `-b BAUD' Set the baud rate. `-B SEQUENCE' Set the button sequence. `123' is the normal sequence, `321' can be used by left-handed people, and `132' can be useful with two-button mice (especially within Emacs). All the button permutations are allowable. `-d DELTA' Set the delta value. When a single motion event is longer than DELTA, ACCEL is used as a multiplying factor. (Must be 2 or above) `-D' Do not automatically enter background operation when started, and log messages to the standard error stream, not the syslog mechanism. This is useful for debugging; in previous releases it was done with a compile-time option. `-g NUMBER' With glidepoint devices, emulate the specified button with tapping. NUMBER must be `1', `2', or `3', and refers to the button number _before_ the `-B' button remapping is performed. This option applies to the mman and ps2 decoding. No button is emulated by default because the ps2 tapping is incompatible with some normal ps2 mice `-h' Print a summary of command line options. `-i INTERVAL' Set INTERVAL to be used as an upper time limit for multiple clicks. If the interval between button-up and button-down events is less than LIMIT, the press is considered a double or triple click. Time is in milliseconds. `-k' Kill a running gpm. This can be used by busmouse users to kill gpm before running X (unless they use `-R' or the single-open limitation is removed from the kernel). `-l CHARSET' Choose the `inword()' look up table. The CHARSET argument is a list of characters. `-' is used to specify a range and `\ ' is used to escape the next character or to provide octal codes. Only visible character can appear in CHARSET because control characters can't appear in text-mode video memory, whence selection is cut. `-m FILENAME' Choose the mouse file to open. Must be before -t and -o. `-M' Enable multiple mode. The daemon will read two different mouse devices. Any subsequent option will refer to the second device, while any preceding option will be used for the first device. This option automatically forces the _repeater_ (`-R') option on. `-o LIST-OF-EXTRA-OPTIONS' The option works similary to the "-o" option of mount; it is used to specify a list of "extra options" that are specific to each mouse type. The list is comma-separated. The options `dtr', `rts' or `both' are used by the serial initialization to toggle the modem lines like, compatibly with earlier gpm versions; note however that using -o dtr associated with non-plain-serial mouse types may now generate an error. *Note Mouse Types::. And by the way, use -o after -m and after -t. `-p' Forces the pointer to be visible while selecting. This is the behaviour of `selection-1.7', but it is sometimes confusing. The default is not to show the pointer, which can be confusing as well. `-r NUMBER' Set the responsiveness. A higher responsiveness is used for a faster cursor motion. `-R[NAME]' Causes `gpm' to act as a repeater: any mouse data received while in graphic mode will be produced on the fifo `/dev/gpmdata' in protocol NAME, given as an optional argument (no space in between !). In principle, you can use the same names as for the `-t' option, although repeating into some protocols may not be implemented for a while. *Note Mouse Types::. In addition, you can specify `raw' as the NAME, to repeat the mouse data byte by byte, without any protocol translation. If NAME is omitted, it defaults to `msc'. Using gpm in repeater mode, you can configure the X server to use its fifo as a mouse device. This option is useful for bus-mouse owners to override the single-open limitation. It is also an easy way to manage those stupid dual-mode mice which force you to keep the middle button down while changing video mode. The option is forced on by the `-M' option. `-s NUMBER' Set the sample rate for the mouse device. `-S COMMANDS' Enable special-command processing, and optionally specify custom commands as a colon-separated list. See above for a detailed description of special commands. `-t NAME' Set the mouse type. Use `-t help' to get a list of allowable types. Since version 1.18.1, the list also shows which protocols are available as repeaters (see -R above), by marking them with an asterisk ("*"). *Note Mouse Types::. Use -t after you selected the mouse device with -m. `-v' Print version information and exit. `-2' Force two buttons. This means that the middle button, if any, will be taken as it was the right one. `-3' Force three buttons. By default the mouse is considered to be a 2-buttons one, until the middle button is pressed. If three buttons are there, the right one is used to extend the selection, and the middle one is used to paste it. Beware: if you use the `-3' option with a 2-buttons mouse, you won't be able to paste the selection. * Menu: * Bugs and Problems::  File: gpm.info, Node: Bugs and Problems, Next: Mouse Types, Prev: Command Line, Up: Server Invocation 2.3 Bugs and Problems ===================== The `gpm' server may have problems interacting with X: if your mouse is a single-open device (i.e. a bus mouse), you should kill `gpm' before starting X, or use the `-R' option (see above). To kill `gpm' just invoke `gpm -k'. This problem doesn't apply to serial mice. Two instances of gpm can't run on the same system. If you have two mice use the `-M' option (see above). While the current console is in graphic mode, `gpm' sleeps until text mode is back (unless `-R' is used). Thus, it won't reply to clients. Anyways, it is unlikely that mouse-eager clients will spur out in hidden consoles. The clients shipped out with gpm are not updated, thus there are potential security risks when using them.  File: gpm.info, Node: Mouse Types, Prev: Bugs and Problems, Up: Server Invocation 2.4 Mouse Types =============== This section of the gpm documentation manual describes the various pointer types currently available in gpm. If you look at the source code, you'll find that pointer-specific code is confined to `mice.c' (while it used to only include mouse decoders, gpm now supports tablets and touchscreens as well). The mouse type is specified on command line with the `-t' option. The option takes an argument, which represents the name of a mouse type. Each type can be associated to different names. For old mouse types, one name is the old selection-compatible name, and another is the XFree name. After version 1.18.1 of gpm, the number of synonyms was made arbitrary and the actual name being used is made available to the function responsible for mouse initialization. Therefore it is possible for a mouse decoder to behave slightly differently according to the name being used for the device (if this feature was already present, we wouldn't have for example ms+ and ms+lr as different mouse types). The initialization procedure of each mouse type can also receive extra option, by means of the -o command line option. Since interpretation of the option string is decoder-specific, the allowed options are described in association to each mouse type. When no description of option strings is provided, that means the option string is unused for that mouse type and specifying one generates an error. When the document refer to "standard serial options" it means that one of -o dtr, -o rts, -o both can be specified to toggle the control lines of the serial port. The following mouse type are corrently recognized: `bare Microsoft' The Microsoft protocol, without any extension. It only reports two buttons. If your device has three, you should either try running the mman decoder or msc. In the latter case, you need to tell the mouse to talk msc protocol by toggling the DTR and RTS lines (with one of -o drt, -o rts or -o both) or invoking `gpm -t msc' while keeping the middle button pressed. Very annoying, indeed. This mouse decoder accepts standard serial options, although they should not be needed. `ms' This is the original Microsoft protocol, with a middle-button extension. Some old two-button devices send some spurious packets which can be misunderstood as middle-button events. If this is your case, use the `bare' mouse type. Some new two-button devices are "plug and play", and they don't play fair at all; in this case try -t pnp. Many (most) three-button devices that use the microsoft protocol fail to report some middle-button events during mouse motion. Since the protocol does not distinguish between the middle button going up and the middle button going down it would be liable to get out of step, so this decoder declares the middle button to be up whenever the mouse moves. This prevents dragging with the middle button, so you should probably use `-t ms+lr' instead of this decoder, especially if you want to use X. This mouse decoder accepts standard serial options, although they should not be needed. `ms+' This is the same as `-t ms' except that the middle button is not reset during mouse motion. So you can drag with the middle button. However, if your mouse exhibits the usual buggy behaviour the decoder is likely to get out of step with reality, thinking the middle button is up when it's down and vice versa. You should probably use `-t ms+lr' instead of this decoder. This mouse decoder accepts standard serial options, although they should not be needed. `ms+lr' This is the same as `-t ms+' except that there is an additional facility to reset the state of the middle button by pressing the other two buttons together. Do this when the decoder gets into a confused state where it thinks the middle button is up when it's down and vice versa. (If you get sick of having to do this, please don't blame gpm; blame your buggy mouse! Note that most three-button mice that do the microsoft protocol can be made to do the MouseSystems protocol instead. The "3 Button Serial Mouse mini-HOWTO" has information about this.) This mouse decoder accepts standard serial options, although they should not be needed. `msc MouseSystems' This is the standard protocol for three-button serial devices. Some of such devices only enter MouseSystem mode if the RTS, DTR or both lines are pushed low. Thus, you may try -t msc associated with -o rts, -o dtr or -o both. `mman Mouseman' The protocol used by the new Logitech devices with three buttons. It is backward compatible with the Microsoft protocol, so if your mouse has three buttons and works with -t ms or similar decoders you may try -t mman instead to use the middle button. This mouse decoder accepts standard serial options, although they should not be needed. `sun' The protocol used on Sparc computers and a few others. This mouse decoder accepts standard serial options, although they should not be needed. `mm MMSeries' Title says it all. This mouse decoder accepts standard serial options, although they should not be needed. `logi Logitech' This is the protocol used by old serial Logitech mice. `bm BusMouse' Some bus devices use this protocol, including those produced by Logitech. `ps2 PS/2' The protocol used by most busmice. `ncr' This `type' is able to decode the pointing pen found on some laptops (the NCR 3125 pen) `wacom' The protocol used by the Wacom tablet. Since version 1.18.1 we have a new Wacom decoder, as the old one was not working with new tablets. This decoder was tested with Ultrapad, PenPartner, and Graphire tablets. Options: -o relative (default) for relative mode, -o absolute for absolute mode. `genitizer' The \"Genitizer\" tablet, in relative mode. This mouse decoder accepts standard serial options, although they should not be needed. `logim' Used to turn Logitech mice into Mouse-Systems-Compatible. Obviously, it only works with some of the Logitech mice. `pnp' This decoder works with the new mice produces by our friend Bill, and maybe with the old ones as well. The Pnp protocol is hardwired at 1200 baud and is upset by normal initialization, so this is a -t bare decoder with no initialization at all. This mouse decoder accepts standard serial options, although they should not be needed. `ms3' A decoder for the new serial IntelliMouse devices, the ones with three buttons and a protocol incompatible with older ones. The wheel is currently unused. `imps2' "IntelliMouse" on the ps/2 port. This type can also be used for a generic 2-button ps/2 mouse too, since it will auto-detect the type. `netmouse' Decodes the "Genius NetMouse" type of devices on the ps/2 port. For serial "Netmouse" devices, use the "ms3" decoder. `cal' A decoder of the "Calcomp UltraSlate device. `calr' Same as above, but in relative mode. `twid' Support for the twiddler keyboard. As of gpm-1.14 this decoder includes a char generator for the text console, but doesn't yet support X keycodes. If used with `-R', `gpm' will anyway repeat mouse events to the X server. More information about twiddler support can be found in `README.twiddler', in the gpm distribution. `syn synaptics' A decoder for the Synaptics TouchPad connected to the serial port. This mouse decoder accepts standard serial options, although they should not be needed. `synps2 synaptics_ps2' Same as above, but for the devices attached to the ps2 port. `brw' A decoder for the Fellowes Browser, a device with 4 buttons and a wheel. This mouse decoder accepts standard serial options, although they should not be needed. `js Joystick' This mouse type uses the joystick device to generate mouse events. It is only available if the header `linux/joystick.h' is found at compile time. The header (and the device as well) has been introduced only during 2.1 development, and is not present in version 2.0 of the kernel. `summa' This is a decode for the Symmagraphics of Genius tablet, run in absolute mode. A repeater is associated to this decoder, so it can -R summa can be used to generate X events even for other absolute-pointing devices, like touchscreens. To use the repeated data from X, you need a modified xf86Summa.o module. `mtouch' A decoder for the MicroTouch touch screen. Please refer to the file `README.microtouch' in the source tree of gpm for further information. In the near future, anyways, I plan to fold back to this documentation the content of that file. `gunze' A decoder for the gunze touch screen. Please refer to the file `README.gunze' in the source tree of gpm for further information. In the near future, anyways, I plan to fold back to this documentation the content of that file. The decoder accepts the following options: smooth=, debounce=. An higher smoothness results in slower motion as well; a smaller smoothness gives faster motion but, obviously, less smooth. The default smoothness is 9. The debounce time is express in milliseconds and is the minimum duration of an up-down event to be taken as a tap. Smaller bounces are ignored. `acecad' The Acecad tablet in absolute mode. `wp wizardpad' Genius WizardPad tablet  File: gpm.info, Node: Gpm Internals, Next: The ClientLib, Prev: Server Invocation, Up: Top 3 Gpm Internals *************** The server is organized as a main loop built around a `select()' system call. It responds both to mouse events and to input from the clients, which are connected to the server through a unix domain socket. The connection is used to tell the server what a client is interested in, and to get mouse events. When no clients are connected to the active console, the server runs the selection mechanism (cut and paste of text). The selection mechanism is a simple and well-designed application, whose behaviour can be cloned by clients, by telling the server to inherit the default response for certain mouse events (motion being the most interesting). * Menu: * Events:: * Margins:: * Event Types:: * Connection Details:: * Default Handlers::  File: gpm.info, Node: Events, Next: Margins, Prev: Gpm Internals, Up: Gpm Internals 3.1 Events ========== Whenever the mouse generates an event, the event is dispatched to the active client for the current console, or to the default handler, if present. Otherwise selection is run. A default handler is a client process which gets mouse events form all the virtual consoles. *Note Default Handlers::. When a client is involved, it is handled a `Gpm_Event' structure, built by the server. The fields for `Gpm_Event' are the following: `unsigned char buttons;' An or-mask of the values `GPM_B_LEFT', `GPM_B_MIDDLE' and `GPM_B_RIGHT'. It corresponds to the state of the mouse buttons when the event is reported. The current implementation of gpm allows at most three buttons. `unsigned char modifiers;' The value of the kernel variable `shift_state', as of `keyboard.c', when the event is reported. It is a bitmask value, and corresponds to the least significant byte of the value used by the `loadkeys' program. Use of symbolic names in source code is available after inclusion of `linux/keyboard.h', as exemplified in `mev.c'. `unsigned short vc;' The number of the active virtual console when the event is reported. The client is not expected to use this value, which corresponds to the controlling terminal of the client process, unless it gets events form multiple consoles. *Note Default Handlers::. `short x, y;' The position of the mouse pointer where the event is reported. It is 1-based by default, to be compatible with `selection' and `libcurses'. This behavior can be overriden, though, by setting the library variable `gpm_zerobased'. *Note Variables::. `short dx, dy;' The change in position since the last reported event. `enum Gpm_Etype type;' A bit-mask, representing the type of reported event, as described later. *Note Event Types::. `int clicks;' A counter, which is valid at button-down, drag or button-up. It can be 0, 1 or 2 to mean single, double or triple click. `enum Gpm_Margin margin;' A bit-mask, telling if the pointer has gone out of the visible screen. The indivudual bits are named `GPM_TOP', `GPM_BOT', `GPM_LFT', `GPM_RGT'. Only one of them is active at a time, to allow using `switch' on the value. Vertical outrun takes precedence on horizontal outrun. *Note Margins::.  File: gpm.info, Node: Margins, Next: Event Types, Prev: Events, Up: Gpm Internals 3.2 How margins are managed =========================== Motion and button-press events are constrained to remain within the visible screen. This means that the `x' will be within 1 and 80 and `y' will be within 1 and 25 when the console is 80x25 cells. However, a client can keep track of movements outside the screen, by using the `dx' and `dy' fields, which aren't subject to clipping. The server helps applications in detecting margin conditions by filling the `margin' field. Whenever the pointer tries to cross screen boundaries, it is forced to remain on the border, but a flag is set in `margin'. A different policy is in force for drag and button-release events. In this case the pointer is allowed to go outside the physical screen by exactly one position. This allows, for example, selecting to end of line by dragging down-left. The peculiar situation is nonetheless signaled through the `margin' flags. The client should be careful to fit the values within the screen if needed. *Note Utility Functions::.  File: gpm.info, Node: Event Types, Next: Connection Details, Prev: Margins, Up: Gpm Internals 3.3 Event Types =============== The `type' field in `Gpm_Event' is made up of bit-wide flags. The existing bit masks belong to two groups: bare events and cooked events. The bit-mask `GPM_BARE_EVENTS' is provided to extract bare events, by and-ing (`&') it with the `type' field. For any event, exactly one bit will be set in the resulting bitmask. Bare events are the following: `GPM_MOVE' A motion event, with all buttons up. `GPM_DRAG' A motion event, but one or more buttons are kept pressed. `GPM_DOWN' A button press event. The `buttons' field will report which buttons are pressed after the event. `GPM_UP' A button release event. The `buttons' field will report which buttons are being released. Note that this is different from the previous case. `GPM_ENTER' This means "enter in the current Region of Interest", and such event can only happen if the high-level library is used. When the type is `GPM_ENTER', all the other fields are undefined. *Note High Level Lib::. `GPM_LEAVE' This is only delivered by the high level library, too. Events of type `GPM_LEAVE' have all other fields undefined. Cooked events are the following: `GPM_SINGLE' This bit may be set at button-press, drag and button release events, and can be used to identify a single press. The time interval used to choose a double click from two single clicks is set by a parameter in the daemon (configurable at daemon invocation). `GPM_DOUBLE' Used to identify a double click (press, drag, release) `GPM_TRIPLE' Used to identify a triple click (press, drag, release) `GPM_MFLAG' The "motion flag" is true if some dragging happened between button-press and button-release. It can be used by those applications which respond to events at button release. It is available at drag and release.  File: gpm.info, Node: Connection Details, Next: Default Handlers, Prev: Event Types, Up: Gpm Internals 3.4 Connection Details ====================== Each virtual console has a stack of clients attached to it. They talk to gpm by writing to a control socket and get mouse events by reading it. All the clients in the stack can receive events. Gpm-1.10 and earlier only sent events to the top client, but sometimes users play with multiple programs using suspend-resume (thanks Ian). In addition to the per-console stacks, another stack is there to store default-handling clients. *Note Default Handlers::. Each client registers with the server and tells which events it is interested in. Events not managed by the client can be handled by the selection mechanism, which is compiled in the server itself. This approach simplifies writing clients which respond only to button press/release events, because highlighting the mouse pointer can be performed by the server. A default handler in turn can respond only to mouse events associated with modifier keys, so that selection is used for any mouse-only event. Clients are required to fill a `Gpm_Connect' structure and pass it to the server. The structure is made up by four `unsigned int' fields. *Note Open and Close::. `eventMask' A bitmask of the events the client wants to receive. Both bare and cooked events are allowed to appear in the mask. `defaultMask' A mask to tell which events allow a default treatment (the selection one). These are mouse events, independent of the modifier keys. `minMod' The minimum amount of modifiers required by the client. This field is used for default-handlers which manage control-mouse events without interfering with mouse-only ones. *Note Default Handlers::. `maxMod' The maximum amount of modifiers the client is willing to receive. Events featuring a modifier key not included in `maxMod' won't be passed to the client. Two more fields are there to tell about the connection itself, and you're not asked to fill them, because `Gpm_Open' will do it for you. `int pid' The process id of the connecting application. `int vc' Which virtual console to gain control of. Keyboard modifiers are used to multiplex clients on the same virtual console. You (as a programmer) don't need to care about the internal workings. They are detailed in *note Default Handlers::, but you only need to choose the right values for your application. Examples: `minMod=0; maxMod=0;' specifies a client which senses mouse-only events, but neither shift-mouse nor alt-mouse nor control-mouse. `minMod=0; maxMod=~0;' is a client which gets any mouse event. `minMod=1< /tmp/du" } button 3 { name "jump" foreground black background red border bright yellow head bright yellow "tty1" f.jptty "1" "tty2" f.jptty "2" "tty3" f.jptty "3" "tty4" f.jptty "4" "tty5" f.jptty "5" "tty6" f.jptty "6" "" f.nop "more of them..." { "tty 17" f.jptty "17" } } The syntax for the file won't be described here, being it quite apparent from the example above. Blanks and newlines are unused in parsing the file, and the layout of the file is free. Comments are allowed in the file: any hash mark (`#') found at the beginning of the line or after white space makes the parser discard anything up to the next line. To insert quotes (`"') in strings precede them with a backslash. Note that recursive menus are allowed, to any level of recursion. Keywords belong to three groups: the button keyword, the cfg keywords and the action keywords. They are all described in the table below: `button NUMBER MENU' The `button' keyword is used to introduce a menu. It is followed by the number of the relevant button (1=left, 2=middle, 3=right), an open brace, a menu and a closed brace. A menu is made up of cfg statements, followed by action statements. Cfg statements can come in any order, while the order of action statements tells the actual order in which actions will appear on the screen, top to bottom. The following statements belong to the cfg set. `name STRING' If the `name' keyword is present, the specified STRING will be used as the name for the current menu. `background COLOR' This statements is used to specify the background color to be used in the current menu. The COLOR can be specified with one of the eight canonical strings `black', `red', `cyan' etc. The background defaults to black. `foreground COLOR' This statements is used to specify the foreground color for menu items. Its value defaults to `white'. An optional `bright' keyword can appear before the actual color. `border COLOR' `border' is used to specify the border color for the menu. Its value defaults to `white'. An optional `bright' keyword can appear before the actual color. `head COLOR' `head' is used to specify the foreground color for the title of the menu. Its value defaults to `white'. An optional `bright' keyword can appear before the actual color. The following statements belong to the action set. `STRING f.fgcmd CMDSTRING' When the mouse button is released above the corresponding menu item, the CMDSTRING is pasted in the keyboard queue of the current console. This is not yet implemented. `STRING f.bgcmd CMDSTRING' When the mouse button is released above the corresponding menu item, a shell (`/bin/sh') is forked to execute the specified command, with `stdin' connected to `/dev/null', and `stdout', `stderr' connected to the active console. `STRING f.jptty TTYNUMBER' When the mouse button is released above the corresponding menu item, the console is switched to the one specified. The TTYNUMBER must be specified as a string. Any tty can be reached this way, even those which are not accessible via the keyboard. `STRING f.mktty TTYNUMBER' When the mouse button is released above the corresponding menu item, an unused console is selected, and `/sbin/mingetty' is executed in it. The current console is switched to the newly opened console. I use this command to save kernel memory by opening a single console through `/etc/inittab' and requesting the others only when i need to login. `STRING WHOLE-MENU' A menu can directly follow the label string. When the mouse pointer leaves the menu frame at the level of STRING, a second menu is posted on screen. `STRING f.lock' When the mouse button is released above the corresponding menu item, the keyboard and the screen are locked, and only the locking user or the superuser can unlock them. This is not yet implemented. `STRING f.load' The current loadavg when the menu is posted is concatenated to STRING to build the actual message displayed on screen. Nothing happens at button release. `STRING f.free' The free memory and swap when the menu is posted is concatenated to STRING to build the actual message displayed on screen. Nothing happens at button release. `STRING f.time' The current time is formatted with strftime(3), according to STRING. The resulting string is the actual message displayed on screen. Nothing happens at button release. `STRING f.pipe CMDLINE' When the mouse pointer leaves the menu frame at the level of STRING, a message box is posted on screen showing the last ten lines of the output of CMDLINE. CMDLINE is executed by `/bin/sh'. This is not yet implemented. `STRING f.nop' This does nothing, it only displays STRING on the menu. The `HOME', `LOGNAME' and `USER' environment variables are setup to the values for the invoking user before spawning an external process (`f.bgcmd', `f.pipe'). The current directory is always `/'. Known bugs have been fixed. In particular, if you invoke `gpm-root' right after `gpm', it will delay a few seconds before trying to connect to the daemon.  File: gpm.info, Node: hltest, Next: mouse-test, Prev: gpm-root, Up: Demo Clients 5.5 `hltest' ============ High-level test is a simple sample application using the high-level library. It implements something like a window manager for text windows, though it is small and unuseful. The application is meant to be read by programmers trying to use the high-level library. It is equipped with event reporting to help in understanding the internal workings.  File: gpm.info, Node: mouse-test, Prev: hltest, Up: Demo Clients 5.6 `mouse-test' ================ This experimental and incomplete application tries to help in detecting which protocol does your mouse speak. It is able to detect MouseMan devices, and to choose between `-t ms' (three-buttons aware) and `-t bare' old two-buttons-only serial mice. I know the application is buggy, but I only own one mouse device. If you are interested in this application, just call me and awake me from my laziness.  File: gpm.info, Node: Type Index, Next: Function Index, Prev: Demo Clients, Up: Top Type Index ********** [index] * Menu: * Gpm_Connect: Connection Details. (line 26) * Gpm_Event: Events. (line 13) * Gpm_Handler: Handling Functions. (line 11) * Gpm_roi: Concepts. (line 12)  File: gpm.info, Node: Function Index, Next: Variable Index, Prev: Type Index, Up: Top API Index ********* [index] * Menu: * Gpm_CharsQueued: Getting Events. (line 17) * Gpm_Close: Open and Close. (line 34) * GPM_DRAWPOINTER: Utility Functions. (line 14) * Gpm_DrawPointer: Utility Functions. (line 13) * Gpm_FitEvent: Utility Functions. (line 25) * Gpm_FitValues: Utility Functions. (line 24) * Gpm_FitValuesM: Utility Functions. (line 23) * Gpm_Getc: Getting Events. (line 31) * Gpm_Getch: Getting Events. (line 42) * Gpm_Getchar: Getting Events. (line 32) * Gpm_GetEvent: Getting Events. (line 7) * Gpm_GetLibVersion: Extra Functions. (line 7) * Gpm_GetServerVersion: Extra Functions. (line 16) * Gpm_GetSnapshot: Extra Functions. (line 29) * Gpm_HandleRoi: hl-Functions. (line 40) * Gpm_LowerRoi: hl-Functions. (line 34) * Gpm_Open: Open and Close. (line 7) * Gpm_PopRoi: hl-Functions. (line 25) * Gpm_PushRoi: hl-Functions. (line 8) * Gpm_RaiseRoi: hl-Functions. (line 29) * Gpm_Repeat: Utility Functions. (line 7) * Gpm_UseRoi: hl-Functions. (line 20) * Gpm_Wgetch: Getting Events. (line 41)  File: gpm.info, Node: Variable Index, Prev: Function Index, Up: Top Variable Index ************** [index] * Menu: * gpm_current_roi: hl-Variables. (line 11) * gpm_data: Variables. (line 44) * gpm_fd: Variables. (line 16) * gpm_flag: Variables. (line 9) * gpm_handler: Variables. (line 44) * gpm_hflag: Variables. (line 40) * gpm_morekeys: Variables. (line 48) * gpm_mx: Variables. (line 30) * gpm_my: Variables. (line 30) * gpm_roi: hl-Variables. (line 7) * gpm_roi_data: hl-Variables. (line 20) * gpm_roi_handler: hl-Variables. (line 17) * gpm_tried: Variables. (line 12) * gpm_visiblepointer: Variables. (line 26) * gpm_zerobased: Variables. (line 20)  Tag Table: Node: Top1260 Node: Overview1493 Node: Building the Release3268 Node: Server Invocation3689 Node: Special Commands4877 Node: Command Line7290 Node: Bugs and Problems13896 Node: Mouse Types14767 Node: Gpm Internals24609 Node: Events25487 Node: Margins27967 Node: Event Types29085 Node: Connection Details31096 Node: Default Handlers35096 Node: The ClientLib36669 Node: Handling Functions37350 Node: Low Level Library40215 Node: Variables40708 Node: Open and Close42806 Node: Getting Events44779 Node: Utility Functions47018 Node: Extra Functions48601 Node: High Level Lib51023 Node: Concepts51971 Node: hl-Variables53367 Node: hl-Functions54038 Node: Xterm56567 Node: Demo Clients57685 Node: mev57915 Node: sample/rmev61127 Node: Emacs Support61630 Node: gpm-root63732 Node: hltest72087 Node: mouse-test72554 Node: Type Index73067 Node: Function Index73495 Node: Variable Index75310  End Tag Table