1 Class and object hierarchies

While Notion does not have a truly object-oriented design¹, things that appear on the computer screen are, however, quite naturally expressed as such ``objects''. Therefore Notion implements a rather primitive OO system for these screen objects and some other things.

It is essential for the module writer to learn this object system, but also people who write their own binding configuration files necessarily come into contact with the class and object hierarchies - you need to know which binding setup routines apply where, and what functions can be used as handlers in which bindings. It is the purpose of this section to attempt to explain these hierarchies. If you do not wish the read the full section, at least read the summary at the end of it, so that you understand the very basic relations.

For simplicity we consider only the essential-for-basic-configuration Notioncore, mod_tiling and mod_query classes. See Appendix B for the full class hierarchy visible to Lua side.

1.1 Class hierarchy

One of the most important principles of object-oriented design methodology is inheritance; roughly how classes (objects are instances of classes) extend on others' features. Inheritance gives rise to class hierarchy. In the case of single-inheritance this hierarchy can be expressed as a tree where the class at the root is inherited by all others below it and so on. Figure 1 lists out the Notion class hierarchy and below we explain what features of Notion the classes implement.

Figure 1: Partial Notioncore, mod_tiling and mod_query class hierarchy.

    Obj
     |-->WRegion
     |    |-->WClientWin
     |    |-->WWindow
     |    |    |-->WRootWin
     |    |    |-->WMPlex
     |    |    |    |-->WFrame
     |    |    |    `-->WScreen
     |    |    `-->WInput (mod_query)
     |    |         |-->WEdln (mod_query)
     |    |         `-->WMessage (mod_query)
     |    |-->WGroup
     |    |    |-->WGroupWS
     |    |    `-->WGroupCW
     |    `-->WTiling (mod_tiling)
     `-->WSplit (mod_tiling)

The core classes:

Obj

Is the base of Notion's object system.

WRegion

is the base class for everything corresponding to something on the screen. Each object of type WRegion has a size and position relative to the parent WRegion. While a big part of Notion operates on these instead of more specialised classes, WRegion is a ``virtual'' base class in that there are no objects of ``pure'' type WRegion; all concrete regions are objects of some class that inherits WRegion.

WClientWin

is a class for client window objects, the objects that window managers are supposed to manage.

WWindow

is the base class for all internal objects having an X window associated to them (WClientWins also have X windows associated to them).

WMPlex

is a base class for all regions that ``multiplex'' other regions. This means that of the regions managed by the multiplexer, only one can be displayed at a time.

WScreen

is an instance of WMPlex for screens.

WRootWin

is the class for root windows of X screens. Note that an ``X screen'' or root window is not necessarily a single physical screen as a root window may be split over multiple screens when techniques such as Xinerama are used. (Actually there can be only one root window when Xinerama is used.)

WFrame

is the class for frames. While most Notion's objects have no graphical presentation, frames basically add to WMPlexes the decorations around client windows (borders, tabs).

WGroup

is the base class for groups. Particular types of groups are workspaces (WGroupWS) and groups of client windows (WGroupCW).

Classes implemented by the mod_tiling module:

WTiling

is the class for tilings of frames.

WSplit

(or, more specifically, classes that inherit it) encode the WTiling tree structure.

Classes implemented by the mod_query module:

WInput

is a virtual base class for the two classes below.

WEdln

is the class for the ``queries'', the text inputs that usually appear at bottoms of frames and sometimes screens. Queries are the functional equivalent of ``mini buffers'' in many text editors.

WMessage

implements the boxes for warning and other messages that Notion may wish to display to the user. These also usually appear at bottoms of frames.

There are also some other ``proxy'' classes that do not refer to objects on the screen. The only important one of these for basic configuration is WMoveresMode that is used for binding callbacks in the move and resize mode.

1.1.1 Run-time access to types

Even though it often indicates a design mistake, sometimes it can be useful to have run-time access to the types of objects.

For example, to check wether a given object is of type WMPlex, the following C code can be used:

    if(obj_is((Obj*)cwin, &CLASSDESCR(WMPlex)))
        ....

Its lua counterpart is:

    if(obj_is(cwin, "WMPlex"))
        ....

While there's also an 'obj_cast' method available, C structs can be freely cast to their 'superclass' using a regular C cast, for example:

bool input_fitrep(WInput *input, WWindow *par, const WFitParams *fp)
{
    if(par!=NULL && !region_same_rootwin((WRegion*)input, (WRegion*)par))
        return FALSE;
    ...

1.2 Object hierarchies: WRegion parents and managers

1.2.1 Parent-child relations

Each object of type WRegion has a parent and possibly a manager associated to it. The parent for an object is always a WWindow and for WRegion with an X window (WClientWin, WWindow) the parent WWindow is given by the same relation of the X windows. For other WRegions the relation is not as clear. There is generally very few restrictions other than the above on the parent--child relation but the most common is as described in Figure 2.

Figure 2: Most common parent-child relations

    WRootWins
     |-->WGroupWSs
     |-->WTilings
     |-->WClientWins in full screen mode
     `-->WFrames
          |-->WGroupCWs
          |-->WClientWins
          |-->WFrames for transients
          `-->a possible WEdln or WMessage

1.2.2 Manager-managed relations

WRegions have very little control over their children as a parent. The manager WRegion has much more control over its managed WRegions. Managers, for example, handle resize requests, focusing and displaying of the managed regions. Indeed the manager--managed relationship gives a better picture of the logical ordering of objects on the screen. Again, there are generally few limits, but the most common hierarchy is given in Figure 3. Note that sometimes the parent and manager are the same object and not all regions may have a manager, but all non-screen regions have a parent--a screen if not anything else.

Figure 3: Most common manager-managed relations

    WRootWins
     |-->WGroupCWs for full screen WClientWins
     |    |-->WClientWins
     |    `-->WFrames for transients (dialogs)
     |         `--> WClientWin
     |-->WGroupWSs for workspaces
     |    |-->WTiling
     |    |    |-->WFrames
     |    |    |    `-->WGroupCWs (with contents as above)
     |    |    `-->possibly a WStatusBar or WDock
     |    |-->WFrames for floating content
     |    |-->possibly a WEdln, WMessage or WMenu
     |    `-->possibly a WStatusBar or WDock (if no tiling)
     `-->WFrames for sticky stuff, such as the scratchpad

Note that a workspace can manage another workspace. This can be achieved with the WGroup.attach_new function, and allows you to nest workspaces as deep as you want.

In the presense of Xinerama there may be WScreen objects at the top of the manager-managed tree instead of WRootWin.

1.3 Summary

In the standard setup, keeping queries, messages and menus out of consideration:

• The top-level objects that matter are screens and they correspond to physical screens. The class for screens is WScreen.
• Screens contain (multiplex) groups (WGroup) and other objects, such as WFrames. Some of these are mutually exclusive to be viewed at a time.
• Groups of the specific kind WGroupWS often contain a WTiling tiling for tiling frames (WFrame), but groups may also directly contain floating frames.
• Frames are the objects with decorations such as tabs and borders. Frames contain (multiplex) among others (groups of) client windows, to each of which corresponds a tab in the frame's decoration. Only one client window (or other object) can be shown at a time in each frame. The class for client windows is WClientWin.

Footnotes

... design¹

the author doesn't like such artificial designs