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