Writing a Mouse-Sensitive Application

Terminal-oriented programs tend to have an unwieldy interface, while writing X-Windows applications is difficult. By using the gpm client library you can easily turn a text-oriented program into an easy-to-port mouse-sensitive application.
Using mev

To test library features without loosing your youth in a compile-execute-understand-recompile loop, the mev program is distributed along with the gpm server. This tool is based on the idea of xev, the X event reporter. mev reports any event it gets on the current console, and you can specify on the command line the event and modifier masks to be used. Thus, mev can help in testing your connection parameters before you hardwire them in your application. Mev can also demonstrate use of the connection stack by getting push and pop commands from standard input.

Though mev was originally designed as a test case to debug the gpm server, it is now quite useful in itself and I use it as the engine for the emacs library.

Taking input from multiple sources

After connecting to the server, the application must respond to both keyboard events and mouse events. To ease this, libgpm offers replacement functions for getc and its relatives, but the application designer is not forced to use them.

Programmers who want to autonomously manage the two input channels must invariably use the select() system call, unless the application puts the input files in non-blocking mode and keeps polling them. Polling can be wise if your application takes a long time to do its job, and you want the user to be able to regain control with a single key or mouse press. A good example of this technique is to be found in the Netscape WWW browser.

Many screen-oriented applications, on the contrary, spend most of their time waiting for user input, and could well benefit from the functions in libgpm. Externally, Gpm_Getc() and its relatives behave just like the originals when keyboard events are received; internally, they can receive mouse events and handle them through a user-defined function.

These input procedures, as you can imagine, are built around select(). This is the only way to relieve the user from using select in the application body. When stdin is reported as readable, the original getc function is called; when the mouse connection is readable, Gpm_GetEvent() is called.

Applications can invoke Gpm_GetEvent() by themselves if they need to, but you must remember that Get_Event is based on a read() call, and thus is blocking. The normal gpm input functions (usually Gpm_Getc) in libgpm invoke Gpm_GetEvent only when there is data to read. The getc-replacing function then delivers the event to a mouse-handling function specified by the application. Note that Gpm_GetEvent() is only in charge of reading the event from the current source and does not deliver the event to the mouse-handling function.

The user function in charge of handling mouse events—let's call it “mouse handler”---is registered by the user in a global variable before invoking the input functions, and its invocation doesn't interfere with the running Gpm_Getc() invocation. Be careful, however, that the input function is waiting for the handler to complete; long-running tasks don't fit into the mouse handler well.

Faking Keys

More often than not, the mouse is simply used as a shortcut for the keyboard: for example, clicking on a menu-button is like pressing f1, clicking on a listbox item is like entering its highlighted letter, pressing the button outside an active menu is like issuing the esc key, and using the scrollbar is like pressing the arrow keys many times. Application design is greatly simplified if the mouse can return keys to the input subsystem—the dual input mechanism is again joined into a single input stream, greatly reducing the amount of status information to be managed.

Within libgpm, this behaviour is enforced by the return value of the mouse handler. The handling function returns an integer value which gets interpreted in the following way:

  • EOF This value is used to signal a fatal error and will cause the input function to return the same value to the caller.

  • 0 A zero return value means that the input function should go on as before, without returning to the caller. The event is considered eaten by the handler and no key-press is simulated.

  • Anything else Any other value is considered a “simulated” keystroke character, and is returned to the caller. Note that these values are not limited to ASCII characters—any integer value can be returned.

Before returning a fake key, the input functions set a global variable, which signals that the key is not a true key press; before returning a keyboard-generated character, the flag is cleared. Applications are free to use or ignore this information. Personally, I have never used it.

Note that the ability to return any integer value is powerful and is perfectly compatible with the libc environment, because getc() returns an integer by definition. Return values exceeding a character range can be used to encapsulate mouse activity into a generic “event” integer entity, and the same switch construct in the main loop can handle any input the application gets.

Using the fake-key capability, any mouse event can be packed in an integer value to be interpreted later in the main loop of the application. Personally, I prefer to interpret the event inside the mouse handler and return to the caller only a integer belonging to a small set of actions.

The mouse handler can also register its intent to return more keys, so it may be called without waiting for a new mouse event. Thus, a scrollbar can easily be implemented in the mouse handler by returning to the caller the right number of arrow key presses.

Smart use of the fake-key mechanism can greatly ease the design of a complex application, with negligible computational overhead. In practice, you must be careful when you write mouse-handling code which can't fit the fake-key mechanism; you must be sure that a user sitting on a vt100 tty without any pointing device won't loose control of the application by falling into a state which is unrecoverable without the mouse. It is best if the unfortunate mouseless user can exploit your application in full despite limited input capabilities.