The Xlib API

• For most X Window applications that you'll develop, you'll probably use one of the high-level toolkits such as Motif, Athena, GTK, or Qt.
• However, in addition to providing the software interface between higher-level toolkits and the X server, the Xlib API provides useful graphics operations that you're likely to need in graphics-oriented applications.
• XopenDisplay; Xlib functions require a display pointer. We use XopenDisplay to connect a program to an X server. The display name has the general form hostname:displaynumber:screen-number. You might want to simply use localhost and default the display and screen numbers. The function signature is as follows:

  Display * XOpenDisplay(char *display_name)
  

• XcreateSimpleWindow and XcreateWindow; The function XcreateWindow is the general-purpose function for creating new windows on an X display. The simpler XCreateSimpleWindow function creates a window using default values inherited from the parent window. The function signatures are as follows:

  Window XcreateWindow(Display *display, Window parent,
  int x, int y,
  int width, int height,
  unsigned int border_width,
  unsigned int depth, int class,
  Visual * visual,
  unsigned long valuemask,
  XSetWindowAttributes * attributes)
  

  Window XCreateSimpleWindow(Display * display,
  Window parent,
  int x, int y,
  unsigned int width,
  unsigned int height,
  unsigned int border_width,
  unsigned long border,
  unsigned long background)
  

  see man XSetWindowAttributes
• Mapping and Unmapping Windows; An X Window is made visible by mapping and invisible by unmapping. The function signatures for the utility functions that control window visibility are as follows:

  XMapWindow(Display *display, Window w)
  XMapSubwindows(Display * display, Window w)
  XUnmapWindow(Display * display, Window w)
  

  • Mapping a window might not immediately make it visible because a window and all of its parents need to be mapped to become visible.
  • This behavior is convenient because you can make an entire tree of nested (or child) windows invisible by unmapping the topmost window.
  • When you unmap a window, the X server automatically generates a windows expose event for any windows that are uncovered.
• Destroying Windows; In order to free system resources, X Windows should be destroyed when they are no longer needed. The XDestroyWindow function destroys a single window, while XDestroySubWindows destroys all child windows. The signatures for these functions are as follows:

  XDestroyWindow(Display * display, Window w)
  XDestroySubwindows(Display * display, Window w)
  

• Event Handling; Event handling with the Xlib API is not too difficult. A program must register for the types of events that it is interested in by using XSelectInput, and check for events from the X server by using XNextEvent.
• XSelectInput; The function signature for XSelectInput is as follows:

  XSelectInput(Display * display, Window w, long event_mask)
  

  The display variable defines which X server the application is using for display. Events are window-specific.
• Initializing Graphics Context and Fonts; An X window has a Graphics Context (GC) that specifies drawing parameters such as foreground and background colors and the current font. A GC is created with XCreateGC that has the following function signature:

  GC XCreateGC(Display * display, Drawable d, unsigned long valuemask,
               XGCValues * values)
  

  • A Drawable is usually a Window object, but can also be a PixMap.
  • After defining a GC, a program might want to set the font, foreground color, and background color using the following functions:

    XSetFont(Display *display, GC gc, Font font)
    XSetForeground(Display *display, GC gc, unsigned long a_color)
    XSetBackground(Display *display, GC gc, unsigned long a_color)
    

  • A color value can be obtained by using XParseColor or using one of the following macros:

    BlackPixel(Display * display, Screen screen)
    WhitePixel(Display * display, Screen screen)
    

• Drawing in an X Window; Usually, drawing in an X Window is performed after a program receives an expose event. The following list of drawing functions shows a sample of the graphics operations available to X Window programmers:

  XDrawString(Display *display, Drawable d, GC gc, int x, int y,
              char * string, int string_length)
  XDrawLine(Display *display, Drawable d, GC gc, int x1, int y1, 
              int x2, int y2)
  XDrawRectangle(Display *display, Drawable d, GC gc, int x, 
                 int y, unsigned int width, unsigned int height)
  XDrawArc(Display *display, Drawable d, GC gc, int x, int y,
         unsigned int width, unsigned int height, int angle1, int angle2)