XEmacs Window Manager

Edition 1.0, for XWEM version 0.0.1

Zajcev Evgeny
Alex Ott

Table of Contents


Here is basic overview of XWEM. What it is. Why it is needed. Why one should use it. etc

TODO: write me

Getting Started

You must provide some effort in way to make XWEM usable. Configuring XWEM splits to three tasks:

Configuring X

First off all we need to configure keyboard to obtain control over XWEM. XWEM expects that there is Hyper key setuped on your keyboard and that Hyper key acts as modifier(i.e. in X's modifiers list). Hyper key for XWEM is like Meta key for Emacs. All default commands in XWEM uses Hyper, it is not necessary, but recommended, so XWEM bindings will not overlaps with keybindings of other X application.

There is two ways to configure Hyper key. One is using XKB X extension and the other(easier) is using xmodmap application. Find a key(keycode) to which you want bind Hyper, using xev(1) utility. Consider it is 109.

$ xmodmap -e "keycode 109 = Hyper_R"
$ xmodmap -e "add mod3 = Hyper_R"

or add following to your ~/.Xmodmap or whatever:

keycode 109 = Hyper_R
add mod3 = Hyper_R

after that xev should report that keycode 109 have corresponded Hyper_R keysym.

Now it is time to modify a little your ~/.xinitrc. Who will be your window manager? of course your guess about emacs is correct. So instead of running afterstep for example you need to run emacs. Part of your ~/.xinitrc should looks like:

; exec afterstep
exec xemacs

You should run xinit, or startx with -tcp-listen option, otherwise Xlib will not be able to connect to X server.

Configuring Emacs

Now we are almost ready to run XWEM. Add something like

(add-to-list 'load-path (expand-file-name "/path/to/xwem"))
(require 'xwem-main)

at the end of your ~/.emacs(or whatever)(2).

TODO: write how you need to configure emacs, i.e. what to need to add in ~/.emacs.

Configuring XWEM

You may configure any of XWEM's subroutines using ~/.xwemrc.el file. It will be evaluated at the top of xwem-init function.

Here is example of what you can do:

;; Since we are using `background' to start processes, customize it a
;; little.
(setq background-show nil)              ; do not show jobs buffers

;; Debugging stuff
(when (getenv "XWEMDEBUGGING")
        (setq X-debugging t)
        (setq debug-on-error t))

;; Add our GCs, it will be used to display gnus info
(setq xwem-gc-bonus-gcs
      (list (xwem-gc-new 'my-titl1 'black 'black
                 X-LineSolid 1)
            (xwem-gc-new 'my-titl2 'black 'black
                 X-LineSolid 1)
            (xwem-gc-new 'my-titl3 'black 'black
                 X-LineSolid 1)

;; We want gnus info in frame's title
(require 'gnus)

(defun myxwem-display-gnusinfo (frame)
  (let ((gnacin (gnus-active "mail.misc")))
    (when gnacin
      (let* ((gntextsp
               (cons "Gnus: " (xwem-gc-get xwem-gcs-list 'my-titl2))
               (cons (int-to-string (car gnacin))
                     (xwem-gc-get xwem-gcs-list 'my-titl1))
               (cons (concat "/" (int-to-string (cdr gnacin)))
                     (xwem-gc-get xwem-gcs-list 'my-titl2))))
         (gnth (xwem-textsp-height gntextsp))
         (gntw (xwem-textsp-width gntextsp)))

        (xwem-textsp-draw (xwem-dpy) (xwem-frame-win frame)
                         (- (xwem-frame-get-prop frame 'width)
                            (+ gntw 10))
                          gnth gntextsp)))

(add-hook 'xwem-frame-after-title-hooks 'myxwem-display-gnusinfo)

;; TODO: add system tray configuration

TODO: what you may add to ~/.xwemrc.el.


Here is introduction to XWEM primitives, such as frame, window, client, minibuffer, specials, etc.


Frame is general thing that used to hold XWEM windows(see section Window). Usually Frame have something like titlebar which is used to display information related to manager state, such as names for XWEM Clients(see section Client) or user defined information.

TODO: add some info about Frames properties, such as GCs list, root window, selected window, etc.

Variable: xwem-frame-background
This is symbol specifies background color used in XWEM Frame. This color should be in xwem-gc-syscolors or in xwem-gc-bonus-colors.
        => gray60

Variable: xwem-frame-cursor-shape
This specifies shape of cursor when pointer is over XWEM Frame. It is value of one of X-XC-... variable.
(eq xwem-frame-cursor-shape X-XC-left_ptr)
        => t

Variable: xwem-frame-cursor-color
Specifies cursor color when pointer is over XWEM Frame. Value of this variable is list of two vectors of three integers(in RGB order) ranges from 0 to 65536, which defines foregroung and background cursor colors.

NOTE: second vector(which defines background color) may be ommited.

        => ([0 10000 0] [0 20000 0])
        => ([0 0 20000])

Variable: xwem-frame-cursor
Variable used internally by XWEM. Holds cursor wich is used when pointer is over XWEM Frame.

Variable: xwem-frame-defprops
Plist which is used to define default properties for newly created XWEM Frames. Keys in this plist is symbols, you can use one of:

title-height - Height in pixels to be used for title bar.

border-width - Width in pixels of XWEM Frame border.

title-thickness - Used for 3D view of title bar.

        => (root nil
                   selected nil
                   border t
                   border-width 0
                   title t
                   title-height 16
                   title-thickness 2
                   rw-border-width 0
                   attachable nil)

Variable: xwem-frame-title-format
Quoted textspec which is displayed in XWEM Frame's title bar. You may use frame symbol to refer to frame for which textspec is used. See also see section Text.

Variable: xwem-frame-after-title-hooks
List of hooks which will be runned after title which defined in xwem-frame-title-format displayed. Functions in this variable must accept one argument - frame for which title displayed. xwem-frame-after-title-hooks variable should be used to display additional information in XWEM Frame's title bar.
        => xwem-my-display-gnus-info

Variable: xwem-frame-list
Internal variable which holds list of all XWEM Frames.

Variable: xwem-current-frame
Internal variable which holds selected XWEM Frame.

Variable: xwem-frame-switch-hooks
List of hooks which is runned when switching between XWEM Frames occurs(i.e. xwem-current-frame changes. It runs after switching. Functions in xwem-frame-switch-hooks must accept two arguments - old-frame and new-frame.
        => (xwem-frame-focus xwem-frame-select-defhook)

Function: xwem-frame-p frame
Returns non-nil if frame is XWEM Frame.

Function: xwem-frame-dummy
Return dummy(not usable) XWEM Frame.
(xwem-frame-p (xwem-frame-dummy))
        => t

Function: xwem-frame-selected
Returns selected XWEM Frame(i.e value of xwem-current-frame).

Function: xwem-frame-selected-p frame
Return non-nil if frame is selected XWEM Frame.

Function: xwem-frame-select frame
Makes frame to be selected. Runs xwem-frame-switch-hooks if frame is not already selected.

Function: xwem-init-frames
Initialise all stuff needed to manipulate with XWEM Frames.

Function: xwem-make-frame props
Creates new XWEM Frames with merged xwem-frame-defprops and props together properties.

Function: xwem-find-frame

Function: xwem-frame-find how arg
Finds XWEM Frame according to how argument which can be one of 'xwin, 'win or 'cl and value of arg which should be of appopriate type.

Function: xwem-frame-num frame
Returns index position of frame in xwem-frame-list.

Function: xwem-frame-evhandle answer win ans
Event handler for Frames. TODO: add some description.

Variable: xwem-frame-exposes-counter
Counter of Expose X Events. The thing is that when some X window can't be redrawed without help of applicatio(say using backing store) Exposure events will be generated for each part which need to be redraw and Expose event contain counter of how many Expose events will be sended to X window, but when first event arrives we fully redraws frame, so there is no need to process others Expose events.

NOTE: Actually each XWEM Frame should have his own exposes-counter.

Function: xwem-frame-expose win ans
This function handles X Expose event.win is X Window and ans is event. Do real work only if xwem-frame-exposes-counter is equal to zero to not make same thing multiple times.

Function: xwem-frame-draw frame fully
Draw XWEM frame. If fully is non-nil then XClearArea window before drawing.

Function: xwem-frame-draw-title frame
Draws title bar for frame. Also runs functions that in xwem-frame-after-title-hooks.

Function: xwem-frame-redraw frame
Redraws outlines for XWEM Windows inside frame.

Function: xwem-frame-switch-nth n
Switch to n XWEM Frame in xwem-frame-list.

Function: xwem-frame-destroy frame
Destroys XWEM frame. TODO: I think this function should be reviewed.

Function: xwem-frame-del-win &optional frame window
Removes XWEM window from XWEM frame.

Function: xwem-frame-del-others &optional frame window
Removes all XWEM Windows from XWEM frame other then window.

Function: xwem-frame-split-horiz &optional frame
Splits XWEM frame horizontally.

Function: xwem-frame-split-vert &optional frame
Splits XWEM frame vertically.

Function: xwem-frame-win-enlarge-hor n
Enlarges xwem-win-selected in xwem-frame-selected by n pixels horizontally.

Function: xwem-frame-win-enlarge-ver n
Enlarges xwem-win-selected in xwem-frame-selected by n pixels vertically.

Function: xwem-frame-goto direction &optional frame
Go to next XWEM Window in frame in direction.


Window is subpart of XWEM Frame(see section Frame) that holds XWEM Clients (see section Client). Each XWEM Frames always contain at least one XWEM Window, but you con divide it vertically or horizontally to obtain new XWEM Windows. XWEM Windows never overlaps. There is always selected XWEM Window in each XWEM Frame, but it is not guaranties that selected XWEM Window will have input focus.

Variable: xwem-win-min-width
Minimal width in pixels that XWEM Window may have after spliting.
        => 40

Variable: xwem-win-min-height
Minimal height in pixels that XWEM Window may have after spliting.
        => 40

Variable: xwem-win-delim-width
XWEM Window delimeter width in pixels, including shadow.

Variable: xwem-win-delim-shadow-thicksness
When drawing 3D shadows for XWEM Window delimeters, this variable used.

Variable: xwem-window-defprops
Plist of default properties for newly created XWEM Windows. Keys in list is one of symbol:

Variable: xwem-win-switch-hooks
List of hooks that will be runned when selected window changes. Functions in that list should accept two arguments - old-win and new-win.
        => (xwem-win-focus xwem-win-title)

Function: xwem-win-p win
Returns non-nil if win is XWEM Window.

Function: xwem-win-dummy
Return new XWEM Window.
(eq (xwem-win-p (xwem-win-dummy)))
        => t

Function: xwem-win-selected
Returns selected XWEM Window.

Function: xwem-win-selected-p window
Return non-nil if window is selected.

Function: xwem-window-select window
Select window as current XWEM Window. Runs xwem-win-switch-hooks.

Function: xwem-win-make-list-by-next window
Creates list of XWEM Windows using 'next property.

Function: xwem-win-new props
Creates new XWEM Window using properties obtained after merging xwem-window-defprops and props together.

Function: xwem-win-replace oldw neww
Replace oldw XWEM Window with contents of neww XWEM Window.

Function: xwem-win-make-parent window
Creates dummy parent XWEM Window for window.

Function: xwem-window-next &optional window
Returns next XWEM Window after window in canonical ordering.

Function: xwem-window-next-vertical &optional window
Returns XWEM Window which is vertically after window.

Function: xwem-window-prev &optional window
Returns previous XWEM Window before window in canonical ordering of XWEM Windows.

Function: xwem-window-set-pixsize window nsize nodelete is-height
Sets size of window to nsize in pixels. If is-height is non-nil then nsize is new window height.

Function: xwem-window-delete &optional window
Deletes XWEM window. If ommited than xwem-win-selected will be used.

Function: xwem-window-delete-others &optional window
Deletes all XWEM Windows other then window.

Function: xwem-win-delete-subwindows window
Mark all child of XWEM window as deleted.

Function: xwem-win-mark-deleted window

Function: xwem-win-map fn &optional window
Apply fn function to window and each child of it. fn will be called with an XWEM Window as argument.

Function: xwem-win-count &optional window
Count childs in window.

Function: xwem-win-only-one-p &optional window
Returns non-nil if window is only one in XWEM Windows chain.

Function: xwem-window-list &optional frame

Function: xwem-curr-win-config &optional frame
Returns current XWEM Windows configuration for XWEM frame. You may restore it than using xwem-set-win-config.

Function: xwem-set-win-config win-config &optional frame
Restores window configuration win-config, returned by xwem-curr-win-config in frame.

Function: xwem-win-split &optional window how new-size
Splits XWEM window, how is one of 'vertical or horizontal(default is 'horizontal). new-size is size in pixels which should have window after split.

Function: xwem-win-draw-delims window
Draws delimeters in XWEM window.

Function: xwem-window-change-size window delta height-p
Changes XWEM window size to old-size plus delta. height-p is non-nil if height changes.

Function: xwem-init-win
Initilizes all stuff we will need.


Client is normal X11 application already managed by XWEM. All XWEM Clients manages according to XWEM Manage Database(see section Manage Database). Default behaviour is to enlarge each XWEM Client which have no override redirect flag ot XWEM Window used to hold that Client.

Variable: xwem-clients
Internally used list of XWEM Clients.

Variable: xwem-cl-setup-hooks
List of hooks which is called after XWEM Client is managed. Functions in that list should accept one argument - XWEM Client.

Variable: xwem-cl-desetup-hooks
List of hooks wich will be called when XWEM Client is demanaged. Called with one argument - XWEM Client.

Function: xwem-cl-p client
Returns non-nil if client is XWEM Client.

Function: xwem-cl-dummy
Returns XWEM Client.
(xwem-cl-p (xwem-cl-dummy))
        => t

Function: xwem-cl-hint client &optional hint
Return property hint of XWEM Client X Window. If hint is ommited than list of all properties returned. hint is number, but you can use defined values of variables: Xwemcl-WM-NORMAL-HINTS, Xwemcl-WM-HINTS, Xwemcl-WM-CLASS, Xwemcl-WM-COMMAND, Xwemcl-WM-NAME, Xwemcl-WM-TRANSIENT-FOR.

Function: xwem-client-name cl &optional clist
Returns unique name for XWEM Client cl using clist as list of XWEM Clients.

Function: xwem-find-client xwin
Finds XWEM Client by X window xwin.

Function: xwem-remove-client cl
Removes cl from XWEM Clients list xwem-clients.

TODO: write me

XWEM Minibuffer

XWEM minibuffer is global minibuffer(usually value of default-minibuffer-frame) used as minibuffer by all Emacs frames.

XWEM minibuffer is described in section Manage Database by default.

TODO: write me

XWEM Subsystems

There many subsystems in XWEM. Such as keyboard operations, pointer operations, text and graphical contexts operations, manage database operations and so on.

TODO: write me


Keyboard support in XWEM is much like how Emacs deals with keyboard i.e. keymap notation used to interpret key sequences to commands relation.


Keymaps used in xwem is:

Variable: xwem-mode-map
This is base XWEM keymap which contain other XWEM keymaps.

Variable: xwem-hyp-x-map
This keymap is for Hyper-X commands.

Variable: xwem-hyp-u-map
This keymap is for universal argument supplying.

Variable: xwem-hyp-m-map
This keymap is used to deal with X11 keyboard macros. NOTE: it is not implemented yet.

Keymap Operations

TODO: write me

Smart Modifiers

Smart modifier is key which can act as modifier when it is used in combination with some other key and as normal key when it is just clicked i.e. pressed and released.

To use smart modifiers you must set (setq xwem-use-smart-modifiers t), default is nil. And add items to xwem-key-smart-modifiers. Item is vector in form [Modifier-keysym Key-Keysym nil nil]. Second and third elements is used internally and it is no need to fill them.


(add-to-list 'xwem-key-smart-modifiers (vector XK-Control-R XK-Space nil
        => add right control to active grabs and send space key
        when it is clicked.


When I was planning to write XWEM I thought that mouse support will be minimal, but when I played a little with X11 stuff I realized where mouse may be used to get really useful functionality. Main mouse feature over keyboard is that you can generate multiple movement or button press/release events in a moment. It can be used to interact with Strokes.

Stroke is some mouse motion which yields some command.

TODO: xwem strokes description.

TODO: popup menus description.


Text Specification is list of conses in form (lala-text . GC).

TODO: write me

Manage Database

Manage Database is list of some information about certain X11 application. It contain info about how to deal with that X11 application, how it should managed, demanaged, iconified, refited, etc.

TODO: write me

System Tray

System Tray is some area in your screen, that used to hold some X applications called dock applications or dockapps in short. XWEM's system tray uses section XWEM Minibuffer as that area, so you does not lost it. It is morden to implement system tray using XEMBED protocol, which describes how dockapps and tray window should communicate. XWEM's system tray uses extended version of XEMBED protocol, which allow any dockapp to run Emacs Lisp!

Variable: xwem-use-tray
Non-nil means that user want system tray support in XWEM.

Variable: xwem-tray-max-docks
Maximum number of dockapps to be used in system tray. If value is to much, than system tray may eat too much space in XWEM's minibuffer and you will not be able to comfortable interact with it. Default value is 6.

Variable: xwem-tray-minib-position
Symbol that may be 'right or 'left specifies position in XWEM's minibuffer where first dockapp appears.

Variable: xwem-tray-minib-posoffset
Offset in pixels from XWEM's minibuffer edge.

Variable: xwem-tray-minib-docoffset
Offset in pixels between two dockapps.

Variable: xwem-tray-cursor-shape
Shape of cursor when pointer is over one of dockapp, see X-XC-XXX constants values. Default is value of X-XC-right_ptr.

Variable: xwem-tray-cursor-color
Specifies foreground and background color of curser, when pointer is over one of dockapp. Default value is '([0 0 30000] [0 0 15000]).

Variable: xwem-tray-config
This is a list of vectors and each vector is in form [type value]. Type is one of XWEM-TRAY-DOCK or XWEM-TRAY-DELIM. If type is XWEM-TRAY-DOCK than value is string and it specifies program and program's arguments you need to launch and put in system tray. If type is XWEM-TRAY-DELIM than value is integer, which specifies offset in pixels to be inserted in system tray.
        '([XWEM-TRAY-DOCK "/path/to/xwem-minitime -f 004400
                           -b bbbbbb"]
          [XWEM-TRAY-DOCK "/path/to/xwem-miniapm"]
          [XWEM-TRAY-DELIM 10]
          [XWEM-TRAY-DOCK "path/to/xwem-minilaunch
                           -l /path/to/icons/xterm.xpm xterm"]
          [XWEM-TRAY-DOCK "/path/to/xwem-minilaunch
                           -l /path/to/icons/xterm_big.xpm
                           xterm -fn 10x20"]
          [XWEM-TRAY-DOCK "/path/to/xwem-minilaunch
                           -e \"(make-frame)\"
                           /path/to/icons/xemacs.xpm emacs"]
          [XWEM-TRAY-DOCK "/path/to/xwem-minilaunch
                           -l /path/to/icons/netscape.xpm

Function: xwem-tray-run-config config
This function takes config in format described above, and executes it. See example of its usage.
(add-hook 'xwem-after-init-hooks
          (lambda ()
            (xwem-tray-run-config xwem-tray-config)))


XWEM supports multiple hooks across each routines. Here is some basic hooks that you can use to alter XWEM behaviour.

Variable: X-error-hooks
Functions in this list will be called after X11 error occurs. It called with two arguments: err-num -- error number and err-desc -- error description.

Variable: xwem-cl-setup-hooks
Called after XWEM Client managed.

Variable: xwem-cl-desetup-hooks
Called after XWEM Client demanaged.

Variable: xwem-frame-after-title-hooks
Called after title for certain frame displayed.

Variable: xwem-frame-switch-hooks
Called after selected frame changes.

Variable: xwem-after-init-hooks
Called after XWEM initialization.

Variable: xwem-minib-after-creat-hooks
Called after XWEM Minibuffer creation.

Variable: xwem-win-switch-hooks
Called after selected window changes. Called with two arguments: old-win and new-win.

TODO: describe xwem-xXXX hooks


XWEM support some logging facilities. To obtain some debug info you may want to make next:

(setq X-debugging t)
(setenv "DISPLAY" "")

and run xmond to listen 6004 port which corresponds to 4 display number.

TODO: write me

X Library Interface

Xlib is powerfull Emacs interface to X server. It supports most of things specified in X protocol and some its extensions. It can handle X windows, X graphical contexts, X fonts and more.

Xlib Constants

TODO: write me

Xlib Structures

TODO: write me

Xlib Connection

TODO: write me

Events and Errors

TODO: write me

Display Operations

TODO: write me

Window Operations

TODO: write me

Graphical Contexts

TODO: write me


TODO: write me


I think there is must be GPL text.


Jump to: c - d - e - f - g - h - i - k - l - m - o - p - s - t - w - x


  • client
  • configuring, configuring, configuring
  • connection
  • constants
  • d

  • display
  • e

  • errors
  • events
  • f

  • font
  • fonts
  • Frame
  • g

  • gc
  • h

  • hooking
  • i

  • interface
  • k

  • keyboard
  • keymap, keymap
  • l

  • license
  • logging
  • m

  • manage
  • minibuffer
  • modifiers
  • mouse
  • o

  • overview
  • p

  • primitives
  • s

  • starting
  • strokes
  • structures
  • subsystem
  • t

  • text font
  • tray
  • w

  • window, window
  • x

  • xlib

  • Footnotes


    xev utility ships with X distribution and used to report X events and its description to user.


    Note that XWEM is not yet works after compilation, so maybe there is need to remove any of .elc files from xwem's directiory.

    This document was generated on 9 August 2003 using texi2html 1.56k.