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