- Changed splittest.c to run through all the examples of window splitting in the
authorPhilip Chimento <philip.chimento@gmail.com>
Tue, 19 May 2009 20:47:32 +0000 (20:47 +0000)
committerPhilip Chimento <philip.chimento@gmail.com>
Tue, 19 May 2009 20:47:32 +0000 (20:47 +0000)
  Glk spec
- Took screenshots and added those to the documentation

git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@55 ddfedd41-794f-dd11-ae45-00112f111e67

25 files changed:
docs/reference/Makefile.am
docs/reference/glk-window-arrangement.sgml
docs/reference/images/fig1.png [new file with mode: 0644]
docs/reference/images/fig10.png [new file with mode: 0644]
docs/reference/images/fig11.png [new file with mode: 0644]
docs/reference/images/fig2.png [new file with mode: 0644]
docs/reference/images/fig3a.png [new file with mode: 0644]
docs/reference/images/fig3b.png [new file with mode: 0644]
docs/reference/images/fig3c.png [new file with mode: 0644]
docs/reference/images/fig4a.png [new file with mode: 0644]
docs/reference/images/fig4b.png [new file with mode: 0644]
docs/reference/images/fig4c.png [new file with mode: 0644]
docs/reference/images/fig5-7a.png [new file with mode: 0644]
docs/reference/images/fig6.png [new file with mode: 0644]
docs/reference/images/fig7b.png [new file with mode: 0644]
docs/reference/images/fig7c.png [new file with mode: 0644]
docs/reference/images/fig7d.png [new file with mode: 0644]
docs/reference/images/fig7e.png [new file with mode: 0644]
docs/reference/images/fig8a.png [new file with mode: 0644]
docs/reference/images/fig8b.png [new file with mode: 0644]
docs/reference/images/fig8c.png [new file with mode: 0644]
docs/reference/images/fig9.png [new file with mode: 0644]
src/main.c
src/splittest.c
src/window.c

index 4e05bb91a6fda3f6eafac8d7ed40316a1d3406b8..3af6caa9bb44595aada863de010d7b87d304b7f0 100644 (file)
@@ -51,7 +51,27 @@ IGNORE_HFILES = chimara-glk-private.h \
        callbacks.h error.h
 
 # Images to copy into HTML directory.
-HTML_IMAGES = 
+HTML_IMAGES = \
+       $(srcdir)/images/fig1.png \
+       $(srcdir)/images/fig2.png \
+       $(srcdir)/images/fig3a.png \
+       $(srcdir)/images/fig3b.png \
+       $(srcdir)/images/fig3c.png \
+       $(srcdir)/images/fig4a.png \
+       $(srcdir)/images/fig4b.png \
+       $(srcdir)/images/fig4c.png \
+       $(srcdir)/images/fig5-7a.png \
+       $(srcdir)/images/fig6.png \
+       $(srcdir)/images/fig7b.png \
+       $(srcdir)/images/fig7c.png \
+       $(srcdir)/images/fig7d.png \
+       $(srcdir)/images/fig7e.png \
+       $(srcdir)/images/fig8a.png \
+       $(srcdir)/images/fig8b.png \
+       $(srcdir)/images/fig8c.png \
+       $(srcdir)/images/fig9.png \
+       $(srcdir)/images/fig10.png \
+       $(srcdir)/images/fig11.png
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 content_files = version.xml \
index 9926d817c5d81f04bbc138de262021190da24540..fe9f66705d67b8b1612bd3d3583b21a7d5b17f04 100644 (file)
@@ -37,11 +37,40 @@ It is important to remember that the order of splitting matters. If you split tw
 </para>
 <para>
 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.
