Introduction to Microwindows Programming, Part 3

Nowadays, it seems that when I've got an idea for a new program I want to write for Linux, if I search the Net, someone's already published an open-source version of it. Such was the case recently when I thought it'd really be fun to have a graphical solitaire game for Microwindows. Entering Solitaire+Linux into the search engine gave me quite a few different implementations of Klondike, as well as an old favorite, FreeCell. Most of them were written for the X Windows System environment to be played on the Linux desktop. I figured that if I could find a well-written program based only on Xlib, it would be pretty straightforward to port it to the Nano-X API of Microwindows. And what do you know--third from the top of the list appeared xfreecell, a small, well-written freecell implementation based on Xlib. Porting xfreecell to Nano-X and going over the similarities and differences between the Xlib API and Nano-X API will be the subject of this month's column. The freecell source code is available at ftp://microwindows.org/pub/microwindows/nxfreecell-0.1.tar.gz.

Portability Concerns

Of course, there are quite a few concerns that need to be thought about when considering bringing a program built for the desktop over to an embedded environment. The program's overall structure, suitability for touch-screen rather than mouse input, size, graphical widget set used and external libraries required are some of the first things to look at. Most graphical programs written for X are either based on the low-level client graphics library, Xlib, or written on top of a much larger graphical applications toolkit like GTK+, Qt or FLTK. For the utmost smallest size, writing directly to the graphical windowing system's library will usually produce the smallest and quickest code, although there are tradeoffs. The low-level client libraries are exactly that--low level. Programs gain access directly to the drawing primitives that the windowing system provides. These include support for creating windows, drawing points, lines, polygons and filling areas. The windowing system handles drawings clipped to a given window and manages the window stacking view for the user. However, neither X nor Nano-X support the prebuilt, low-level widgets, like edit boxes and pushbuttons, that many desktop programs require. All of these have to be built on top of the low-level library, or a higher level applications toolkit must be used.

Xfreecell uses only low-level Xlib calls for all its drawing functions. The images for the playing cards are all specified as monochrome bitmaps in X11 format. These can be converted to Nano-X format with little effort. Xfreecell has a few dialog boxes and data input controls, but these are written directly on top of Xlib. The remaining portions of xfreecell handles event input, which is handled similarly between X and Nano-X.

Graphical windowing environments usually differ in their basic approach to how an application must be structured to work with the windowing environment. The design of Nano-X very closely follows the windowing and graphics drawing abstractions put forth by X. Although the Nano-X API isn't a reimplementation of X, most parameters for drawing functions have the same meanings. This approach was designed for a reason: if the API were exactly the same, then a reimplementation of X wouldn't likely be much smaller because most of the X server's code is there for a reason. In addition, folks are already working on making X smaller. The Nano-X implementation uses the same window and graphics abstractions as X but redesigns certain areas that are overly complex in X, like the color model, color maps and visuals. The result is a system that has many of the same capabilities as X and uses the same programming approach but is a lot less complex and quite a bit smaller.

In porting xfreecell, I decided that I would try leaving as much of xfreecell unmodified as possible, rather than changing the names of each drawing function, for instance. The result was the creation of the XtoNX.h header file, a set of C macros that greatly speed the process of porting a program from X to Nano-X. I'll go through each of the major sections of the header file as I explain the issues I found when porting xfreecell.

The first step was to produce a set of typedefs for making the X window, pixmap, region and other IDs compatible with Nano-X. With these declarations, various structures and data types used by X are made compatible without further modification, since windows, pixmaps, graphics contexts, regions and cursors are already abstractly compatible:

typedef GR_WINDOW_ID   Window;
typedef GR_WINDOW_ID   Pixmap;
typedef GR_GC_ID       GC;
typedef GR_FONT_ID     Font;
typedef GR_CURSOR_ID   Cursor;
typedef GR_REGION_ID   Region;
typedef GR_POINT       XPoint;
typedef GR_RECT        XRectangle;
typedef unsigned long  Time;

In order to ease porting, event and font structure typedefs were also created, although their member names aren't completely compatible. In this way, the compiler will accept the variable declarations and will later flag errors when member names are referenced incompatibly:

typedef GR_EVENT      XEvent;
typedef GR_FONT_INFO  XFontStruct;

Listing 1. Display Structure

Event handling is also very similar between the two graphical windowing environments, although the structure member names can't always be made compatible. Because of this, certain portions of the event handling code will have to be changed when porting to Nano-X. However, most of the events themselves are very similar, so we can add macros that define the correlation between similar events (see Listing 2).

Listing 2. Macros