Chapter 5. Fundamental Concepts of Nano-X

Table of Contents
Graphics Contexts
Modifiers and Mouse Buttons
Error Codes
Screen Properties

This introduction to Nano-X is based on the original Mini-X tutorial written by David I. Bell in 1991. Much of this is a lot easier to understand if you are familiar with X. I am not going to try to explain every concept in detail here, nor how to put it all together to make really fancy programs. Instead, I am only going to tell you just enough to let you make some simple graphics programs which work. Experience with simple test programs will enable you to build much fancier graphics programs much easier than trying to decipher what I could tell you.

I am assuming that you basically know what a screen, pixels, colors, keyboards, mice, buttons, and windows are. However, you probably don't know exactly what the properties of windows in this system are. Also, you might not know two other concepts which are important here, which are graphics contexts and events. So these things will be explained in this tutorial.


Windows are rectangular areas which can be drawn into. Windows have a position, specified by the x and y coordinates of their upper left corners, and also a size, specified by their width and height. Windows are arranged in a tree structure, with the parent windows controlling the child windows. The top of the tree is known as the root window. The root window is always present, and represents the total screen area.

Each child window is clipped by its parent window. This means that a window can be very large, but the only part of the window that can ever be seen is the part which shows through its parent window. This applies recursively, so that all of the parents of a window limit its visibility. The position of a window is specified relative to its parent, and not absolutely. This means that for example, when a window is moved, then all of its children will move with it. The position of a window can be negative.

Windows which have the same parent can clip each other. That is, there is a defined order among the children of a window as to which is more important. If two sibling windows overlap, then the more important window will be visible in preference to the less important window. The precedence of visibility of siblings can be dynamically adjusted. Clipping can also occur on a window by earlier siblings of any of the window's parents.

Windows can be mapped or unmapped. Unmapped windows are not visible, and cause no events. They can be thought of as "in storage" or offscreen. When a window is mapped, then it can become visible on the screen. Children of an unmapped window are implicitly also unmapped. So a window is not visible until it and all of its parents are mapped. A newly created window starts off unmapped.

Windows have a background color. A newly mapped window is filled with its background color. Clearing the window later, or having obscured portions of the window become visible again, will fill the region with the background. The client program can then draw into the window to make it look correct.

Windows may have a border. A border is a set of rectangles adjacent to the four sides of the window which is drawn in a specified color, with a specified width. This makes pretty lines around the window, for example. The border cannot be drawn in by the program. Borders are optional, so that a window with a border width of zero has no border at all. Borders are "around" the window, so that they do not affect the coordinates of the window. Whether or not a window has borders, its position determines the location of the upper left corner which can be drawn into.

Windows can have a cursor associated with them. The graphics server tracks the location of the mouse, and maintains the position of a graphics cursor on the screen. This cursor can automatically change its shape and colors as it moves between different windows. The use of different cursors for different windows can be used to provide a powerful clue to the user as to what will happen if a mouse button is pressed in a window. Newly created windows inherit the same cursor as their parent.

There are two types of windows, input-output and input-only windows. Input-output windows are normal windows which are visible and can be drawn into. Input-only windows are invisible, have no border, and cannot be drawn into. Their purpose is to catch events, and to enable the cursor to be changed in different regions of a visible window. The only children of input-only windows are also input-only windows.

Windows are identified by integers called window ids. The root window has a constant window id value of GR_ROOT_WINDOW_ID. The root window does not need creating, and cannot be unmapped, moved, resized, or destroyed. However, it can be drawn into and events can be delivered to it. New windows can be created from existing windows. Their window ids are not constants, but once created the window id remains until the window is destroyed. Window ids are not reused as windows are created and destroyed.