-<mediaobject><textobject><phrase>Screen shot 1</phrase></textobject></mediaobject>
+<informaltable frame="none"><tgroup cols="2"><tbody><row>
+<entry><mediaobject><imageobject><imagedata fileref="fig1.png"/></imageobject></mediaobject></entry>
+<entry><mediaobject><textobject><literallayout class="monospaced">
+   O
+  / \
+ A   O
+    / \
+   B   C
+</literallayout></textobject></mediaobject></entry>
+</row></tbody></tgroup></informaltable>
 Or, you could split A into A and B, and then split A again into A and C.
-<mediaobject><textobject><phrase>Screen shot 2</phrase></textobject></mediaobject>
+<informaltable frame="none"><tgroup cols="2"><tbody><row>
+<entry><mediaobject><imageobject><imagedata fileref="fig2.png"/></imageobject></mediaobject></entry>
+<entry><mediaobject><textobject><literallayout class="monospaced">
+     O
+    / \
+   O   B
+  / \
+ A   C
+</literallayout></textobject></mediaobject></entry>
+</row></tbody></tgroup></informaltable>
 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.
-<mediaobject><textobject><phrase>Screen shot 3</phrase></textobject></mediaobject>
+<informaltable frame="none"><tgroup cols="4"><tbody><row>
+<entry><mediaobject><imageobject><imagedata fileref="fig3a.png"/></imageobject></mediaobject></entry>
+<entry><mediaobject><imageobject><imagedata fileref="fig3b.png"/></imageobject></mediaobject></entry>
+<entry><mediaobject><imageobject><imagedata fileref="fig3c.png"/></imageobject></mediaobject></entry>
+<entry><mediaobject><textobject><literallayout class="monospaced">
+   O
+  / \
+ A   O
+    / \
+   B   C
+</literallayout></textobject></mediaobject></entry>
+</row></tbody></tgroup></informaltable>
 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).
 </para>
 <para>
@@ -55,7 +84,28 @@ The visible windows on the Glk screen are <quote>leaf nodes</quote> of the binar
 </para>
 <para>
 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.
-<mediaobject><textobject><phrase>Screen shot 4</phrase></textobject></mediaobject>
+<informaltable frame="none"><tgroup cols="2"><tbody><row>
+<entry><mediaobject><imageobject><imagedata fileref="fig4a.png"/></imageobject></mediaobject></entry>
+<entry><mediaobject><textobject><literallayout class="monospaced">
+   A
+</literallayout></textobject></mediaobject></entry>
+</row><row>
+<entry><mediaobject><imageobject><imagedata fileref="fig4b.png"/></imageobject></mediaobject></entry>
+<entry><mediaobject><textobject><literallayout class="monospaced">
+   O
+  / \
+ A   B
+</literallayout></textobject></mediaobject></entry>
+</row><row>
+<entry><mediaobject><imageobject><imagedata fileref="fig4c.png"/></imageobject></mediaobject></entry>
+<entry><mediaobject><textobject><literallayout class="monospaced">
+   O
+  / \
+ A   O
+    / \
+   B   C
+</literallayout></textobject></mediaobject></entry>
+</row></tbody></tgroup></informaltable>
 </para>
 <para>
 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.
