The example client program creates and displays a simple pop-up menu consisting of a column of strings--a title string followed by selectable menu item strings. The implementation uses one window to represent the entire menu, plus a set of subwindows, one for each menu item. Here is the definition of a structure which represents such a menu.

(defstruct (menu)
   "A simple menu of text strings."
   (title "Choose an item:")
   item-alist                   ;((item-window item-string))
   window
   gcontext
   width
   title-width
   item-width
   item-height
   (geometry-changed-p t))      ;nil if unchanged since displayed
        

The window slot will contain the window object that represents the menu. The item- alist represents the relationship between the menu items and their associated subwindows. Each entry in item-alist is a list whose first element is a (sub)window object and whose second element is the corresponding item string. A window object is an instance of a CLX-defined data type which represents X windows. A window object actually carries two pieces of information: an X window ID integer and a display object. A display is another CLX-defined data type that represents a connection to a specific X display server. The gcontext slot contains an instance of a CLX data type known as a graphics context. A graphics context is a set of display attribute values, such as foreground color, fill style, line style, text font, and so forth. Each X graphics request (and hence each CLX graphics function call) must supply a graphics context to use in displaying the request. The menu's gcontext will thus hold all of the attribute values used during menu display.

The first thing to do is make an instance of a menu object:

(defun create-menu (parent-window text-color background-color text-font)
   (make-menu
      ;; Create menu graphics context
      :gcontext (CREATE-GCONTEXT :drawable   parent-window
                                 :foreground text-color
                                 :background background-color
                                 :font       text-font)

      ;; Create menu window
      :window    (CREATE-WINDOW
                  :parent            parent-window
                  :class             :input-output
                  :x                 0                     ;temporary value
                  :y                 0                     ;temporary value
                  :width             16                    ;temporary value
                  :height            16                    ;temporary value
                  :border-width 2  
                  :border            text-color
                  :background        background-color
                  :save-under        :on
                  :override-redirect :on                   ;override window mgr when positioning
                  :event-mask        (MAKE-EVENT-MASK :leave-window :exposure))))
        

create-window is one of the most important CLX functions, since it creates and returns a window object. Several of its options are shown here. The default window class is :input-output, but X provides for :input-only windows, too. Every window must have a parent window, except for a system-defined root window, which represents an entire display screen. The :event-mask keyword value, a CLX event-mask data type, says that an input event will be received for the menu window when the window is exposed and also when the pointer cursor leaves the window. The window border is a pattern-filled or (as in this case) a solid-colored boundary which is maintained automatically by the X server; a client cannot draw in a window's border, since all graphics requests are relative to the origin (upper-left corner) of the window's interior and are clipped by the server to this inside region. Turning on the :save-under option is a hint to the X server that, when this window is made visible, it may be more efficient to save the pixels it obscures, rather than require several client programs to refresh their windows when the pop-up menu disappears. This is a way to work around X's client-managed refresh policy when only a small amount of screen space is needed temporarily.

Why is :override-redirect turned on for the menu window? This is actually a little unusual, because it prevents any window manager client from redirecting the position of the menu when it is popped up. Remember that the window manager represents the user's policy for controlling the positions of his windows, so this kind of redirection is ordinarily correct. However, in this case, as a favor to the user, the menu avoids redirection in order to pop up the menu at a very specific location; that is, under the pointer cursor.

What about the item subwindows? The menu-set-item-list function in the following example creates them whenever the menu's item list is changed. The upper-left x and y coordinates and the width and height are not important yet, because they are computed just before the menu is displayed. This function also calls create-window, demonstrating the equal treatment of parent and children windows in the X window hierarchy.

(defun menu-set-item-list (menu &rest item-strings)
  ;; Assume the new items will change the menu's width and height
  (setf (menu-geometry-changed-p menu) t)

  ;; Destroy any existing item windows
  (dolist (item (menu-item-alist menu))
    (DESTROY-WINDOW (first item)))
  
  ;; Add (item-window item-string) elements to item-alist
  (setf (menu-item-alist menu)
        (let (alist)
          (dolist (item item-strings (nreverse alist))
            (push (list (CREATE-WINDOW
                         :parent       (menu-window menu)
                         :x            0           ;temporary value
                         :y            0           ;temporary value
                         :width        16          ;temporary value
                         :height       16          ;temporary value
                         :background   (GCONTEXT-BACKGROUND (menu-gcontext menu))
                         :event-mask   (MAKE-EVENT-MASK :enter-window
                                                        :leave-window
                                                        :button-press
                                                        :button-release))
                        item)
                  alist)))))