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
.
-
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 thePixmap
(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. Theiconslist
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 theiconslist
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 theWM_HINTS
property. These are not shared. - match_net_wm_icon
-
The image is specified in the
_NET_WM_ICON
property. Thesestruct 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.