diff --git a/docs/reference/images/fig1.png b/docs/reference/images/fig1.png
new file mode 100644 (file)
index 0000000..3314081
Binary files /dev/null and b/docs/reference/images/fig1.png differ
diff --git a/docs/reference/images/fig10.png b/docs/reference/images/fig10.png
new file mode 100644 (file)
index 0000000..54c2989
Binary files /dev/null and b/docs/reference/images/fig10.png differ
diff --git a/docs/reference/images/fig11.png b/docs/reference/images/fig11.png
new file mode 100644 (file)
index 0000000..04baff6
Binary files /dev/null and b/docs/reference/images/fig11.png differ
diff --git a/docs/reference/images/fig2.png b/docs/reference/images/fig2.png
new file mode 100644 (file)
index 0000000..2865a2f
Binary files /dev/null and b/docs/reference/images/fig2.png differ
diff --git a/docs/reference/images/fig3a.png b/docs/reference/images/fig3a.png
new file mode 100644 (file)
index 0000000..b178d7d
Binary files /dev/null and b/docs/reference/images/fig3a.png differ
diff --git a/docs/reference/images/fig3b.png b/docs/reference/images/fig3b.png
new file mode 100644 (file)
index 0000000..112f4af
Binary files /dev/null and b/docs/reference/images/fig3b.png differ
diff --git a/docs/reference/images/fig3c.png b/docs/reference/images/fig3c.png
new file mode 100644 (file)
index 0000000..6309db9
Binary files /dev/null and b/docs/reference/images/fig3c.png differ
diff --git a/docs/reference/images/fig4a.png b/docs/reference/images/fig4a.png
new file mode 100644 (file)
index 0000000..973e6de
Binary files /dev/null and b/docs/reference/images/fig4a.png differ
diff --git a/docs/reference/images/fig4b.png b/docs/reference/images/fig4b.png
new file mode 100644 (file)
index 0000000..4410962
Binary files /dev/null and b/docs/reference/images/fig4b.png differ
diff --git a/docs/reference/images/fig4c.png b/docs/reference/images/fig4c.png
new file mode 100644 (file)
index 0000000..b5b60ca
Binary files /dev/null and b/docs/reference/images/fig4c.png differ
diff --git a/docs/reference/images/fig5-7a.png b/docs/reference/images/fig5-7a.png
new file mode 100644 (file)
index 0000000..543c689
Binary files /dev/null and b/docs/reference/images/fig5-7a.png differ
diff --git a/docs/reference/images/fig6.png b/docs/reference/images/fig6.png
new file mode 100644 (file)
index 0000000..15f6331
Binary files /dev/null and b/docs/reference/images/fig6.png differ
diff --git a/docs/reference/images/fig7b.png b/docs/reference/images/fig7b.png
new file mode 100644 (file)
index 0000000..63fe6c7
Binary files /dev/null and b/docs/reference/images/fig7b.png differ
diff --git a/docs/reference/images/fig7c.png b/docs/reference/images/fig7c.png
new file mode 100644 (file)
index 0000000..839c945
Binary files /dev/null and b/docs/reference/images/fig7c.png differ
diff --git a/docs/reference/images/fig7d.png b/docs/reference/images/fig7d.png
new file mode 100644 (file)
index 0000000..9631819
Binary files /dev/null and b/docs/reference/images/fig7d.png differ
diff --git a/docs/reference/images/fig7e.png b/docs/reference/images/fig7e.png
new file mode 100644 (file)
index 0000000..a7c3cf5
Binary files /dev/null and b/docs/reference/images/fig7e.png differ
diff --git a/docs/reference/images/fig8a.png b/docs/reference/images/fig8a.png
new file mode 100644 (file)
index 0000000..7fa9ea7
Binary files /dev/null and b/docs/reference/images/fig8a.png differ
diff --git a/docs/reference/images/fig8b.png b/docs/reference/images/fig8b.png
new file mode 100644 (file)
index 0000000..2a4c05b
Binary files /dev/null and b/docs/reference/images/fig8b.png differ
diff --git a/docs/reference/images/fig8c.png b/docs/reference/images/fig8c.png
new file mode 100644 (file)
index 0000000..d579b84
Binary files /dev/null and b/docs/reference/images/fig8c.png differ
diff --git a/docs/reference/images/fig9.png b/docs/reference/images/fig9.png
new file mode 100644 (file)
index 0000000..7386955
Binary files /dev/null and b/docs/reference/images/fig9.png differ
index c34e4c5f8883a1dd548041257d11f0c6b6d365d0..496f1b23423b8356814e975181dafdb8f52ca589 100644 (file)
@@ -118,7 +118,7 @@ main(int argc, char *argv[])
 
        g_object_unref( G_OBJECT(builder) );
 
