2 \section{Class and object hierarchies}
5 While Ion does not not have a truly object-oriented design
6 \footnote{the author doesn't like such artificial designs},
7 things that appear on the computer screen are, however, quite
8 naturally expressed as such ``objects''. Therefore Ion implements
9 a rather primitive OO system for these screen objects and some
12 It is essential for the module writer to learn this object
13 system, but also people who write their own binding configuration files
14 necessarily come into contact with the class and object hierarchies
15 -- you need to know which binding setup routines apply where,
16 and what functions can be used as handlers in which bindings.
17 It is the purpose of this section to attempt to explain these
18 hierarchies. If you do not wish the read the full section, at least
19 read the summary at the end of it, so that you understand the very
22 For simplicity we consider only the essential-for-basic-configuration
23 Ioncore, \file{mod\_tiling} and \file{mod\_query} classes.
24 See Appendix \ref{app:fullhierarchy} for the full class hierarchy visible
27 \subsection{Class hierarchy}
29 One of the most important principles of object-oriented design methodology
30 is inheritance; roughly how classes (objects are instances of classes)
31 extend on others' features. Inheritance gives rise to class hierarchy.
32 In the case of single-inheritance this hierarchy can be expressed as a
33 tree where the class at the root is inherited by all others below it
34 and so on. Figure \ref{fig:classhierarchy} lists out the Ion class
35 hierarchy and below we explain what features of Ion the classes
40 \docode % latex2html kludge
51 | | `-->WInput (mod_query)
52 | | |-->WEdln (mod_query)
53 | | `-->WMessage (mod_query)
57 | `-->WTiling (mod_tiling)
58 `-->WSplit (mod_tiling)
60 \caption{Partial Ioncore, \file{mod\_tiling} and \file{mod\_query}
62 \label{fig:classhierarchy}
68 \item[\type{Obj}]\indextype{Obj}
69 Is the base of Ion's object system.
71 \item[\type{WRegion}]\indextype{WRegion}
72 is the base class for everything corresponding to something on the
73 screen. Each object of type \type{WRegion} has a size and position
74 relative to the parent \type{WRegion}. While a big part of Ion
75 operates on these instead of more specialised classes, \type{WRegion}
76 is a ``virtual'' base class in that there are no objects of ``pure''
77 type \type{WRegion}; all concrete regions are objects of some class
78 that inherits \type{WRegion}.
80 \item[\type{WClientWin}]\indextype{WClientWin} is a class for
81 client window objects, the objects that window managers are
84 \item[\type{WWindow}]\indextype{WWindow} is the base class for all
85 internal objects having an X window associated to them
86 (\type{WClientWins} also have X windows associated to them).
88 \item[\type{WMPlex}] is a base class for all regions that ``multiplex''
89 other regions. This means that of the regions managed by the multiplexer,
90 only one can be displayed at a time.
92 \item[\type{WScreen}]\indextype{WScreen} is an instance of \type{WMPlex}
95 \item[\type{WRootWin}]\indextype{WRootWin} is the class for
96 root windows\index{root window} of X screens\index{screen!X}.
97 It is an instance of \type{WScreen}.
98 Note that an ``X screen'' or root window is not necessarily a
99 single physical screen\index{screen!physical} as a root window
100 may be split over multiple screens when ugly hacks such as
101 Xinerama\index{Xinerama} are used. (Actually there can be only
102 one root window when Xinerama is used.)
104 \item[\type{WFrame}]\indextype{WFrame} is the class for frames.
105 While most Ion's objects have no graphical presentation, frames
106 basically add to \type{WMPlex}es the decorations around client
107 windows (borders, tabs).
109 \item[\type{WGroup}]\indextype{WGroup} is the base class for groups.
110 Particular types of groups are workspaces
111 (\type{WGroupWS}\indextype{WGroupWS})
112 and groups of client windows
113 (\type{WGroupCW}\indextype{WGroupCW}).
117 Classes implemented by the \file{mod\_tiling} module:
120 \item[\type{WTiling}]\indextype{WTiling} is the class for tilings
122 \item[\type{WSplit}]\indextype{WSplit} (or, more specifically, classes
123 that inherit it) encode the \type{WTiling} tree structure.
127 Classes implemented by the \file{mod\_query} module:
130 \item[\type{WInput}]\indextype{WInput} is a virtual base class for the
132 \item[\type{WEdln}]\indextype{WEdln} is the class for the ``queries'',
133 the text inputs that usually appear at bottoms of frames and sometimes
134 screens. Queries are the functional equivalent of ``mini buffers'' in
136 \item[\type{WMessage}]\indextype{WMessage} implements the boxes for
137 warning and other messages that Ion may wish to display to the user.
138 These also usually appear at bottoms of frames.
141 There are also some other ``proxy'' classes that do not refer
142 to objects on the screen. The only important one of these for
143 basic configuration is \type{WMoveresMode} that is used for
144 binding callbacks in the move and resize mode.
147 \subsection{Object hierarchies: \type{WRegion} parents and managers}
149 \subsubsection{Parent--child relations}
150 Each object of type \type{WRegion} has a parent and possibly a manager
151 associated to it. The parent\index{parent} for an object is always a
152 \type{WWindow} and for \type{WRegion} with an X window (\type{WClientWin},
153 \type{WWindow}) the parent \type{WWindow} is given by the same relation of
154 the X windows. For other \type{WRegion}s the relation is not as clear.
155 There is generally very few restrictions other than the above on the
156 parent---child relation but the most common is as described in
157 Figure \ref{fig:parentship}.
161 \docode % latex2html kludge
167 |-->WClientWins in full screen mode
171 |-->WFrames for transients
172 `-->a possible WEdln or WMessage
174 \caption{Most common parent--child relations}
175 \label{fig:parentship}
178 \type{WRegion}s have very little control over their children as a parent.
179 The manager\index{manager} \type{WRegion} has much more control over its
180 managed \type{WRegion}s. Managers, for example, handle resize requests,
181 focusing and displaying of the managed regions. Indeed the manager---managed
182 relationship gives a better picture of the logical ordering of objects on
183 the screen. Again, there are generally few limits, but the most common
184 hierarchy is given in Figure \ref{fig:managership}. Note that sometimes
185 the parent and manager are the same object and not all regions may have
186 a manager, but all have a parent--a screen if not anything else.
188 \subsubsection{Manager--managed relations}
192 \docode % latex2html kludge
196 |-->WGroupCWs for full screen WClientWins
198 | `-->WFrames for transients (dialogs)
200 |-->WGroupWSs for workspaces
203 | | | `-->WGroupCWs (with contents as above)
204 | | `-->possibly a WStatusBar or WDock
205 | |-->WFrames for floating content
206 | |-->possibly a WEdln, WMessage or WMenu
207 | `-->possibly a WStatusBar or WDock (if no tiling)
208 `-->WFrames for sticky stuff, such as the scratchpad
210 \caption{Most common manager--managed relations}
211 \label{fig:managership}
214 Note that a workspace can manage another workspace. This can be
215 achieved with the \fnref{attach_new} function, and allows you to nest
216 workspaces as deep as you want.
218 %Note how the \type{WClientWin}s managed by \type{WFloatFrame}s don't have
219 %transients managed by them. This is because WFloatWSs choose to handle
220 %transients differently (transients are put in separate frames like normal
225 In the standard setup, keeping queries, messages and menus out of
229 \item The top-level objects that matter are screens and they correspond
230 to physical screens. The class for screens is \type{WScreen}.
231 \item Screens contain (multiplex) groups (\type{WGroup}) and other
232 objects, such as \type{WFrames}. Some of these are mutually exclusive
233 to be viewed at a time.
234 \item Groups of the specific kind \type{WGroupWS} often contain a
235 \type{WTiling} tiling for tiling frames (\type{WFrame}), but
236 groups may also directly contain floating frames.
237 \item Frames are the objects with decorations such as tabs and borders.
238 Frames contain (multiplex) among others (groups of) client windows,
239 to each of which corresponds a tab in the frame's decoration. Only
240 one client window (or other object) can be shown at a time in each
241 frame. The class for client windows is \type{WClientWin}.