= CTWM PRINCIPLES OF OPERATION Olaf 'Rhialto' Seibert This document briefly explains some of the internal workings of ctwm. == 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.`. 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. == 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. === 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. === 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. == 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. == 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. == 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. == Icon Managers == === 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 === 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. == 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. footnote:[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. // vim:ft=asciidoc:expandtab: // Gen: // asciidoc -atoc -anumbered -o PRINCIPLES-OF-OPERATION.html PRINCIPLES-OF-OPERATION.txt