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