4 #include "chimara-glk-private.h"
8 extern GPrivate *glk_data_key;
11 window_new_common(glui32 rock)
13 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
14 winid_t win = g_new0(struct glk_window_struct, 1);
16 win->magic = MAGIC_WINDOW;
18 if(glk_data->register_obj)
19 win->disprock = (*glk_data->register_obj)(win, gidisp_Class_Window);
21 win->window_node = g_node_new(win);
23 /* Every window has a window stream, but printing to it might have no effect */
24 win->window_stream = stream_new_common(0);
25 win->window_stream->file_mode = filemode_Write;
26 win->window_stream->type = STREAM_TYPE_WINDOW;
27 win->window_stream->window = win;
28 win->window_stream->style = "normal";
29 win->window_stream->glk_style = "normal";
31 win->echo_stream = NULL;
32 win->input_request_type = INPUT_REQUEST_NONE;
33 win->line_input_buffer = NULL;
34 win->line_input_buffer_unicode = NULL;
36 win->echo_line_input = TRUE;
37 win->echo_current_line_input = TRUE;
38 win->extra_line_terminators = NULL;
39 win->current_extra_line_terminators = NULL;
41 /* Initialise the buffer */
42 win->buffer = g_string_sized_new(1024);
44 /* Initialise hyperlink table */
45 win->hyperlinks = g_hash_table_new_full(g_int_hash, g_int_equal, g_free, g_free);
50 /* Internal function: do all the stuff necessary to close a window. Call only
53 window_close_common(winid_t win, gboolean destroy_node)
55 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
57 if(glk_data->unregister_obj)
59 (*glk_data->unregister_obj)(win, gidisp_Class_Window, win->disprock);
60 win->disprock.ptr = NULL;
64 g_node_destroy(win->window_node);
66 win->magic = MAGIC_FREE;
68 g_list_foreach(win->history, (GFunc)g_free, NULL);
69 g_list_free(win->history);
70 g_slist_free(win->extra_line_terminators);
71 g_slist_free(win->current_extra_line_terminators);
73 g_string_free(win->buffer, TRUE);
74 g_hash_table_destroy(win->hyperlinks);
75 g_free(win->current_hyperlink);
77 if(win->backing_store)
78 cairo_surface_destroy(win->backing_store);
85 * @win: A window, or %NULL.
86 * @rockptr: Return location for the next window's rock, or %NULL.
88 * This function can be used to iterate through the list of all open windows
89 * (including pair windows.) See <link
90 * linkend="chimara-Iterating-Through-Opaque-Objects">Iterating Through Opaque
93 * As that section describes, the order in which windows are returned is
94 * arbitrary. The root window is not necessarily first, nor is it necessarily
97 * Returns: the next window, or %NULL if there are no more.
100 glk_window_iterate(winid_t win, glui32 *rockptr)
102 VALID_WINDOW_OR_NULL(win, return NULL);
104 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
108 retnode = glk_data->root_window;
111 GNode *node = win->window_node;
112 if( G_NODE_IS_LEAF(node) )
114 while(node && node->next == NULL)
117 retnode = node->next;
122 retnode = g_node_first_child(node);
124 winid_t retval = retnode? (winid_t)retnode->data : NULL;
126 /* Store the window's rock in rockptr */
127 if(retval && rockptr)
128 *rockptr = glk_window_get_rock(retval);
134 * glk_window_get_rock:
137 * Returns @win's rock value. Pair windows always have rock 0; all other windows
138 * return whatever rock value you created them with.
140 * Returns: A rock value.
143 glk_window_get_rock(winid_t win)
145 VALID_WINDOW(win, return 0);
150 * glk_window_get_type:
153 * Returns @win's type, one of %wintype_Blank, %wintype_Pair,
154 * %wintype_TextBuffer, %wintype_TextGrid, or %wintype_Graphics.
156 * Returns: The window's type.
159 glk_window_get_type(winid_t win)
161 VALID_WINDOW(win, return 0);
166 * glk_window_get_parent:
169 * Returns the window which is the parent of @win. If @win is the root window,
170 * this returns %NULL, since the root window has no parent. Remember that the
171 * parent of every window is a pair window; other window types are always
174 * Returns: A window, or %NULL.
177 glk_window_get_parent(winid_t win)
179 VALID_WINDOW(win, return NULL);
181 /* Value will also be NULL if win is the root window */
182 if(win->window_node->parent == NULL)
185 return (winid_t)win->window_node->parent->data;
189 * glk_window_get_sibling:
192 * Returns the other child of @win's parent. If @win is the root window, this
195 * Returns: A window, or %NULL.
198 glk_window_get_sibling(winid_t win)
200 VALID_WINDOW(win, return NULL);
202 if(G_NODE_IS_ROOT(win->window_node))
204 if(win->window_node->next)
205 return (winid_t)win->window_node->next->data;
206 return (winid_t)win->window_node->prev->data;
210 * glk_window_get_root:
212 * Returns the root window. If there are no windows, this returns %NULL.
214 * Returns: A window, or %NULL.
217 glk_window_get_root()
219 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
220 if(glk_data->root_window == NULL)
222 return (winid_t)glk_data->root_window->data;
227 * @split: The window to split to create the new window. Must be 0 if there
228 * are no windows yet.
229 * @method: Position of the new window and method of size computation. One of
230 * %winmethod_Above, %winmethod_Below, %winmethod_Left, or %winmethod_Right
231 * OR'ed with %winmethod_Fixed or %winmethod_Proportional. If @wintype is
232 * %wintype_Blank, then %winmethod_Fixed is not allowed. May also be OR'ed with
233 * %winmethod_Border or %winmethod_NoBorder.
234 * @size: Size of the new window, in percentage points if @method is
235 * %winmethod_Proportional, otherwise in characters if @wintype is
236 * %wintype_TextBuffer or %wintype_TextGrid, or pixels if @wintype is
238 * @wintype: Type of the new window. One of %wintype_Blank, %wintype_TextGrid,
239 * %wintype_TextBuffer, or %wintype_Graphics.
240 * @rock: The new window's rock value.
242 * Creates a new window. If there are no windows, the first three arguments are
243 * meaningless. @split <emphasis>must</emphasis> be 0, and @method and @size
244 * are ignored. @wintype is the type of window you're creating, and @rock is
245 * the rock (see <link linkend="chimara-Rocks">Rocks</link>).
247 * If any windows exist, new windows must be created by splitting existing
248 * ones. @split is the window you want to split; this <emphasis>must
249 * not</emphasis> be zero. @method specifies the direction and the split method
250 * (see below). @size is the size of the split. @wintype is the type of window
251 * you're creating, and @rock is the rock.
253 * The method argument must be the logical-or of a direction constant
254 * (%winmethod_Above, %winmethod_Below, %winmethod_Left, %winmethod_Right) and a
255 * split-method constant (%winmethod_Fixed, %winmethod_Proportional).
257 * Remember that it is possible that the library will be unable to create a new
258 * window, in which case glk_window_open() will return %NULL.
261 * It is acceptable to gracefully exit, if the window you are creating is an
262 * important one — such as your first window. But you should not try to
263 * perform any window operation on the id until you have tested to make sure
267 * The examples we've seen so far have the simplest kind of size control. (Yes,
268 * this is <quote>below</quote>.) Every pair is a percentage split, with
271 * <mathphrase>X</mathphrase>
273 * percent going to one side, and
276 * <mathphrase>(100 - X)</mathphrase>
278 * percent going to the other side. If the player resizes the window, the whole
279 * mess expands, contracts, or stretches in a uniform way.
281 * As I said above, you can also make fixed-size splits. This is a little more
282 * complicated, because you have to know how this fixed size is measured.
284 * Sizes are measured in a way which is different for each window type. For
285 * example, a text grid window is measured by the size of its fixed-width font.
286 * You can make a text grid window which is fixed at a height of four rows, or
287 * ten columns. A text buffer window is measured by the size of its font.
290 * Remember that different windows may use different size fonts. Even two
291 * text grid windows may use fixed-size fonts of different sizes.
294 * Graphics windows are measured in pixels, not characters. Blank windows
295 * aren't measured at all; there's no meaningful way to measure them, and
296 * therefore you can't create a blank window of a fixed size, only of a
297 * proportional (percentage) size.
299 * So to create a text buffer window which takes the top 40% of the original
300 * window's space, you would execute
301 * |[ newwin = glk_window_open(win, winmethod_Above | winmethod_Proportional, 40, wintype_TextBuffer, 0); ]|
303 * To create a text grid which is always five lines high, at the bottom of the
304 * original window, you would do
305 * |[ newwin = glk_window_open(win, winmethod_Below | winmethod_Fixed, 5, wintype_TextGrid, 0); ]|
307 * Note that the meaning of the @size argument depends on the @method argument.
308 * If the method is %winmethod_Fixed, it also depends on the @wintype argument.
309 * The new window is then called the <quote>key window</quote> of this split,
310 * because its window type determines how the split size is computed.
313 * For %winmethod_Proportional splits, you can still call the new window the
314 * <quote>key window</quote>. But the key window is not important for
315 * proportional splits, because the size will always be computed as a simple
316 * ratio of the available space, not a fixed size of one child window.
319 * This system is more or less peachy as long as all the constraints work out.
320 * What happens when there is a conflict? The rules are simple. Size control
321 * always flows down the tree, and the player is at the top. Let's bring out an
323 * <informaltable frame="none"><tgroup cols="2"><tbody><row>
324 * <entry><mediaobject><imageobject><imagedata fileref="fig5-7a.png"/>
325 * </imageobject></mediaobject></entry>
326 * <entry><mediaobject><textobject><literallayout class="monospaced">
332 * </literallayout></textobject></mediaobject></entry>
333 * </row></tbody></tgroup></informaltable>
335 * First we split A into A and B, with a 50% proportional split. Then we split
336 * A into A and C, with C above, C being a text grid window, and C gets a fixed
337 * size of two rows (as measured in its own font size). A gets whatever remains
338 * of the 50% it had before.
340 * Now the player stretches the window vertically.
341 * <informalfigure><mediaobject><imageobject><imagedata fileref="fig6.png"/>
342 * </imageobject></mediaobject></informalfigure>
344 * The library figures: the topmost split, the original A/B split, is 50-50. So
345 * B gets half the screen space, and the pair window next to it (the lower
346 * <quote>O</quote>) gets the other half. Then it looks at the lower
347 * <quote>O</quote>. C gets two rows; A gets the rest. All done.
349 * Then the user maliciously starts squeezing the window down, in stages:
350 * <informaltable xml:id="chimara-Figure-Squeezing-Window" frame="none">
351 * <tgroup cols="5"><tbody><row valign="top">
352 * <entry><mediaobject><imageobject><imagedata fileref="fig5-7a.png"/>
353 * </imageobject></mediaobject></entry>
354 * <entry><mediaobject><imageobject><imagedata fileref="fig7b.png"/>
355 * </imageobject></mediaobject></entry>
356 * <entry><mediaobject><imageobject><imagedata fileref="fig7c.png"/>
357 * </imageobject></mediaobject></entry>
358 * <entry><mediaobject><imageobject><imagedata fileref="fig7d.png"/>
359 * </imageobject></mediaobject></entry>
360 * <entry><mediaobject><imageobject><imagedata fileref="fig7e.png"/>
361 * </imageobject></mediaobject></entry>
362 * </row></tbody></tgroup></informaltable>
364 * The logic remains the same. B always gets half the space. At stage 3,
365 * there's no room left for A, so it winds up with zero height. Nothing
366 * displayed in A will be visible. At stage 4, there isn't even room in the
367 * upper 50% to give C its two rows; so it only gets one. Finally, C is
368 * squashed out of existence as well.
370 * When a window winds up undersized, it remembers what size it should be. In
371 * the example above, A remembers that it should be two rows; if the user
372 * expands the window to the original size, it would return to the original
375 * The downward flow of control is a bit harsh. After all, in stage 4, there's
376 * room for C to have its two rows if only B would give up some of its 50%. But
377 * this does not happen.
380 * This makes life much easier for the Glk library. To determine the
381 * configuration of a window, it only needs to look at the window's
382 * ancestors, never at its descendants. So window layout is a simple
383 * recursive algorithm, no backtracking.
386 * What happens when you split a fixed-size window? The resulting pair window
387 * — that is, the two new parts together — retain the same size
388 * constraint as the original window that was split. The key window for the
389 * original split is still the key window for that split, even though it's now
390 * a grandchild instead of a child.
392 * The easy, and correct, way to think about this is that the size constraint
393 * is stored by a window's parent, not the window itself; and a constraint
394 * consists of a pointer to a key window plus a size value.
396 * <informaltable frame="none"><tgroup cols="6"><tbody><row>
397 * <entry><mediaobject><imageobject><imagedata fileref="fig8a.png"/>
398 * </imageobject></mediaobject></entry>
399 * <entry><mediaobject><textobject><literallayout class="monospaced">
401 * </literallayout></textobject></mediaobject></entry>
402 * <entry><mediaobject><imageobject><imagedata fileref="fig8b.png"/>
403 * </imageobject></mediaobject></entry>
404 * <entry><mediaobject><textobject><literallayout class="monospaced">
408 * </literallayout></textobject></mediaobject></entry>
409 * <entry><mediaobject><imageobject><imagedata fileref="fig8c.png"/>
410 * </imageobject></mediaobject></entry>
411 * <entry><mediaobject><textobject><literallayout class="monospaced">
417 * </literallayout></textobject></mediaobject></entry>
418 * </row></tbody></tgroup></informaltable>
419 * The initial window is A. After the first split, the new pair window (O1,
420 * which covers the whole screen) knows that its new child (B) is below A, and
421 * gets 50% of its own area. (B is the key window for this split, but a
422 * proportional split doesn't care about key windows.)
424 * After the <emphasis>second</emphasis> split, all this remains true; O1 knows
425 * that its first child gets 50% of its space, and B is O1's key window. But
426 * now O1's first child is O2 instead of A. The newer pair window (O2) knows
427 * that its first child (C) is above the second, and gets a fixed size of two
428 * rows. (As measured in C's font, because C is O2's key window.)
430 * If we split C, now, the resulting pair will still be two C-font rows high
431 * — that is, tall enough for two lines of whatever font C displays. For
432 * the sake of example, we'll do this vertically.
433 * <informaltable frame="none"><tgroup cols="2"><tbody><row>
434 * <entry><mediaobject><imageobject><imagedata fileref="fig9.png"/>
435 * </imageobject></mediaobject></entry>
436 * <entry><mediaobject><textobject><literallayout class="monospaced">
444 * </literallayout></textobject></mediaobject></entry>
445 * </row></tbody></tgroup></informaltable>
447 * O3 now knows that its children have a 50-50 left-right split. O2 is still
448 * committed to giving its upper child, O3, two C-font rows. Again, this is
449 * because C is O2's key window.
452 * This turns out to be a good idea, because it means that C, the text grid
453 * window, is still two rows high. If O3 had been a upper-lower split, things
454 * wouldn't work out so neatly. But the rules would still apply. If you don't
455 * like this, don't do it.
458 * Returns: the new window, or %NULL on error.
461 glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype,
464 VALID_WINDOW_OR_NULL(split, return NULL);
465 g_return_val_if_fail(!(((method & winmethod_DivisionMask) == winmethod_Proportional) && size > 100), NULL);
466 if(method != (method & (winmethod_DirMask | winmethod_DivisionMask | winmethod_BorderMask)))
467 WARNING("Unrecognized bits in method constant");
469 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
471 if(split == NULL && glk_data->root_window != NULL)
473 ILLEGAL("Tried to open a new root window, but there is already a root window");
479 /* Create the new window */
480 winid_t win = window_new_common(rock);
487 /* A blank window will be a label without any text */
488 GtkWidget *label = gtk_label_new("");
489 gtk_widget_show(label);
493 /* A blank window has no size */
495 win->unit_height = 0;
499 case wintype_TextGrid:
501 GtkWidget *textview = gtk_text_view_new();
502 GtkTextBuffer *textbuffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(textview) );
504 gtk_text_view_set_wrap_mode( GTK_TEXT_VIEW(textview), GTK_WRAP_NONE );
505 gtk_text_view_set_editable( GTK_TEXT_VIEW(textview), FALSE );
506 gtk_widget_show(textview);
508 /* Create the styles available to the window stream */
509 style_init_textgrid(textbuffer);
510 gtk_widget_modify_font( textview, get_current_font(wintype) );
512 win->widget = textview;
513 win->frame = textview;
515 /* Determine the size of a "0" character in pixels */
516 PangoLayout *zero = gtk_widget_create_pango_layout(textview, "0");
517 pango_layout_set_font_description( zero, get_current_font(wintype) );
518 pango_layout_get_pixel_size(zero, &(win->unit_width), &(win->unit_height));
519 g_object_unref(zero);
520 /* width and height are set later */
522 /* Connect signal handlers */
523 win->char_input_keypress_handler = g_signal_connect(textview, "key-press-event", G_CALLBACK(on_char_input_key_press_event), win);
524 g_signal_handler_block(textview, win->char_input_keypress_handler);
525 win->line_input_keypress_handler = g_signal_connect(textview, "key-press-event", G_CALLBACK(on_line_input_key_press_event), win);
526 g_signal_handler_block(textview, win->line_input_keypress_handler);
527 win->shutdown_keypress_handler = g_signal_connect(textview, "key-press-event", G_CALLBACK(on_shutdown_key_press_event), win);
528 g_signal_handler_block(textview, win->shutdown_keypress_handler);
529 win->button_press_event_handler = g_signal_connect( textview, "button-press-event", G_CALLBACK(on_window_button_press), win );
530 g_signal_handler_block(textview, win->button_press_event_handler);
534 case wintype_TextBuffer:
536 GtkWidget *overlay = gtk_overlay_new();
537 GtkWidget *scrolledwindow = gtk_scrolled_window_new(NULL, NULL);
538 GtkWidget *textview = gtk_text_view_new();
539 GtkWidget *pager = gtk_button_new_with_label("More");
540 GtkWidget *image = gtk_image_new_from_stock(GTK_STOCK_GO_DOWN, GTK_ICON_SIZE_BUTTON);
541 GtkTextBuffer *textbuffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(textview) );
543 gtk_scrolled_window_set_policy( GTK_SCROLLED_WINDOW(scrolledwindow), GTK_POLICY_NEVER, GTK_POLICY_AUTOMATIC );
545 gtk_button_set_image( GTK_BUTTON(pager), image );
546 gtk_widget_set_halign(pager, GTK_ALIGN_END);
547 gtk_widget_set_valign(pager, GTK_ALIGN_END);
548 gtk_widget_set_no_show_all(pager, TRUE);
550 gtk_text_view_set_wrap_mode( GTK_TEXT_VIEW(textview), GTK_WRAP_WORD_CHAR );
551 gtk_text_view_set_editable( GTK_TEXT_VIEW(textview), FALSE );
552 gtk_text_view_set_pixels_inside_wrap( GTK_TEXT_VIEW(textview), 3 );
553 gtk_text_view_set_left_margin( GTK_TEXT_VIEW(textview), 20 );
554 gtk_text_view_set_right_margin( GTK_TEXT_VIEW(textview), 20 );
556 gtk_container_add( GTK_CONTAINER(scrolledwindow), textview );
557 gtk_container_add( GTK_CONTAINER(overlay), scrolledwindow );
558 gtk_overlay_add_overlay( GTK_OVERLAY(overlay), pager );
559 gtk_widget_show_all(overlay);
561 win->widget = textview;
562 win->scrolledwindow = scrolledwindow;
564 win->frame = overlay;
566 /* Create the styles available to the window stream */
567 style_init_textbuffer(textbuffer);
568 gtk_widget_modify_font( textview, get_current_font(wintype) );
570 /* Determine the size of a "0" character in pixels */
571 PangoLayout *zero = gtk_widget_create_pango_layout(textview, "0");
572 pango_layout_set_font_description( zero, get_current_font(wintype) );
573 pango_layout_get_pixel_size(zero, &(win->unit_width), &(win->unit_height));
574 g_object_unref(zero);
576 /* Connect signal handlers */
579 g_signal_connect_after( textview, "size-allocate", G_CALLBACK(pager_after_size_allocate), win );
580 win->pager_keypress_handler = g_signal_connect( textview, "key-press-event", G_CALLBACK(pager_on_key_press_event), win );
581 g_signal_handler_block(textview, win->pager_keypress_handler);
582 GtkAdjustment *adj = gtk_scrolled_window_get_vadjustment(GTK_SCROLLED_WINDOW(scrolledwindow));
583 win->pager_adjustment_handler = g_signal_connect_after(adj, "value-changed", G_CALLBACK(pager_after_adjustment_changed), win);
585 /* Char and line input */
586 win->char_input_keypress_handler = g_signal_connect( textview, "key-press-event", G_CALLBACK(on_char_input_key_press_event), win );
587 g_signal_handler_block(textview, win->char_input_keypress_handler);
588 win->line_input_keypress_handler = g_signal_connect( textview, "key-press-event", G_CALLBACK(on_line_input_key_press_event), win );
589 g_signal_handler_block(textview, win->line_input_keypress_handler);
590 win->insert_text_handler = g_signal_connect_after( textbuffer, "insert-text", G_CALLBACK(after_window_insert_text), win );
591 g_signal_handler_block(textbuffer, win->insert_text_handler);
593 /* Shutdown key press */
594 win->shutdown_keypress_handler = g_signal_connect( textview, "key-press-event", G_CALLBACK(on_shutdown_key_press_event), win );
595 g_signal_handler_block(textview, win->shutdown_keypress_handler);
597 /* Create an editable tag to indicate uneditable parts of the window
599 gtk_text_buffer_create_tag(textbuffer, "uneditable", "editable", FALSE, "editable-set", TRUE, NULL);
601 /* Mark the position where the user will input text and the end mark */
603 gtk_text_buffer_get_end_iter(textbuffer, &end);
604 gtk_text_buffer_create_mark(textbuffer, "input_position", &end, TRUE);
605 gtk_text_buffer_create_mark(textbuffer, "end_position", &end, FALSE);
607 /* Create the pager position mark; it stands for the last character in the buffer
608 that has been on-screen */
609 gtk_text_buffer_create_mark(textbuffer, "pager_position", &end, TRUE);
613 case wintype_Graphics:
615 GtkWidget *image = gtk_drawing_area_new();
616 gtk_widget_show(image);
619 win->unit_height = 1;
622 win->background_color = 0x00FFFFFF;
623 win->backing_store = NULL;
625 /* Connect signal handlers */
626 win->button_press_event_handler = g_signal_connect(image, "button-press-event", G_CALLBACK(on_window_button_press), win);
627 g_signal_handler_block(image, win->button_press_event_handler);
628 win->shutdown_keypress_handler = g_signal_connect(image, "key-press-event", G_CALLBACK(on_shutdown_key_press_event), win);
629 g_signal_handler_block(image, win->shutdown_keypress_handler);
630 g_signal_connect(image, "configure-event", G_CALLBACK(on_graphics_configure), win);
631 g_signal_connect(image, "draw", G_CALLBACK(on_graphics_draw), win);
637 ILLEGAL_PARAM("Unknown window type: %u", wintype);
639 g_node_destroy(glk_data->root_window);
640 glk_data->root_window = NULL;
644 /* Set the minimum size to "as small as possible" so it doesn't depend on
645 the size of the window contents */
646 gtk_widget_set_size_request(win->widget, 0, 0);
647 gtk_widget_set_size_request(win->frame, 0, 0);
651 /* When splitting, construct a new parent window
652 * copying most characteristics from the window that is being split */
653 winid_t pair = window_new_common(0);
654 pair->type = wintype_Pair;
656 /* The pair window must know about its children's split method */
657 pair->key_window = win;
658 pair->split_method = method;
659 pair->constraint_size = size;
661 /* Insert the new window into the window tree */
662 if(split->window_node->parent == NULL)
663 glk_data->root_window = pair->window_node;
666 if( split->window_node == g_node_first_sibling(split->window_node) )
667 g_node_prepend(split->window_node->parent, pair->window_node);
669 g_node_append(split->window_node->parent, pair->window_node);
670 g_node_unlink(split->window_node);
672 /* Place the windows in the correct order */
673 switch(method & winmethod_DirMask)
676 case winmethod_Above:
677 g_node_append(pair->window_node, win->window_node);
678 g_node_append(pair->window_node, split->window_node);
680 case winmethod_Right:
681 case winmethod_Below:
682 g_node_append(pair->window_node, split->window_node);
683 g_node_append(pair->window_node, win->window_node);
688 /* Set the window as root window */
689 glk_data->root_window = win->window_node;
692 /* Set the window as a child of the Glk widget, don't trigger an arrange event */
693 g_mutex_lock(glk_data->arrange_lock);
694 glk_data->needs_rearrange = TRUE;
695 glk_data->ignore_next_arrange_event = TRUE;
696 g_mutex_unlock(glk_data->arrange_lock);
697 gtk_widget_set_parent(win->frame, GTK_WIDGET(glk_data->self));
698 gtk_widget_queue_resize(GTK_WIDGET(glk_data->self));
700 /* For text grid windows, fill the buffer with blanks. */
701 if(wintype == wintype_TextGrid)
703 /* Create the cursor position mark */
705 GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
706 gtk_text_buffer_get_start_iter(buffer, &begin);
707 gtk_text_buffer_create_mark(buffer, "cursor_position", &begin, TRUE);
711 glk_window_clear(win);
715 /* Internal function: if node's key window is closing_win or one of its
716 children, set node's key window to NULL. */
718 remove_key_windows(GNode *node, winid_t closing_win)
720 winid_t win = (winid_t)node->data;
721 if(win->key_window && (win->key_window == closing_win || g_node_is_ancestor(closing_win->window_node, win->key_window->window_node)))
722 win->key_window = NULL;
723 return FALSE; /* Don't stop the traversal */
726 /* Internal function: destroy this window's GTK widgets, window streams,
727 and those of all its children. GDK threads must be locked. */
729 destroy_windows_below(winid_t win, stream_result_t *result)
734 case wintype_TextGrid:
735 case wintype_TextBuffer:
736 case wintype_Graphics:
737 gtk_widget_unparent(win->frame);
741 destroy_windows_below(win->window_node->children->data, NULL);
742 destroy_windows_below(win->window_node->children->next->data, NULL);
746 ILLEGAL_PARAM("Unknown window type: %u", win->type);
749 stream_close_common(win->window_stream, result);
752 /* Internal function: free the winid_t structure of this window and those of all its children */
754 free_winids_below(winid_t win)
756 if(win->type == wintype_Pair) {
757 free_winids_below(win->window_node->children->data);
758 free_winids_below(win->window_node->children->next->data);
760 window_close_common(win, FALSE);
765 * @win: Window to close.
766 * @result: Pointer to a #stream_result_t in which to store the write count.
768 * Closes @win, which is pretty much exactly the opposite of opening a window.
769 * It is legal to close all your windows, or to close the root window (which is
772 * The @result argument is filled with the output character count of the window
773 * stream. See <link linkend="chimara-Streams">Streams</link> and <link
774 * linkend="chimara-Closing-Streams">Closing Streams</link>.
776 * When you close a window (and it is not the root window), the other window
777 * in its pair takes over all the freed-up area. Let's close D, in the current
779 * <informaltable frame="none"><tgroup cols="2"><tbody><row>
780 * <entry><mediaobject><imageobject><imagedata fileref="fig10.png"/>
781 * </imageobject></mediaobject></entry>
782 * <entry><mediaobject><textobject><literallayout class="monospaced">
788 * </literallayout></textobject></mediaobject></entry>
789 * </row></tbody></tgroup></informaltable>
791 * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right
792 * split has gone with it. The other size constraints are unchanged; O2 is
793 * still committed to giving its upper child two rows, as measured in the font
794 * of O2's key window, which is C. Conveniently, O2's upper child is C, just as
795 * it was before we created D. In fact, now that D is gone, everything is back
796 * to the way it was before we created D.
798 * But what if we had closed C instead of D? We would have gotten this:
799 * <informaltable frame="none"><tgroup cols="2"><tbody><row>
800 * <entry><mediaobject><imageobject><imagedata fileref="fig11.png"/>
801 * </imageobject></mediaobject></entry>
802 * <entry><mediaobject><textobject><literallayout class="monospaced">
808 * </literallayout></textobject></mediaobject></entry>
809 * </row></tbody></tgroup></informaltable>
811 * Again, O3 is gone. But D has collapsed to zero height. This is because its
812 * height is controlled by O2, and O2's key window was C, and C is now gone. O2
813 * no longer has a key window at all, so it cannot compute a height for its
814 * upper child, so it defaults to zero.
817 * This may seem to be an inconvenient choice. That is deliberate. You should
818 * not leave a pair window with no key, and the zero-height default reminds
819 * you not to. You can use glk_window_set_arrangement() to set a new split
820 * measurement and key window. See <link
821 * linkend="chimara-Changing-Window-Constraints">Changing Window
822 * Constraints</link>.
826 glk_window_close(winid_t win, stream_result_t *result)
828 VALID_WINDOW(win, return);
830 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
832 gdk_threads_enter(); /* Prevent redraw while we're trashing the window */
834 /* If any pair windows have this window or its children as a key window,
835 set their key window to NULL */
836 g_node_traverse(glk_data->root_window, G_IN_ORDER, G_TRAVERSE_NON_LEAVES, -1, (GNodeTraverseFunc)remove_key_windows, win);
838 /* Close all the window streams and destroy the widgets of this window
839 and below, before trashing the window tree */
840 destroy_windows_below(win, result);
842 /* Then free the winid_t structures below this node, but not this one itself */
843 if(win->type == wintype_Pair) {
844 free_winids_below(win->window_node->children->data);
845 free_winids_below(win->window_node->children->next->data);
847 /* So now we should be left with a skeleton tree hanging off this node */
849 /* Parent window changes from a split window into the sibling window */
850 /* The parent of any window is either a pair window or NULL */
851 GNode *pair_node = win->window_node->parent;
852 /* If win was not the root window: */
853 if(pair_node != NULL)
855 gboolean new_child_on_left = ( pair_node == g_node_first_sibling(pair_node) );
857 /* Lookup our sibling */
858 GNode *sibling_node = pair_node->children;
859 if(sibling_node == win->window_node)
860 sibling_node = sibling_node->next;
862 GNode *new_parent_node = pair_node->parent;
863 g_node_unlink(pair_node);
864 g_node_unlink(sibling_node);
865 /* pair_node and sibling_node should now be totally unconnected to the tree */
867 if(new_parent_node == NULL)
869 glk_data->root_window = sibling_node;
873 if(new_child_on_left)
874 g_node_prepend(new_parent_node, sibling_node);
876 g_node_append(new_parent_node, sibling_node);
879 stream_close_common( ((winid_t) pair_node->data)->window_stream, NULL );
880 window_close_common( (winid_t) pair_node->data, TRUE);
882 else /* it was the root window */
884 glk_data->root_window = NULL;
887 window_close_common(win, FALSE);
889 /* Schedule a redraw */
890 g_mutex_lock(glk_data->arrange_lock);
891 glk_data->needs_rearrange = TRUE;
892 glk_data->ignore_next_arrange_event = TRUE;
893 g_mutex_unlock(glk_data->arrange_lock);
894 gtk_widget_queue_resize( GTK_WIDGET(glk_data->self) );
902 * Erases @win. The meaning of this depends on the window type.
905 * <term>Text buffer</term>
907 * This may do any number of things, such as delete all text in the window, or
908 * print enough blank lines to scroll all text beyond visibility, or insert a
909 * page-break marker which is treated specially by the display part of the
914 * <term>Text grid</term>
916 * This will clear the window, filling all positions with blanks (in the
917 * normal style). The window cursor is moved to the top left corner (position
922 * <term>Graphics</term>
924 * Clears the entire window to its current background color. See <link
925 * linkend="chimara-The-Types-of-Windows#wintype-Graphics">Graphics
930 * <term>Other window types</term>
931 * <listitem><para>No effect.</para></listitem>
935 * It is illegal to erase a window which has line input pending.
938 glk_window_clear(winid_t win)
940 VALID_WINDOW(win, return);
941 g_return_if_fail(win->input_request_type != INPUT_REQUEST_LINE && win->input_request_type != INPUT_REQUEST_LINE_UNICODE);
943 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
952 case wintype_TextGrid:
953 /* fill the buffer with blanks */
955 /* Wait for the window's size to be updated */
956 g_mutex_lock(glk_data->arrange_lock);
957 if(glk_data->needs_rearrange)
958 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
959 g_mutex_unlock(glk_data->arrange_lock);
963 /* Manually put newlines at the end of each row of characters in the buffer; manual newlines make resizing the window's grid easier. */
964 gchar *blanks = g_strnfill(win->width, ' ');
965 gchar **blanklines = g_new0(gchar *, win->height + 1);
967 for(count = 0; count < win->height; count++)
968 blanklines[count] = blanks;
969 blanklines[win->height] = NULL;
970 gchar *text = g_strjoinv("\n", blanklines);
971 g_free(blanklines); /* not g_strfreev() */
974 GtkTextBuffer *textbuffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
975 gtk_text_buffer_set_text(textbuffer, text, -1);
978 GtkTextIter start, end;
979 gtk_text_buffer_get_start_iter(textbuffer, &start);
980 gtk_text_buffer_get_end_iter(textbuffer, &end);
982 /* Determine default style */
983 GtkTextTagTable *tags = gtk_text_buffer_get_tag_table(textbuffer);
984 GtkTextTag *default_tag = gtk_text_tag_table_lookup(tags, "default");
985 GtkTextTag *style_tag = gtk_text_tag_table_lookup(tags, "normal");
986 GtkTextTag *glk_style_tag = gtk_text_tag_table_lookup(tags, "normal");
989 gtk_text_buffer_apply_tag(textbuffer, default_tag, &start, &end);
991 // Player's style overrides
992 gtk_text_buffer_apply_tag(textbuffer, style_tag, &start, &end);
994 // GLK Program's style overrides
995 gtk_text_buffer_apply_tag(textbuffer, glk_style_tag, &start, &end);
997 if(win->zcolor != NULL)
998 gtk_text_buffer_apply_tag(textbuffer, win->zcolor, &start, &end);
1000 gtk_text_buffer_move_mark_by_name(textbuffer, "cursor_position", &start);
1002 gdk_threads_leave();
1006 case wintype_TextBuffer:
1007 /* delete all text in the window */
1009 gdk_threads_enter();
1011 GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
1012 GtkTextIter start, end;
1013 gtk_text_buffer_get_bounds(buffer, &start, &end);
1014 gtk_text_buffer_delete(buffer, &start, &end);
1016 gdk_threads_leave();
1020 case wintype_Graphics:
1022 GtkAllocation allocation;
1024 /* Wait for the window's size to be updated */
1025 g_mutex_lock(glk_data->arrange_lock);
1026 if(glk_data->needs_rearrange)
1027 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
1028 g_mutex_unlock(glk_data->arrange_lock);
1030 gdk_threads_enter();
1031 gtk_widget_get_allocation(win->widget, &allocation);
1032 gdk_threads_leave();
1034 glk_window_erase_rect(win, 0, 0, allocation.width, allocation.height);
1039 ILLEGAL_PARAM("Unknown window type: %d", win->type);
1045 * @win: A window, or %NULL.
1047 * Sets the current stream to @win's window stream. If @win is %NULL, it is
1049 * |[ glk_stream_set_current(NULL); ]|
1050 * If @win is not %NULL, it is equivalent to
1051 * |[ glk_stream_set_current(glk_window_get_stream(win)); ]|
1052 * See <link linkend="chimara-Streams">Streams</link>.
1055 glk_set_window(winid_t win)
1057 VALID_WINDOW_OR_NULL(win, return);
1059 glk_stream_set_current( glk_window_get_stream(win) );
1061 glk_stream_set_current(NULL);
1065 * glk_window_get_stream:
1068 * Returns the stream which is associated with @win. (See <link
1069 * linkend="chimara-Window-Streams">Window Streams</link>.) Every window has a
1070 * stream which can be printed to, but this may not be useful, depending on the
1074 * For example, printing to a blank window's stream has no effect.
1077 * Returns: A window stream.
1079 strid_t glk_window_get_stream(winid_t win)
1081 VALID_WINDOW(win, return NULL);
1082 return win->window_stream;
1086 * glk_window_set_echo_stream:
1088 * @str: A stream to attach to the window, or %NULL.
1090 * Sets @win's echo stream to @str, which can be any valid output stream. You
1091 * can reset a window to stop echoing by calling
1092 * <code>#glk_window_set_echo_stream(@win, %NULL)</code>.
1094 * It is illegal to set a window's echo stream to be its
1095 * <emphasis>own</emphasis> window stream. That would create an infinite loop,
1096 * and is nearly certain to crash the Glk library. It is similarly illegal to
1097 * create a longer loop (two or more windows echoing to each other.)
1100 glk_window_set_echo_stream(winid_t win, strid_t str)
1102 VALID_WINDOW(win, return);
1103 VALID_STREAM_OR_NULL(str, return);
1105 /* Test for an infinite loop */
1107 for(; next && next->type == STREAM_TYPE_WINDOW; next = next->window->echo_stream)
1109 if(next == win->window_stream)
1111 ILLEGAL("Infinite loop detected");
1112 win->echo_stream = NULL;
1117 win->echo_stream = str;
1121 * glk_window_get_echo_stream:
1124 * Returns the echo stream of window @win. Initially, a window has no echo
1125 * stream, so <code>#glk_window_get_echo_stream(@win)</code> will return %NULL.
1127 * Returns: A stream, or %NULL.
1130 glk_window_get_echo_stream(winid_t win)
1132 VALID_WINDOW(win, return NULL);
1133 return win->echo_stream;
1137 * glk_window_get_size:
1139 * @widthptr: Pointer to a location to store the window's width, or %NULL.
1140 * @heightptr: Pointer to a location to store the window's height, or %NULL.
1142 * Simply returns the actual size of the window, in its measurement system.
1143 * As described in <link linkend="chimara-Other-API-Conventions">Other API
1144 * Conventions</link>, either @widthptr or @heightptr can be %NULL, if you
1145 * only want one measurement.
1147 * <note><para>Or, in fact, both, if you want to waste time.</para></note>
1150 glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr)
1152 VALID_WINDOW(win, return);
1154 GtkAllocation allocation;
1155 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
1161 if(widthptr != NULL)
1163 if(heightptr != NULL)
1167 case wintype_TextGrid:
1168 /* Wait until the window's size is current */
1169 g_mutex_lock(glk_data->arrange_lock);
1170 if(glk_data->needs_rearrange)
1171 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
1172 g_mutex_unlock(glk_data->arrange_lock);
1174 gdk_threads_enter();
1175 gtk_widget_get_allocation(win->widget, &allocation);
1176 /* Cache the width and height */
1177 win->width = (glui32)(allocation.width / win->unit_width);
1178 win->height = (glui32)(allocation.height / win->unit_height);
1179 gdk_threads_leave();
1181 if(widthptr != NULL)
1182 *widthptr = win->width;
1183 if(heightptr != NULL)
1184 *heightptr = win->height;
1187 case wintype_TextBuffer:
1188 /* Wait until the window's size is current */
1189 g_mutex_lock(glk_data->arrange_lock);
1190 if(glk_data->needs_rearrange)
1191 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
1192 g_mutex_unlock(glk_data->arrange_lock);
1194 gdk_threads_enter();
1195 gtk_widget_get_allocation(win->widget, &allocation);
1196 if(widthptr != NULL)
1197 *widthptr = (glui32)(allocation.width / win->unit_width);
1198 if(heightptr != NULL)
1199 *heightptr = (glui32)(allocation.height / win->unit_height);
1200 gdk_threads_leave();
1204 case wintype_Graphics:
1205 g_mutex_lock(glk_data->arrange_lock);
1206 if(glk_data->needs_rearrange)
1207 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
1208 g_mutex_unlock(glk_data->arrange_lock);
1210 gdk_threads_enter();
1211 gtk_widget_get_allocation(win->widget, &allocation);
1212 if(widthptr != NULL)
1213 *widthptr = (glui32)(allocation.width);
1214 if(heightptr != NULL)
1215 *heightptr = (glui32)(allocation.height);
1216 gdk_threads_leave();
1221 ILLEGAL_PARAM("Unknown window type: %u", win->type);
1226 * glk_window_set_arrangement:
1227 * @win: a pair window to rearrange.
1228 * @method: new method of size computation. One of %winmethod_Above,
1229 * %winmethod_Below, %winmethod_Left, or %winmethod_Right OR'ed with
1230 * %winmethod_Fixed or %winmethod_Proportional.
1231 * @size: new size constraint, in percentage points if @method is
1232 * %winmethod_Proportional, otherwise in characters if @win's type is
1233 * %wintype_TextBuffer or %wintype_TextGrid, or pixels if @win's type is
1234 * %wintype_Graphics.
1235 * @keywin: new key window, or %NULL to leave the key window unchanged.
1237 * Changes the size of an existing split — that is, it changes the
1238 * constraint of a given pair window.
1240 * Consider the example above, where D has collapsed to zero height. Say D was a
1241 * text buffer window. You could make a more useful layout by doing
1244 * o2 = glk_window_get_parent(d);
1245 * glk_window_set_arrangement(o2, winmethod_Above | winmethod_Fixed, 3, d);
1247 * That would set D (the upper child of O2) to be O2's key window, and give it a
1248 * fixed size of 3 rows.
1250 * If you later wanted to expand D, you could do
1251 * |[ glk_window_set_arrangement(o2, winmethod_Above | winmethod_Fixed, 5, NULL); ]|
1252 * That expands D to five rows. Note that, since O2's key window is already set
1253 * to D, it is not necessary to provide the @keywin argument; you can pass %NULL
1254 * to mean <quote>leave the key window unchanged.</quote>
1256 * If you do change the key window of a pair window, the new key window
1257 * <emphasis>must</emphasis> be a descendant of that pair window. In the current
1258 * example, you could change O2's key window to be A, but not B. The key window
1259 * also cannot be a pair window itself.
1261 * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Fixed, 3, NULL); ]|
1262 * This changes the constraint to be on the <emphasis>lower</emphasis> child of
1263 * O2, which is A. The key window is still D; so A would then be three rows high
1264 * as measured in D's font, and D would get the rest of O2's space. That may not
1265 * be what you want. To set A to be three rows high as measured in A's font, you
1267 * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Fixed, 3, a); ]|
1269 * Or you could change O2 to a proportional split:
1270 * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Proportional, 30, NULL); ]|
1272 * |[ glk_window_set_arrangement(o2, winmethod_Above | winmethod_Proportional, 70, NULL); ]|
1273 * These do exactly the same thing, since 30% above is the same as
1274 * 70% below. You don't need to specify a key window with a proportional
1275 * split, so the @keywin argument is %NULL. (You could actually specify either A
1276 * or D as the key window, but it wouldn't affect the result.)
1278 * Whatever constraint you set, glk_window_get_size() will tell you the actual
1279 * window size you got.
1281 * Note that you can resize windows, and alter the Border/NoBorder flag. But you
1282 * can't flip or rotate them. You can't move A above D, or change O2 to a
1283 * vertical split where A is left or right of D.
1285 * To get this effect you could close one of the windows, and re-split the
1286 * other one with glk_window_open().
1290 glk_window_set_arrangement(winid_t win, glui32 method, glui32 size, winid_t keywin)
1292 VALID_WINDOW(win, return);
1293 VALID_WINDOW_OR_NULL(keywin, return);
1294 g_return_if_fail(win->type == wintype_Pair);
1297 g_return_if_fail(keywin->type != wintype_Pair);
1298 g_return_if_fail(g_node_is_ancestor(win->window_node, keywin->window_node));
1300 g_return_if_fail(method == (method & (winmethod_DirMask | winmethod_DivisionMask)));
1301 g_return_if_fail(!(((method & winmethod_DivisionMask) == winmethod_Proportional) && size > 100));
1303 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
1305 win->split_method = method;
1306 win->constraint_size = size;
1308 win->key_window = keywin;
1310 /* Tell GTK to rearrange the windows */
1311 gdk_threads_enter();
1312 g_mutex_lock(glk_data->arrange_lock);
1313 glk_data->needs_rearrange = TRUE;
1314 glk_data->ignore_next_arrange_event = TRUE;
1315 g_mutex_unlock(glk_data->arrange_lock);
1316 gtk_widget_queue_resize(GTK_WIDGET(glk_data->self));
1317 gdk_threads_leave();
1321 * glk_window_get_arrangement:
1322 * @win: a pair window.
1323 * @methodptr: return location for the constraint flags of @win, or %NULL.
1324 * @sizeptr: return location for the constraint size of @win, or %NULL.
1325 * @keywinptr: return location for the key window of @win, or %NULL.
1327 * Queries the constraint of a given pair window.
1330 glk_window_get_arrangement(winid_t win, glui32 *methodptr, glui32 *sizeptr, winid_t *keywinptr)
1332 VALID_WINDOW(win, return);
1333 g_return_if_fail(win->type == wintype_Pair);
1336 *methodptr = win->split_method;
1338 *sizeptr = win->constraint_size;
1340 *keywinptr = win->key_window;
1344 * glk_window_move_cursor:
1345 * @win: A text grid window.
1346 * @xpos: Horizontal cursor position.
1347 * @ypos: Vertical cursor position.
1349 * Sets the cursor position. If you move the cursor right past the end of a
1350 * line, it wraps; the next character which is printed will appear at the
1351 * beginning of the next line.
1353 * If you move the cursor below the last line, or when the cursor reaches the
1354 * end of the last line, it goes <quote>off the screen</quote> and further
1355 * output has no effect. You must call glk_window_move_cursor() or
1356 * glk_window_clear() to move the cursor back into the visible region.
1359 * Note that the arguments of glk_window_move_cursor() are <type>unsigned
1360 * int</type>s. This is okay, since there are no negative positions. If you try
1361 * to pass a negative value, Glk will interpret it as a huge positive value,
1362 * and it will wrap or go off the last line.
1366 * Also note that the output cursor is not necessarily visible. In particular,
1367 * when you are requesting line or character input in a grid window, you cannot
1368 * rely on the cursor position to prompt the player where input is indicated.
1369 * You should print some character prompt at that spot — a
1370 * <quote>></quote> character, for example.
1374 glk_window_move_cursor(winid_t win, glui32 xpos, glui32 ypos)
1376 VALID_WINDOW(win, return);
1377 g_return_if_fail(win->type == wintype_TextGrid);
1379 flush_window_buffer(win);
1381 ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
1383 /* Wait until the window's size is current */
1384 g_mutex_lock(glk_data->arrange_lock);
1385 if(glk_data->needs_rearrange)
1386 g_cond_wait(glk_data->rearranged, glk_data->arrange_lock);
1387 g_mutex_unlock(glk_data->arrange_lock);
1389 /* Don't do anything if the window is shrunk down to nothing */
1390 if(win->width == 0 || win->height == 0)
1393 /* Calculate actual position if cursor is moved past the right edge */
1394 if(xpos >= win->width)
1396 ypos += xpos / win->width;
1400 /* Go to the end if the cursor is moved off the bottom edge */
1401 if(ypos >= win->height)
1403 xpos = win->width - 1;
1404 ypos = win->height - 1;
1407 gdk_threads_enter();
1409 GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(win->widget) );
1411 /* There must actually be a character at xpos, or the following function will choke */
1412 gtk_text_buffer_get_iter_at_line_offset(buffer, &newpos, ypos, xpos);
1413 gtk_text_buffer_move_mark_by_name(buffer, "cursor_position", &newpos);
1415 gdk_threads_leave();