   This file is a user's and programmer's manual for gpm 0.9.

   Copyright (C) 1994 Alessandro Rubini

   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 0.9 release of the "General Purpose Mouse"
(gpm) server for the Linux text console (October 1994).

gpm-Linux
*********

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. It is heavily based on selection,
by Andrew Haylett, and it is intended as a replacement for it.

   The first application to support the mouse is the mousless 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.
See Emacs Support

Current State
=============

   This release is almost-1.0, in that all basic features are already
available, and the clients I know of run sufficiently well with it.

   I have limited availability of mouse types, so please report to me
any bug you find, especially those relating with mouse types.

   A single sample client, named `mev' is provided. It uses the minimum
client library avalaible to dump events on stdout. `mev' is something
like `xev' for the X environment. See mev.

   Another "client" is the lisp library for emacs. It uses `mev' to get
events and does quiet a good work, in my opinion. See Emacs Support.

   The documentation tries to be useful to both the developer and the
user. Forgive me for the poor english language, but I take a while to
fix my errors. The source is still the main source of information for
the internals of both the server and the clients, but feel free to ask
if the docs are obscure. I'm E-mailable at the address
`rubini@ipvvis.unipv.it'.

Compiling and Installing
========================

   Just say `make && make install' to your shell. You'll need gpm
installed to compile the latest release of `The Mouseless Commander'
with mouse support enabled.

   As of 0.14, binaries are released with the package. You can just
`make quickinst' to install everything under `/usr/local' or `make
quickinst PREFIX=/usr/tools/gpm' to install under your custom directory.

   Warning: If you run gpm from `rc.local' or other initialization
scripts, you'd better `rm -f /tmp/gpm*' before that. This should be
redundant as of gpm-0.16, unless the system reboots after a crash.
See External Interactions.

Kernel Patches
==============

   Old Linux kernels need to be patched to provide features I rely on.
As of 1.1.32, however, my patches are in the official release, so you
won't need any kernel recompilation. Remember, anyway, to enable
selection while compiling the kernel, or this package won't work.
Refer to `kernel/README' to probe further.

Open Issues
===========

   * Maybe I'd better allow a user-space buffer for selection.  It
would make the kernel smaller and the package more flexible (allowing
incremental selection, or history management...) However it would also
be an incompatible change, and most difficult to convince Linus about.

   * It would be nice to have a configurable highlight algorithm, by
passing an array of bytes to the kernel. My current approach is fine if
you use colors, but the pointer cancels selection in if you use black
and white.  Is it worth the effort?

   * The three-button contraint is really ugly. Is there anybody with
more than 3 buttons? Should I relax the constraint?

   * The current policy for out-of-screen events is better than
nothing, but it is far from optimal. Should I change it?

   * The problem with the last  point is allowing the clients to pass
different data structures to the server, it would break the simple
approach to the server code. Fixed size messages are really nice to
manage.

Server Invocation
*****************

   The `gpm' executable is meant to act like a daemon, in just the same
way as `selection' used to. This section is meant to describe the
command-line options for `gpm', while its internals are outlined in the
nect section.  See Gpm Internals.

   The server can be configured to match the user's taste, and any
application using the mouse will inherit the server's attitude. No
user-wide configuration file is provided, because the mouse is a
machine-wide resource. If you feel that different users on a Linux
machine could benefit from personal mouse setup at login, feel free to
email me, and I'll look about it. As of this release, only the
`inword()' look up table can be changed without restarting the server.

   The server program does not put itself in the background. Not yet,
at least.

   Available command line options are the following:

`-a ACCEL'
     Set the acceleration.

`-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. The other sequences are available
     as well.

`-d DELTA'
     Set the delta value. When a single motion event is longer than
     DELTA, ACCEL is used as a multiplying factor.

`-D'
     Dirty operation (debug only). It causes gpm to kill an already
     running gpm, if any. The default behaviour is to not kill it.
     See External Interactions.

`-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.

`-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.  Only visible character can appear
     in CHARSET because control characters can't appear in text-mode
     video memory, whence selection is cut.

`-L CHARSET'
     Modify the  `inword()' look up table. This option causes the
     server to exit after modifying the `lut'.  You can thus modify the
     behaviour of a running server.

`-m FILENAME'
     Choose the mouse file to open. This option is not needed for
     normal operation of `gpm', because the program tries to open
     `/dev/mouse', and then, if that fails, a device dependent of the
     mouse type.

`-r NUMBER'
     Set the responsiveness. A higher responsiveness is used for a
     faster cursor motion.

