doc/objects.tex

   1
   2 \section{Class and object hierarchies}
   3 \label{sec:objects}
   4
   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
  10 other things.
  11
  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
  20 basic relations.
  21
  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 hierachy visible
  25 to Lua side.
  26
  27 \subsection{Class hierarchy}
  28
  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
  36 implement.
  37
  38 \begin{figure}
  39 \begin{htmlonly}
  40 \docode % latex2html kludge
  41 \end{htmlonly}
  42 \begin{verbatim}
  43     Obj
  44      |-->WRegion
  45      |    |-->WClientWin
  46      |    |-->WWindow
  47      |    |    |-->WMPlex
  48      |    |    |    |-->WFrame
  49      |    |    |    |-->WScreen
  50      |    |    |         |-->WRootWin
  51      |    |    |-->WInput (mod_query)
  52      |    |         |-->WEdln (mod_query)
  53      |    |         |-->WMessage (mod_query)
  54      |    |-->WGroup
  55      |    |    |-->WGroupWS
  56      |    |    |-->WGroupCW
  57      |    |-->WTiling (mod_tiling)
  58      |-->WSplit (mod_tiling)
  59 \end{verbatim}
  60 \caption{Partial Ioncore, \file{mod\_tiling} and \file{mod\_query}
  61     class hierarchy.}
  62 \label{fig:classhierarchy}
  63 \end{figure}
  64
  65 The core classes:
  66
  67 \begin{description}
  68   \item[\type{Obj}]\indextype{Obj}
  69     Is the base of Ion's object system.
  70
  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}.
  79
  80   \item[\type{WClientWin}]\indextype{WClientWin} is a class for
  81     client window objects, the objects that window managers are
  82     supposed to manage.
  83
  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).
  87
  88   \item[\type{WRootWin}]\indextype{WRootWin} is the class for
  89     root windows\index{root window} of X screens\index{screen!X}.
  90     Note that an ''X screen'' or root window is not necessarily a
  91     single  physical screen\index{screen!physical} as a root window
  92     may be split over multiple screens when hacks such as
  93     Xinerama\index{Xinerama} are used. (Actually there can be only
  94     one root window when Xinerama is used.)
  95
  96   \item[\type{WMPlex}] is a base class for all regions that''multiplex''
  97     other regions. This means that of the regions managed by the multiplexer,
  98     only one can be displayed at a time. Classes that inhereit \type{WMPlex}
  99     include screens and frames.
 100
 101   \item[\type{WScreen}]\indextype{WScreen} is the class for objects
 102     corresponding to physical screens. Screens may share a root
 103     window when the Xinerama extension is used as explained above.
 104
 105   \item[\type{WFrame}]\indextype{WFrame} is the class for frames.
 106     While most Ion's objects have no graphical presentation, frames basically
 107     add to \type{WMPlex}es the decorations around client windows
 108     (borders, tabs).
 109
 110   \item[\type{WGroup}]\indextype{WGroup} is the base class for groups.
 111     Particular types of groups are workspaces
 112     (\type{WGroupWS}\indextype{WGroupWS})
 113     and groups of client windows
 114     (\type{WGroupCW}\indextype{WGroupCW}).
 115 \end{description}
 116
 117
 118 Classes implemented by the \file{mod\_tiling} module:
 119
 120 \begin{description}
 121   \item[\type{WTiling}]\indextype{WTiling} is the class for tilings
 122     of frames.
 123   \item[\type{WSplit}]\indextype{WSplit} (or, more specifically, classes
 124     that inherit it) encode the \type{WTiling} tree structure.
 125 \end{description}
 126
 127
 128 Classes implemented by the \file{mod\_query} module:
 129
 130 \begin{description}
 131   \item[\type{WInput}]\indextype{WInput} is a virtual base class for the
 132     two classes below.
 133   \item[\type{WEdln}]\indextype{WEdln} is the class for the ''queries'',
 134     the text inputs that usually appear at bottoms of frames and sometimes
 135     screens. Queries are the functional equivalent of ''mini buffers'' in
 136     many text editors.
 137   \item[\type{WMessage}]\indextype{WMessage} implements the boxes for
 138     warning and other messages that Ion may wish to display to the user.
 139     These also usually appear at bottoms of frames.
 140 \end{description}
 141
 142 There are also some other ''proxy'' classes that do not refer
 143 to objects on the screen. The only important one of these for
 144 basic configuration is \type{WMoveresMode} that is used for
 145 binding callbacks in the move and resize mode.
 146
 147
 148 \subsection{Object hierarchies: \type{WRegion} parents and managers}
 149
 150 \subsubsection{Parent--child relations}
 151 Each object of type \type{WRegion} has a parent and possibly a manager
 152 associated to it. The parent\index{parent} for an object is always a
 153 \type{WWindow} and for \type{WRegion} with an X window (\type{WClientWin},
 154 \type{WWindow}) the parent \type{WWindow} is given by the same relation of
 155 the X windows. For other \type{WRegion}s the relation is not as clear.
 156 There is generally very few restrictions other than the above on the
 157 parent---child relation but the most common is as described in
 158 Figure \ref{fig:parentship}.
 159
 160 \begin{figure}
 161 \begin{htmlonly}
 162 \docode % latex2html kludge
 163 \end{htmlonly}
 164 \begin{verbatim}
 165     WRootWins
 166      |-->WScreens
 167           |-->WGroupWSs
 168           |-->WTilings
 169           |-->WClientWins in full screen mode
 170           |-->WFrames
 171                |-->WGroupCWs
 172                |-->WClientWins
 173                |-->WFrames for transients
 174                |-->a possible WEdln or WMessage
 175 \end{verbatim}
 176 \caption{Most common parent--child relations}
 177 \label{fig:parentship}
 178 \end{figure}
 179
 180 \type{WRegion}s have very little control over their children as a parent.
 181 The manager\index{manager} \type{WRegion} has much more control over its
 182 managed \type{WRegion}s. Managers, for example, handle resize requests,
 183 focusing and displaying of the managed regions. Indeed the manager---managed
 184 relationship gives a better picture of the logical ordering of objects on
 185 the screen. Again, there are generally few limits, but the most common
 186 hierarchy is given in Figure \ref{fig:managership}. Note that sometimes
 187 the parent and manager are the same object and not all objects may have
 188 a manager (e.g. the dock in the dock module at the time of writing this)
 189 but all have a parent--a screen if not anything else.
 190
 191 \subsubsection{Manager--managed relations}
 192
 193 \begin{figure}
 194 \begin{htmlonly}
 195 \docode % latex2html kludge
 196 \end{htmlonly}
 197 \begin{verbatim}
 198     WRootWins
 199      |-->WScreens
 200           |-->WGroupCWs for full screen WClientWins
 201           |    |-->WClientWins
 202           |    |-->WFrames for transients (dialogs)
 203           |         |--> WClientWin
 204           |-->WGroupWSs for workspaces
 205           |    |-->WTiling
 206           |    |    |-->WFrames
 207           |    |    |    |-->WGroupCWs (with contents as above)
 208           |    |    |-->possibly a WStatusBar or WDock
 209           |    |-->WFrames for floating content
 210           |    |-->possibly a WEdln, WMessage or WMenu
 211           |    |-->possibly a WStatusBar or WDock (if no tiling)
 212           |-->WFrames for sticky stuff, such as the scratchpad
 213 \end{verbatim}
 214 \caption{Most common manager--managed relations}
 215 \label{fig:managership}
 216 \end{figure}
 217
 218 Note that a workspace can manage another workspace. This can be
 219 achieved with the \fnref{attach_new} function, and allows you to nest
 220 workspaces as deep as you want.
 221
 222 %Note how the \type{WClientWin}s managed by \type{WFloatFrame}s don't have
 223 %transients managed by them. This is because WFloatWSs choose to handle
 224 %transients differently (transients are put in separate frames like normal
 225 %windows).
 226
 227 \subsection{Summary}
 228
 229 In the standard setup, keeping queries, messages and menus out of
 230 consideration:
 231
 232 \begin{itemize}
 233   \item The top-level objects that matter are screens and they correspond
 234     to physical screens. The class for screens is \type{WScreen}.
 235   \item Screens contain (multiplex) groups (\type{WGroup}) and other
 236     objects, such as \type{WFrames}. Some of these are mutually exclusive
 237     to be viewed at a time.
 238   \item Groups of the specific kind \type{WGroupWS} often contain a
 239     \type{WTiling} tiling for tiling frames (\type{WFrame}), but
 240     groups may also directly contain floating frames.
 241   \item Frames are the objects with decorations such as tabs and borders.
 242     Frames contain (multiplex) among others (groups of) client windows,
 243     to each of which corresponds a tab in the frame's decoration. Only
 244     one client window (or other object) can be shown at a time in each
 245     frame. The class for client windows is \type{WClientWin}.
 246 \end{itemize}
 247