Mouse Programming with libgpm

A description of how to work with gpm for event handling, menus and more.

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)

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.

Simple Example

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.

______________________

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Mouse programming

ajayan's picture

really good stuff ,
thanks to author , i got this at right time

Re: Mouse Programming with libgpm

Anonymous's picture

I tried the sample progam but the #includes on

the website did not appear on my netscape.

So I used the obvious includes and it worked

just fine. Here are the includes you need

without angle brackets that this web site can't

digest. (Webmaster, please work on accepting

plain text in comments, we're not all MS junkies

here).

stdio.h

stdlib.h

ncurses.h

gpm.h

However, after exiting, the sample program, I

could not cut and paste as before to or from that

one xterm window. All other windows, xterm or

GUI, were unaffected. I don't know what this

means but I know it works in Xfree86 using Gnome.

I assume that means it works as well on the CRT

80x24 screen as well.

This might be something to follow up on for

anybody writing sam and smit type console programs

for linux administration. I know I hate using the

GUI with pictures, where you don't know if the

little birdie icon means add or delete. I like

the text based GUI that spells it out so you know

what you get when you press return, or maybe, now,

if you click on the highlighted text.

Re: Mouse Programming with libgpm

Anonymous's picture

Which sample program you had problems? I checked all of them on plain console and I have no problems

--pradeep

Re: Mouse Programming with libgpm

Anonymous's picture

This is that code.... after exiting .... just see whether cut copy paste with mouse works ... on the same xterm where u executed this program .

#include
#include
#include
#include

int my_handler(Gpm_Event *event, void *data)
{ printf("Event Type : %d at x=%d y=%d
", 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
");

gpm_handler = my_handler;
while((c = Gpm_Getc(stdin)) != EOF)
printf("%c", c);
Gpm_Close();
return 0;
}

How to capture special keys like F1 F2 etc...

suneel's picture

Gpm_Getc does not appear to be returning F1 F2... etc other keystrokes. Do u know how to capture those apart fromthis mouse and regular key strokes.

Suneel

Webinar
One Click, Universal Protection: Implementing Centralized Security Policies on Linux Systems

As Linux continues to play an ever increasing role in corporate data centers and institutions, ensuring the integrity and protection of these systems must be a priority. With 60% of the world's websites and an increasing share of organization's mission-critical workloads running on Linux, failing to stop malware and other advanced threats on Linux can increasingly impact an organization's reputation and bottom line.

Learn More

Sponsored by Bit9

Webinar
Linux Backup and Recovery Webinar

Most companies incorporate backup procedures for critical data, which can be restored quickly if a loss occurs. However, fewer companies are prepared for catastrophic system failures, in which they lose all data, the entire operating system, applications, settings, patches and more, reducing their system(s) to “bare metal.” After all, before data can be restored to a system, there must be a system to restore it to.

In this one hour webinar, learn how to enhance your existing backup strategies for better disaster recovery preparedness using Storix System Backup Administrator (SBAdmin), a highly flexible bare-metal recovery solution for UNIX and Linux systems.

Learn More

Sponsored by Storix