`-s NUMBER'
     Set the sample rate for the mouse device.

`-t NAME'
     Set the mouse type. Use `gpm -h' to get a list of allowable types.

`-v'
     Print version information and exit.

`-2'
     Force two buttons. This means to use both the middle and right
     button to paste text, when `gpm' works like `selection'.

`-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.

External Interactions
=====================

   The `gpm' server may have problems interacting with X, with
`selection' and with itself.

   With X11 `gpm' has the same problems as `selection'. If your mouse
is a single-open device, you should kill `gpm' before strating X. You
can use the file `/tmp/gpmpid' to retrieve the process id of the
running server.

   Gpm and selection can't run together, because they will contend the
mouse.  They can control two mice independently, however.

   Two instances of gpm can't run on the same system, even if you have
two mice.  In order to avoid contention, `gpm' checks for its
uniqueness at startup, using the file `/tmp/gpmpid'. You'd better
remove it before invoking the server if you run `gpm' from `rc.local',
though the problem should be fixed as of gpm-0.16.

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
behaves like the `selection' package by Andrew Haylett, whose code has
been the starting point for gpm.  I chose to embed selection within gpm
because this is the most straightforward approach -- people is used to
have selection running on all the virtual consoles, and my package won't
break with them. Moreover, my implementation of selection is a little
different from selection-1.6 because much of the processing is made by
the server main loop. Selection, then, 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).

Events
======

   Whenever the mouse generates an event, it 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. See Mouse 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 the same 4-bit
     value used by the `loadkeys' program.

`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.

`short x, y;'
     The position of the mouse pointer where the event is reported. Is
     is 1-based, to be compatible with `selection'.

`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. See 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.  See Margins

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 exacly 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. Maybe this issue will be
handled in the clientlibrary befor 1.0 is out.

Event Types
===========

   The `type' field int 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, and
exactly one bit is set in the corresponding bit-set.

   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 pressed.

`GPM_DOWN'
     A button press event.

`GPM_UP'
     A button release event.

   Cooked events are the following:

`GPM_SINGLE'
     This bit is optionally 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). See Dispatching Events.

`GPM_DOUBLE'
     Used to identify a double click.

`GPM_TRIPLE'
     Used to identify a triple click.

`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.

`GPM_HARD'
     This bit is used only by clients while connecting.  See
     Dispatching Events.

Mouse Types
===========

   I chose to isolate anything related to mouse types, because I can't
test them all. The source file `mice.c' is made up of type-specific
functions, as well as a table to dispatch computation. The table offers
a default device name for each mouse type as well, but I lack
information about some of them.  Contributions in this field are
particularly welcome.

Dispatching Events
==================

   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. Only the top-of-stack client can get events from the server; other
clients in the stack are assumed to be waiting for the top one.

   In addition to the per-console stacks, another stack is there to
store default-handling clients. The additional stack is looked up
whenever no client is registered for the active console.
Default-handling clients can be used to override the selection
mechanism, or to catch particular events which deserve a special
treatment. A typical default-handling application is one which draws
menus on the background of the screen when a control-mouse event is
detected.

   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:

`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 wich 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
     whithout interfering with mouse-only ones.

`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:

`int pid'
     The `pid' of the connecting application.

`int vc'
     Which virtual console to gain control of.

   Mouse events are passed to the following clients, in order:

   * The current client for the current console, if any.

   * The default handler, if any.

   * The builtin `selection' mechanism.

   If the modifier keys in the event are too few or too many, the event
is passed to the next recipient in the list. If the event is not used
by the client, it can be passed to the next recipient, according to the
`defaultMask'.  If the event is used by the client, it can be
nonetheless passed along the chain, if the GPM_HARD bit is set in the
`defaultMask'. See Event Types.

   Good values for `defaultMask' can thus be the following:

`0'
     To sink any event, even those I don't use.

`~eventMask'
     Pass along any event I don't use.

`~GPM_HARD'
     Just the same, independently of `eventMask'.

`GPM_MOVE|GPM_HARD'
     Pass motion events, even if I use them.  This is the good choice
     for an application which wants information on mouse motion, but
     leaves the task of cursor-drawing to the server.

The Client Library
******************

   The `libgpm.a' archive is meant to provide the mouse protocol at
different levels of abstracion. Applications linking to the gpm server
are expected to benefit from using the library, as compared to managing
the raw socket interface. Any source file using the library should
include `<gpm.h>' to get gpm specific macros and prototypes.

Mouse Handlers
==============

   A mouse handler is a function which registers itself within the
library, and is called whenever a mouse event is reported to the
application. It is passed two arguments and returns an integer value,
according to the following typedef:

   `typedef int Gpm_Handler(Gpm_Event *EVENT, void *CLIENTDATA);'

   The `event' is used to instantiate the mouse event just received,
and the `clientdata' pointer is needed to implement some higher level
functionality. An handler will be tipically invoked by `Gpm_Getc', and
the following discussion assumes the invoking function is `Gpm_Getc'.

   The return value from an handler is used as follows:

`EOF'
     This value is used to signal a fatal error, and will cause
     `Gpm_Getc' to return the same value to the caller, after setting
     `gpm_hflag' to 1.

`0'
     A zero return value means that `Gpm_Getc' should go on as before,
     without returning to the caller. The event has been eaten by the
     handler and no key-press is simulated.

`ANYTHING-ELSE'
     Any other value is considered a "simulated" character, and is
     returned to the caller after setting `gpm_hflag'.  This allows a
     quick way to implement yes/no boxes abd simple menus without
     interfering with the main body of an existing application.
     Moreover, if return values greater than 255 are used a single
     switch loop can parse both keyboard and mouse events.

The currently active handler is passed as second argument the content
of the `gpm_data' variable, i.e. the current clientdata. This approach
allows the higher-level management of mouse events to be a superset of
the low-level code, rather than an incompatible alternative.

Higher Level Library
====================

   The high level part of the library is not available by now. I plan to
use the concept of `region of interest' (something like a window) so
that the client can express interest in regions of the screen, and have
the right handlers invoked when the mouse enters, leaves or acts within
each region.

   I conceive the final support to mimic Tk, the X toolkit built around
the Tcl language (simplifying quite a lot, however); it should offer a
flexible way to establish bindings on events, so that handlers can be
invoked. The `data' argument to the handler is meant to allow a single
routine to manage multiple events.

Running under xterm
===================

   As of release 0.18, gpm-based applications can run under xterm
without any need for recompilation. The library is designed to convert
xterm mouse events to gpm-style structures, so that the client will get
the same events it got under the Linux console. Moreover, a source file
(gpm-xterm.c) is available to mimick libgpm under a different OS than
Linux. Porting to other text-based consoles is an open issue, but I
myself have Linux alone.

   The goal is to provide a uniform mouse interface with both xterm and
the Linux console. Some features of libgpm would not be available, but
if you run under xterm you know what you get, so you couldn't use them
on the console anyway.

   The sample directory in the distribution tree is meant to show how a
simple mouse-sensitive application can be easily autoconfigured and
compiled. The rmev program has proved to compile and run smoothly under
Linux (both with and without libgpm.a), SunOS-4, Solaris-5, hpux-8.x
and Ultrix-3.0.

The C API
*********

   The library offers utility functions to establish the connection and
to get mouse events. They are designed to work painlessly if the server
is not running on the host machine. Xterm support is available as well.
See Xterm.

Global Variables
================

`int gpm_flag'
     Initially zero, it is used to tell if the process is connected
     with a mouse server or not. It is used as a counter to manage
     multiple opens as well.

`int gpm_tried'
     A flag, used to avoid retrying a connection if the server is not
     available on the system.

`int gpm_fd'
     Initially `-1', it is the file descriptor used to talk with the
     server.

`int gpm_zerobased'
     Since selection has always been one-based, this variable, zero by
     default, can be used to trigger zero-based coordinates in event
     reporting. It must be set before opening the mouse connection, and
     never changed later.

`int gpm_visiblepointer'
     If not zero, causes the mouse cursor to be always visible on the
     window. It is zero by default.

`int gpm_hflag'
     Used to signal if a character has been generated by a mouse
     handler. See Mouse Handlers

`Gpm_Handler *gpm_handler; void *gpm_data'
     Both initially `NULL', they're used to setup asynchronous mouse
     handling, as described below under the `Gpm_Getc()' item.

`gpm_morekeys'
     Used by the mouse handler to provide more than one key: if
     gpm_morekeys is not zero, `Gpm_Getc' will invoke the handler
     without waiting for events. gpm_morekeys is never set by the mouse
     library.

