\section{Class and object hierarchies}
\label{sec:objects}

While Ion does not not have a truly object-oriented design
\footnote{the author doesn't like such artificial designs},
things that appear on the computer screen are, however, quite
naturally expressed as such ''objects''. Therefore Ion implements
a rather primitive OO system for these screen objects and some
other things. 

It is essential for the module writer to learn this object
system, but also people who write their own binding configuration files
necessarily come into contact with the class and object hierarchies
-- you need to know which binding setup routines apply where, 
and what functions can be used as handlers in which bindings.
It is the purpose of this section to attempt to explain these 
hierarchies. If you do not wish the read the full section, at least
read the summary at the end of it, so that you understand the very
basic relations.

For simplicity we consider only the essential-for-basic-configuration
Ioncore, \file{mod\_ionws} and \file{mod\_query} classes. 
See Appendix \ref{app:fullhierarchy} for the full class hierachy visible
to Lua side.

\subsection{Class hierarchy}

One of the most important principles of object-oriented design methodology
is inheritance; roughly how classes (objects are instances of classes)
extend on others' features. Inheritance gives rise to class hierarchy.
In the case of single-inheritance this hierarchy can be expressed as a
tree where the class at the root is inherited by all others below it
and so on. Figure \ref{fig:classhierarchy} lists out the Ion class 
hierarchy and below we explain what features of Ion the classes 
implement.

\begin{figure}
\begin{htmlonly}
\docode % latex2html kludge
\end{htmlonly}
\begin{verbatim}
    Obj
     |-->WRegion
     |    |-->WClientWin
     |    |-->WWindow
     |    |    |-->WRootWin
     |    |    |-->WMPlex
     |    |    |    |-->WScreen
     |    |    |    |-->WFrame
     |    |    |-->WInput (mod_query)
     |    |         |-->WEdln (mod_query)
     |    |         |-->WMessage (mod_query)
     |    |-->WGenWS
     |         |-->WIonWS (mod_ionws)
     |-->WSplit (mod_ionws)
\end{verbatim}
\caption{Ioncore, \file{mod\_ionws} and \file{mod\_query} class hierarchy.}
\label{fig:classhierarchy}
\end{figure}

The core classes:

\begin{description}
  \item[\type{Obj}]\indextype{Obj}
    Is the base of Ion's object system.

  \item[\type{WRegion}]\indextype{WRegion}
    is the base class for everything corresponding to something on the
    screen. Each object of type \type{WRegion} has a size and  position
    relative to the parent \type{WRegion}. While a big part of Ion 
    operates on these instead of more specialised classes, \type{WRegion}
    is a ''virtual''  base class in that there are no objects of ''pure''
    type \type{WRegion}; all concrete regions are objects of some class 
    that inherits \type{WRegion}.

  \item[\type{WClientWin}]\indextype{WClientWin} is a class for
    client window objects, the objects that window managers are
    supposed to manage.

  \item[\type{WWindow}]\indextype{WWindow} is the base class for all
    internal objects having an X window associated to them
    (\type{WClientWins} also have X windows associated to them).
    
  \item[\type{WRootWin}]\indextype{WRootWin} is the class for
    root windows\index{root window} of X screens\index{screen!X}.
    Note that an ''X screen'' or root window is not necessarily a
    single  physical screen\index{screen!physical} as a root window
    may be split over multiple screens when multi-head extensions 
    such as Xinerama\index{Xinerama} are used. (Actually there
    can be only one \type{WRootWin} when Xinerama is used.)
	
  \item[\type{WMPlex}] is a base class for all regions that''multiplex'' 
    other regions. This means that of the regions managed by the multiplexer,
    only one can be displayed at a time. Classes that inhereit \type{WMPlex}
    include screens and frames.
    
  \item[\type{WScreen}]\indextype{WScreen} is the class for objects
    corresponding to physical screens. Screens may share a root
    window when Xinerama multihead extensions are used as explained
    above.

  \item[\type{WFrame}]\indextype{WFrame} is the class for frames.
    While most Ion's objects have no graphical presentation, frames basically
    add to \type{WMPlex}es the decorations around client windows 
    (borders, tabs).

  \item[\type{WGenWS}]\indextype{WGenWS} is a light base class for
    different types of workspaces.
\end{description}


Classes implemented by the ionws module:

\begin{description}
  \item[\type{WIonWS}]\indextype{WIonWS} is the class for the
    usual tiled workspaces.
  \item[\type{WSplit}]\indextype{WSplit} (or, more specifically, classes
    that inherit it) encode the \type{WIonWS} tree structure.
\end{description}


Classes implemented by the query module:

\begin{description}
  \item[\type{WInput}]\indextype{WInput} is a virtual base class for the
    two classes below.
  \item[\type{WEdln}]\indextype{WEdln} is the class for the ''queries'',
    the text inputs that usually appear at bottoms of frames and sometimes
    screens. Queries are the functional equivalent of ''mini buffers'' in
    many text editors.
  \item[\type{WMessage}]\indextype{WMessage} implements the boxes for 
    warning and other messages that Ion may wish to display to the user. 
    These also usually appear at bottoms of frames.
\end{description}


\subsection{Object hierarchies: \type{WRegion} parents and managers}

\subsubsection{Parent--child relations}
Each object of type \type{WRegion} has a parent and possibly a manager
associated to it. The parent\index{parent} for an object is always a 
\type{WWindow} and for \type{WRegion} with an X window (\type{WClientWin},
\type{WWindow}) the parent \type{WWindow} is given by the same relation of
the X windows. For other \type{WRegion}s the relation is not as clear.
There is generally very few restrictions other than the above on the
parent---child relation but the most common is as described in
Figure \ref{fig:parentship}.

\begin{figure}
\begin{htmlonly}
\docode % latex2html kludge
\end{htmlonly}
\begin{verbatim}
    WRootWins
     |-->WScreens
          |-->WIonWSs
          |-->WClientWins in full screen mode
          |-->WFrames
               |-->WClientWins, including transients
               |-->a possible WEdln or WMessage
\end{verbatim}
\caption{Most common parent--child relations}
\label{fig:parentship}
\end{figure}

\type{WRegion}s have very little control over their children as a parent.
The manager\index{manager} \type{WRegion} has much more control over its
managed \type{WRegion}s. Managers, for example, handle resize requests,
focusing and displaying of the managed regions. Indeed the manager---managed
relationship gives a better picture of the logical ordering of objects on
the screen. Again, there are generally few limits, but the most common
hierarchy is given in Figure \ref{fig:managership}. Note that sometimes
the parent and manager are the same object and not all objects may have
a manager (e.g. the dock in the dock module at the time of writing this)
but all have a parent--a screen if not anything else.

\subsubsection{Manager--managed relations}

\begin{figure}
\begin{htmlonly}
\docode % latex2html kludge
\end{htmlonly}
\begin{verbatim}
    WRootWins
     |-->WScreens
          |-->full screen WClientWins
          |    |-->transient WClientWins (dialogs)
          |-->WScratchpad
          |-->WIonWSs/WFloatWS/WPaneWS
               |-->WFrames
               |    |-->WClientWins
               |    |    |-->transient WClientWins (dialogs)
               |    |-->possibly a WEdln or WMessage
               |-->WIonWSs/WFloatWS/WPaneWS
\end{verbatim}
\caption{Most common manager--managed relations}
\label{fig:managership}
\end{figure}

Note that a workspace can manage another workspace. This can be
achieved with the \fnref{attach_new} function, and allows you to nest
workspaces as deep as you want.

%Note how the \type{WClientWin}s managed by \type{WFloatFrame}s don't have
%transients managed by them. This is because WFloatWSs choose to handle
%transients differently (transients are put in separate frames like normal
%windows).

\subsection{Summary}

In the standard setup, keeping queries, messages and menus out of
consideration:

\begin{itemize}
  \item The top-level objects that matter are screens and they correspond
    to physical screens. The class for screens is \type{WScreen}.
  \item Screens contain (multiplex) workspaces and full screen client
    windows. Only one of them can be viewed at a time.
    Workspace classes are \type{WIonWS} and \type{WFloatWS} 
    for the two different types of workspaces (and \type{WGenWS}).
  \item Frames are managed by workspaces. Frames are the objects with 
    decorations such as tabs and borders.
  \item Frames contain (multiplex) client windows, to each of which
    corresponds a tab in the frame's decoration. Only one client
    window (or other object) can be shown at a time in each frame.
    The class for client windows is \type{WClientWin}.
\end{itemize}