]> git.decadent.org.uk Git - ion3-doc.git/blob - objects.tex
80321fa94cc61cade38de40cdf2d994c0109ec76
[ion3-doc.git] / 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           |    |    |-->possibly a WEdln, WMessage or WMenu
207           |    |    |-->WFrames
208           |    |         |-->WGroupCWs (with contents as above)
209           |    |-->WFrames for floating content
210           |-->WFrames for sticky stuff, such as the scratchpad
211 \end{verbatim}
212 \caption{Most common manager--managed relations}
213 \label{fig:managership}
214 \end{figure}
215
216 Note that a workspace can manage another workspace. This can be
217 achieved with the \fnref{attach_new} function, and allows you to nest
218 workspaces as deep as you want.
219
220 %Note how the \type{WClientWin}s managed by \type{WFloatFrame}s don't have
221 %transients managed by them. This is because WFloatWSs choose to handle
222 %transients differently (transients are put in separate frames like normal
223 %windows).
224
225 \subsection{Summary}
226
227 In the standard setup, keeping queries, messages and menus out of
228 consideration:
229
230 \begin{itemize}
231   \item The top-level objects that matter are screens and they correspond
232     to physical screens. The class for screens is \type{WScreen}.
233   \item Screens contain (multiplex) groups (\type{WGroup}) and other 
234     objects, such as \type{WFrames}. Some of these are mutually exclusive
235     to be viewed at a time.
236   \item Groups of the specific kind \type{WGroupWS} often contain a
237     \type{WTiling} tiling for tiling frames (\type{WFrame}), but 
238     groups may also directly contain floating frames.
239   \item Frames are the objects with decorations such as tabs and borders.
240     Frames contain (multiplex) among others (groups of) client windows, 
241     to each of which corresponds a tab in the frame's decoration. Only 
242     one client window (or other object) can be shown at a time in each 
243     frame. The class for client windows is \type{WClientWin}.
244 \end{itemize}
245