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