Edited includes to finish fixing #17
[rodin/chimara.git] / libchimara / window.c
1 #include "window.h"
2 #include "magic.h"
3 #include "chimara-glk-private.h"
4
5 extern ChimaraGlkPrivate *glk_data;
6
7 /**
8  * glk_window_iterate:
9  * @win: A window, or %NULL.
10  * @rockptr: Return location for the next window's rock, or %NULL.
11  *
12  * This function can be used to iterate through the list of all open windows
13  * (including pair windows.) See <link 
14  * linkend="chimara-Iterating-Through-Opaque-Objects">Iterating Through Opaque
15  * Objects</link>.
16  *
17  * As that section describes, the order in which windows are returned is
18  * arbitrary. The root window is not necessarily first, nor is it necessarily
19  * last.
20  *
21  * Returns: the next window, or %NULL if there are no more.
22  */
23 winid_t
24 glk_window_iterate(winid_t win, glui32 *rockptr)
25 {
26         VALID_WINDOW_OR_NULL(win, return NULL);
27         
28         GNode *retnode;
29         
30         if(win == NULL)
31                 retnode = glk_data->root_window;
32         else
33         {
34                 GNode *node = win->window_node;
35                 if( G_NODE_IS_LEAF(node) )
36                 {
37                         while(node && node->next == NULL)
38                                 node = node->parent;
39                         if(node)
40                                 retnode = node->next;
41                         else
42                                 retnode = NULL;
43                 }
44                 else
45                         retnode = g_node_first_child(node);
46         }
47         winid_t retval = retnode? (winid_t)retnode->data : NULL;
48                 
49         /* Store the window's rock in rockptr */
50         if(retval && rockptr)
51                 *rockptr = glk_window_get_rock(retval);
52                 
53         return retval;
54 }
55
56 /**
57  * glk_window_get_rock:
58  * @win: A window.
59  * 
60  * Returns @win's rock value. Pair windows always have rock 0; all other windows
61  * return whatever rock value you created them with.
62  *
63  * Returns: A rock value.
64  */
65 glui32
66 glk_window_get_rock(winid_t win)
67 {
68         VALID_WINDOW(win, return 0);
69         return win->rock;
70 }
71
72 /**
73  * glk_window_get_type:
74  * @win: A window.
75  *
76  * Returns @win's type, one of %wintype_Blank, %wintype_Pair,
77  * %wintype_TextBuffer, %wintype_TextGrid, or %wintype_Graphics.
78  *
79  * Returns: The window's type.
80  */
81 glui32
82 glk_window_get_type(winid_t win)
83 {
84         VALID_WINDOW(win, return 0);
85         return win->type;
86 }
87
88 /**
89  * glk_window_get_parent:
90  * @win: A window.
91  *
92  * Returns the window which is the parent of @win. If @win is the root window,
93  * this returns %NULL, since the root window has no parent. Remember that the
94  * parent of every window is a pair window; other window types are always
95  * childless.
96  *
97  * Returns: A window, or %NULL.
98  */
99 winid_t
100 glk_window_get_parent(winid_t win)
101 {
102         VALID_WINDOW(win, return NULL);
103         /* Value will also be NULL if win is the root window */
104         return (winid_t)win->window_node->parent->data;
105 }
106
107 /**
108  * glk_window_get_sibling:
109  * @win: A window.
110  *
111  * Returns the other child of @win's parent. If @win is the root window, this
112  * returns %NULL.
113  *
114  * Returns: A window, or %NULL.
115  */
116 winid_t
117 glk_window_get_sibling(winid_t win)
118 {
119         VALID_WINDOW(win, return NULL);
120         
121         if(G_NODE_IS_ROOT(win->window_node))
122                 return NULL;
123         if(win->window_node->next)
124                 return (winid_t)win->window_node->next;
125         return (winid_t)win->window_node->prev;
126 }
127
128 /**
129  * glk_window_get_root:
130  * 
131  * Returns the root window. If there are no windows, this returns %NULL.
132  *
133  * Returns: A window, or %NULL.
134  */
135 winid_t
136 glk_window_get_root()
137 {
138         if(glk_data->root_window == NULL)
139                 return NULL;
140         return (winid_t)glk_data->root_window->data;
141 }
142
143 /**
144  * glk_window_open:
145  * @split: The window to split to create the new window. Must be 0 if there
146  * are no windows yet.
147  * @method: Position of the new window and method of size computation. One of
148  * %winmethod_Above, %winmethod_Below, %winmethod_Left, or %winmethod_Right
149  * OR'ed with %winmethod_Fixed or %winmethod_Proportional. If @wintype is
150  * %wintype_Blank, then %winmethod_Fixed is not allowed.
151  * @size: Size of the new window, in percentage points if @method is
152  * %winmethod_Proportional, otherwise in characters if @wintype is 
153  * %wintype_TextBuffer or %wintype_TextGrid, or pixels if @wintype is
154  * %wintype_Graphics.
155  * @wintype: Type of the new window. One of %wintype_Blank, %wintype_TextGrid,
156  * %wintype_TextBuffer, or %wintype_Graphics.
157  * @rock: The new window's rock value.
158  *
159  * Creates a new window. If there are no windows, the first three arguments are
160  * meaningless. @split <emphasis>must</emphasis> be 0, and @method and @size
161  * are ignored. @wintype is the type of window you're creating, and @rock is
162  * the rock (see <link linkend="chimara-Rocks">Rocks</link>).
163  *
164  * If any windows exist, new windows must be created by splitting existing
165  * ones. @split is the window you want to split; this <emphasis>must 
166  * not</emphasis> be zero. @method is a mask of constants to specify the
167  * direction and the split method (see below). @size is the size of the split.
168  * @wintype is the type of window you're creating, and @rock is the rock.
169  *
170  * Remember that it is possible that the library will be unable to create a new
171  * window, in which case glk_window_open() will return %NULL.
172  * 
173  * <note><para>
174  *   It is acceptable to gracefully exit, if the window you are creating is an
175  *   important one &mdash; such as your first window. But you should not try to
176  *   perform any window operation on the id until you have tested to make sure
177  *   it is non-zero.
178  * </para></note>
179  * 
180  * The examples we've seen so far have the simplest kind of size control. (Yes,
181  * this is <quote>below</quote>.) Every pair is a percentage split, with 
182  * <inlineequation>
183  *   <alt>X</alt>
184  *   <mathphrase>X</mathphrase>
185  * </inlineequation>
186  * percent going to one side, and 
187  * <inlineequation>
188  *   <alt>(100-X)</alt>
189  *   <mathphrase>(100 - X)</mathphrase>
190  * </inlineequation> 
191  * percent going to the other side. If the player resizes the window, the whole
192  * mess expands, contracts, or stretches in a uniform way.
193  * 
194  * As I said above, you can also make fixed-size splits. This is a little more
195  * complicated, because you have to know how this fixed size is measured.
196  * 
197  * Sizes are measured in a way which is different for each window type. For
198  * example, a text grid window is measured by the size of its fixed-width font.
199  * You can make a text grid window which is fixed at a height of four rows, or
200  * ten columns. A text buffer window is measured by the size of its font.
201  * 
202  * <note><para>
203  *   Remember that different windows may use different size fonts. Even two
204  *   text grid windows may use fixed-size fonts of different sizes.
205  * </para></note>
206  *
207  * Graphics windows are measured in pixels, not characters. Blank windows
208  * aren't measured at all; there's no meaningful way to measure them, and
209  * therefore you can't create a blank window of a fixed size, only of a
210  * proportional (percentage) size.
211  * 
212  * So to create a text buffer window which takes the top 40% of the original
213  * window's space, you would execute
214  * |[ newwin = #glk_window_open(win, #winmethod_Above | #winmethod_Proportional, 40, #wintype_TextBuffer, 0); ]|
215  *
216  * To create a text grid which is always five lines high, at the bottom of the
217  * original window, you would do
218  * |[ newwin = #glk_window_open(win, #winmethod_Below | #winmethod_Fixed, 5, #wintype_TextGrid, 0); ]|
219  * 
220  * Note that the meaning of the @size argument depends on the @method argument.
221  * If the method is %winmethod_Fixed, it also depends on the @wintype argument.
222  * The new window is then called the <quote>key window</quote> of this split,
223  * because its window type determines how the split size is computed.
224  * 
225  * <note><para>
226  *   For %winmethod_Proportional splits, you can still call the new window the
227  *   <quote>key window</quote>. But the key window is not important for
228  *   proportional splits, because the size will always be computed as a simple
229  *   ratio of the available space, not a fixed size of one child window.
230  * </para></note>
231  * 
232  * This system is more or less peachy as long as all the constraints work out.
233  * What happens when there is a conflict? The rules are simple. Size control
234  * always flows down the tree, and the player is at the top. Let's bring out an
235  * example:
236  * <informaltable frame="none"><tgroup cols="2"><tbody><row>
237  * <entry><mediaobject><imageobject><imagedata fileref="fig5-7a.png"/>
238  * </imageobject></mediaobject></entry>
239  * <entry><mediaobject><textobject><literallayout class="monospaced">
240  *      O
241  *     / \
242  *    O   B
243  *   / \
244  *  A   C
245  * </literallayout></textobject></mediaobject></entry>
246  * </row></tbody></tgroup></informaltable>
247  * 
248  * First we split A into A and B, with a 50% proportional split. Then we split
249  * A into A and C, with C above, C being a text grid window, and C gets a fixed
250  * size of two rows (as measured in its own font size). A gets whatever remains
251  * of the 50% it had before.
252  * 
253  * Now the player stretches the window vertically.
254  * <informalfigure><mediaobject><imageobject><imagedata fileref="fig6.png"/>
255  * </imageobject></mediaobject></informalfigure>
256  * 
257  * The library figures: the topmost split, the original A/B split, is 50-50. So
258  * B gets half the screen space, and the pair window next to it (the lower
259  * <quote>O</quote>) gets the other half. Then it looks at the lower 
260  * <quote>O</quote>. C gets two rows; A gets the rest. All done.
261  * 
262  * Then the user maliciously starts squeezing the window down, in stages:
263  * <informaltable frame="none"><tgroup cols="5"><tbody><row valign="top">
264  * <entry><mediaobject><imageobject><imagedata fileref="fig5-7a.png"/>
265  * </imageobject></mediaobject></entry>
266  * <entry><mediaobject><imageobject><imagedata fileref="fig7b.png"/>
267  * </imageobject></mediaobject></entry>
268  * <entry><mediaobject><imageobject><imagedata fileref="fig7c.png"/>
269  * </imageobject></mediaobject></entry>
270  * <entry><mediaobject><imageobject><imagedata fileref="fig7d.png"/>
271  * </imageobject></mediaobject></entry>
272  * <entry><mediaobject><imageobject><imagedata fileref="fig7e.png"/>
273  * </imageobject></mediaobject></entry>
274  * </row></tbody></tgroup></informaltable>
275  * 
276  * The logic remains the same. B always gets half the space. At stage 3,
277  * there's no room left for A, so it winds up with zero height. Nothing
278  * displayed in A will be visible. At stage 4, there isn't even room in the
279  * upper 50% to give C its two rows; so it only gets one. Finally, C is
280  * squashed out of existence as well.
281  * 
282  * When a window winds up undersized, it remembers what size it should be. In
283  * the example above, A remembers that it should be two rows; if the user
284  * expands the window to the original size, it would return to the original
285  * layout.
286  * 
287  * The downward flow of control is a bit harsh. After all, in stage 4, there's
288  * room for C to have its two rows if only B would give up some of its 50%. But
289  * this does not happen.
290  * 
291  * <note><para>
292  *   This makes life much easier for the Glk library. To determine the
293  *   configuration of a window, it only needs to look at the window's
294  *   ancestors, never at its descendants. So window layout is a simple
295  *   recursive algorithm, no backtracking.
296  * </para></note>
297  * 
298  * What happens when you split a fixed-size window? The resulting pair window
299  * &mdash; that is, the two new parts together &mdash; retain the same size
300  * constraint as the original window that was split. The key window for the
301  * original split is still the key window for that split, even though it's now
302  * a grandchild instead of a child.
303  * 
304  * The easy, and correct, way to think about this is that the size constraint
305  * is stored by a window's parent, not the window itself; and a constraint
306  * consists of a pointer to a key window plus a size value.
307  * 
308  * <informaltable frame="none"><tgroup cols="6"><tbody><row>
309  * <entry><mediaobject><imageobject><imagedata fileref="fig8a.png"/>
310  * </imageobject></mediaobject></entry>
311  * <entry><mediaobject><textobject><literallayout class="monospaced">
312  *  A   
313  * </literallayout></textobject></mediaobject></entry>
314  * <entry><mediaobject><imageobject><imagedata fileref="fig8b.png"/>
315  * </imageobject></mediaobject></entry>
316  * <entry><mediaobject><textobject><literallayout class="monospaced">
317  *    O1  
318  *   / \  
319  *  A   B 
320  * </literallayout></textobject></mediaobject></entry> 
321  * <entry><mediaobject><imageobject><imagedata fileref="fig8c.png"/>
322  * </imageobject></mediaobject></entry>
323  * <entry><mediaobject><textobject><literallayout class="monospaced">
324  *      O1  
325  *     / \  
326  *    O2  B 
327  *   / \    
328  *  A   C   
329  * </literallayout></textobject></mediaobject></entry> 
330  * </row></tbody></tgroup></informaltable>
331  * After the first split, the new pair window (O1, which covers the whole
332  * screen) knows that its first child (A) is above the second, and gets 50% of
333  * its own area. (A is the key window for this split, but a proportional split
334  * doesn't care about key windows.)
335  * 
336  * After the second split, all this remains true; O1 knows that its first child
337  * gets 50% of its space, and A is O1's key window. But now O1's first child is
338  * O2 instead of A. The newer pair window (O2) knows that its first child (C)
339  * is above the second, and gets a fixed size of two rows. (As measured in C's
340  * font, because C is O2's key window.)
341  * 
342  * If we split C, now, the resulting pair will still be two C-font rows high
343  * &mdash; that is, tall enough for two lines of whatever font C displays. For
344  * the sake of example, we'll do this vertically.
345  * <informaltable frame="none"><tgroup cols="2"><tbody><row>
346  * <entry><mediaobject><imageobject><imagedata fileref="fig9.png"/>
347  * </imageobject></mediaobject></entry>
348  * <entry><mediaobject><textobject><literallayout class="monospaced">
349  *      O1
350  *     / \
351  *    O2  B
352  *   / \
353  *  A   O3
354  *     / \
355  *    C   D
356  * </literallayout></textobject></mediaobject></entry> 
357  * </row></tbody></tgroup></informaltable>
358  * 
359  * O3 now knows that its children have a 50-50 left-right split. O2 is still
360  * committed to giving its upper child, O3, two C-font rows. Again, this is
361  * because C is O2's key window. 
362  *
363  * <note><para>
364  *   This turns out to be a good idea, because it means that C, the text grid
365  *   window, is still two rows high. If O3 had been a upper-lower split, things
366  *   wouldn't work out so neatly. But the rules would still apply. If you don't
367  *   like this, don't do it.
368  * </para></note>
369  *
370  * Returns: the new window, or %NULL on error.
371  */
372 winid_t
373 glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype, 
374                 glui32 rock)
375 {
376         VALID_WINDOW_OR_NULL(split, return NULL);
377         g_return_val_if_fail(method == (method & (winmethod_DirMask | winmethod_DivisionMask)), NULL);
378         g_return_val_if_fail(!(((method & winmethod_DivisionMask) == winmethod_Proportional) && size > 100), NULL);     
379
380         if(split == NULL && glk_data->root_window != NULL)
381         {
382                 ILLEGAL("Tried to open a new root window, but there is already a root window");
383                 return NULL;
384         }
385         
386         gdk_threads_enter();
387         
388         /* Create the new window */
389         winid_t win = g_new0(struct glk_window_struct, 1);
390         win->magic = MAGIC_WINDOW;
391         win->rock = rock;
392         win->type = wintype;
393         win->window_node = g_node_new(win);
394
395         switch(wintype)
396         {
397                 case wintype_Blank:
398                 {
399                         /* A blank window will be a label without any text */
400                         GtkWidget *label = gtk_label_new("");
401                         gtk_widget_show(label);
402                         
403                         win->widget = label;
404                         win->frame = label;
405                         /* A blank window has no size */
406                         win->unit_width = 0;
407                         win->unit_height = 0;
408                         /* You can print to a blank window's stream, but it does nothing */
409                         win->window_stream = window_stream_new(win);
410                         win->echo_stream = NULL;
411                 }
412                         break;
413                 
414                 case wintype_TextGrid:
415                 {
416                     GtkWidget *textview = gtk_text_view_new();
417
418                     gtk_text_view_set_wrap_mode( GTK_TEXT_VIEW(textview), GTK_WRAP_NONE );
419                     gtk_text_view_set_editable( GTK_TEXT_VIEW(textview), FALSE );
420                         gtk_widget_show(textview);
421                                 
422                         /* Set the window's font */
423                         gtk_widget_modify_font(textview, glk_data->monospace_font_desc);
424                     
425                     win->widget = textview;
426                     win->frame = textview;
427                         
428                         /* Determine the size of a "0" character in pixels */
429                         PangoLayout *zero = gtk_widget_create_pango_layout(textview, "0");
430                         pango_layout_set_font_description(zero, glk_data->monospace_font_desc);
431                         pango_layout_get_pixel_size(zero, &(win->unit_width), &(win->unit_height));
432                         g_object_unref(zero);
433                         
434                         /* Set the other parameters (width and height are set later) */
435                         win->window_stream = window_stream_new(win);
436                         win->echo_stream = NULL;
437                         win->input_request_type = INPUT_REQUEST_NONE;
438                         win->line_input_buffer = NULL;
439                         win->line_input_buffer_unicode = NULL;
440                         
441                         /* Connect signal handlers */
442                         win->keypress_handler = g_signal_connect( G_OBJECT(textview), "key-press-event", G_CALLBACK(on_window_key_press_event), win );
443                         g_signal_handler_block( G_OBJECT(textview), win->keypress_handler );
444                 }
445                     break;
446                 
447                 case wintype_TextBuffer:
448                 {
449                         GtkWidget *scrolledwindow = gtk_scrolled_window_new(NULL, NULL);
450                         GtkWidget *textview = gtk_text_view_new();
451                         GtkTextBuffer *textbuffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(textview) );
452
453                         gtk_scrolled_window_set_policy( GTK_SCROLLED_WINDOW(scrolledwindow), GTK_POLICY_NEVER, GTK_POLICY_AUTOMATIC );
454                         
455                         gtk_text_view_set_wrap_mode( GTK_TEXT_VIEW(textview), GTK_WRAP_WORD_CHAR );
456                         gtk_text_view_set_editable( GTK_TEXT_VIEW(textview), FALSE );
457                         gtk_text_view_set_pixels_inside_wrap( GTK_TEXT_VIEW(textview), 3 );
458                         gtk_text_view_set_left_margin( GTK_TEXT_VIEW(textview), 20 );
459                         gtk_text_view_set_right_margin( GTK_TEXT_VIEW(textview), 20 );
460
461                         gtk_container_add( GTK_CONTAINER(scrolledwindow), textview );
462                         gtk_widget_show_all(scrolledwindow);
463
464                         /* Set the window's font */
465                         gtk_widget_modify_font(textview, glk_data->default_font_desc);
466                         
467                         win->widget = textview;
468                         win->frame = scrolledwindow;
469                         
470                         /* Determine the size of a "0" character in pixels */
471                         PangoLayout *zero = gtk_widget_create_pango_layout(textview, "0");
472                         pango_layout_set_font_description(zero, glk_data->default_font_desc);
473                         pango_layout_get_pixel_size(zero, &(win->unit_width), &(win->unit_height));
474                         g_object_unref(zero);
475                         
476                         /* Set the other parameters */
477                         win->window_stream = window_stream_new(win);
478                         win->echo_stream = NULL;
479                         win->input_request_type = INPUT_REQUEST_NONE;
480                         win->line_input_buffer = NULL;
481                         win->line_input_buffer_unicode = NULL;
482
483                         /* Connect signal handlers */
484                         win->keypress_handler = g_signal_connect( G_OBJECT(textview), "key-press-event", G_CALLBACK(on_window_key_press_event), win );
485                         g_signal_handler_block( G_OBJECT(textview), win->keypress_handler );
486
487                         win->insert_text_handler = g_signal_connect_after( G_OBJECT(textbuffer), "insert-text", G_CALLBACK(after_window_insert_text), win );
488                         g_signal_handler_block( G_OBJECT(textbuffer), win->insert_text_handler );
489
490                         /* Create an editable tag to indicate uneditable parts of the window
491                         (for line input) */
492                         gtk_text_buffer_create_tag(textbuffer, "uneditable", "editable", FALSE, "editable-set", TRUE, NULL);
493
494                         /* Create the default styles available to the window stream */
495                         style_init_textbuffer(textbuffer);
496
497                         /* Mark the position where the user will input text */
498                         GtkTextIter end;
499                         gtk_text_buffer_get_end_iter(textbuffer, &end);
500                         gtk_text_buffer_create_mark(textbuffer, "input_position", &end, TRUE);
501                 }
502                         break;
503                         
504                 default:
505                         gdk_threads_leave();
506                         ILLEGAL_PARAM("Unknown window type: %u", wintype);
507                         g_free(win);
508                         g_node_destroy(glk_data->root_window);
509                         glk_data->root_window = NULL;
510                         return NULL;
511         }
512
513         /* Set the minimum size to "as small as possible" so it doesn't depend on
514          the size of the window contents */
515         gtk_widget_set_size_request(win->widget, 0, 0);
516         gtk_widget_set_size_request(win->frame, 0, 0);
517         
518         if(split)
519         {
520                 /* When splitting, construct a new parent window
521                  * copying most characteristics from the window that is being split */
522                 winid_t pair = g_new0(struct glk_window_struct, 1);
523                 pair->magic = MAGIC_WINDOW;
524                 pair->rock = 0;
525                 pair->type = wintype_Pair;
526                 pair->window_node = g_node_new(pair);
527                 /* You can print to a pair window's window stream, but it has no effect */
528                 pair->window_stream = window_stream_new(pair);
529                 pair->echo_stream = NULL;
530
531                 /* The pair window must know about its children's split method */
532                 pair->key_window = win;
533                 pair->split_method = method;
534                 pair->constraint_size = size;
535                 
536                 /* Insert the new window into the window tree */
537                 if(split->window_node->parent == NULL)
538                         glk_data->root_window = pair->window_node;
539                 else 
540                 {
541                         if( split->window_node == g_node_first_sibling(split->window_node) )
542                                 g_node_prepend(split->window_node->parent, pair->window_node);
543                         else
544                                 g_node_append(split->window_node->parent, pair->window_node);
545                         g_node_unlink(split->window_node);
546                 }
547                 /* Place the windows in the correct order */
548                 switch(method & winmethod_DirMask)
549                 {
550                         case winmethod_Left:
551                         case winmethod_Above:
552                                 g_node_append(pair->window_node, win->window_node);
553                                 g_node_append(pair->window_node, split->window_node);
554                                 break;
555                         case winmethod_Right:
556                         case winmethod_Below:
557                                 g_node_append(pair->window_node, split->window_node);
558                                 g_node_append(pair->window_node, win->window_node);
559                                 break;
560                 }
561
562         } else {
563                 /* Set the window as root window */
564                 glk_data->root_window = win->window_node;
565         }
566
567         /* Set the window as a child of the Glk widget, don't trigger an arrange event */
568         g_mutex_lock(glk_data->arrange_lock);
569         glk_data->needs_rearrange = TRUE;
570         glk_data->ignore_next_arrange_event = TRUE;
571         g_mutex_unlock(glk_data->arrange_lock);
572         gtk_widget_set_parent(win->frame, GTK_WIDGET(glk_data->self));
573         gtk_widget_queue_resize(GTK_WIDGET(glk_data->self));
574         
575     /* For text grid windows, fill the buffer with blanks. */
576     if(wintype == wintype_TextGrid)
577     {
578         /* Create the cursor position mark */
579         GtkTextIter begin;
580         GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
581         gtk_text_buffer_get_start_iter(buffer, &begin);
582         gtk_text_buffer_create_mark(buffer, "cursor_position", &begin, TRUE);
583         }
584
585         gdk_threads_leave();
586     glk_window_clear(win);
587         return win;
588 }
589
590 /* Internal function: if node's key window is closing_win or one of its
591  children, set node's key window to NULL. */
592 static gboolean 
593 remove_key_windows(GNode *node, winid_t closing_win)
594 {
595         winid_t win = (winid_t)node->data;
596         if(win->key_window && (win->key_window == closing_win || g_node_is_ancestor(closing_win->window_node, win->key_window->window_node)))
597                 win->key_window = NULL;
598         return FALSE; /* Don't stop the traversal */
599 }
600
601 /* Internal function: destroy this window's GTK widgets, window streams, 
602  and those of all its children. GDK threads must be locked. */
603 static void
604 destroy_windows_below(winid_t win, stream_result_t *result)
605 {
606         switch(win->type)
607         {
608                 case wintype_Blank:
609             case wintype_TextGrid:
610                 case wintype_TextBuffer:
611                         gtk_widget_unparent(win->frame);
612                         break;
613
614                 case wintype_Pair:
615                         destroy_windows_below(win->window_node->children->data, NULL);
616                         destroy_windows_below(win->window_node->children->next->data, NULL);
617                         break;
618
619                 default:
620                         ILLEGAL_PARAM("Unknown window type: %u", win->type);
621                         return;
622         }
623         stream_close_common(win->window_stream, result);
624 }
625
626 /* Internal function: free the winid_t structure of this window and those of all its children */
627 static void
628 free_winids_below(winid_t win)
629 {
630         if(win->type == wintype_Pair) {
631                 free_winids_below(win->window_node->children->data);
632                 free_winids_below(win->window_node->children->next->data);
633         }
634         win->magic = MAGIC_FREE;
635         g_free(win);
636 }
637
638 /**
639  * glk_window_close:
640  * @win: Window to close.
641  * @result: Pointer to a #stream_result_t in which to store the write count.
642  *
643  * Closes @win, which is pretty much exactly the opposite of opening a window.
644  * It is legal to close all your windows, or to close the root window (which is
645  * the same thing.) 
646  *
647  * The @result argument is filled with the output character count of the window
648  * stream. See <link linkend="chimara-Streams">Streams</link> and <link
649  * linkend="chimara-Closing-Streams">Closing Streams</link>.
650  * 
651  * When you close a window (and it is not the root window), the other window
652  * in its pair takes over all the freed-up area. Let's close D, in the current
653  * example:
654  * <informaltable frame="none"><tgroup cols="2"><tbody><row>
655  * <entry><mediaobject><imageobject><imagedata fileref="fig10.png"/>
656  * </imageobject></mediaobject></entry>
657  * <entry><mediaobject><textobject><literallayout class="monospaced">
658  *      O1
659  *     / \
660  *    O2  B
661  *   / \
662  *  A   C
663  * </literallayout></textobject></mediaobject></entry> 
664  * </row></tbody></tgroup></informaltable>
665  * 
666  * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right
667  * split has gone with it. The other size constraints are unchanged; O2 is
668  * still committed to giving its upper child two rows, as measured in the font
669  * of O2's key window, which is C. Conveniently, O2's upper child is C, just as
670  * it was before we created D. In fact, now that D is gone, everything is back
671  * to the way it was before we created D.
672  * 
673  * But what if we had closed C instead of D? We would have gotten this:
674  * <informaltable frame="none"><tgroup cols="2"><tbody><row>
675  * <entry><mediaobject><imageobject><imagedata fileref="fig11.png"/>
676  * </imageobject></mediaobject></entry>
677  * <entry><mediaobject><textobject><literallayout class="monospaced">
678  *      O1
679  *     / \
680  *    O2  B
681  *   / \
682  *  A   D
683  * </literallayout></textobject></mediaobject></entry> 
684  * </row></tbody></tgroup></informaltable>
685  * 
686  * Again, O3 is gone. But D has collapsed to zero height. This is because its
687  * height is controlled by O2, and O2's key window was C, and C is now gone. O2
688  * no longer has a key window at all, so it cannot compute a height for its
689  * upper child, so it defaults to zero.
690  * 
691  * <note><para>
692  *   This may seem to be an inconvenient choice. That is deliberate. You should
693  *   not leave a pair window with no key, and the zero-height default reminds
694  *   you not to. You can use glk_window_set_arrangement() to set a new split
695  *   measurement and key window. See <link 
696  *   linkend="chimara-Changing-Window-Constraints">Changing Window
697  *   Constraints</link>.
698  * </para></note>
699  */
700 void
701 glk_window_close(winid_t win, stream_result_t *result)
702 {
703         VALID_WINDOW(win, return);
704         
705         gdk_threads_enter(); /* Prevent redraw while we're trashing the window */
706         
707         /* If any pair windows have this window or its children as a key window,
708          set their key window to NULL */
709         g_node_traverse(glk_data->root_window, G_IN_ORDER, G_TRAVERSE_NON_LEAVES, -1, (GNodeTraverseFunc)remove_key_windows, win);
710         
711         /* Close all the window streams and destroy the widgets of this window
712          and below, before trashing the window tree */
713         destroy_windows_below(win, result);
714         
715         /* Then free the winid_t structures below this node, but not this one itself */
716         if(win->type == wintype_Pair) {
717                 free_winids_below(win->window_node->children->data);
718                 free_winids_below(win->window_node->children->next->data);
719         }
720         /* So now we should be left with a skeleton tree hanging off this node */       
721         
722         /* Parent window changes from a split window into the sibling window */
723         /* The parent of any window is either a pair window or NULL */
724         GNode *pair_node = win->window_node->parent;
725         g_node_destroy(win->window_node);
726         /* If win was not the root window: */
727         if(pair_node != NULL)
728         {
729                 gboolean new_child_on_left = ( pair_node == g_node_first_sibling(pair_node) );
730                 GNode *sibling_node = pair_node->children; /* only one child left */
731                 GNode *new_parent_node = pair_node->parent;
732                 g_node_unlink(pair_node);
733                 g_node_unlink(sibling_node);
734                 /* pair_node and sibling_node should now be totally unconnected to the tree */
735                 
736                 if(new_parent_node == NULL)
737                 {
738                         glk_data->root_window = sibling_node;
739                 } 
740                 else 
741                 {
742                         if(new_child_on_left)
743                                 g_node_prepend(new_parent_node, sibling_node);
744                         else
745                                 g_node_append(new_parent_node, sibling_node);
746                 }
747
748                 winid_t pair = (winid_t) pair_node->data;
749                 g_node_destroy(pair_node);
750                 
751                 pair->magic = MAGIC_FREE;
752                 g_free(pair);
753         } 
754         else /* it was the root window */
755         {
756                 glk_data->root_window = NULL;
757         }
758
759         win->magic = MAGIC_FREE;
760         g_free(win);
761
762         /* Schedule a redraw */
763         g_mutex_lock(glk_data->arrange_lock);
764         glk_data->needs_rearrange = TRUE;
765         glk_data->ignore_next_arrange_event = TRUE;
766         g_mutex_unlock(glk_data->arrange_lock);
767         gtk_widget_queue_resize( GTK_WIDGET(glk_data->self) );
768         gdk_threads_leave();
769 }
770
771 /**
772  * glk_window_clear:
773  * @win: A window.
774  *
775  * Erases @win. The meaning of this depends on the window type.
776  * <variablelist>
777  * <varlistentry>
778  *  <term>Text buffer</term>
779  *  <listitem><para>
780  *   This may do any number of things, such as delete all text in the window, or
781  *   print enough blank lines to scroll all text beyond visibility, or insert a
782  *   page-break marker which is treated specially by the display part of the
783  *   library.
784  *  </para></listitem>
785  * </varlistentry>
786  * <varlistentry>
787  *  <term>Text grid</term>
788  *  <listitem><para>
789  *   This will clear the window, filling all positions with blanks. The window
790  *   cursor is moved to the top left corner (position 0,0).
791  *  </para></listitem>
792  * </varlistentry>
793  * <varlistentry>
794  *  <term>Graphics</term>
795  *  <listitem><para>
796  *   Clears the entire window to its current background color. See <link
797  *   linkend="chimara-Graphics-Windows">Graphics Windows</link>.
798  *  </para></listitem>
799  * </varlistentry>
800  * <varlistentry>
801  *  <term>Other window types</term>
802  *  <listitem><para>No effect.</para></listitem>
803  * </varlistentry>
804  * </variablelist>
805  *
806  * It is illegal to erase a window which has line input pending. 
807  */
808 void
809 glk_window_clear(winid_t win)
810 {
811         VALID_WINDOW(win, return);
812         g_return_if_fail(win->input_request_type != INPUT_REQUEST_LINE && win->input_request_type != INPUT_REQUEST_LINE_UNICODE);
813         
814         switch(win->type)
815         {
816                 case wintype_Blank:
817                 case wintype_Pair:
818                         /* do nothing */
819                         break;
820                 
821                 case wintype_TextGrid:
822                     /* fill the buffer with blanks */
823                 {
824                         /* Wait for the window's size to be updated */
825                         g_mutex_lock(glk_data->arrange_lock);
826                         if(glk_data->needs_rearrange)
827                                 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
828                         g_mutex_unlock(glk_data->arrange_lock);
829                         
830                     gdk_threads_enter();
831                     
832             /* Manually put newlines at the end of each row of characters in the buffer; manual newlines make resizing the window's grid easier. */
833             gchar *blanks = g_strnfill(win->width, ' ');
834             gchar **blanklines = g_new0(gchar *, win->height + 1);
835             int count;
836             for(count = 0; count < win->height; count++)
837                 blanklines[count] = blanks;
838             blanklines[win->height] = NULL;
839             gchar *text = g_strjoinv("\n", blanklines);
840             g_free(blanklines); /* not g_strfreev() */
841             g_free(blanks);
842             
843             GtkTextBuffer *textbuffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
844             gtk_text_buffer_set_text(textbuffer, text, -1);
845             g_free(text);
846             
847             GtkTextIter begin;
848             gtk_text_buffer_get_start_iter(textbuffer, &begin);
849             gtk_text_buffer_move_mark_by_name(textbuffer, "cursor_position", &begin);
850                     
851                     gdk_threads_leave();
852                 }
853                     break;
854                 
855                 case wintype_TextBuffer:
856                         /* delete all text in the window */
857                 {
858                         gdk_threads_enter();
859
860                         GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
861                         GtkTextIter start, end;
862                         gtk_text_buffer_get_bounds(buffer, &start, &end);
863                         gtk_text_buffer_delete(buffer, &start, &end);
864
865                         gdk_threads_leave();
866                 }
867                         break;
868                 
869                 default:
870                         ILLEGAL_PARAM("Unknown window type: %d", win->type);
871         }
872 }
873
874 /**
875  * glk_set_window:
876  * @win: A window.
877  *
878  * Sets the current stream to @win's window stream. It is exactly equivalent to
879  * |[ #glk_stream_set_current(#glk_window_get_stream(@win)) ]| 
880  * See <link linkend="chimara-Streams">Streams</link>.
881  */
882 void
883 glk_set_window(winid_t win)
884 {
885         VALID_WINDOW(win, return);
886         glk_stream_set_current( glk_window_get_stream(win) );
887 }
888
889 /**
890  * glk_window_get_stream:
891  * @win: A window.
892  *
893  * Returns the stream which is associated with @win. (See <link 
894  * linkend="chimara-Window-Streams">Window Streams</link>.) Every window has a
895  * stream which can be printed to, but this may not be useful, depending on the
896  * window type.
897  * 
898  * <note><para>
899  *   For example, printing to a blank window's stream has no effect.
900  * </para></note>
901  *
902  * Returns: A window stream.
903  */
904 strid_t glk_window_get_stream(winid_t win)
905 {
906         VALID_WINDOW(win, return NULL);
907         return win->window_stream;
908 }
909
910 /**
911  * glk_window_set_echo_stream:
912  * @win: A window.
913  * @str: A stream to attach to the window, or %NULL.
914  *
915  * Sets @win's echo stream to @str, which can be any valid output stream. You
916  * can reset a window to stop echoing by calling 
917  * <code>#glk_window_set_echo_stream(@win, %NULL)</code>.
918  *
919  * It is illegal to set a window's echo stream to be its 
920  * <emphasis>own</emphasis> window stream. That would create an infinite loop,
921  * and is nearly certain to crash the Glk library. It is similarly illegal to
922  * create a longer loop (two or more windows echoing to each other.)
923  */
924 void
925 glk_window_set_echo_stream(winid_t win, strid_t str)
926 {
927         VALID_WINDOW(win, return);
928         VALID_STREAM_OR_NULL(str, return);
929         
930         /* Test for an infinite loop */
931         strid_t next = str;
932         for(; next && next->type == STREAM_TYPE_WINDOW; next = next->window->echo_stream)
933         {
934                 if(next == win->window_stream)
935                 {
936                         ILLEGAL("Infinite loop detected");
937                         win->echo_stream = NULL;
938                         return;
939                 }
940         }
941         
942         win->echo_stream = str;
943 }
944
945 /**
946  * glk_window_get_echo_stream:
947  * @win: A window.
948  *
949  * Returns the echo stream of window @win. Initially, a window has no echo
950  * stream, so <code>#glk_window_get_echo_stream(@win)</code> will return %NULL.
951  *
952  * Returns: A stream, or %NULL.
953  */
954 strid_t
955 glk_window_get_echo_stream(winid_t win)
956 {
957         VALID_WINDOW(win, return NULL);
958         return win->echo_stream;
959 }
960
961 /**
962  * glk_window_get_size:
963  * @win: A window.
964  * @widthptr: Pointer to a location to store the window's width, or %NULL.
965  * @heightptr: Pointer to a location to store the window's height, or %NULL.
966  *
967  * Simply returns the actual size of the window, in its measurement system.
968  * As described in <link linkend="chimara-Other-API-Conventions">Other API 
969  * Conventions</link>, either @widthptr or @heightptr can be %NULL, if you
970  * only want one measurement. 
971  *
972  * <note><para>Or, in fact, both, if you want to waste time.</para></note>
973  */
974 void
975 glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr)
976 {
977         VALID_WINDOW(win, return);
978
979     switch(win->type)
980     {
981         case wintype_Blank:
982                 case wintype_Pair:
983             if(widthptr != NULL)
984                 *widthptr = 0;
985             if(heightptr != NULL)
986                 *heightptr = 0;
987             break;
988             
989         case wintype_TextGrid:
990                         /* Wait until the window's size is current */
991                         g_mutex_lock(glk_data->arrange_lock);
992                         if(glk_data->needs_rearrange)
993                                 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
994                         g_mutex_unlock(glk_data->arrange_lock);
995                         
996                         gdk_threads_enter();
997                         /* Cache the width and height */
998                         win->width = (glui32)(win->widget->allocation.width / win->unit_width);
999                     win->height = (glui32)(win->widget->allocation.height / win->unit_height);
1000             gdk_threads_leave();
1001                         
1002             if(widthptr != NULL)
1003                 *widthptr = win->width;
1004             if(heightptr != NULL)
1005                 *heightptr = win->height;
1006             break;
1007             
1008         case wintype_TextBuffer:
1009             /* Wait until the window's size is current */
1010                         g_mutex_lock(glk_data->arrange_lock);
1011                         if(glk_data->needs_rearrange)
1012                                 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
1013                         g_mutex_unlock(glk_data->arrange_lock);
1014                         
1015             gdk_threads_enter();
1016             if(widthptr != NULL)
1017                 *widthptr = (glui32)(win->widget->allocation.width / win->unit_width);
1018             if(heightptr != NULL)
1019                 *heightptr = (glui32)(win->widget->allocation.height / win->unit_height);
1020             gdk_threads_leave();
1021             
1022             break;
1023             
1024         default:
1025             ILLEGAL_PARAM("Unknown window type: %u", win->type);
1026     }
1027 }
1028
1029 /**
1030  * glk_window_set_arrangement:
1031  * @win: a pair window to rearrange.
1032  * @method: new method of size computation. One of %winmethod_Above, 
1033  * %winmethod_Below, %winmethod_Left, or %winmethod_Right OR'ed with 
1034  * %winmethod_Fixed or %winmethod_Proportional.
1035  * @size: new size constraint, in percentage points if @method is
1036  * %winmethod_Proportional, otherwise in characters if @win's type is 
1037  * %wintype_TextBuffer or %wintype_TextGrid, or pixels if @win's type is
1038  * %wintype_Graphics.
1039  * @keywin: new key window, or %NULL to leave the key window unchanged.
1040  *
1041  * Changes the size of an existing split &mdash; that is, it changes the 
1042  * constraint of a given pair window.
1043  * 
1044  * Consider the example above, where D has collapsed to zero height. Say D was a
1045  * text buffer window. You could make a more useful layout by doing
1046  * |[
1047  * #winid_t o2;
1048  * o2 = #glk_window_get_parent(d);
1049  * glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Fixed, 3, d);
1050  * ]|
1051  * That would set D (the upper child of O2) to be O2's key window, and give it a
1052  * fixed size of 3 rows.
1053  * 
1054  * If you later wanted to expand D, you could do
1055  * |[ glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Fixed, 5, NULL); ]|
1056  * That expands D to five rows. Note that, since O2's key window is already set 
1057  * to D, it is not necessary to provide the @keywin argument; you can pass %NULL
1058  * to mean <quote>leave the key window unchanged.</quote>
1059  * 
1060  * If you do change the key window of a pair window, the new key window 
1061  * <emphasis>must</emphasis> be a descendant of that pair window. In the current
1062  * example, you could change O2's key window to be A, but not B. The key window
1063  * also cannot be a pair window itself.
1064  * 
1065  * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Fixed, 3, NULL); ]|
1066  * This changes the constraint to be on the <emphasis>lower</emphasis> child of 
1067  * O2, which is A. The key window is still D; so A would then be three rows high
1068  * as measured in D's font, and D would get the rest of O2's space. That may not
1069  * be what you want. To set A to be three rows high as measured in A's font, you
1070  * would do
1071  * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Fixed, 3, a); ]|
1072  * 
1073  * Or you could change O2 to a proportional split:
1074  * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Proportional, 30, NULL); ]|
1075  * or
1076  * |[ glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Proportional, 70, NULL); ]|
1077  * These do exactly the same thing, since 30&percnt; above is the same as 
1078  * 70&percnt; below. You don't need to specify a key window with a proportional
1079  * split, so the @keywin argument is %NULL. (You could actually specify either A
1080  * or D as the key window, but it wouldn't affect the result.)
1081  * 
1082  * Whatever constraint you set, glk_window_get_size() will tell you the actual 
1083  * window size you got.
1084  * 
1085  * Note that you can resize windows, but you can't flip or rotate them. You 
1086  * can't move A above D, or change O2 to a vertical split where A is left or 
1087  * right of D. 
1088  * <note><para>
1089  *   To get this effect you could close one of the windows, and re-split the 
1090  *   other one with glk_window_open().
1091  * </para></note>
1092  */
1093 void
1094 glk_window_set_arrangement(winid_t win, glui32 method, glui32 size, winid_t keywin)
1095 {
1096         VALID_WINDOW(win, return);
1097         VALID_WINDOW_OR_NULL(keywin, return);
1098         g_return_if_fail(win->type == wintype_Pair);
1099         if(keywin)
1100         {
1101                 g_return_if_fail(keywin->type != wintype_Pair);
1102                 g_return_if_fail(g_node_is_ancestor(win->window_node, keywin->window_node));
1103         }
1104         g_return_if_fail(method == (method & (winmethod_DirMask | winmethod_DivisionMask)));
1105         g_return_if_fail(!(((method & winmethod_DivisionMask) == winmethod_Proportional) && size > 100));
1106         
1107         win->split_method = method;
1108         win->constraint_size = size;
1109         if(keywin)
1110                 win->key_window = keywin;
1111
1112         /* Tell GTK to rearrange the windows */
1113         gdk_threads_enter();
1114         g_mutex_lock(glk_data->arrange_lock);
1115         glk_data->needs_rearrange = TRUE;
1116         glk_data->ignore_next_arrange_event = TRUE;
1117         g_mutex_unlock(glk_data->arrange_lock);
1118         gtk_widget_queue_resize(GTK_WIDGET(glk_data->self));
1119         gdk_threads_leave();
1120 }
1121
1122 /**
1123  * glk_window_get_arrangement:
1124  * @win: a pair window.
1125  * @methodptr: return location for the constraint flags of @win, or %NULL.
1126  * @sizeptr: return location for the constraint size of @win, or %NULL.
1127  * @keywinptr: return location for the key window of @win, or %NULL.
1128  *
1129  * Queries the constraint of a given pair window.
1130  */
1131 void
1132 glk_window_get_arrangement(winid_t win, glui32 *methodptr, glui32 *sizeptr, winid_t *keywinptr)
1133 {
1134         VALID_WINDOW(win, return);
1135         g_return_if_fail(win->type == wintype_Pair);
1136         
1137         if(methodptr)
1138                 *methodptr = win->split_method;
1139         if(sizeptr)
1140                 *sizeptr = win->constraint_size;
1141         if(keywinptr)
1142                 *keywinptr = win->key_window;
1143 }
1144
1145 /**
1146  * glk_window_move_cursor:
1147  * @win: A text grid window.
1148  * @xpos: Horizontal cursor position.
1149  * @ypos: Vertical cursor position.
1150  * 
1151  * Sets the cursor position. If you move the cursor right past the end of a 
1152  * line, it wraps; the next character which is printed will appear at the
1153  * beginning of the next line.
1154  * 
1155  * If you move the cursor below the last line, or when the cursor reaches the
1156  * end of the last line, it goes <quote>off the screen</quote> and further
1157  * output has no effect. You must call glk_window_move_cursor() or
1158  * glk_window_clear() to move the cursor back into the visible region.
1159  * 
1160  * <note><para>
1161  *  Note that the arguments of glk_window_move_cursor() are <type>unsigned 
1162  *  int</type>s. This is okay, since there are no negative positions. If you try
1163  *  to pass a negative value, Glk will interpret it as a huge positive value,
1164  *  and it will wrap or go off the last line.
1165  * </para></note>
1166  *
1167  * <note><para>
1168  *  Also note that the output cursor is not necessarily visible. In particular,
1169  *  when you are requesting line or character input in a grid window, you cannot
1170  *  rely on the cursor position to prompt the player where input is indicated.
1171  *  You should print some character prompt at that spot &mdash; a 
1172  *  <quote>&gt;</quote> character, for example.
1173  * </para></note>
1174  */
1175 void
1176 glk_window_move_cursor(winid_t win, glui32 xpos, glui32 ypos)
1177 {
1178         VALID_WINDOW(win, return);
1179         g_return_if_fail(win->type == wintype_TextGrid);
1180         
1181         /* Wait until the window's size is current */
1182         g_mutex_lock(glk_data->arrange_lock);
1183         if(glk_data->needs_rearrange)
1184                 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
1185         g_mutex_unlock(glk_data->arrange_lock);
1186
1187         /* Don't do anything if the window is shrunk down to nothing */
1188         if(win->width == 0 || win->height == 0)
1189                 return;
1190         
1191         /* Calculate actual position if cursor is moved past the right edge */
1192         if(xpos >= win->width)
1193         {
1194             ypos += xpos / win->width;
1195             xpos %= win->width;
1196         }
1197         /* Go to the end if the cursor is moved off the bottom edge */
1198         if(ypos >= win->height)
1199         {
1200             xpos = win->width - 1;
1201             ypos = win->height - 1;
1202         }
1203         
1204         gdk_threads_enter();
1205         
1206         GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
1207         GtkTextIter newpos;
1208         /* There must actually be a character at xpos, or the following function will choke */
1209         gtk_text_buffer_get_iter_at_line_offset(buffer, &newpos, ypos, xpos);
1210         gtk_text_buffer_move_mark_by_name(buffer, "cursor_position", &newpos);
1211         
1212         gdk_threads_leave();
1213 }
1214