Beginner's Xlib Tutorial

The intention of this tutorial is to teach you how to use the Xlib interface for programming X, and how to learn more so that you can write advanced applications that require the speed or power of Xlib. This tutorial briefly covers the concepts behind:

• fundamental types
• windows
• widgets
• gadgets
• pixmaps
• events
• requests
• colors
• graphics contexts
• images
• help
• downloads

A simple example is given at the end that uses colors, draws rectangles, and handles events.

• Window
• Pixmap
• XdbeBackBuffer

• buttons
• menus
• scrollbars

• mouse button presses/releases
• keyboard key presses/releases
• a new window
• exposure of a window through raising it, uncovering it, or creating it
• the resizing of a window
• a property changing for a window (for example: the title)

X has been ported to dozens of different kinds of machines. From black and white displays, to 32-bit or higher displays. Most common displays are now using 16, 24, or 32 bits for each pixel. Older displays may only allow for 8 bits. Colors may be represented differently depending on the system. Some systems may have colormaps that retain a variable number of color cells, while others may have a static map of colors.

XParseColor() is used to convert a symbolic name to a series of RGB values for an XColor structure. XAllocColor is used after a color is parsed, and its RGB components stored in a structure. XAllocColor will match the color's RGB components to a cell in the colormap for the display.

X uses an XImage structure for storage of regions of the display, that can be manipulated as sequential bytes of memory in the ->data member of the structure, or via the XPutPixel()/XGetPixel() functions.

The format of the XImage ->data member is dependent on the visual, and byte order of the display. An X server may run on a Sparc™ while the client runs on an Intel Pentium™. This means that the data will need to be reformated, because the byte order is different on these two processors. If the data is not reformatted then the colors may be incorrect. There are two formats for the ->byte_order member; LSBFirst (least significant byte first), and MSBFirst (most significant byte first). See XPutImage below.

The XPutPixel and XGetPixel functions properly handle the display's visual formats, and translate as needed. However, the large number of function calls needed for setting/manipulating an image may cause a slowdown if they are used.

int get_byte_order (void) {
	union {
		char c[sizeof(short)];
		short s;
	} order;

	order.s = 1;
	if ((1 == order.c[0])) {
		return LSBFirst;
        }
	return MSBFirst; 
}

First we must retrieve an event using the XNextEvent() function. Then we must switch on the event's type in order to find what the server has sent our client. Finally we can find the structure member that has the information we want.

For example to find which button was pressed in a window, that we have selected input from, we start by doing man XEvent. We want the XButtonEvent's member which the manual page says is "xbutton", so thus far we have a name of: event.xbutton. Now we need to find which member of the XButtonEvent structure contains the value of the button. We find it via man XButtonEvent which states that the member is "button". Thus, to print the button that was pressed we would use event.xbutton.button.

Here is some code taken from the final example given at the end of this tutorial:

XNextEvent(dis, &event);
switch (event.type) {
	case ButtonPress:
		printf ("You pressed button %d\n", event.xbutton.button);
	break;
}