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