This document briefly explains some of the internal workings of ctwm.

1. Screens

Every X server may serve multiple screens, and ctwm can manage them all at once from a single instance. In practice, this does not happen often. Furthermore, in ctwm’s code you see this only in a few places; it is hidden in quite a few more. Each screen can have its own configuration file: $HOME/.ctwmrc.<screen number>.

At the start of the event handler, the screen for the current event is determined. That is stored in the global variable Scr. Everything that uses Scr is properly separated for the different screens.

2. Workspaces

The idea of workspaces is that every window has a bitfield called occupation which indicates in which workspaces it should be visible.

If a window’s occupation changes, or if the user switches the current workspace, the visibility of windows needs to be adjusted. All windows actually "exist" at all times (they are not destroyed), but the ones that are not to be visible are unmapped. When switching workspaces or occupation, some windows will be unmapped and others will be remapped.

Because windows are merely unmapped when invisible (and not destroyed), they remain in the window stack. In other words they retain their stacking order which is the order in which they are front-to-back. There is only a single stacking order for all workspaces, even though it seems that every workspace has its own. Each workspace really just shows a subset of the global stacking order.

Because of the unmapping, all windows can keep the same root window as their parent.

2.1. The Occupation Window

There is a single Occupation Window for each Screen, which is used every time the f.occupy function is invoked. The Occupation Window is reparented and moved every time it is needed. If it is already mapped, and f.occupy is invoked again, the invocation fails. This makes it impossible for the user to manipulate the occupation of the occupation window in this way.

2.2. The Workspace Manager Window

Each Virtual Screen has a separate Workspace Manager Window. By default it has full occupation, i.e. it is visible in all workspaces. You can change its occupation if you wish.

This window is filled by asking the X server for the stacking order with XQueryTree(). Now that we have OTP (see later), this should be used instead.

3. On Top Priority

After version 3.8.2, OTP (OnTopPriority) was added. This allows the user to select a priority for each window. Windows of lower priority can never get on top of a window of higher priority.

To administrate this, the OTP module aims to keep a private representation of a somewhat idealized single window stack. This clashes with reality somewhat, as will become clear in other sections.

To check if the internalized single window stack matches the X server’s idea of the stack, there are regular consistency checks. If the OTP stack doesn’t match, ctwm aborts. This should possibly be relaxed before a full release.

4. Window boxes

Windows that are inside a box are not children of the root window. Therefore they are not in its stacking order either. But they must fit somewhere in OTP’s illusion of the global stacking order. The solution for that is that windows in a box are thought to be directly on top of their box.

In the OTP consistency checking, the windows in a box are special-cased. They are not checked to be in proper order in the stacking order because they are not in the stacking order at all.

If they were not ignored in this way, they would cause false alarms about the OWL list being incorrect.

5. Virtual Screens

At some point, X servers started to be able to present multiple monitors as a single screen. This is the so-called Xinerama extension (or nowadays XRandR). However, people often still want to have some separation between their monitors. Thus, Virtual Screens were invented in ctwm.

Ctwm’s Virtual Screens (vscreen, or vs) work best if your monitors are the same size. What they do is allow you to show one workspace on one screen, and another workspace on the other. You can switch workspaces independently (with some small limitations).

To make each virtual screen independent of the others (for example, each one needs their own coordinate system starting at (0,0)), a separate virtual root window is created for each virtual screen. Each monitor then is associated with one of the virtual screens (and their root window). In your configuration you must give the geometry such that the vscreens match the monitors.

X has the important property that the windows form a strict tree: a window can have only a single parent, and it can’t be added twice to the same parent either.

Because of that, you can’t view the same workspace on two virtual screens, for that would show its windows twice. Moreover, windows that occupy multiple workspaces can also be visible once only, in a single vscreen. If multiple visibility is about to happen, a single vscreen is chosen to show the window. If a window is hidden from one vscreen, it might be possible to then show it on another.

If a window was first shown on one vscreen, and later on another, it needs to be reparented from one root window to another. This is done lazily.

Ctwm administrates this with the TwmWin.vs and TwmWin.parent_vs. parent_vs indicates the current parent virtual root window. Because a window always has a parent, this can never be NULL. TwmWin.vs indicates the virtual screen where it is visible. This may be NULL, if the window has no occupation in (the workspace currently shown in) the virtual screen. If it is not NULL, it must equal .parent_vs. (So .vs could be replaced with a boolean in most places)

