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