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 *textview = gtk_text_view_new();
 368
 369                     gtk_text_view_set_wrap_mode( GTK_TEXT_VIEW(textview), GTK_WRAP_CHAR );
 370                     gtk_text_view_set_editable( GTK_TEXT_VIEW(textview), FALSE );
 371                         gtk_widget_show(textview);
 372
 373                         /* Set the window's font */
 374                         gtk_widget_modify_font(textview, glk_data->monospace_font_desc);
 375
 376                     win->widget = textview;
 377                     win->frame = textview;
 378
 379                         /* Determine the size of a "0" character in pixels */
 380                         PangoLayout *zero = gtk_widget_create_pango_layout(textview, "0");
 381                         pango_layout_set_font_description(zero, glk_data->monospace_font_desc);
 382                         pango_layout_get_pixel_size(zero, &(win->unit_width), &(win->unit_height));
 383                         g_object_unref(zero);
 384
 385                         /* Set the other parameters (width and height are set later) */
 386                         win->window_stream = window_stream_new(win);
 387                         win->echo_stream = NULL;
 388                         win->input_request_type = INPUT_REQUEST_NONE;
 389                         win->line_input_buffer = NULL;
 390                         win->line_input_buffer_unicode = NULL;
 391
 392                         /* Connect signal handlers */
 393                         win->keypress_handler = g_signal_connect( G_OBJECT(textview), "key-press-event", G_CALLBACK(on_window_key_press_event), win );
 394                         g_signal_handler_block( G_OBJECT(textview), win->keypress_handler );
 395                 }
 396                     break;
 397
 398                 case wintype_TextBuffer:
 399                 {
 400                         GtkWidget *scrolledwindow = gtk_scrolled_window_new(NULL, NULL);
 401                         GtkWidget *textview = gtk_text_view_new();
 402                         GtkTextBuffer *textbuffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(textview) );
 403
 404                         gtk_scrolled_window_set_policy( GTK_SCROLLED_WINDOW(scrolledwindow), GTK_POLICY_NEVER, GTK_POLICY_AUTOMATIC );
 405
 406                         gtk_text_view_set_wrap_mode( GTK_TEXT_VIEW(textview), GTK_WRAP_WORD_CHAR );
 407                         gtk_text_view_set_editable( GTK_TEXT_VIEW(textview), FALSE );
 408
 409                         gtk_container_add( GTK_CONTAINER(scrolledwindow), textview );
 410                         gtk_widget_show_all(scrolledwindow);
 411
 412                         /* Set the window's font */
 413                         gtk_widget_modify_font(textview, glk_data->default_font_desc);
 414
 415                         win->widget = textview;
 416                         win->frame = scrolledwindow;
 417
 418                         /* Determine the size of a "0" character in pixels */
 419                         PangoLayout *zero = gtk_widget_create_pango_layout(textview, "0");
 420                         pango_layout_set_font_description(zero, glk_data->default_font_desc);
 421                         pango_layout_get_pixel_size(zero, &(win->unit_width), &(win->unit_height));
 422                         g_object_unref(zero);
 423
 424                         /* Set the other parameters */
 425                         win->window_stream = window_stream_new(win);
 426                         win->echo_stream = NULL;
 427                         win->input_request_type = INPUT_REQUEST_NONE;
 428                         win->line_input_buffer = NULL;
 429                         win->line_input_buffer_unicode = NULL;
 430
 431                         /* Connect signal handlers */
 432                         win->keypress_handler = g_signal_connect( G_OBJECT(textview), "key-press-event", G_CALLBACK(on_window_key_press_event), win );
 433                         g_signal_handler_block( G_OBJECT(textview), win->keypress_handler );
 434
 435                         win->insert_text_handler = g_signal_connect_after( G_OBJECT(textbuffer), "insert-text", G_CALLBACK(after_window_insert_text), win );
 436                         g_signal_handler_block( G_OBJECT(textbuffer), win->insert_text_handler );
 437
 438                         /* Create an editable tag to indicate uneditable parts of the window
 439                         (for line input) */
 440                         gtk_text_buffer_create_tag(textbuffer, "uneditable", "editable", FALSE, "editable-set", TRUE, NULL);
 441
 442                         /* Mark the position where the user will input text */
 443                         GtkTextIter end;
 444                         gtk_text_buffer_get_end_iter(textbuffer, &end);
 445                         gtk_text_buffer_create_mark(textbuffer, "input_position", &end, TRUE);
 446                 }
 447                         break;
 448
 449                 default:
 450                         gdk_threads_leave();
 451                         ILLEGAL_PARAM("Unknown window type: %u", wintype);
 452                         g_free(win);
 453                         g_node_destroy(glk_data->root_window);
 454                         glk_data->root_window = NULL;
 455                         return NULL;
 456         }
 457
 458         /* Set the minimum size to "as small as possible" so it doesn't depend on
 459          the size of the window contents */
 460         gtk_widget_set_size_request(win->widget, 0, 0);
 461         gtk_widget_set_size_request(win->frame, 0, 0);
 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                         glk_data->root_window = pair->window_node;
 484                 else
 485                 {
 486                         if( split->window_node == g_node_first_sibling(split->window_node) )
 487                                 g_node_prepend(split->window_node->parent, pair->window_node);
 488                         else
 489                                 g_node_append(split->window_node->parent, pair->window_node);
 490                         g_node_unlink(split->window_node);
 491                 }
 492                 /* Place the windows in the correct order */
 493                 switch(method & winmethod_DirMask)
 494                 {
 495                         case winmethod_Left:
 496                         case winmethod_Above:
 497                                 g_node_append(pair->window_node, win->window_node);
 498                                 g_node_append(pair->window_node, split->window_node);
 499                                 break;
 500                         case winmethod_Right:
 501                         case winmethod_Below:
 502                                 g_node_append(pair->window_node, split->window_node);
 503                                 g_node_append(pair->window_node, win->window_node);
 504                                 break;
 505                 }
 506
 507         } else {
 508                 /* Set the window as root window */
 509                 glk_data->root_window = win->window_node;
 510         }
 511
 512         /* Set the window as a child of the Glk widget */
 513         gtk_widget_set_parent(win->frame, GTK_WIDGET(glk_data->self));
 514         gtk_widget_queue_resize(GTK_WIDGET(glk_data->self));
 515
 516         gdk_threads_leave();
 517
 518         /* For blank or pair windows, this is almost a no-op. For text grid and
 519          text buffer windows, this will wait for GTK to draw the window. Otherwise,
 520          opening a window and getting its size immediately will give you the wrong
 521          size. */
 522         glk_window_get_size(win, NULL, NULL);
 523
 524     /* For text grid windows, fill the buffer with blanks. */
 525     if(wintype == wintype_TextGrid)
 526     {
 527         /* Create the cursor position mark */
 528                 gdk_threads_enter();
 529         GtkTextIter begin;
 530         GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
 531         gtk_text_buffer_get_start_iter(buffer, &begin);
 532         gtk_text_buffer_create_mark(buffer, "cursor_position", &begin, TRUE);
 533         gdk_threads_leave();
 534
 535         /* Fill the buffer with blanks and move the cursor to the upper left */
 536         glk_window_clear(win);
 537     }
 538
 539         return win;
 540 }
 541
 542 /* Internal function: if node's key window is closing_win or one of its
 543  children, set node's key window to NULL. */
 544 static gboolean
 545 remove_key_windows(GNode *node, winid_t closing_win)
 546 {
 547         winid_t win = (winid_t)node->data;
 548         if(win->key_window && (win->key_window == closing_win || g_node_is_ancestor(closing_win->window_node, win->key_window->window_node)))
 549                 win->key_window = NULL;
 550         return FALSE; /* Don't stop the traversal */
 551 }
 552
 553 /* Internal function: destroy this window's GTK widgets, window streams,
 554  and those of all its children */
 555 static void
 556 destroy_windows_below(winid_t win, stream_result_t *result)
 557 {
 558         switch(win->type)
 559         {
 560                 case wintype_Blank:
 561                         gdk_threads_enter();
 562                         gtk_widget_unparent(win->widget);
 563                         gdk_threads_leave();
 564                         break;
 565
 566             case wintype_TextGrid:
 567                 case wintype_TextBuffer:
 568                         gdk_threads_enter();
 569                         gtk_widget_unparent(win->frame);
 570                         gdk_threads_leave();
 571                         /* TODO: Cancel all input requests */
 572                         break;
 573
 574                 case wintype_Pair:
 575                         destroy_windows_below(win->window_node->children->data, NULL);
 576                         destroy_windows_below(win->window_node->children->next->data, NULL);
 577                         break;
 578
 579                 default:
 580                         ILLEGAL_PARAM("Unknown window type: %u", win->type);
 581                         return;
 582         }
 583         stream_close_common(win->window_stream, result);
 584 }
 585
 586 /* Internal function: free the winid_t structure of this window and those of all its children */
 587 static void
 588 free_winids_below(winid_t win)
 589 {
 590         if(win->type == wintype_Pair) {
 591                 free_winids_below(win->window_node->children->data);
 592                 free_winids_below(win->window_node->children->next->data);
 593         }
 594         win->magic = MAGIC_FREE;
 595         g_free(win);
 596 }
 597
 598 /**
 599  * glk_window_close:
 600  * @win: Window to close.
 601  * @result: Pointer to a #stream_result_t in which to store the write count.
 602  *
 603  * Closes @win, which is pretty much exactly the opposite of opening a window.
 604  * It is legal to close all your windows, or to close the root window (which is
 605  * the same thing.)
 606  *
 607  * The @result argument is filled with the output character count of the window
 608  * stream. See <link linkend="chimara-Streams">Streams</link> and <link
 609  * linkend="chimara-Closing-Streams">Closing Streams</link>.
 610  *
 611  * When you close a window (and it is not the root window), the other window
 612  * in its pair takes over all the freed-up area. Let's close D, in the current
 613  * example:
 614  * <mediaobject><textobject><phrase>Screen shot 10</phrase></textobject>
 615  * </mediaobject>
 616  *
 617  * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right
 618  * split has gone with it. The other size constraints are unchanged; O2 is
 619  * still committed to giving its upper child two rows, as measured in the font
 620  * of O2's key window, which is C. Conveniently, O2's upper child is C, just as
 621  * it was before we created D. In fact, now that D is gone, everything is back
 622  * to the way it was before we created D.
 623  *
 624  * But what if we had closed C instead of D? We would have gotten this:
 625  * <mediaobject><textobject><phrase>Screen shot 11</phrase></textobject>
 626  * </mediaobject>
 627  *
 628  * Again, O3 is gone. But D has collapsed to zero height. This is because its
 629  * height is controlled by O2, and O2's key window was C, and C is now gone. O2
 630  * no longer has a key window at all, so it cannot compute a height for its
 631  * upper child, so it defaults to zero.
 632  *
 633  * <note><para>
 634  *   This may seem to be an inconvenient choice. That is deliberate. You should
 635  *   not leave a pair window with no key, and the zero-height default reminds
 636  *   you not to. You can use glk_window_set_arrangement() to set a new split
 637  *   measurement and key window. See <link
 638  *   linkend="chimara-Changing-Window-Constraints">Changing Window
 639  *   Constraints</link>.
 640  * </para></note>
 641  */
 642 void
 643 glk_window_close(winid_t win, stream_result_t *result)
 644 {
 645         VALID_WINDOW(win, return);
 646
 647         /* If any pair windows have this window or its children as a key window,
 648          set their key window to NULL */
 649         g_node_traverse(glk_data->root_window, G_IN_ORDER, G_TRAVERSE_NON_LEAVES, -1, (GNodeTraverseFunc)remove_key_windows, win);
 650
 651         /* Close all the window streams and destroy the widgets of this window
 652          and below, before trashing the window tree */
 653         destroy_windows_below(win, result);
 654
 655         /* Then free the winid_t structures below this node, but not this one itself */
 656         if(win->type == wintype_Pair) {
 657                 free_winids_below(win->window_node->children->data);
 658                 free_winids_below(win->window_node->children->next->data);
 659         }
 660         /* So now we should be left with a skeleton tree hanging off this node */
 661
 662         /* Parent window changes from a split window into the sibling window */
 663         /* The parent of any window is either a pair window or NULL */
 664         GNode *pair_node = win->window_node->parent;
 665         g_node_destroy(win->window_node);
 666         /* If win was not the root window: */
 667         if(pair_node != NULL)
 668         {
 669                 gboolean new_child_on_left = ( pair_node == g_node_first_sibling(pair_node) );
 670                 GNode *sibling_node = pair_node->children; /* only one child left */
 671                 GNode *new_parent_node = pair_node->parent;
 672                 g_node_unlink(pair_node);
 673                 g_node_unlink(sibling_node);
 674                 /* pair_node and sibling_node should now be totally unconnected to the tree */
 675
 676                 if(new_parent_node == NULL)
 677                 {
 678                         glk_data->root_window = sibling_node;
 679                 }
 680                 else
 681                 {
 682                         if(new_child_on_left)
 683                                 g_node_prepend(new_parent_node, sibling_node);
 684                         else
 685                                 g_node_append(new_parent_node, sibling_node);
 686                 }
 687
 688                 winid_t pair = (winid_t) pair_node->data;
 689                 g_node_destroy(pair_node);
 690
 691                 pair->magic = MAGIC_FREE;
 692                 g_free(pair);
 693         }
 694         else /* it was the root window */
 695         {
 696                 glk_data->root_window = NULL;
 697         }
 698
 699         win->magic = MAGIC_FREE;
 700         g_free(win);
 701
 702         /* Schedule a redraw */
 703         gdk_threads_enter();
 704         gtk_widget_queue_resize( GTK_WIDGET(glk_data->self) );
 705         gdk_threads_leave();
 706 }
 707
 708 /**
 709  * glk_window_clear:
 710  * @win: A window.
 711  *
 712  * Erases @win. The meaning of this depends on the window type.
 713  * <variablelist>
 714  * <varlistentry>
 715  *  <term>Text buffer</term>
 716  *  <listitem><para>
 717  *   This may do any number of things, such as delete all text in the window, or
 718  *   print enough blank lines to scroll all text beyond visibility, or insert a
 719  *   page-break marker which is treated specially by the display part of the
 720  *   library.
 721  *  </para></listitem>
 722  * </varlistentry>
 723  * <varlistentry>
 724  *  <term>Text grid</term>
 725  *  <listitem><para>
 726  *   This will clear the window, filling all positions with blanks. The window
 727  *   cursor is moved to the top left corner (position 0,0).
 728  *  </para></listitem>
 729  * </varlistentry>
 730  * <varlistentry>
 731  *  <term>Graphics</term>
 732  *  <listitem><para>
 733  *   Clears the entire window to its current background color. See <link
 734  *   linkend="chimara-Graphics-Windows">Graphics Windows</link>.
 735  *  </para></listitem>
 736  * </varlistentry>
 737  * <varlistentry>
 738  *  <term>Other window types</term>
 739  *  <listitem><para>No effect.</para></listitem>
 740  * </varlistentry>
 741  * </variablelist>
 742  *
 743  * It is illegal to erase a window which has line input pending.
 744  */
 745 void
 746 glk_window_clear(winid_t win)
 747 {
 748         VALID_WINDOW(win, return);
 749         g_return_if_fail(win->input_request_type != INPUT_REQUEST_LINE && win->input_request_type != INPUT_REQUEST_LINE_UNICODE);
 750
 751         switch(win->type)
 752         {
 753                 case wintype_Blank:
 754                 case wintype_Pair:
 755                         /* do nothing */
 756                         break;
 757
 758                 case wintype_TextGrid:
 759                     /* fill the buffer with blanks */
 760                 {
 761                     gdk_threads_enter();
 762
 763             /* Manually put newlines at the end of each row of characters in the buffer; manual newlines make resizing the window's grid easier. */
 764             gchar *blanks = g_strnfill(win->width, ' ');
 765             gchar **blanklines = g_new0(gchar *, win->height + 1);
 766             int count;
 767             for(count = 0; count < win->height; count++)
 768                 blanklines[count] = blanks;
 769             blanklines[win->height] = NULL;
 770             gchar *text = g_strjoinv("\n", blanklines);
 771             g_free(blanklines); /* not g_strfreev() */
 772             g_free(blanks);
 773
 774             GtkTextBuffer *textbuffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
 775             gtk_text_buffer_set_text(textbuffer, text, -1);
 776             g_free(text);
 777
 778             GtkTextIter begin;
 779             gtk_text_buffer_get_start_iter(textbuffer, &begin);
 780             gtk_text_buffer_move_mark_by_name(textbuffer, "cursor_position", &begin);
 781
 782                     gdk_threads_leave();
 783                 }
 784                     break;
 785
 786                 case wintype_TextBuffer:
 787                         /* delete all text in the window */
 788                 {
 789                         gdk_threads_enter();
 790
 791                         GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
 792                         GtkTextIter start, end;
 793                         gtk_text_buffer_get_bounds(buffer, &start, &end);
 794                         gtk_text_buffer_delete(buffer, &start, &end);
 795
 796                         gdk_threads_leave();
 797                 }
 798                         break;
 799
 800                 default:
 801                         ILLEGAL_PARAM("Unknown window type: %d", win->type);
 802         }
 803 }
 804
 805 /**
 806  * glk_set_window:
 807  * @win: A window.
 808  *
 809  * Sets the current stream to @win's window stream. It is exactly equivalent to
 810  * <code>#glk_stream_set_current(#glk_window_get_stream(@win))</code>.
 811  */
 812 void
 813 glk_set_window(winid_t win)
 814 {
 815         VALID_WINDOW_OR_NULL(win, return);
 816         glk_stream_set_current( glk_window_get_stream(win) );
 817 }
 818
 819 /**
 820  * glk_window_get_stream:
 821  * @win: A window.
 822  *
 823  * Returns the stream which is associated with @win. (See <link
 824  * linkend="chimara-Window-Streams">Window Streams</link>.) Every window has a
 825  * stream which can be printed to, but this may not be useful, depending on the
 826  * window type.
 827  *
 828  * <note><para>
 829  *   For example, printing to a blank window's stream has no effect.
 830  * </para></note>
 831  *
 832  * Returns: A window stream.
 833  */
 834 strid_t glk_window_get_stream(winid_t win)
 835 {
 836         VALID_WINDOW(win, return NULL);
 837         return win->window_stream;
 838 }
 839
 840 /**
 841  * glk_window_set_echo_stream:
 842  * @win: A window.
 843  * @str: A stream to attach to the window, or %NULL.
 844  *
 845  * Sets @win's echo stream to @str, which can be any valid output stream. You
 846  * can reset a window to stop echoing by calling
 847  * <code>#glk_window_set_echo_stream(@win, %NULL)</code>.
 848  *
 849  * It is illegal to set a window's echo stream to be its
 850  * <emphasis>own</emphasis> window stream. That would create an infinite loop,
 851  * and is nearly certain to crash the Glk library. It is similarly illegal to
 852  * create a longer loop (two or more windows echoing to each other.)
 853  */
 854 void
 855 glk_window_set_echo_stream(winid_t win, strid_t str)
 856 {
 857         VALID_WINDOW(win, return);
 858         VALID_STREAM_OR_NULL(str, return);
 859
 860         /* Test for an infinite loop */
 861         strid_t next = str;
 862         for(; next && next->type == STREAM_TYPE_WINDOW; next = next->window->echo_stream)
 863         {
 864                 if(next == win->window_stream)
 865                 {
 866                         ILLEGAL("Infinite loop detected");
 867                         win->echo_stream = NULL;
 868                         return;
 869                 }
 870         }
 871
 872         win->echo_stream = str;
 873 }
 874
 875 /**
 876  * glk_window_get_echo_stream:
 877  * @win: A window.
 878  *
 879  * Returns the echo stream of window @win. Initially, a window has no echo
 880  * stream, so <code>#glk_window_get_echo_stream(@win)</code> will return %NULL.
 881  *
 882  * Returns: A stream, or %NULL.
 883  */
 884 strid_t
 885 glk_window_get_echo_stream(winid_t win)
 886 {
 887         VALID_WINDOW(win, return NULL);
 888         return win->echo_stream;
 889 }
 890
 891 /**
 892  * glk_window_get_size:
 893  * @win: A window.
 894  * @widthptr: Pointer to a location to store the window's width, or %NULL.
 895  * @heightptr: Pointer to a location to store the window's height, or %NULL.
 896  *
 897  * Simply returns the actual size of the window, in its measurement system.
 898  * As described in <link linkend="chimara-Other-API-Conventions">Other API
 899  * Conventions</link>, either @widthptr or @heightptr can be %NULL, if you
 900  * only want one measurement.
 901  *
 902  * <note><para>Or, in fact, both, if you want to waste time.</para></note>
 903  */
 904 void
 905 glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr)
 906 {
 907         VALID_WINDOW(win, return);
 908
 909     switch(win->type)
 910     {
 911         case wintype_Blank:
 912                 case wintype_Pair:
 913             if(widthptr != NULL)
 914                 *widthptr = 0;
 915             if(heightptr != NULL)
 916                 *heightptr = 0;
 917             break;
 918
 919         case wintype_TextGrid:
 920                         gdk_threads_enter();
 921                         /* Wait for the window to be drawn, and then cache the width and height */
 922                         while(win->widget->allocation.width == 1 && win->widget->allocation.height == 1)
 923                     {
 924                         /* Release the GDK lock momentarily */
 925                         gdk_threads_leave();
 926                         gdk_threads_enter();
 927                         while(gtk_events_pending())
 928                             gtk_main_iteration();
 929                     }
 930                     win->width = (glui32)(win->widget->allocation.width / win->unit_width);
 931                     win->height = (glui32)(win->widget->allocation.height / win->unit_height);
 932             gdk_threads_leave();
 933
 934             if(widthptr != NULL)
 935                 *widthptr = win->width;
 936             if(heightptr != NULL)
 937                 *heightptr = win->height;
 938             break;
 939
 940         case wintype_TextBuffer:
 941             /* 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. */
 942             gdk_threads_enter();
 943             /*if(win->widget->allocation.width == 1 && win->widget->allocation.height == 1)
 944             {
 945                 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.");
 946                 guess the size from the parent window;
 947                 break;
 948             } */
 949
 950             /* Instead, we wait for GTK to draw the widget. This is probably very slow and should be fixed. */
 951             while(win->widget->allocation.width == 1 && win->widget->allocation.height == 1)
 952             {
 953                 /* Release the GDK lock momentarily */
 954                 gdk_threads_leave();
 955                 gdk_threads_enter();
 956                 while(gtk_events_pending())
 957                     gtk_main_iteration();
 958             }
 959
 960             if(widthptr != NULL)
 961                 *widthptr = (glui32)(win->widget->allocation.width / win->unit_width);
 962             if(heightptr != NULL)
 963                 *heightptr = (glui32)(win->widget->allocation.height / win->unit_height);
 964             gdk_threads_leave();
 965
 966             break;
 967
 968         default:
 969             ILLEGAL_PARAM("Unknown window type: %u", win->type);
 970     }
 971 }
 972
 973 /**
 974  * glk_window_move_cursor:
 975  * @win: A text grid window.
 976  * @xpos: Horizontal cursor position.
 977  * @ypos: Vertical cursor position.
 978  *
 979  * Sets the cursor position. If you move the cursor right past the end of a
 980  * line, it wraps; the next character which is printed will appear at the
 981  * beginning of the next line.
 982  *
 983  * If you move the cursor below the last line, or when the cursor reaches the
 984  * end of the last line, it goes <quote>off the screen</quote> and further
 985  * output has no effect. You must call glk_window_move_cursor() or
 986  * glk_window_clear() to move the cursor back into the visible region.
 987  *
 988  * <note><para>
 989  *  Note that the arguments of glk_window_move_cursor() are <type>unsigned
 990  *  int</type>s. This is okay, since there are no negative positions. If you try
 991  *  to pass a negative value, Glk will interpret it as a huge positive value,
 992  *  and it will wrap or go off the last line.
 993  * </para></note>
 994  *
 995  * <note><para>
 996  *  Also note that the output cursor is not necessarily visible. In particular,
 997  *  when you are requesting line or character input in a grid window, you cannot
 998  *  rely on the cursor position to prompt the player where input is indicated.
 999  *  You should print some character prompt at that spot &mdash; a
1000  *  <quote>&gt;</quote> character, for example.
1001  * </para></note>
1002  */
1003 void
1004 glk_window_move_cursor(winid_t win, glui32 xpos, glui32 ypos)
1005 {
1006         VALID_WINDOW(win, return);
1007         g_return_if_fail(win->type == wintype_TextGrid);
1008
1009         /* Calculate actual position if cursor is moved past the right edge */
1010         if(xpos >= win->width)
1011         {
1012             ypos += xpos / win->width;
1013             xpos %= win->width;
1014         }
1015         /* Go to the end if the cursor is moved off the bottom edge */
1016         if(ypos >= win->height)
1017         {
1018             xpos = win->width - 1;
1019             ypos = win->height - 1;
1020         }
1021
1022         gdk_threads_enter();
1023
1024         GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
1025         GtkTextIter newpos;
1026         /* There must actually be a character at xpos, or the following function will choke */
1027         gtk_text_buffer_get_iter_at_line_offset(buffer, &newpos, ypos, xpos);
1028         gtk_text_buffer_move_mark_by_name(buffer, "cursor_position", &newpos);
1029
1030         gdk_threads_leave();
1031 }
1032