Note that most of ctwm’s code still assumes there is a single window stack for all windows, but with the virtual screens this is not true any more! Each virtual root window has its own window stack.

What is true, for each separate vscreen, is that if you select from ctwm’s global stack those windows that are actually parented in that vscreen, that selection corresponds to the vscreen's window stack.

In effect, the various vscreen's window stacks are potentially interlaced like several packs of cards. Depending on "where you are", you must ignore the "wrong" windows in it.

6. Icon Managers

6.1. Let’s start with the one-workspace case.

In the .ctwmrc you can specify multiple icon managers, and which windows will be placed in them. Let’s call them the primary IconMgr and secondary ``IconMgr``s. There is nothing stopping you from specifying them so, that one window might appear in multiple icon managers, but it will only go into the first one that matches.

ScreenInfo.iconmgr (Scr->iconmgr) points to the primary icon manager. The secondary ones are linked to it via IconMgr.next and .prev.

So each window occurs in a single icon manager: it has a little sub-window in it. The sub-window is represented by a WList. twm_win->iconmanagerlist points to the WList for the window.

The various WLists that are in the same iconmanager are linked via WList.next and .prev.

Undiscovered:
  • IconMgr.lasti

  • how IconMgr.first .last .active (``WList``s) are related to the pointers from the windows

6.2. Expand to multiple workspaces.

The Icon Managers are different windows in each workspace: it is not just a single window with multiple occupation. This is so that you can move it where you want in each of them. (Personally I would probably have used a single window and moved it around to remembered locations in each workspace)

So both the IconMgr and the ``WList``s are replicated for each workspace. These instances are linked via IconMgr.nextv and WList.nextv.

The replicated instances are created after the first IconMgr, in AllocateOtherIconManagers().

If we believe CreateIconManagers(), then from the primary IconMgr for workspace #0 (Scr->iconmgr), you can follow ->nextv to get to the replicas for workspace #1, #2, …, and from each of those, follow ->next to get to the secondary ``IconMgr``s for the same workspace. But the replication function is confusing.

On the other hand, in AddIconManager(), a primary or secondary IconMgr is selected from workspace #0, and then ->nextv is followed to find each of the replicas.

WorkSpace.iconmgr points to the primary Icon Manager that belongs to that workspace.

In GotoWorkspace(), there is a "reorganisation" of ``WList``s. I am not 100% sure what that means. Probably it is doing the job that more logically should be done in ChangeOccupation(), but lazily: put windows (``WList``s) in icon managers and take them out, depending on their occupation.

7. Icons

Icons consist of several parts. Some of them can come from different sources or be shared among windows.

  • struct Icon, which refers to

    • struct Image, which contains

      • X Pixmap(s) for image and optionally shape

    • X Window to place the Pixmap(s) in

Each TwmWindow may have a struct Icon which describes the currently associated icon. Icons may change, if the title matches different images from the Icon list over time:

Icons
{
     "XTerm"   "xpm:xterm"
     "* - VIM" "xpm:vim"
}

``Image``s that are loaded from an xpm or other file are stored as struct Image and cached in a global cache named Scr->ImageCache. Therefore they can be shared. The source of an Image is recorded in Icon->match and can have the values match_none, match_list, match_icon_pixmap_hint, match_net_wm_icon, match_unknown_default.

match_list

If a window changes icons like this (Vim changes the terminal window’s title when it starts up), it stores old icons on TwmWin->iconslist for later re-use. It must be certain that all these ``Image``s are indeed from the cache and not from other sources, otherwise there may be a memory leak or use-after-free. The iconslist is freed when a window is freed, but the ``Image``s it points to are left alone.
[A different implementation would allow ``Image``s from any source on the iconslist and check their source when freeing the list.]

match_icon_pixmap_hint

Another source of struct Image is the Pixmap(s) that are given in the WM_HINTS property. These are not shared.

match_net_wm_icon

The image is specified in the _NET_WM_ICON property. These struct Images are also not shared. Usually there are icons of different sizes. The user can specify the desired size (width * height). If an exact match is not found, the closest match is taken. This is based on the area (total number of pixels) of the icon. The differences are compared proportionally: the specified size times 2 is closer than the size divided by 3.

match_unknown_default

Finally there is a default Image, which is shared among all windows where needed.

Usually ctwm creates the window to display the icon itself, but again there may be one given in the WM_HINTS. If so, this window must not be destroyed.