The following major sections describe the Xlib library and its functions:
When users enter input on a terminal, an X server distributes that input to client programs that are on the same system or elsewhere in the network. The X server then returns the requested actions, such as refreshing the screen or starting an application. The windowing interface is consistent across platforms and remains consistent because the Xlib library controls system calls.The Xlib library is a C language function library that client programs use to communicate with the windowing system. Calls to the client are sent through the Xlib library, and return information passes back through the Xlib library, which translates information to a standard X-Window language.
As a programmer, the application program you create is the client of the client-server relationship; you write the program and the X server gives it hardware independence. There is one X server for each virtual terminal that runs AIXwindows.
A window is a rectangular area on the screen that displays graphical output. Client applications can display overlapping and nested windows on one or more screens that are driven by X servers on one or more systems. There can be one or more physical screens each containing several windows. (The term screen refers to a physical monitor, which can be color or black and white, and associated hardware.)
The following compiler command can be used to build your program:
cc {Compiler Options} -oSample Sample.c -lX11
In this example, Sample.c is the name of your C language source program, Sample is the name of your executable C program and -lX11 indicates the function library (/usr/lib/libX11.a). The -l is the flag and X11 indicates the library.
The compiler definitions for structures, parameters, error codes, and data types are located in the /usr/include/X11/Xlib.h and /usr/include/X11/X.h files. You must include these files in any program that uses these functions. To include these files, enter the following statement early in your program:
#include <X11/Xlib.h> /* also includes X11/X.h */
The windows in an X server are arranged in a strict hierarchy. At the top of the hierarchy is the root window, which covers the entire display screen. The root window is partially or completely covered by lower-level child windows. The root window is parent to its child windows, and all windows except the root have parents. Child windows can, in turn, have their own children, which allows an application program to create an organizational tree on the screen. There is usually at least one window per application.
A child window can be larger than its parent, and part or all of the child window can extend beyond the boundaries of the parent. However, moving a child window outside the parent clips it; the only visible part of the window is that part within the parent's boundaries.
If several children of a window have overlapping locations, one of the children is considered to be on top of or raised over the others, obscuring them. Output to areas covered by other windows is not displayed; it is suppressed by the window system.
A window has a border that can be any pattern or solid color. A window usually has a background pattern that the window system repaints when the window is uncovered. (To keep track of objects within, each window has its own coordinate system.) Child windows obscure their parents unless the child has no background. Graphic operations in the parent window are usually clipped by the child windows.
Input takes the form of events. Events can be side effects of a command (for example, restacking windows generates exposure events) or they can be completely asynchronous (keyboard entries). AIXwindows never sends events that a client application did not request; the client application must request to be informed of events.
AIXwindows does not take responsibility for the contents of windows. When part or all of a window is hidden and then brought back onto the screen, its contents may be lost. The client program is then notified by an exposure event that part or all of the window needs to be repainted. Your programs must be prepared to regenerate the contents of windows on demand.
AIXwindows provides off-screen storage of graphics objects, called pixmaps. Keeping graphics off screen allows the system to redraw windows more quickly because the information within them is still in memory. Single plane (depth 1) pixmaps are sometimes referred to as bitmaps. Bitmaps can be used in most graphics functions interchangeably with windows and are used in various graphics operations to define patterns, also called tiles. (Windows and pixmaps together are referred to as drawables.)
Most of the functions in the Xlib library only add requests to an output buffer. These requests run later (and asynchronously) on the X server. Functions that attempt to return values stored in the X server do not return; these functions block until the X server sends an explicit reply or an error occurs. If a nonblocking call results in an error, the error is generally not reported by an optional error handler until a later blocking call is made.
If AIXwindows does not process a request asynchronously, a client can follow the request with a call to the XSync function. The XSync function blocks until all previously buffered asynchronous events are sent and acted upon. The output buffer is always erased by a call to any function that returns a value or waits for input (for example, the XPending, XNextEvent, XWindowEvent, XFlush, or XSynchronize functions).
Many Xlib functions return an integer resource ID that allows you to refer to objects stored on the X server. These objects can be of type Window, Font, Pixmap, Bitmap, Cursor, and GContext, as defined in the file <X11/X.h>. (The < > is defined by the #include statement of the C compiler and is a file relative to a well-known directory. In the AIX Operating System this directory is /usr/include.)
Some functions return Status, which is an integer error indication. If the function fails, the Status is 0 (zero). A status of 0 indicates the function did not update the return parameters. Because the C language does not provide multiple return values, many functions must return their results by writing to client-passed storage. A pointer that is used to return a value is designated by the Return suffix as part of its name. All other pointers passed to these functions are used for reading only. By default, errors are handled either by a standard library function or by a library function that you provide. Functions that return pointers to strings return NULL pointers if the string does not exist.
Input events (for example, key press events or mouse activity events) arrive asynchronously from the server and are queued until they are requested by a call to the XNextEvent or XWindowEvent functions. In addition, some of the library functions (such as the XResizeWindow and XRaiseWindow functions) generate exposure events or requests to repaint sections of a window that do not have valid contents. These events also arrive asynchronously, but the client can wait for them by explicitly calling the XSync function after calling a function that generates exposure events.
AIXwindows Overview provides a conceptual introduction to using AIXwindows functions, macros, protocols, extensions, and events. The AIXwindows program is a tool designed to help enhance the usability of the overall application processing environment.