docs/reference/glk-window-arrangement.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 <!ENTITY version SYSTEM "version.xml">
   5 ]>
   6 <refentry id="chimara-Window-Arrangement">
   7 <refmeta>
   8 <refentrytitle>Window Arrangement</refentrytitle>
   9 <manvolnum>3</manvolnum>
  10 <refmiscinfo>CHIMARA Library</refmiscinfo>
  11 </refmeta>
  12 <refnamediv>
  13 <refname>Window Arrangement</refname>
  14 <refpurpose>The Way of Window Arrangement</refpurpose>
  15 </refnamediv>
  16 <refsect1>
  17 <title>Description</title>
  18 <para>
  19 The Way of Window Arrangement is fairly complicated. I'll try to explain it coherently.
  20 </para>
  21 <note><para>If you are reading this document to get an overview of Glk, by all means skip forward to <link linkend="chimara-The-Types-of-Windows">The Types of Windows</link>. Come back here later.
  22 </para></note>
  23 <para>
  24 Originally, there are no windows. You can create a window, which will take up the entire available screen area. You can then split this window in two. One of the halves is the original window; the other half is new, and can be of any type you want. You can control whether the new window is left, right, above, or below the original one. You can also control how the split occurs. It can be 50-50, or 70-30, or any other percentage split. Or, you can give a fixed width to the new window, and allow the old one to take up the rest of the available space. Or you can give a fixed width to the old window, and let the new one take up the rest of the space.
  25 </para>
  26 <para>
  27 Now you have two windows. In exactly the same way, you can split either of them &mdash; the original window, or the one you just created. Whichever one you split becomes two, which together take up the same space that the one did before.
  28 </para>
  29 <para>
  30 You can repeat this as often as you want. Every time you split a window, one new window is created. Therefore, the call that does this is called glk_window_open().
  31 </para>
  32 <note><para>
  33 It might have been less confusing to call it <quote>glk_split_window()</quote> &mdash; or it might have been more confusing. I picked one.
  34 </para></note>
  35 <para>
  36 It is important to remember that the order of splitting matters. If you split twice, you don't have a trio of windows; you have a pair with another pair on one side. Mathematically, the window structure is a binary tree.
  37 </para>
  38 <para>
  39 Example time. Say you do two splits, each a 50-50 percentage split. You start with the original window A, and split that into A and B; then you split B into B and C.
  40 <informaltable frame="none"><tgroup cols="2"><tbody><row>
  41 <entry><mediaobject><imageobject><imagedata fileref="fig1.png"/></imageobject></mediaobject></entry>
  42 <entry><mediaobject><textobject><literallayout class="monospaced">
  43    O
  44   / \
  45  A   O
  46     / \
  47    B   C
  48 </literallayout></textobject></mediaobject></entry>
  49 </row></tbody></tgroup></informaltable>
  50 Or, you could split A into A and B, and then split A again into A and C.
  51 <informaltable frame="none"><tgroup cols="2"><tbody><row>
  52 <entry><mediaobject><imageobject><imagedata fileref="fig2.png"/></imageobject></mediaobject></entry>
  53 <entry><mediaobject><textobject><literallayout class="monospaced">
  54      O
  55     / \
  56    O   B
  57   / \
  58  A   C
  59 </literallayout></textobject></mediaobject></entry>
  60 </row></tbody></tgroup></informaltable>
  61 I'm using the simplest possible splits in the examples above. Every split is 50-50, and the new window of the pair is always below the original one (the one that gets split.) You can get fancier than that. Here are three more ways to perform the first example; all of them have the same tree structure, but look different on the screen.
  62 <informaltable frame="none"><tgroup cols="4"><tbody><row>
  63 <entry><mediaobject><imageobject><imagedata fileref="fig3a.png"/></imageobject></mediaobject></entry>
  64 <entry><mediaobject><imageobject><imagedata fileref="fig3b.png"/></imageobject></mediaobject></entry>
  65 <entry><mediaobject><imageobject><imagedata fileref="fig3c.png"/></imageobject></mediaobject></entry>
  66 <entry><mediaobject><textobject><literallayout class="monospaced">
  67    O
  68   / \
  69  A   O
  70     / \
  71    B   C
  72 </literallayout></textobject></mediaobject></entry>
  73 </row></tbody></tgroup></informaltable>
  74 On the left, we turn the second split (B into B/C) upside down; we put the new window (C) above the old window (B).
  75 </para>
  76 <para>
  77 In the center, we mess with the percentages. The first split (A into A/B) is a 25-75 split, which makes B three times the size of A. The second (B into B/C) is a 33-66 split, which makes C twice the size of B. This looks rather like the second example above, but has a different internal structure.
  78 </para>
  79 <para>
  80 On the right, the second split (B into B/C) is vertical instead of horizontal, with the new window (C) on the left of the old one.
  81 </para>
  82 <para>
  83 The visible windows on the Glk screen are <quote>leaf nodes</quote> of the binary tree; they hang off the ends of the branches in the diagram. There are also the <quote>internal nodes</quote>, the ones at the forks, which are marked as <quote>O</quote>. These are the mysterious pair windows.
  84 </para>
  85 <para>
  86 You don't create pair windows directly; they are created as a consequence of window splits. Whenever you create a new window, a new pair window is also created automatically. In the following two-split process, you can see that when a window is split, it is replaced by a new pair window, and moves down to become one of that <quote>O</quote>'s two children.
  87 <informaltable frame="none"><tgroup cols="2"><tbody><row>
  88 <entry><mediaobject><imageobject><imagedata fileref="fig4a.png"/></imageobject></mediaobject></entry>
  89 <entry><mediaobject><textobject><literallayout class="monospaced">
  90    A
  91 </literallayout></textobject></mediaobject></entry>
  92 </row><row>
  93 <entry><mediaobject><imageobject><imagedata fileref="fig4b.png"/></imageobject></mediaobject></entry>
  94 <entry><mediaobject><textobject><literallayout class="monospaced">
  95    O
  96   / \
  97  A   B
  98 </literallayout></textobject></mediaobject></entry>
  99 </row><row>
 100 <entry><mediaobject><imageobject><imagedata fileref="fig4c.png"/></imageobject></mediaobject></entry>
 101 <entry><mediaobject><textobject><literallayout class="monospaced">
 102    O
 103   / \
 104  A   O
 105     / \
 106    B   C
 107 </literallayout></textobject></mediaobject></entry>
 108 </row></tbody></tgroup></informaltable>
 109 </para>
 110 <para>
 111 You can't draw into a pair window. It's completely filled up with the two windows it contains. They're what you should be drawing into.
 112 </para>
 113 <para>
 114 Why have pair windows in the system at all? They're convenient for certain operations. For example, you can close any window at any time; but sometimes you want to close an entire nest of windows at once. In the third stage shown, if you close the lower pair window, it blows away all its descendents &mdash; both B and C &mdash; and leaves just a single window, A, which is what you started with.
 115 </para>
 116 <para>
 117 I'm using some math terminology already, so I'll explain it briefly. The <quote>root</quote> of the tree is the top (math trees, like family trees, grow upside down.) If there's only one window, it's the root; otherwise the root is the topmost <quote>O</quote>. Every pair window has exactly two <quote>children</quote>. Other kinds of windows are leaves on the tree, and have no children. A window's <quote>descendants</quote>, obviously, are its children and grandchildren and great-grandchildren and so on. The <quote>parent</quote> and <quote>ancestors</quote> of a window are exactly what you'd expect. So the root window is the ancestor of every other window.
 118 </para>
 119 <para>
 120 There are Glk functions to determine the root window, and to determine the parent of any given window. Note that every window's parent is a pair window. (Except for the root window, which has no parent.)
 121 </para>
 122 </refsect1>
 123 </refentry>