From 70990779c31c6d8a4e7c5c159a0926012721bd13 Mon Sep 17 00:00:00 2001 From: fliep Date: Sun, 3 May 2009 21:52:25 +0000 Subject: [PATCH] Added comments and cleaned up code --- src/window.c | 121 ++++++++++++++++++++------------------------------- 1 file changed, 47 insertions(+), 74 deletions(-) diff --git a/src/window.c b/src/window.c index 8922d8f..c1a79ee 100644 --- a/src/window.c +++ b/src/window.c @@ -541,80 +541,7 @@ glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype, return win; } -/** - * glk_window_close: - * @win: Window to close. - * @result: Pointer to a #stream_result_t in which to store the write count. - * - * Closes @win, which is pretty much exactly the opposite of opening a window. - * It is legal to close all your windows, or to close the root window (which is - * the same thing.) - * - * The @result argument is filled with the output character count of the window - * stream. See Streams and Closing Streams. - * - * When you close a window (and it is not the root window), the other window - * in its pair takes over all the freed-up area. Let's close D, in the current - * example: - * Screen shot 10 - * - * - * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right - * split has gone with it. The other size constraints are unchanged; O2 is - * still committed to giving its upper child two rows, as measured in the font - * of O2's key window, which is C. Conveniently, O2's upper child is C, just as - * it was before we created D. In fact, now that D is gone, everything is back - * to the way it was before we created D. - * - * But what if we had closed C instead of D? We would have gotten this: - * Screen shot 11 - * - * - * Again, O3 is gone. But D has collapsed to zero height. This is because its - * height is controlled by O2, and O2's key window was C, and C is now gone. O2 - * no longer has a key window at all, so it cannot compute a height for its - * upper child, so it defaults to zero. - * - * - * This may seem to be an inconvenient choice. That is deliberate. You should - * not leave a pair window with no key, and the zero-height default reminds - * you not to. You can use glk_window_set_arrangement() to set a new split - * measurement and key window. See Changing Window - * Constraints. - * - */ - -static void -dump_window_tree(GNode *node) -{ - if(node == NULL) { - g_printerr("NULL"); - return; - } - g_printerr("["); - switch(((winid_t)node->data)->type) { - case wintype_Pair: - g_printerr("Pair "); - dump_window_tree(node->children); - dump_window_tree(node->children->next); - g_printerr("]"); - break; - case wintype_TextBuffer: - g_printerr("Buffer]"); - break; - case wintype_TextGrid: - g_printerr("Grid]"); - break; - case wintype_Blank: - g_printerr("Blank]"); - break; - default: - g_printerr("Fucked up - %d]", ((winid_t)node->data)->type); - } -} - +/* Internal function: close the window streams of this window and all its children */ static void close_window_streams_below(winid_t win, stream_result_t *result) { @@ -625,6 +552,7 @@ close_window_streams_below(winid_t win, stream_result_t *result) stream_close_common(win->window_stream, result); } +/* Internal function: destroy this window's GTK widgets and those of all its children */ static void destroy_widgets_below(winid_t win) { @@ -655,6 +583,7 @@ destroy_widgets_below(winid_t win) } } +/* Internal function: free the winid_t structure of this window and those of all its children */ static void free_winids_below(winid_t win) { @@ -666,6 +595,50 @@ free_winids_below(winid_t win) g_free(win); } +/** + * glk_window_close: + * @win: Window to close. + * @result: Pointer to a #stream_result_t in which to store the write count. + * + * Closes @win, which is pretty much exactly the opposite of opening a window. + * It is legal to close all your windows, or to close the root window (which is + * the same thing.) + * + * The @result argument is filled with the output character count of the window + * stream. See Streams and Closing Streams. + * + * When you close a window (and it is not the root window), the other window + * in its pair takes over all the freed-up area. Let's close D, in the current + * example: + * Screen shot 10 + * + * + * Notice what has happened. D is gone. O3 is gone, and its 50-50 left-right + * split has gone with it. The other size constraints are unchanged; O2 is + * still committed to giving its upper child two rows, as measured in the font + * of O2's key window, which is C. Conveniently, O2's upper child is C, just as + * it was before we created D. In fact, now that D is gone, everything is back + * to the way it was before we created D. + * + * But what if we had closed C instead of D? We would have gotten this: + * Screen shot 11 + * + * + * Again, O3 is gone. But D has collapsed to zero height. This is because its + * height is controlled by O2, and O2's key window was C, and C is now gone. O2 + * no longer has a key window at all, so it cannot compute a height for its + * upper child, so it defaults to zero. + * + * + * This may seem to be an inconvenient choice. That is deliberate. You should + * not leave a pair window with no key, and the zero-height default reminds + * you not to. You can use glk_window_set_arrangement() to set a new split + * measurement and key window. See Changing Window + * Constraints. + * + */ void glk_window_close(winid_t win, stream_result_t *result) { -- 2.30.2