-    if( !chimara_glk_run(CHIMARA_GLK(glk), ".libs/first.so", &error) ) {
+    if( !chimara_glk_run(CHIMARA_GLK(glk), ".libs/splittest.so", &error) ) {
         error_dialog(GTK_WINDOW(window), error, "Error starting Glk library: ");
         return 1;
     }
index 58ed6f698b346fe70746a9b7520c2fbcd5f1e2da..7448437e15e40a124ca87ecbead7c29c2c412b3d 100644 (file)
-#include "stdio.h"
+#include <stdio.h>
+#include <string.h>
 #include "glk.h"
 
-void glk_main(void)
+#define SPACE_FACTOR 1.8
+
+void center_text(winid_t win, char *text)
+{
+       glui32 width, height;
+       glk_window_get_size(win, &width, &height);
+       
+       glk_set_window(win);
+       glk_window_clear(win);
+       
+       if(glk_window_get_type(win) == wintype_TextGrid) {
+               glk_window_move_cursor(win, width / 2 - strlen(text) / 2, height / 2);
+               glk_put_string(text);
+       } else if(glk_window_get_type(win) == wintype_TextBuffer) {
+               int count;
+               for(count = 0; count < height / 2; count++)
+                       glk_put_char('\n');
+               for(count = 0; 
+                       count < (int)(SPACE_FACTOR * (width / 2 - strlen(text) / 2)); 
+                       count++)
+                       glk_put_char(' ');
+               glk_put_string(text);
+       }
+}
+
+void print_two_rows(winid_t win)
+{
+       glui32 width, height;
+       glk_window_get_size(win, &width, &height);
+       
+       glk_set_window(win);
+       glk_window_clear(win);
+       
+       glui32 x = width / 2 - 3;
+       glui32 y = (height - 1) / 2;
+       if(x < 0) 
+               x = 0;
+       if(y < 0)
+               y = 0;
+       
+       glk_window_move_cursor(win, x, y);
+       glk_put_string("C: 2");
+       glk_window_move_cursor(win, x + 3, y + 1);
+       glk_put_string("rows");
+}
+
+void wait_for_key(winid_t win)
 {
     event_t ev;
-    winid_t mainwin = glk_window_open(0, 0, 0, wintype_TextBuffer, 0);
-    if(!mainwin)
-        return;
-    
-       winid_t subwin = glk_window_open(mainwin, winmethod_Right | winmethod_Proportional, 50, wintype_TextBuffer, 1);
-       printf("created new window\n");
-    glk_set_window(mainwin);
-    glk_put_string("Philip en Marijn zijn vet goed.\n");
-    glk_set_window(subwin);
-    glk_put_string("A veeeeeeeeeeeeeeeeeeeeeeeeeeeery looooooooooooooooooooooooong striiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiing.\n");
+       glk_request_char_event(win);
+       do
+               glk_select(&ev);
+    while(ev.type != evtype_CharInput);
+}
 
-    
-    guint32 width, height;
-    glk_window_get_size(mainwin, &width, &height);
-       printf("got window size\n");
-    fprintf(stderr, "\nWidth: %d\nHeight: %d\n", width, height);
-    
-    glk_request_char_event(mainwin);
-    //while(1) {
-        glk_select(&ev);
-        if(ev.type == evtype_CharInput) {
-            glk_window_get_size(mainwin, &width, &height);
-            fprintf(stderr, "\nWidth: %d\nHeight: %d\n", width, height);
-        }
-    //}
-       glk_window_close(subwin, NULL);
-       printf("closed window\n");
+void glk_main(void)
+{
+    winid_t win_a = NULL, win_b = NULL, win_c = NULL, win_d = NULL;
+       
+       fprintf(stderr, "TEST CASES FROM GLK SPEC\n\n"
+                       "(Press a key in window A to continue each time)\n\n"
+                       "Say you do two splits, each a 50-50 percentage split. You start\n"
+                       "with the original window A, and split that into A and B; then\n"
+                       "you split B into B and C.\n\n");
+       
+       win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0);
+       win_b = glk_window_open(win_a, winmethod_Proportional | winmethod_Below,
+                                                       50, wintype_TextBuffer, 0);
+       win_c = glk_window_open(win_b, winmethod_Proportional | winmethod_Below,
+                                                       50, wintype_TextBuffer, 0);
+       if(!win_a || !win_b || !win_c)
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       
+       wait_for_key(win_a);
+       glk_window_close(glk_window_get_root(), NULL);
+       
+       fprintf(stderr, "Or, you could split A into A and B, and then split A\n"
+                       "again into A and C.\n\n");
+       
+       win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0);
+       win_b = glk_window_open(win_a, winmethod_Proportional | winmethod_Below,
+                                                       50, wintype_TextBuffer, 0);
+       win_c = glk_window_open(win_a, winmethod_Proportional | winmethod_Below,
+                                                       50, wintype_TextBuffer, 0);
+       if(!win_a || !win_b || !win_c)
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       
+       wait_for_key(win_a);
+       glk_window_close(glk_window_get_root(), NULL);
+       
+       fprintf(stderr, "Here are more ways to perform the first example; all of\n"
+                       "them have the same tree structure, but look different on the\n"
+                       "screen. Here, we turn the second split (B into B/C) upside down;\n"
+                       "we put the new window (C) above the old window (B).\n\n");
+       
+       win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0);
+       win_b = glk_window_open(win_a, winmethod_Proportional | winmethod_Below,
+                                                       50, wintype_TextBuffer, 0);
+       win_c = glk_window_open(win_b, winmethod_Proportional | winmethod_Above,
+                                                       50, wintype_TextBuffer, 0);
+       if(!win_a || !win_b || !win_c)
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       
+       wait_for_key(win_a);
+       glk_window_close(glk_window_get_root(), NULL);
+                       
+       fprintf(stderr, "Here, we mess with the percentages. The first split (A\n"
+                       "into A/B) is a 25-75 split, which makes B three times the size\n"
+                       "of A. The second (B into B/C) is a 33-66 split, which makes C\n"
+                       "twice the size of B. This looks rather like the second example,\n"
+                       "but has a different internal structure.\n\n");
+       
+       win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0);
+       win_b = glk_window_open(win_a, winmethod_Proportional | winmethod_Below,
+                                                       75, wintype_TextBuffer, 0);
+       win_c = glk_window_open(win_b, winmethod_Proportional | winmethod_Below,
+                                                       67, wintype_TextBuffer, 0);
+       if(!win_a || !win_b || !win_c)
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       
+       wait_for_key(win_a);
+       glk_window_close(glk_window_get_root(), NULL);
+       
+       fprintf(stderr, "Here, the second split (B into B/C) is vertical instead\n"
+                       "of horizontal, with the new window (C) on the left of the old\n"
+                       "one.\n\n");
+       
+       win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0);
+       win_b = glk_window_open(win_a, winmethod_Proportional | winmethod_Below,
+                                                       50, wintype_TextBuffer, 0);
+       win_c = glk_window_open(win_b, winmethod_Proportional | winmethod_Left,
+                                                       50, wintype_TextBuffer, 0);
+       if(!win_a || !win_b || !win_c)
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       
+       wait_for_key(win_a);
+       glk_window_close(glk_window_get_root(), NULL);
+       
+       fprintf(stderr, "In the following two-split process, you can see that\n"
+                       "when a window is split, it is replaced by a new pair window, and\n"
+                       "moves down to become one of its two children.\n\n");
+       
+       if(!(win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0)))
+               return;
+       center_text(win_a, "A");
+       wait_for_key(win_a);
+       
+       if(!(win_b = glk_window_open(win_a, 
+                                                                winmethod_Proportional | winmethod_Below,
+                                                                50, wintype_TextBuffer, 0)))
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       wait_for_key(win_a);
+       
+       if(!(win_c = glk_window_open(win_b, winmethod_Proportional | winmethod_Left,
+                                                                50, wintype_TextBuffer, 0)))
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       wait_for_key(win_a);
+       
+       glk_window_close(glk_window_get_root(), NULL);
+       
+       fprintf(stderr, "What happens when there is a conflict? The rules are\n"
+                       "simple. Size control always flows down the tree, and the player\n"
+                       "is at the top. Let's bring out an example: first we split A into\n"
+                       "A and B, with a 50%% proportional split. Then we split A into A\n"
+                       "and C, with C above, being a text grid window, and C gets a\n"
+                       "fixed size of two rows (as measured in its own font size). A\n"
+                       "gets whatever remains of the 50%% it had before.\n\n");
+       
+       win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0);
+       win_b = glk_window_open(win_a, winmethod_Proportional | winmethod_Below,
+                                                       50, wintype_TextBuffer, 0);
+       win_c = glk_window_open(win_a, winmethod_Fixed | winmethod_Above,
+                                                       2, wintype_TextGrid, 0);
+       if(!win_a || !win_b || !win_c)
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B: 50%");
+       print_two_rows(win_c);
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "(Stage 1) Now the player stretches the window\n"
+                       "vertically.\n\n");
+       
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "(Stage 2) Then the user maliciously starts squeezing the\n"
+                       "window down, in stages.\n\n");
+       
+       center_text(win_a, "A");
+       center_text(win_b, "B: 50%");
+       print_two_rows(win_c);
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "(Stage 3) The logic remains the same. At stage 3,\n"
+                       "there's no room left for A, so it winds up with zero height.\n"
+                       "Nothing displayed in A will be visible.\n\n");
+       
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "(Stage 4) At stage 4, there isn't even room in the upper\n"
+                       "50%% to give C its two rows; so it only gets one.\n\n");
+       
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "(Stage 5) Finally, C is squashed out of existence as\n"
+                       "well.\n\n");
+       
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       wait_for_key(win_a);
+       
+       glk_window_close(glk_window_get_root(), NULL);
+       
+       fprintf(stderr, "What happens when you split a fixed-size window? The\n"
+                       "resulting pair window retains the same size constraint as the\n"
+                       "original window that was split. The key window for the original\n"
+                       "split is still the key window for that split, even though it's\n"
+                       "now a grandchild instead of a child.\n\n");
+       
+       if(!(win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0)))
+               return;
+       center_text(win_a, "A");
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "After the first split, the new pair window (O1, which\n"
+                       "covers the whole screen) knows that its first child (A) is above\n"
+                       "the second, and gets 50%% of its own area. (A is the key window\n"
+                       "for this split, but a proportional split doesn't care about key\n"
+                       "windows.)\n\n");
+       
+       if(!(win_b = glk_window_open(win_a, 
+                                                                winmethod_Proportional | winmethod_Below,
+                                                                50, wintype_TextBuffer, 0)))
+               return;
+       center_text(win_a, "A: 50%");
+       center_text(win_b, "B");
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "After the second split, all this remains true; O1 knows\n"
+                       "that its first child gets 50%% of its space, and A is O1's key\n"
+                       "window. But now O1's first child is O2 instead of A. The newer\n"
+                       "pair window (O2) knows that its first child (C) is above the\n"
+                       "second, and gets a fixed size of two rows. (As measured in C's\n"
+                       "font, because C is O2's key window.)\n\n");
+       
+       if(!(win_c = glk_window_open(win_a, winmethod_Fixed | winmethod_Above, 2,
+                                                                wintype_TextGrid, 0)))
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       print_two_rows(win_c);
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "If we split C, now, the resulting pair will still be two\n"
+                       "C-font rows high -- that is, tall enough for two lines of\n"
+                       "whatever font C displays. For the sake of example, we'll do this\n"
+                       "vertically.\n\n");
+       
+       if(!(win_d = glk_window_open(win_c, 
+                                                                winmethod_Proportional | winmethod_Right,
+                                                                50, wintype_TextBuffer, 0)))
+               return;
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       center_text(win_d, "D");
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "When you close a window (and it is not the root window),\n"
+                       "the other window in its pair takes over all the freed-up area.\n"
+                       "Let's close D, in the current example:\n\n");
+       
+       glk_window_close(win_d, NULL);
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_c, "C");
+       wait_for_key(win_a);
+       
+       fprintf(stderr, "But what if we had closed C instead of D? We would have\n"
+                       "gotten this:\n\n");
+       
+       glk_window_close(glk_window_get_root(), NULL);
+       win_a = glk_window_open(0, 0, 0, wintype_TextBuffer, 0);
+       win_b = glk_window_open(win_a, winmethod_Proportional | winmethod_Below, 50,
+                                                       wintype_TextBuffer, 0);
+       win_c = glk_window_open(win_a, winmethod_Fixed | winmethod_Above, 2,
+                                                       wintype_TextGrid, 0);
+       win_d = glk_window_open(win_c, winmethod_Proportional | winmethod_Right, 50,
+                                                       wintype_TextBuffer, 0);
+       glk_window_close(win_c, NULL);
+       center_text(win_a, "A");
+       center_text(win_b, "B");
+       center_text(win_d, "D");
+       wait_for_key(win_a);
+       
+       glk_window_close(win_d, NULL);
+       glk_window_close(win_b, NULL);
+       glk_window_clear(win_a);
+       glk_set_window(win_a);
+       glk_put_string("That's all, folks...");
 }
