]> git.decadent.org.uk Git - ion3-doc.git/blob - ionnotes/node2.html
Merge commit '20080207' into HEAD
[ion3-doc.git] / ionnotes / node2.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2
3 <!--Converted with LaTeX2HTML 2002-2-1 (1.71)
4 original version by:  Nikos Drakos, CBLU, University of Leeds
5 * revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
6 * with significant contributions from:
7   Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8 <HTML>
9 <HEAD>
10 <TITLE>1 Class and object hierarchies</TITLE>
11 <META NAME="description" CONTENT="1 Class and object hierarchies">
12 <META NAME="keywords" CONTENT="ionnotes">
13 <META NAME="resource-type" CONTENT="document">
14 <META NAME="distribution" CONTENT="global">
15
16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17 <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20 <LINK REL="STYLESHEET" HREF="ionnotes.css">
21
22 <LINK REL="next" HREF="node3.html">
23 <LINK REL="previous" HREF="node1.html">
24 <LINK REL="up" HREF="ionnotes.html">
25 <LINK REL="next" HREF="node3.html">
26 </HEAD>
27
28 <BODY >
29
30 <DIV CLASS="navigation"><!--Navigation Panel-->
31 <A NAME="tex2html81"
32   HREF="node3.html">
33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> 
34 <A NAME="tex2html75"
35   HREF="ionnotes.html">
36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> 
37 <A NAME="tex2html69"
38   HREF="node1.html">
39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> 
40 <A NAME="tex2html77"
41   HREF="node1.html">
42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> 
43 <A NAME="tex2html79"
44   HREF="node8.html">
45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> 
46 <BR>
47 <B> Next:</B> <A NAME="tex2html82"
48   HREF="node3.html">2 Object system implementation</A>
49 <B> Up:</B> <A NAME="tex2html76"
50   HREF="ionnotes.html">Ion: Notes for the</A>
51 <B> Previous:</B> <A NAME="tex2html70"
52   HREF="node1.html">Contents</A>
53  &nbsp; <B>  <A NAME="tex2html78"
54   HREF="node1.html">Contents</A></B> 
55  &nbsp; <B>  <A NAME="tex2html80"
56   HREF="node8.html">Index</A></B> 
57 <BR>
58 <BR></DIV>
59 <!--End of Navigation Panel-->
60 <!--Table of Child-Links-->
61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
62
63 <UL CLASS="ChildLinks">
64 <LI><A NAME="tex2html83"
65   HREF="node2.html#SECTION00021000000000000000"><SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN> Class hierarchy</A>
66 <LI><A NAME="tex2html84"
67   HREF="node2.html#SECTION00022000000000000000"><SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN> Object hierarchies: WRegion parents and managers</A>
68 <UL>
69 <LI><A NAME="tex2html85"
70   HREF="node2.html#SECTION00022100000000000000"><SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Parent-child relations</A>
71 <LI><A NAME="tex2html86"
72   HREF="node2.html#SECTION00022200000000000000"><SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Manager-managed relations</A>
73 </UL>
74 <BR>
75 <LI><A NAME="tex2html87"
76   HREF="node2.html#SECTION00023000000000000000"><SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">3</SPAN> Summary</A>
77 </UL>
78 <!--End of Table of Child-Links-->
79 <HR>
80
81 <H1><A NAME="SECTION00020000000000000000"></A>
82 <A NAME="sec:objects"></A>
83 <BR>
84 <SPAN CLASS="arabic">1</SPAN> Class and object hierarchies
85 </H1>
86
87 <P>
88 While Ion does not not have a truly object-oriented design
89 <A NAME="tex2html1"
90   HREF="#foot215"><SUP><SPAN CLASS="arabic">1</SPAN></SUP></A>,
91 things that appear on the computer screen are, however, quite
92 naturally expressed as such ``objects''. Therefore Ion implements
93 a rather primitive OO system for these screen objects and some
94 other things. 
95
96 <P>
97 It is essential for the module writer to learn this object
98 system, but also people who write their own binding configuration files
99 necessarily come into contact with the class and object hierarchies
100 - you need to know which binding setup routines apply where, 
101 and what functions can be used as handlers in which bindings.
102 It is the purpose of this section to attempt to explain these 
103 hierarchies. If you do not wish the read the full section, at least
104 read the summary at the end of it, so that you understand the very
105 basic relations.
106
107 <P>
108 For simplicity we consider only the essential-for-basic-configuration
109 Ioncore, <SPAN  CLASS="textit">mod_tiling</SPAN> and <SPAN  CLASS="textit">mod_query</SPAN> classes. 
110 See Appendix <A HREF="#app:fullhierarchy"><IMG  ALIGN="BOTTOM" BORDER="1" ALT="[*]" SRC="crossref.png"></A> for the full class hierarchy visible
111 to Lua side.
112
113 <P>
114
115 <H2><A NAME="SECTION00021000000000000000">
116 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN> Class hierarchy</A>
117 </H2>
118
119 <P>
120 One of the most important principles of object-oriented design methodology
121 is inheritance; roughly how classes (objects are instances of classes)
122 extend on others' features. Inheritance gives rise to class hierarchy.
123 In the case of single-inheritance this hierarchy can be expressed as a
124 tree where the class at the root is inherited by all others below it
125 and so on. Figure <A HREF="#fig:classhierarchy">1</A> lists out the Ion class 
126 hierarchy and below we explain what features of Ion the classes 
127 implement.
128
129 <P>
130
131 <DIV ALIGN="CENTER"><A NAME="fig:classhierarchy"></A><A NAME="322"></A>
132 <TABLE>
133 <CAPTION ALIGN="BOTTOM"><STRONG>Figure 1:</STRONG>
134 Partial Ioncore, <SPAN  CLASS="textit">mod_tiling</SPAN> and <SPAN  CLASS="textit">mod_query</SPAN> 
135     class hierarchy.</CAPTION>
136 <TR><TD><PRE>
137     Obj
138      |--&gt;WRegion
139      |    |--&gt;WClientWin
140      |    |--&gt;WWindow
141      |    |    |--&gt;WMPlex
142      |    |    |    |--&gt;WFrame
143      |    |    |    `--&gt;WScreen
144      |    |    |         `--&gt;WRootWin
145      |    |    `--&gt;WInput (mod_query)
146      |    |         |--&gt;WEdln (mod_query)
147      |    |         `--&gt;WMessage (mod_query)
148      |    |--&gt;WGroup
149      |    |    |--&gt;WGroupWS
150      |    |    `--&gt;WGroupCW
151      |    `--&gt;WTiling (mod_tiling)
152      `--&gt;WSplit (mod_tiling)
153 </PRE></TD></TR>
154 </TABLE>
155 </DIV>
156
157 <P>
158 The core classes:
159
160 <P>
161 <DL>
162 <DT><STRONG>Obj</STRONG></DT>
163 <DD><A NAME="332"></A>
164     Is the base of Ion's object system.
165
166 <P>
167 </DD>
168 <DT><STRONG>WRegion</STRONG></DT>
169 <DD><A NAME="333"></A>
170     is the base class for everything corresponding to something on the
171     screen. Each object of type WRegion has a size and  position
172     relative to the parent WRegion. While a big part of Ion 
173     operates on these instead of more specialised classes, WRegion
174     is a ``virtual''  base class in that there are no objects of ``pure''
175     type WRegion; all concrete regions are objects of some class 
176     that inherits WRegion.
177
178 <P>
179 </DD>
180 <DT><STRONG>WClientWin</STRONG></DT>
181 <DD><A NAME="334"></A> is a class for
182     client window objects, the objects that window managers are
183     supposed to manage.
184
185 <P>
186 </DD>
187 <DT><STRONG>WWindow</STRONG></DT>
188 <DD><A NAME="335"></A> is the base class for all
189     internal objects having an X window associated to them
190     (WClientWins also have X windows associated to them).
191
192 <P>
193 </DD>
194 <DT><STRONG>WMPlex</STRONG></DT>
195 <DD>is a base class for all regions that ``multiplex'' 
196     other regions. This means that of the regions managed by the multiplexer,
197     only one can be displayed at a time. 
198
199 <P>
200 </DD>
201 <DT><STRONG>WScreen</STRONG></DT>
202 <DD><A NAME="336"></A> is an instance of WMPlex
203     for screens.
204
205 <P>
206 </DD>
207 <DT><STRONG>WRootWin</STRONG></DT>
208 <DD><A NAME="337"></A> is the class for
209     root windows<A NAME="249"></A> of X screens<A NAME="250"></A>.
210     It is an instance of WScreen.
211     Note that an ``X screen'' or root window is not necessarily a
212     single physical screen<A NAME="252"></A> as a root window
213     may be split over multiple screens when ugly hacks such as 
214     Xinerama<A NAME="253"></A> are used. (Actually there can be only 
215     one root window when Xinerama is used.) 
216
217 <P>
218 </DD>
219 <DT><STRONG>WFrame</STRONG></DT>
220 <DD><A NAME="338"></A> is the class for frames.
221     While most Ion's objects have no graphical presentation, frames 
222     basically add to WMPlexes the decorations around client 
223     windows (borders, tabs).
224
225 <P>
226 </DD>
227 <DT><STRONG>WGroup</STRONG></DT>
228 <DD><A NAME="339"></A> is the base class for groups.
229     Particular types of groups are workspaces 
230     (WGroupWS<A NAME="340"></A>)
231     and groups of client windows
232     (WGroupCW<A NAME="341"></A>).
233 </DD>
234 </DL>
235
236 <P>
237 Classes implemented by the <SPAN  CLASS="textit">mod_tiling</SPAN> module:
238
239 <P>
240 <DL>
241 <DT><STRONG>WTiling</STRONG></DT>
242 <DD><A NAME="344"></A> is the class for tilings
243     of frames.
244   
245 </DD>
246 <DT><STRONG>WSplit</STRONG></DT>
247 <DD><A NAME="345"></A> (or, more specifically, classes
248     that inherit it) encode the WTiling tree structure.
249 </DD>
250 </DL>
251
252 <P>
253 Classes implemented by the <SPAN  CLASS="textit">mod_query</SPAN> module:
254
255 <P>
256 <DL>
257 <DT><STRONG>WInput</STRONG></DT>
258 <DD><A NAME="348"></A> is a virtual base class for the
259     two classes below.
260   
261 </DD>
262 <DT><STRONG>WEdln</STRONG></DT>
263 <DD><A NAME="349"></A> is the class for the ``queries'',
264     the text inputs that usually appear at bottoms of frames and sometimes
265     screens. Queries are the functional equivalent of ``mini buffers'' in
266     many text editors.
267   
268 </DD>
269 <DT><STRONG>WMessage</STRONG></DT>
270 <DD><A NAME="350"></A> implements the boxes for 
271     warning and other messages that Ion may wish to display to the user. 
272     These also usually appear at bottoms of frames.
273 </DD>
274 </DL>
275
276 <P>
277 There are also some other ``proxy'' classes that do not refer
278 to objects on the screen. The only important one of these for
279 basic configuration is WMoveresMode that is used for
280 binding callbacks in the move and resize mode.
281
282 <P>
283
284 <H2><A NAME="SECTION00022000000000000000">
285 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN> Object hierarchies: WRegion parents and managers</A>
286 </H2>
287
288 <P>
289
290 <H3><A NAME="SECTION00022100000000000000">
291 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Parent-child relations</A>
292 </H3>
293 Each object of type WRegion has a parent and possibly a manager
294 associated to it. The parent<A NAME="285"></A> for an object is always a 
295 WWindow and for WRegion with an X window (WClientWin,
296 WWindow) the parent WWindow is given by the same relation of
297 the X windows. For other WRegions the relation is not as clear.
298 There is generally very few restrictions other than the above on the
299 parent--child relation but the most common is as described in
300 Figure <A HREF="#fig:parentship">2</A>.
301
302 <P>
303
304 <DIV ALIGN="CENTER"><A NAME="fig:parentship"></A><A NAME="296"></A>
305 <TABLE>
306 <CAPTION ALIGN="BOTTOM"><STRONG>Figure 2:</STRONG>
307 Most common parent-child relations</CAPTION>
308 <TR><TD><PRE>
309     WRootWins
310      |--&gt;WGroupWSs
311      |--&gt;WTilings
312      |--&gt;WClientWins in full screen mode
313      `--&gt;WFrames
314           |--&gt;WGroupCWs
315           |--&gt;WClientWins
316           |--&gt;WFrames for transients
317           `--&gt;a possible WEdln or WMessage
318 </PRE></TD></TR>
319 </TABLE>
320 </DIV>
321
322 <P>
323 WRegions have very little control over their children as a parent.
324 The manager<A NAME="300"></A> WRegion has much more control over its
325 managed WRegions. Managers, for example, handle resize requests,
326 focusing and displaying of the managed regions. Indeed the manager--managed
327 relationship gives a better picture of the logical ordering of objects on
328 the screen. Again, there are generally few limits, but the most common
329 hierarchy is given in Figure <A HREF="#fig:managership">3</A>. Note that sometimes
330 the parent and manager are the same object and not all regions may have
331 a manager, but all have a parent-a screen if not anything else.
332
333 <P>
334
335 <H3><A NAME="SECTION00022200000000000000">
336 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Manager-managed relations</A>
337 </H3>
338
339 <P>
340
341 <DIV ALIGN="CENTER"><A NAME="fig:managership"></A><A NAME="308"></A>
342 <TABLE>
343 <CAPTION ALIGN="BOTTOM"><STRONG>Figure 3:</STRONG>
344 Most common manager-managed relations</CAPTION>
345 <TR><TD><PRE>
346     WRootWins
347      |--&gt;WGroupCWs for full screen WClientWins
348      |    |--&gt;WClientWins
349      |    `--&gt;WFrames for transients (dialogs)
350      |         `--&gt; WClientWin
351      |--&gt;WGroupWSs for workspaces
352      |    |--&gt;WTiling
353      |    |    |--&gt;WFrames
354      |    |    |    `--&gt;WGroupCWs (with contents as above)
355      |    |    `--&gt;possibly a WStatusBar or WDock
356      |    |--&gt;WFrames for floating content
357      |    |--&gt;possibly a WEdln, WMessage or WMenu
358      |    `--&gt;possibly a WStatusBar or WDock (if no tiling)
359      `--&gt;WFrames for sticky stuff, such as the scratchpad
360 </PRE></TD></TR>
361 </TABLE>
362 </DIV>
363
364 <P>
365 Note that a workspace can manage another workspace. This can be
366 achieved with the <A HREF="#fn:attach_new"><TT>attach_new</TT></A> function, and allows you to nest
367 workspaces as deep as you want.
368
369 <P>
370
371 <H2><A NAME="SECTION00023000000000000000">
372 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">3</SPAN> Summary</A>
373 </H2>
374
375 <P>
376 In the standard setup, keeping queries, messages and menus out of
377 consideration:
378
379 <P>
380
381 <UL>
382 <LI>The top-level objects that matter are screens and they correspond
383     to physical screens. The class for screens is WScreen.
384 </LI>
385 <LI>Screens contain (multiplex) groups (WGroup) and other 
386     objects, such as WFrames. Some of these are mutually exclusive
387     to be viewed at a time.
388 </LI>
389 <LI>Groups of the specific kind WGroupWS often contain a
390     WTiling tiling for tiling frames (WFrame), but 
391     groups may also directly contain floating frames.
392 </LI>
393 <LI>Frames are the objects with decorations such as tabs and borders.
394     Frames contain (multiplex) among others (groups of) client windows, 
395     to each of which corresponds a tab in the frame's decoration. Only 
396     one client window (or other object) can be shown at a time in each 
397     frame. The class for client windows is WClientWin.
398 </LI>
399 </UL>
400
401 <P>
402 <BR><HR><H4>Footnotes</H4>
403 <DL>
404 <DT><A NAME="foot215">... design</A><A
405  HREF="node2.html#tex2html1"><SUP><SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
406 <DD>the author doesn't like such artificial designs
407
408 </DD>
409 </DL>
410 <DIV CLASS="navigation"><HR>
411 <!--Navigation Panel-->
412 <A NAME="tex2html81"
413   HREF="node3.html">
414 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> 
415 <A NAME="tex2html75"
416   HREF="ionnotes.html">
417 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> 
418 <A NAME="tex2html69"
419   HREF="node1.html">
420 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> 
421 <A NAME="tex2html77"
422   HREF="node1.html">
423 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> 
424 <A NAME="tex2html79"
425   HREF="node8.html">
426 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> 
427 <BR>
428 <B> Next:</B> <A NAME="tex2html82"
429   HREF="node3.html">2 Object system implementation</A>
430 <B> Up:</B> <A NAME="tex2html76"
431   HREF="ionnotes.html">Ion: Notes for the</A>
432 <B> Previous:</B> <A NAME="tex2html70"
433   HREF="node1.html">Contents</A>
434  &nbsp; <B>  <A NAME="tex2html78"
435   HREF="node1.html">Contents</A></B> 
436  &nbsp; <B>  <A NAME="tex2html80"
437   HREF="node8.html">Index</A></B> </DIV>
438 <!--End of Navigation Panel-->
439
440 </BODY>
441 </HTML>