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