A Brief intro to X11 Programming

Topics:

• Overview of X11 Programming
• Header Files for X
• Important X Variables
• Handling Input
• Drawing in the Window
• Placing Text in the Window
• Working with Colors
• Compiling your Code
• Miscellaneous X11 Manual Pages
• Conclusions

Overview of X11 Programming

Header Files for X

		#include <X11/Xlib.h>
		#include <X11/Xutil.h>
		#include <X11/Xos.h>

Important X Variables

		Display *dis;
		int screen;
		Window win;
		GC gc;

The graphics context has a lot to do with how things are displayed/drawn in the window. Different masks can be set, etc. and you can get pretty funky with it.

Typically calls to get input and output to the window use one or more of the above variables. See the appropriate sections for details.

Here is a simple routine to create a simple X Windows. It assumes that the above variable have been declared globally:

void init_x() {
	/* get the colors black and white (see section for details) */
	unsigned long black,white;

	/* use the information from the environment variable DISPLAY 
	   to create the X connection:
	*/	
	dis=XOpenDisplay((char *)0);
   	screen=DefaultScreen(dis);
	black=BlackPixel(dis,screen),	/* get color black */
	white=WhitePixel(dis, screen);  /* get color white */

	/* once the display is initialized, create the window.
	   This window will be have be 200 pixels across and 300 down.
	   It will have the foreground white and background black
	*/
   	win=XCreateSimpleWindow(dis,DefaultRootWindow(dis),0,0,	
		200, 300, 5, white, black);

	/* here is where some properties of the window can be set.
	   The third and fourth items indicate the name which appears
	   at the top of the window and the name of the minimized window
	   respectively.
	*/
	XSetStandardProperties(dis,win,"My Window","HI!",None,NULL,0,NULL);

	/* this routine determines which types of input are allowed in
	   the input.  see the appropriate section for details...
	*/
	XSelectInput(dis, win, ExposureMask|ButtonPressMask|KeyPressMask);

	/* create the Graphics Context */
        gc=XCreateGC(dis, win, 0,0);        

	/* here is another routine to set the foreground and background
	   colors _currently_ in use in the window.
	*/
	XSetBackground(dis,gc,white);
	XSetForeground(dis,gc,black);

	/* clear the window and bring it on top of the other windows */
	XClearWindow(dis, win);
	XMapRaised(dis, win);
};

Another important task is closing the window correctly:

void close_x() {
/* it is good programming practice to return system resources to the 
   system...
*/
	XFreeGC(dis, gc);
	XDestroyWindow(dis,win);
	XCloseDisplay(dis);	
	exit(1);				
}

For more information about the routines above, see the following sections (where applicable) and/or try the man pages. They are a great resource.

Handling Input

	main () {
		char tmp[512];
		while (1) {
			scanf("%s",tmp);
			printf("%s",tmp);
		}
	}

How can one variable handle all these different types of events you ask? The answer is that it is a big, complex structure! Don't be afraid! Even though it is big and scary, you don't have to learn every aspect of it to use it.

The key concepts to using the XEvent structure are:

1. setting up the input masks
2. creating an instance of the XEvent
3. checking for events
4. handling events.

Here is code snippet which gives an example of using XEvent's. It assumes that a call has been made to init_x() (see previous section) where the call:

	XSelectInput(dis, win, ExposureMask|ButtonPressMask|KeyPressMask)

	XEvent event;		/* the XEvent declaration !!! */
	KeySym key;		/* a dealie-bob to handle KeyPress Events */	
	char text[255];		/* a char buffer for KeyPress Events */

	/* look for events forever... */
	while(1) {		
		/* get the next event and stuff it into our event variable.
		   Note:  only events we set the mask for are detected!
		*/
		XNextEvent(dis, &event);
	
		if (event.type==Expose && event.xexpose.count==0) {
		/* the window was exposed redraw it! */
			redraw();
		}
		if (event.type==KeyPress&&
		    XLookupString(&event.xkey,text,255,&key,0)==1) {
		/* use the XLookupString routine to convert the invent
		   KeyPress data into regular text.  Weird but necessary...
		*/
			if (text[0]=='q') {
				close_x();
			}
			printf("You pressed the %c key!\n",text[0]);
		}
		if (event.type==ButtonPress) {
		/* tell where the mouse Button was Pressed */
			printf("You pressed a button at (%i,%i)\n",
				event.xbutton.x,event.xbutton.y);
		}
	}
};

There are a lot of Event types and masks. Read the man pages on: XSelectInput and XNextEvent for more information. Also see /usr/include/X11 and search for NoEventMask. This will give you a complete list of all the different sorts of events there are. It is worth noting that XNextEvent will block until another event comes through. So if no events occur, your program just sits there. XCheckWindowEvent is similar to XNextEvent (though it takes different arguments), but it returns a true (1) or a false (0) about whether or not an event occured. If an event did occur it fills an XEvent structure with info about the event. In either case, the program execution continues unabated.

Drawing in the Window

• XDrawLine(dis,win,gc, x1,y1, x2,y2);
• XDrawArc(dis,win,gc,x,y, width, height, arc_start, arc_stop);
• XDrawRectangle(dis, win, gc, x, y, width, height)
• XFillArc(dis,win, gc, x, y, width, height, arc_start, arc_stop);
• XFillRectangle(dis,win,gc, x, y, width, height);

		Display *dis;
		Window win;
		GC gc;

Placing Text in the Window

	XDrawString(dis,win,gc,x,y, string, strlen(string));

Working with Colors

Ahem, now on with the discussion. For the purpose of this introduction I am going to stick with two basic ideas: shared and private colormaps. Colormaps is another word for palettes. I am only going to talk about 256 color colormaps.

Getting the colors you want from a shared colormap is really pretty simple. The easiest way is to consult the rgb.txt file (usually found as /usr/X11/lib/X11/rgb.txt). It list all the string names associated with all the colors of the rainbow! Here is how you use them:

void get_colors() {
	XColor tmp;

	XParseColor(dis, DefaultColormap(dis,screen), "chartreuse", &tmp);
	XAllocColor(dis,DefaultColormap(dis,screen),&tmp);
	chartreuse=tmp.pixel;
};

Creating a private colormap is a bit more involved, but if you want the colors to be perfect in your window, it is the easiest way.

void create_colormap() {
	int i;
	Colormap cmap;
	XColor tmp[255];

	for(i=0;i<255;i++) {
		tmp[i].pixel=i;
		tmp[i].flags=DoRed|DoGreen|DoBlue;
		tmp[i].red=i*256;
		tmp[i].blue=i*256;
		tmp[i].green=i*256;
	}	
	cmap=XCreateColormap(dis,RootWindow(dis,screen),
		DefaultVisual(dis,screen),AllocAll);
	XStoreColors(dis, cmap, tmp,255);
	XSetWindowColormap(dis,win,cmap);
}

Now that your know how to get the pixel values for the color you want (either with a share colormap or private), here is what you can do with this information:

	XSetForeground(dis,gc,chartreuse);
        XDrawArc(dis,win,gc,x,1, 17,17,0,23040);

Compiling your Code

1. gcc hi.c -o hi -lX11
2. gcc hi.c -o hi -I /usr/include/X11 -L /usr/X11/lib -lX11
3. gcc hi.c -o hi -I /sowhere/else -L /who/knows/where -lX11

Before running your program don't forget to set your DISPLAY environment variable! In csh: setenv DISPLAY my.ip.number.here:0. In others try: DISPLAY=my.ip.number.here:0; export DISPLAY.

Conclusions

Here is a very simple sample program for your to try out.

Origional Author of this page: bhammond@blaze.cba.uga.edu