}
proc section {name txt args} {
regsub -all {@#(.*?)#@} $txt {\1} txt
puts "
| $name |
| $txt |
"
}
section "Basic Overview" {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:
A simple example is given at the end that uses colors, draws rectangles, and handles events.
}
section "The Design of X" {
X was designed to make communication between the application and the drawing layer over a network be abstract. The user application is known as a client, and the program that draws what the client requests is known as a server. The client and server can run different operating systems, have different processor types, and be over wide networks. A client/application connects to a server using XOpenDisplay(). XOpenDisplay() returns a pointer to a Display structure. This display structure is passed to most Xlib calls to communicate with the server.
A goal of X was to provide "mechanism and not policy." This has allowed for a great deal of flexibility. This design trait is apparent with window managers, and the fact that unlike some other systems the size of an application's toplevel window is a request, and not an expectation. The window manager is free to position and resize a window as the user wants, or as the window manager deems best. A variety of window managers are available with different interaction styles.
X only provides the base functionality for drawing widgets by design, so there are various toolkits built on top of Xlib. This has allowed for a variety of implementations, such as Tk, Xt/Xaw, Motif, Qt, and Gdk/Gtk+.
}
section "Fundamental Types" {
X has fundamental types that are used to represent drawable surfaces. The following types are classified as Drawable types:
@#Window#@
@#Pixmap#@
@#XdbeBackBuffer#@
The above types and the Drawable type are XIDs. An XID is a unique integer that is usually an 'unsigned long'. A client's XID is associated with a structure on the server's side. A Window or Pixmap can generally be used in places where a Drawable is specifed as the argument type for an Xlib function.
For debugging purposes it is often useful to use a pattern of printf ("winid %lu\n", some_window);
} types
section "Windows and Layers of Windows" {A common misconception is that a window is only what is dragged around on a desktop. X has layers of windows. The root window is also known as the background window. It can have a background image, animation, and other fun things. Immediate children of the root window are generally reparented into window manager windows with titlebars, and buttons. Most applications are made up of many windows, and windows within windows.
A client's Window is an XID. On the server side, the window has a structure associated with it. That structure contains the bytes for the content of the window. Eventually the server's window structure content will be copied to the framebuffer of the video card by X, if the window is on screen, mapped, and is not obscured by other windows.
The content of a window is usually lost when it is unmapped or obscured or moved off screen. Thus, application windows must be redrawn when they are visible again. X sends an Expose event when a part, or all of a window has become visible again. Note: a window attribute called backing store can reduce the need for some Expose events, but it increases the amount of memory required to run X applications, so not all X servers use or support it.
} windows
section "Pixmaps" {
A Pixmap is a Drawable that is offscreen. Like the Window type it is an XID. The structure associated with the Pixmap's XID is stored on the X server. A Pixmap can be drawn on, and then copied to a window. It's also possible to copy a Pixmap to another Pixmap. A Pixmap is useful for buffering a drawing.
} pixmaps
section "XdbeBackBuffer" {
An XdbeBackBuffer is an XID type that is similar to a Pixmap. The contents of a back buffer are used to implement double-buffering. Quite often X applications don't use XDBE, so some flicker can occur. XDBE is generally the best way to implement double-buffering. The DBE man page documents it fairly well. You will generally want to copy a Pixmap to an XdbeBackBuffer and then swap the back buffer for the window to achieve a smooth and flicker-free display.
} xdbebackbuffer
section "Definition of a Widget" {A widget is an object usually associated with a window. It usually responds to input, and/or displays something. A few simple examples of widgets are:
@#buttons#@
@#menus#@
@#scrollbars#@
Some of you may know of widgets as "components."} widgets
section "Definition of a Gadget" {A gadget is typically an item that is drawn onto its parent, and doesn't have a window for itself. Text labels are implemented in some toolkits as gadgets.} gadgets
section "Toolkits" {
An X toolkit is typically a library that is built on top of Xlib. One of the first toolkits created is called Xt (X toolkit). It provides handling of events, widget inheritance, geometry management, and numerous other features. The first widgets built on top of Xt are known as the Xaw widgets or Athena widgets (from project Athena). Several other widget sets have been created on top of Xt, such as Xaw3D, and Motif to name a few.
Some toolkits are synonymous with a widget set, such as Tk, Gtk+, and Qt (to name a few). Tk is built on top of Xlib. Gtk+ is built on top of a layer called Gdk. Gdk is built on top of Xlib.
} toolkits
section "Events and their place in X" {The X server sends messages known as events, to a client so that it may know of:
@#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)#@
The X server doesn't send a client every single event that occurs, unless explicitly told to. To tell the X server which events an application needs the XSelectInput() function is used. It takes a mask of OR'd flags. For example: XSelectInput (dis, win, ExposureMask | KeyPressMask | ButtonPressMask);} events
section "The XEvent Structure" {An XEvent structure contains a union of structures for the various types of events. Each event type contained, and the root XEvent is documented in a man page. For example: "man XButtonEvent"}
section "The Event Queue" {When events are generated by user interaction or background tasks, they are placed into a queue that is specific to each display connection. This queue of events is then processed by the client. A common function for the purpose of retrieving and removing an item from the queue is XNextEvent(). There are several other functions that deal with the event queue. Some check for events without removing them from the queue, others check for specific classes of events.}
section "The Request Buffer" {Xlib functions that send requests are buffered for performance. In many cases an XFlush (dis); is needed to force the buffered requests to be sent/flushed to the server. Another related function is XSync which flushes and then waits until the processing of a request is complete.} requests
section "Colors" {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 array 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 allocated a cell in the colormap for the display.
} colors
section "Graphics Contexts/GCs" {A graphics context (GC) is a structure that contains an X color, font, and a drawing function. Drawing requires a GC. In many cases a GC is also needed for copying drawings to a window or from a drawing to a drawing. A GC is created with XCreateGC} contexts
section "Images" {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 performance problems if they are used.
} images
section "XCreateImage" {The XCreateImage() function is used to create an XImage structure that represents the image data. This structure is then passed to the XPutImage() function to transfer the content to a Pixmap or Window or XdbeBackBuffer. By default the ->byte_order member of an XImage returned is in the format of the server (MSBFirst or LSBFirst (see above)).}
section "XPutImage" {The XPutImage() function is used to transfer an image to the server. It also performs byte order conversions if the ->byte_order of the XImage is different than the server's byte order.}
section "Finding the Byte Order" {It's probably best to set the byte-order in your configuration system for your software, before your main program is compiled. A simple function that can be used to find the byte order is:
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;
}
You may also be able to use the <sys/endian.h> header file if it's available.
}
section "Mapping/Displaying Windows" {After a window is created it isn't visible on the screen. To display a window the XMapWindow() function is used. There are other functions that perform mapping as well, and they are documented in the man page for the XMapWindow() function.}
section "Unmapping/Hiding Windows" {The function XUnmapWindow() is typically used to unmap a window. The contents of the display will be lost in most cases, and you will need to redraw it, after mapping it again (if you do remap in the future).}
section "XEvent Usage" {
After calling XSelectInput and mapping a window on the screen the events that match the input mask will be queued. To retrieve those events we can use several functions. For this example we will use the most common; which is 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.
For example:
XNextEvent(dis, &event);
switch (event.type) {
case ButtonPress:
printf ("You pressed button %d\n", event.xbutton.button);
break;
}
In a real application we would loop, and most likely check other events.} eventusage
section "Helping Yourself" {The X man pages are vital when programming with Xlib. A very common way to help yourself is to run man -k keyword or the apropos command. The X headers can also be useful as a quick reference. When the documentation isn't clear you may find it useful to consult the postscript documentation that is available with the X sources. The X/Xlib sources are also useful when the documentation is unclear. The Xlib sources can be found in xsrc/xc/lib/X11. It's very useful to understand how to use grep when finding how a function is implemented, such as which file, and which line. For example: grep -n 'GC.*XCreateGC' *}
section "Learn by Example" {The various utilities distributed with the X distribution are incredibly useful for learning how to use Xlib features, because they are generally concise and well engineered. The popular toolkits are also good examples of how to use Xlib, but the complexity of such toolkits may require slow reading.}
section "Help!? I'm stuck!" {This happens to most X programmers. Some aspects of X may be confusing you, or you're uncertain of something, or misunderstand a key concept. If the steps outlined in Helping Yourself above don't help then I suggest you study the Usenet archives for comp.windows.x at Google Groups If you are lost amidst the archives, then try posting a question to comp.windows.x} help
section "The Downloadable Example" {The example was written by George Peter Staplin and tested in NetBSD. It should compile with most systems. Linux users (and possibly HPUX) may need to add -ldl to the compile target with -lX11 in the makefile, or alternatively use -static before -lX11.
Xlib_Beginner-4.tar.gz} downloads
puts {