When I was first introduced to programming (back with DOS), I used to add mouse support to my applications to impress my teachers. Programming the mouse largely consisted of putting the right values in the registers (like 0x00 in the ax register to reset the mouse) and calling the interrupt service routine with int86 ( a function provided by Turbo C to access interrupt service routines). So when I put my hands on a Linux box, I looked for some thing similar. I soon found out that only root can access hardware registers directly. But there's an elegant way to handle this.

Welcome to the world of gpm and its client libraries. When I started searching for useful information about how to program mouses in UNIX (Linux in particular), I found some C code that let people access and program the mouse through /dev/mouse . But I was overwhelmed by the intricacies of handling different mice and was forced to look for other avenues. After pouring over the man pages of gpm, I learned to program the mouse with ease, and in no time, I was playing with my mouse. I was quite impressed by the extent of services these libraries provided and was compelled to explore them further.

It is quite easy to program with gpm and write portable and robust applications with a few lines of code. In this article, I will explain the concepts involved in programming the mouse with simple but effective examples. To compile them you will need libgpm, which can be obtained from ftp.prosa.it/pub/gpm. To compile the program successfully, you will have to add the -lgpm flag:

gcc [a c file that uses libgpm] -lgpm

Some programs require ncurses, which can be obtained from ftp.gnu.org/pub/gnu/ncurses. The programs that require curses have to be compiled with the -lncurses flag:

gcc [a c file which uses both libgpm and libncurses] -lgpm -lncurses

GPM (General Purpose Mouse): A Cut an Paste Utility and Mouser server for Linux Virtual Consoles.

These are the first lines of the man page on gpm. To put it simply gpm is a server that says "Hey! I know about the mouse installed here. I know how to handle its events. And I am here to serve you with whatever you are interested in." The clients simply have to connect to the server and inform it of which events they are interested in. They need not worry about the intricacies of the different types of mice. This client-server philosophy is put to its best in Unices. X is a very good example of how this architecture is put to useful ends. The server knows about the hardware, and it will handle all the dirty hardware interrupts, registers, etc. What the clients see is a unified interface that they can use to interact with the hardware. Henceforth, I will use the term gpm to refer to gpm and its libraries and the term server to refer to the gpm dæmon.

To handle the mouse with gpm, the client has to connect to the server and specify which events it wants to handle. The function Gpm_Open() takes a structure of type Gpm_Connect, whose variables have to be filled accordingly. The variables of interest in the Gpm_Connect structure are the eventMask, defaultMask, minMod and maxMod. The variable eventMask is a bitmask of the events the client is interested in. defaultMask specifies which events the client wants the server to handle in the default manner. Thus, we can explicitly specify the events we want to handle and tell the server to handle the others events in the default manner.

The variables minMod and maxMod can be used to access keyboard modifiers like ALT, CTRL and SHIFT. The client will not be informed about mouse events that are less than the set minimum and more than the set maximum. The following code explains these concepts and also shows how to read events.

#include <stdio.h>
#include <gpm.h>
int my_handler(Gpm_Event *event, void *data)
{       printf("Event Type : %d at x=%d y=%d\n", event->type, event->x, event->y);
        return 0;       
}
int main()
{       Gpm_Connect conn;
        int c;
        conn.eventMask  = ~0;   /* Want to know about all the events */
        conn.defaultMask = 0;   /* don't handle anything by default  */
        conn.minMod     = 0;    /* want everything                   */  
        conn.maxMod     = ~0;   /* all modifiers included            */
        
        if(Gpm_Open(&conn, 0) == -1)
                printf("Cannot connect to mouse server\n");
        
        gpm_handler = my_handler;
        while((c = Gpm_Getc(stdin)) != EOF)
                printf("%c", c);
        Gpm_Close();
        return 0;
}

This example introduces us to a useful function, Gpm_Getc(), that works like the ordinary getch() function, except that when a mouse event occurs it calls the gpm_handler with the event structure as a parameter. gpm_handler is a global variable initialized to null. Clients are required to initialize this variable with the function that defines the way they wish to handle events.

Now that we have seen how easy it is to get mouse events with gpm, let's dive into the details. The variables in the connection structure can be manipulated to handle only the events of our choice. For example, we don't want to handle motion and drag of the mouse and are interested only in the clicks of the mouse. Then we can use an eventMask like conn.eventMask = Gpm_Down; and a conn.defaultMask = ~conn.eventMask;. This will only report the mouse button down events to us. Similarly a prudent choice of minMod and maxMod can simplify programming and reduce overhead. It is also useful if you want to pass on the events to other processes.

If we set minMod and maxMod to zero, only mouse events are reported. If we are interested in only mouse + modifier events and not in mouse-only events, then minMod should be a combination of

conn.minMod = 1<<KG_SHIFT; conn.maxMod = ~0;

which tells the server that the client is interested in shift + mouse events but not interested in mouse-only events. This is how gpm-root works. gpm-root takes only the events with modifiers (by default CTRL only) and draws menus accordingly. But we have to remember that gpm-root knows about these events only if the application running on the console is not handling the events or if it has passed them to the default handler. That is why choosing the correct set of events is very important.

