doc/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="tex2html82"
  32   HREF="node3.html">
  33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
  34 <A NAME="tex2html76"
  35   HREF="ionnotes.html">
  36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
  37 <A NAME="tex2html70"
  38   HREF="node1.html">
  39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
  40 <A NAME="tex2html78"
  41   HREF="node1.html">
  42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
  43 <A NAME="tex2html80"
  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="tex2html83"
  48   HREF="node3.html">2 Object system implementation</A>
  49 <B> Up:</B> <A NAME="tex2html77"
  50   HREF="ionnotes.html">Ion: Notes for the</A>
  51 <B> Previous:</B> <A NAME="tex2html71"
  52   HREF="node1.html">Contents</A>
  53  &nbsp; <B>  <A NAME="tex2html79"
  54   HREF="node1.html">Contents</A></B>
  55  &nbsp; <B>  <A NAME="tex2html81"
  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="tex2html84"
  65   HREF="node2.html#SECTION00021000000000000000"><SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN> Class hierarchy</A>
  66 <LI><A NAME="tex2html85"
  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="tex2html86"
  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="tex2html87"
  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="tex2html88"
  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="#foot212"><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 hierachy 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="318"></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="324"></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="325"></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="326"></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="327"></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>WRootWin</STRONG></DT>
 195 <DD><A NAME="328"></A> is the class for
 196     root windows<A NAME="242"></A> of X screens<A NAME="243"></A>.
 197     Note that an ''X screen'' or root window is not necessarily a
 198     single  physical screen<A NAME="244"></A> as a root window
 199     may be split over multiple screens when hacks such as
 200     Xinerama<A NAME="245"></A> are used. (Actually there can be only
 201     one root window when Xinerama is used.)
 202
 203 <P>
 204 </DD>
 205 <DT><STRONG>WMPlex</STRONG></DT>
 206 <DD>is a base class for all regions that''multiplex''
 207     other regions. This means that of the regions managed by the multiplexer,
 208     only one can be displayed at a time. Classes that inhereit WMPlex
 209     include screens and frames.
 210
 211 <P>
 212 </DD>
 213 <DT><STRONG>WScreen</STRONG></DT>
 214 <DD><A NAME="329"></A> is the class for objects
 215     corresponding to physical screens. Screens may share a root
 216     window when the Xinerama extension is used as explained above.
 217
 218 <P>
 219 </DD>
 220 <DT><STRONG>WFrame</STRONG></DT>
 221 <DD><A NAME="330"></A> is the class for frames.
 222     While most Ion's objects have no graphical presentation, frames basically
 223     add to WMPlexes the decorations around client windows
 224     (borders, tabs).
 225
 226 <P>
 227 </DD>
 228 <DT><STRONG>WGroup</STRONG></DT>
 229 <DD><A NAME="331"></A> is the base class for groups.
 230     Particular types of groups are workspaces
 231     (WGroupWS<A NAME="332"></A>)
 232     and groups of client windows
 233     (WGroupCW<A NAME="333"></A>).
 234 </DD>
 235 </DL>
 236
 237 <P>
 238 Classes implemented by the <SPAN  CLASS="textit">mod_tiling</SPAN> module:
 239
 240 <P>
 241 <DL>
 242 <DT><STRONG>WTiling</STRONG></DT>
 243 <DD><A NAME="335"></A> is the class for tilings
 244     of frames.
 245
 246 </DD>
 247 <DT><STRONG>WSplit</STRONG></DT>
 248 <DD><A NAME="336"></A> (or, more specifically, classes
 249     that inherit it) encode the WTiling tree structure.
 250 </DD>
 251 </DL>
 252
 253 <P>
 254 Classes implemented by the <SPAN  CLASS="textit">mod_query</SPAN> module:
 255
 256 <P>
 257 <DL>
 258 <DT><STRONG>WInput</STRONG></DT>
 259 <DD><A NAME="338"></A> is a virtual base class for the
 260     two classes below.
 261
 262 </DD>
 263 <DT><STRONG>WEdln</STRONG></DT>
 264 <DD><A NAME="339"></A> is the class for the ''queries'',
 265     the text inputs that usually appear at bottoms of frames and sometimes
 266     screens. Queries are the functional equivalent of ''mini buffers'' in
 267     many text editors.
 268
 269 </DD>
 270 <DT><STRONG>WMessage</STRONG></DT>
 271 <DD><A NAME="340"></A> implements the boxes for
 272     warning and other messages that Ion may wish to display to the user.
 273     These also usually appear at bottoms of frames.
 274 </DD>
 275 </DL>
 276
 277 <P>
 278 There are also some other ''proxy'' classes that do not refer
 279 to objects on the screen. The only important one of these for
 280 basic configuration is WMoveresMode that is used for
 281 binding callbacks in the move and resize mode.
 282
 283 <P>
 284
 285 <H2><A NAME="SECTION00022000000000000000">
 286 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN> Object hierarchies: WRegion parents and managers</A>
 287 </H2>
 288
 289 <P>
 290
 291 <H3><A NAME="SECTION00022100000000000000">
 292 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Parent-child relations</A>
 293 </H3>
 294 Each object of type WRegion has a parent and possibly a manager
 295 associated to it. The parent<A NAME="281"></A> for an object is always a
 296 WWindow and for WRegion with an X window (WClientWin,
 297 WWindow) the parent WWindow is given by the same relation of
 298 the X windows. For other WRegions the relation is not as clear.
 299 There is generally very few restrictions other than the above on the
 300 parent--child relation but the most common is as described in
 301 Figure <A HREF="#fig:parentship">2</A>.
 302
 303 <P>
 304
 305 <DIV ALIGN="CENTER"><A NAME="fig:parentship"></A><A NAME="292"></A>
 306 <TABLE>
 307 <CAPTION ALIGN="BOTTOM"><STRONG>Figure 2:</STRONG>
 308 Most common parent-child relations</CAPTION>
 309 <TR><TD><PRE>
 310     WRootWins
 311      |--&gt;WScreens
 312           |--&gt;WGroupWSs
 313           |--&gt;WTilings
 314           |--&gt;WClientWins in full screen mode
 315           |--&gt;WFrames
 316                |--&gt;WGroupCWs
 317                |--&gt;WClientWins
 318                |--&gt;WFrames for transients
 319                |--&gt;a possible WEdln or WMessage
 320 </PRE></TD></TR>
 321 </TABLE>
 322 </DIV>
 323
 324 <P>
 325 WRegions have very little control over their children as a parent.
 326 The manager<A NAME="296"></A> WRegion has much more control over its
 327 managed WRegions. Managers, for example, handle resize requests,
 328 focusing and displaying of the managed regions. Indeed the manager--managed
 329 relationship gives a better picture of the logical ordering of objects on
 330 the screen. Again, there are generally few limits, but the most common
 331 hierarchy is given in Figure <A HREF="#fig:managership">3</A>. Note that sometimes
 332 the parent and manager are the same object and not all objects may have
 333 a manager (e.g. the dock in the dock module at the time of writing this)
 334 but all have a parent-a screen if not anything else.
 335
 336 <P>
 337
 338 <H3><A NAME="SECTION00022200000000000000">
 339 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Manager-managed relations</A>
 340 </H3>
 341
 342 <P>
 343
 344 <DIV ALIGN="CENTER"><A NAME="fig:managership"></A><A NAME="304"></A>
 345 <TABLE>
 346 <CAPTION ALIGN="BOTTOM"><STRONG>Figure 3:</STRONG>
 347 Most common manager-managed relations</CAPTION>
 348 <TR><TD><PRE>
 349     WRootWins
 350      |--&gt;WScreens
 351           |--&gt;WGroupCWs for full screen WClientWins
 352           |    |--&gt;WClientWins
 353           |    |--&gt;WFrames for transients (dialogs)
 354           |         |--&gt; WClientWin
 355           |--&gt;WGroupWSs for workspaces
 356           |    |--&gt;WTiling
 357           |    |    |--&gt;WFrames
 358           |    |    |    |--&gt;WGroupCWs (with contents as above)
 359           |    |    |--&gt;possibly a WStatusBar or WDock
 360           |    |--&gt;WFrames for floating content
 361           |    |--&gt;possibly a WEdln, WMessage or WMenu
 362           |    |--&gt;possibly a WStatusBar or WDock (if no tiling)
 363           |--&gt;WFrames for sticky stuff, such as the scratchpad
 364 </PRE></TD></TR>
 365 </TABLE>
 366 </DIV>
 367
 368 <P>
 369 Note that a workspace can manage another workspace. This can be
 370 achieved with the <A HREF="#fn:attach_new"><TT>attach_new</TT></A> function, and allows you to nest
 371 workspaces as deep as you want.
 372
 373 <P>
 374
 375 <H2><A NAME="SECTION00023000000000000000">
 376 <SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">3</SPAN> Summary</A>
 377 </H2>
 378
 379 <P>
 380 In the standard setup, keeping queries, messages and menus out of
 381 consideration:
 382
 383 <P>
 384
 385 <UL>
 386 <LI>The top-level objects that matter are screens and they correspond
 387     to physical screens. The class for screens is WScreen.
 388 </LI>
 389 <LI>Screens contain (multiplex) groups (WGroup) and other
 390     objects, such as WFrames. Some of these are mutually exclusive
 391     to be viewed at a time.
 392 </LI>
 393 <LI>Groups of the specific kind WGroupWS often contain a
 394     WTiling tiling for tiling frames (WFrame), but
 395     groups may also directly contain floating frames.
 396 </LI>
 397 <LI>Frames are the objects with decorations such as tabs and borders.
 398     Frames contain (multiplex) among others (groups of) client windows,
 399     to each of which corresponds a tab in the frame's decoration. Only
 400     one client window (or other object) can be shown at a time in each
 401     frame. The class for client windows is WClientWin.
 402 </LI>
 403 </UL>
 404
 405 <P>
 406 <BR><HR><H4>Footnotes</H4>
 407 <DL>
 408 <DT><A NAME="foot212">... design</A><A
 409  HREF="node2.html#tex2html1"><SUP><SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
 410 <DD>the author doesn't like such artificial designs
 411
 412 </DD>
 413 </DL>
 414 <DIV CLASS="navigation"><HR>
 415 <!--Navigation Panel-->
 416 <A NAME="tex2html82"
 417   HREF="node3.html">
 418 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
 419 <A NAME="tex2html76"
 420   HREF="ionnotes.html">
 421 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
 422 <A NAME="tex2html70"
 423   HREF="node1.html">
 424 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
 425 <A NAME="tex2html78"
 426   HREF="node1.html">
 427 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
 428 <A NAME="tex2html80"
 429   HREF="node8.html">
 430 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
 431 <BR>
 432 <B> Next:</B> <A NAME="tex2html83"
 433   HREF="node3.html">2 Object system implementation</A>
 434 <B> Up:</B> <A NAME="tex2html77"
 435   HREF="ionnotes.html">Ion: Notes for the</A>
 436 <B> Previous:</B> <A NAME="tex2html71"
 437   HREF="node1.html">Contents</A>
 438  &nbsp; <B>  <A NAME="tex2html79"
 439   HREF="node1.html">Contents</A></B>
 440  &nbsp; <B>  <A NAME="tex2html81"
 441   HREF="node8.html">Index</A></B> </DIV>
 442 <!--End of Navigation Panel-->
 443
 444 </BODY>
 445 </HTML>