Connecting and Disconnecting
============================

 - Function: int Gpm_Open (Gpm_Connect *CONN, int FLAG);
     Open a connection with the server. The CONN parameter points to the
     connection information for the being-created connection, as
     already described.  It is passed to the server after filling the
     `pid' and `vc' fields.

     FLAG should be `0' for normal applications, those interested in
     events related to their own console. The own console is considered
     to be the one attached to `stdin', and it must match the string
     `/dev/tty*'. A negative value for FLAG is used to make the
     invoking application a default handler, while a positive value is
     used to force connection to a particular console, either for
     debugging issues or whenever `stdin' is not a tty when `Gpm_Open'
     is invoked.

     Multiple opens are allowed, and a stack of `Gpm_Connect' structures
     is managed by the library. You can, thus, re-open the connection in
     order to temporarily change the range of events you're interested
     in. When you invoke an external program, for example, you should
     re-open the connection with `eventMask' zeroed, and `defaultMask',
     `minMod' and `maxMod' all equal to `~0'.

     The return value is either `-1' or the file descriptor used to
     communicate with the server.

 - Function: int Gpm_Close (void);
     Pops the connection stack. It is used to restore the previous
     situation after a change in the connection masks. Closes the
     actual connection when the stack gets empty. On last close it
     returns 0, -1 otherwise.

Getting Events
==============

 - Function: int Gpm_GetEvent (Gpm_Event *EVENT);
     Reads an event form `gpm_fd'. It should be called only when the
     `gpm_fd' descriptor is reported as readable by a `select()' system
     call. It returns 1 on success, -1 on failure, and 0 after closing
     the connection.

 - Function: int Gpm_Getc (FILE *F);
 - Function: int Gpm_Getchar (void);
     These are intended to be replacements for `getc()' and `getchar()'
     to be used by applications which are interested in the mouse.
     Their external behaviour is the same as `getc()', but a mouse
     handler gets invoked whenever an event is available (see below
     about mouse handlers). A mouse handler can force `Gpm_Getc' to
     return a specific value to the caller, and the "simulated"
     character is signaled by setting `gpm_hflag' to 1.

 - Function: int Gpm_Wgetch (WINDOW *WIN);
 - Function: int Gpm_Getch (void);
     These are intended to be replacements for `wgetch()' and `getch()'
     to be used by applications which are interested in the mouse. They
     are the curses equivalent of Gpm_Getchar.

Support Functions
=================

 - Function: int Gpm_Repeat (int millisecs);
     It returns 1 if no mouse events arrive in the next millicecs
     milliseconds, 0 otherwise. It is meant to be used by those handlers
     which need to repeat an action as long as the mouse button is
     pressed (while(Gpm_Repeat(200))...).

 - Function: int Gpm_DrawPointer (int X, int Y, int FD);
 - Function: int GPM_DRAWPOINTER (Gpm_Event *EPTR;)
     These are actually macros. They should be used to draw the mouse
     pointer after mangling the screen (while dragging on a menu, say),
     because letting it to the server won't work nicely, due to lack of
     synchronism between client and server. The file descriptor should
     refer to the console. The return value is 0 on success and -1 on
     failure. Gpm_DrawPointer is obsolete, and is retained only for
     compatibility.

 - Function: int Gpm_FitValuesM (int *X, int *Y, int MARGIN);
 - Function: int Gpm_FitValues (X,Y);
 - Function: int Gpm_FitEvent (EPTR);
     The first is a function, while the other are macros.  These three
     procedures should be used to fit the pointer inside the visible
     screen. They are needed for drag and release event. A connection
     bit will be available in the future to force the pointer in the
     visible region.

Demonstration Clients
*********************

`mev'
=====

   The `mev' program is modeled after `xev'. It prints to `stdout' the
console events it gets, both keyboard and mouse events.

   `mev''s default behaviour is to get anything, but command line
switches can be used to set the various fields in the `Gpm_Connect'
structure, in order to customize the program's behaviour. I'm using
`mev' to handle mouse events to `emacs' Emacs Support.  really
unstable now.

   Command line switches for `mev' are the following:

`-C NUMBER'
     Select a virtual console to get events from.  This is intended to
     be used for debugging.

`-d NUMBER'
     Choose a default mask. By default the server gets any events not
     belonging to the event mask. The mask can be provided either as a
     decimal number, or as a symbolic string.

`-e NUMBER'
     Choose the event mask. By default any event is received. The mask
     can be provided either as a decimal number, or as a symbolic
     string.

`-E'
     Enter emacs mode. In emacs mode events are reported as lisp forms
     rather than numbers. This is the format used by the t-mouse
     package within emacs.

`-f'
     Fit events inside the screen before reporting them. This options
     re-fits drag events, which are allowed to exit the screen border,
     see Margins.

`-i'
     Interactive. Accepts input from `stdin' to change connection
     parameters.

`-m NUMBER'
     Choose the minimum modifier mask. Any event with fewer modifiers
     will not be reported to `mev'. It defaults to 0.  The mask must be
     provided either as a decimal number, or as a symbolic string.