Note: You must include linux/keyboard.h to make use of the define constants KG_SHIFT, etc.

As you have seen in the above example, the variable event contains details about the event that gpm reports to us. If we look at the event structure, the variables that are of the most interest to us are type, buttons, modifiers, x and y.

The variable type contains the type of the events. This is a bitmask of the various possible events, such as move, drag, click, down, up, etc. To find out about the event, we can test against the enum types GPM_MOVE, GPM_DOWN, GPM_UP, etc., using an expression like

        if(event->type & GPM_MOVE)
                printf("Move event has occured\n");

Similarly the variables buttons and modifiers contain information regarding which button(s) and which modifier(s) are pressed.

Listing 1. Use of the Variables in the Event Structure

There is one more useful function to get events: Gpm_GetEvent() takes a parameter of type Gpm_Event and sets the variables of the structure when an event is reported. The main difference between these two functions, as mentioned in the man page, is that Gpm_GetEvent() tries to read the event with a read call; so it immediately blocks if there is no event to be reported. Hence it should be called only when gpm_fd (mouse file descriptor) is reported readable by select(). Gpm_Getc() will do this work for you, and it calls the handler when an event is reported. So what is the main reason to use Gpm_GetEvent()? Though this function is meant to be used for internal purposes by the GPM client library, if you really want to block for events with the mouse and don't want to do anything else, then you could go for this. Also, if you want a quick and dirty way of reading events without the hassle of handler functions, Gpm_GetEvent() function may be used.

Whenever we think of a GUI or a mouse-sensitive application, menus, dialog boxes and buttons spring to mind. Managing GUI widgets (menus, dialog boxes, etc.) is always difficult and runs into many lines of code, especially those weird switch-case statements. With gpm and curses I tried to create a simple menu; it is shown in Listing 2.

Listing 2. Creating a Menu that Highlights with the Mouse Pointer

Listing 2 creates a menu, and whenever the mouse passes over one option it gets highlighted. When the mouse is clicked on one choice, the choice is reported. This example illustrates the concept of "faking the keys". Generally the mouse is considered to be a shortcut or an easy way of handling the difficult task of remembering key combinations. In the handler we can return values that may or may not be equivalent to key codes, so that we can use the same switch case statement to perform functions. As an example, say a user has clicked on a menu item equivalent to the F1 key, then we can return KEY_F1. We can use a single switch statement in the main loop to do the appropriate work. Though this is not a requirement it does simplify coding and debugging. I often attach mouse support to an existing curses application by using this feature. Dialog is a good example of how we can put this to use though exact values are not returned in this case.

The return value from the handler is interpreted as follows by the Gpm_Getc() family of functions.

When programming like this, we can return the same key code that a keyboard generates, or we can pack it into a value so that the main loop knows the mouse is generating this event. I used the second approach in the above example. Personally, I prefer using the first approach when I want to add functionality to an existing curses application with a lot of manipulation through keys. But the second approach gives more freedom (and sometimes it gives bizarre results too).

As the complexity of the programs and the GUI increases, it becomes difficult to handle different regions and complex widgets. The GPM high level library tries to address this problem. Functions are available to manage regions cleanly and easily. Let's see them in action in Listing 3.

Listing 3. Sample High Level Library

Listing 3 illustrates the main concepts of the high level library. In this example, four windows are created and mouse regions are also initialized. When the user does something in the region, the event is reported in the window. The high level library uses the concept of ROIs (Region of Interest). We tell the library the region we are interested in, and the library informs us when an event occurs in the region. The function Gpm_PushRoi() does this. We can arrange for the handler to be called when some event happens in the region and we can specify the usual mask of events in which we are interested.

In the example in Listing 3, I used a single handler. By making use of the client data, I kept track of the window in which I was working. When we initialize the ROI with Gpm_PushRoi(), the last parameter to the function is the client data which will be passed later to the handler. So we can store useful information in the client data and then use it in the handler.

In the above example I passed the window information required to the handler so that it could prints the messages in the correct window. This simplifies programming and makes management of regions easy. The events GPM_ENTER and GPM_LEAVE tell us when the mouse is coming into or going out of the region. These can be used to do pre-processing or post-processing for the region.

Say we have written a menu and want it to be displayed only when the user passes over a region and then disappear when the user leaves the region. The function Gpm_PopRoi() removes the Roi on the top of the stack. This function can be called when we are no longer interested in the region. The functions Gpm_RaiseRoi() and Gpm_LowerRoi() raise and lower the specified roi in the stack. These functions are useful when we want to keep track of which roi is on top of the stack. Whenever the mouse generates an event in a region it will be reported, even though it is not on top of stack. So these functions are useful when we want to do something special only with the Roi on the top of the stack or with a specific roi. The hltest program that comes with the gpm code uses this concept to make the window on the top of the stack active and handle events related to that window only.

Let's look at some global variables that are essential in any program using gpm libraries. I have used some of them in the above examples, so let me explain some important ones here. The explanations also contain tricks to make some programs work.

I would like to thank my friend Ravi Parimi for his help in editing this document. I am grateful to him for his constant encouragement and motivation.

Pradeep Padala is a software engineer for Hughes Software Systems. He has a degree in Computer Science from MNREC, Allahabad, India.