index 876db66933867406084ab9dfa75081c5b46e2cd1..2f3c6021ec4628d0b9f33af14b0cbea739a4dc20 100644 (file)
@@ -237,8 +237,17 @@ glk_window_get_root()
  * What happens when there is a conflict? The rules are simple. Size control
  * always flows down the tree, and the player is at the top. Let's bring out an
  * example:
- * <mediaobject><textobject><phrase>Screen shot 5</phrase></textobject>
- * </mediaobject>
+ * <informaltable frame="none"><tgroup cols="2"><tbody><row>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig5-7a.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><textobject><literallayout class="monospaced">
+ *      O
+ *     / \
+ *    O   B
+ *   / \
+ *  A   C
+ * </literallayout></textobject></mediaobject></entry>
+ * </row></tbody></tgroup></informaltable>
  * 
  * First we split A into A and B, with a 50% proportional split. Then we split
  * A into A and C, with C above, C being a text grid window, and C gets a fixed
@@ -246,8 +255,8 @@ glk_window_get_root()
  * of the 50% it had before.
  * 
  * Now the player stretches the window vertically.
- * <mediaobject><textobject><phrase>Screen shot 6</phrase></textobject>
- * </mediaobject>
+ * <informalfigure><mediaobject><imageobject><imagedata fileref="fig6.png"/>
+ * </imageobject></mediaobject></informalfigure>
  * 
  * The library figures: the topmost split, the original A/B split, is 50-50. So
  * B gets half the screen space, and the pair window next to it (the lower
@@ -255,8 +264,18 @@ glk_window_get_root()
  * <quote>O</quote>. C gets two rows; A gets the rest. All done.
  * 
  * Then the user maliciously starts squeezing the window down, in stages:
- * <mediaobject id="chimara-Figure-Squeezing-Window"><textobject><phrase>
- * Screen shot 7</phrase></textobject></mediaobject>
+ * <informaltable frame="none"><tgroup cols="5"><tbody><row valign="top">
+ * <entry><mediaobject><imageobject><imagedata fileref="fig5-7a.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig7b.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig7c.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig7d.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig7e.png"/>
+ * </imageobject></mediaobject></entry>
+ * </row></tbody></tgroup></informaltable>
  * 
  * The logic remains the same. B always gets half the space. At stage 3,
  * there's no room left for A, so it winds up with zero height. Nothing
@@ -290,8 +309,29 @@ glk_window_get_root()
  * is stored by a window's parent, not the window itself; and a constraint
  * consists of a pointer to a key window plus a size value.
  * 
- * <mediaobject><textobject><phrase>Screen shot 8</phrase></textobject>
- * </mediaobject>
+ * <informaltable frame="none"><tgroup cols="6"><tbody><row>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig8a.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><textobject><literallayout class="monospaced">
+ *  A   
+ * </literallayout></textobject></mediaobject></entry>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig8b.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><textobject><literallayout class="monospaced">
+ *    O1  
+ *   / \  
+ *  A   B 
+ * </literallayout></textobject></mediaobject></entry> 
+ * <entry><mediaobject><imageobject><imagedata fileref="fig8c.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><textobject><literallayout class="monospaced">
+ *      O1  
+ *     / \  
+ *    O2  B 
+ *   / \    
+ *  A   C   
+ * </literallayout></textobject></mediaobject></entry> 
+ * </row></tbody></tgroup></informaltable>
  * After the first split, the new pair window (O1, which covers the whole
  * screen) knows that its first child (A) is above the second, and gets 50% of
  * its own area. (A is the key window for this split, but a proportional split
@@ -306,8 +346,19 @@ glk_window_get_root()
  * If we split C, now, the resulting pair will still be two C-font rows high
  * &mdash; that is, tall enough for two lines of whatever font C displays. For
  * the sake of example, we'll do this vertically.
- * <mediaobject><textobject><phrase>Screen shot 9</phrase></textobject>
- * </mediaobject>
+ * <informaltable frame="none"><tgroup cols="2"><tbody><row>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig9.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><textobject><literallayout class="monospaced">
+ *      O1
+ *     / \
+ *    O2  B
+ *   / \
+ *  A   O3
+ *     / \
+ *    C   D
+ * </literallayout></textobject></mediaobject></entry> 
+ * </row></tbody></tgroup></informaltable>
  * 
  * O3 now knows that its children have a 50-50 left-right split. O2 is still
  * committed to giving its upper child, O3, two C-font rows. Again, this is
@@ -611,8 +662,17 @@ free_winids_below(winid_t win)
  * When you close a window (and it is not the root window), the other window
  * in its pair takes over all the freed-up area. Let's close D, in the current
  * example:
- * <mediaobject><textobject><phrase>Screen shot 10</phrase></textobject>
- * </mediaobject>
+ * <informaltable frame="none"><tgroup cols="2"><tbody><row>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig10.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><textobject><literallayout class="monospaced">
+ *      O1
+ *     / \
+ *    O2  B
+ *   / \
+ *  A   C
+ * </literallayout></textobject></mediaobject></entry> 
+ * </row></tbody></tgroup></informaltable>
  * 
  * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right
  * split has gone with it. The other size constraints are unchanged; O2 is
@@ -622,8 +682,17 @@ free_winids_below(winid_t win)
  * to the way it was before we created D.
  * 
  * But what if we had closed C instead of D? We would have gotten this:
- * <mediaobject><textobject><phrase>Screen shot 11</phrase></textobject>
- * </mediaobject>
+ * <informaltable frame="none"><tgroup cols="2"><tbody><row>
+ * <entry><mediaobject><imageobject><imagedata fileref="fig11.png"/>
+ * </imageobject></mediaobject></entry>
+ * <entry><mediaobject><textobject><literallayout class="monospaced">
+ *      O1
+ *     / \
+ *    O2  B
+ *   / \
+ *  A   D
+ * </literallayout></textobject></mediaobject></entry> 
+ * </row></tbody></tgroup></informaltable>
  * 
  * Again, O3 is gone. But D has collapsed to zero height. This is because its
  * height is controlled by O2, and O2's key window was C, and C is now gone. O2