`-M NUMBER'
     Choose the maximum modifier mask. Any event with more modifier
     than specified will not be reported to `mev'.  It defaults to
     `\~0', i.e. all events are received.  The mask must be provided
     either as a decimal number, or as a symbolic string.

`-p'
     Requests to draw the pointer during drags. This option is used by
     emacs to avoid invoking ioctl() from lisp code.

   When the arguments are not decimal integers, they are considered
lists of alphanumeric characters, separated by a single non-alphanumeric
character. I use the comma "`,'", but any will do.

   Allowed names for events are `move', `drag', `down' or `press', `up'
or `release', `motion' (which is both `move' adn `drag'), and `hard'.

   Allowed names for modifiers are `shift', `leftAlt', `rightAlt',
`anyAlt' (one or the other), `control'.

   When the `-i' switch is specified, `mev' looks at its standard input
as command lines rather than events. The input lines are parsed, and the
commands `push' and `pop' are recognized.

   The `push' command, then, accepts the options `-d', `-e', `-m' and
`-M', with the same meaning described above. Unspecified options retain
the previous value and the resulting masks are used to reopen the
connection with the server. `pop' is used to pop the connection stack.
If an empty stack is popped the program exits.

   The only other commands recognized are `info', used to return the
stack depth, and `quit' to premautrely terminate the program.

`rmev'
======

   rmev is a reduced version of mev, but it is designed to be as
portable as possible. It uses a subset of the capabilities of libgpm.a,
but works smooth on both xterm and the Linux console. It is distributed
with gpm to show how a curses based application can support the mouse
with a small effort. Most of the xterm decoding is by Janne Kukonlehto.
See Xterm.

Emacs Support
=============

   Emacs support is quite complete as of 0.14.  The enclosed file
`t-mouse.el', also available in compiled form, is used to pass mouse
events to emacs.  `t-mouse.elc' is installed in the `bin' directory of
the install tree (by default `/usr/local'), and you should probably
move it elsewhere, in the load-path for lisp libraries.

   Events with modifiers are managed by selection, while mouse-only
events are passed to the lisp program, which converts them to be
similar to X mouse events inside emacs. Actions are then invoked
through the global keymap. As of this release of gpm, the only thing
you can do is move `point' to the place where the first button is
pressed.

   I suggest to put the following form in your own `.emacs' file, to
avoid loading `t-mouse' when you aren't working on the Linux console:

     (if (and (string-match "i.86-.*-linux" system-configuration)
              (string-match "con.*" (getenv "TERM")))
         (load-library "t-mouse"))

   Mouse events are dispatched through the keymap `t-mouse-keymap',
which tries to mimick the behaviour of emacs under X.

   The scrollbar sits on the last column of the screen, though it is not
visible.  When you click on the last column, a scroll-bar action is
taken.  If this annoys you, please let me know.

   The keymap is configured to handle the following events:

`down-mouse-1'
     Jumps to the location of the click, setting the mark.

`drag-mouse-1'
     Drags the emacs pointer to follow your mouse. The mouse cursor is
     displayed as well.

`mouse-1'
     At mouse release, the cursor flashes to the mark (where the button
     was pressed), and point remains at the release location.  The
     region remains set, though emacs doesn't allow highlighting while
     in text mode. If no drag happened, button release has no effect.

`down-mouse-2'
     This event yanks the top item in the `kill-ring', like the
     key-press of `C-y'.

`down-mouse-3'
     Sets point. This can be used after a button-1 event to set the
     region without dragging.

`double-mouse-1'
     Sets the region to a single word. Not yet implemented.

`triple-mouse-1'
     Sets the region to a single line. Not yet implemented.

`double-mouse-3'
     Kills the region.

`mode-line mouse-1'
     Selects the window.

`mode-line mouse-2'
     Expands the window to the whole frame.

`mode-line mouse-3'
     Deletes the window.

`scroll-bar down-mouse-1'
     Moves the line at the level where you click up to the top of the
     window. By clicking repeatedly in the same place, you can scroll
     by the same distance over and over.

`scroll-bar down-mouse-2'
     Causes point to jump to the required position: pressing at top of
     the scroll-bar jumps to the beginning of the buffer, pressing at
     bottom jumps to end of buffer.

`scroll-bar drag-mouse-2'
     Dragging on the scroll-bar causes the buffer to scroll. The amount
     of scrolling is controlled by the X position of the mouse, in order
     to overcome the coarse granularity of the scroll-bar. In other
     words, horizonatal motion controls the vertical resolution, while
     vertical motion causes actual scrolling.

`scroll-bar down-mouse-3'
     Moves the line at the top of the window down to the level where
     you click. By clicking repeatedly in the same place, you can
     scroll by the same distance over and over.