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