X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=src%2Fwindow.c;h=cfa066cf94b3a822a84d59ebe05a45f1e2ef9b8b;hb=0b8b3b9c20937f7b522274ad83739816d8ef21e3;hp=11e604dad50caea1d96e46d778926018663ae212;hpb=199d247c0c2155c1c8fca97fcc6087efdd29e482;p=rodin%2Fchimara.git

diff --git a/src/window.c b/src/window.c
index 11e604d..cfa066c 100644
--- a/src/window.c
+++ b/src/window.c
@@ -1,10 +1,34 @@
 #include "window.h"
 
-/* Global list of all windows */
+/* Global tree of all windows */
 static GNode *root_window = NULL;
 
+/**
+ * glk_window_open:
+ * @split: The window to split to create the new window. Must be 0 if there
+ * are no windows yet.
+ * @method: Position of the new window and method of size computation. One of
+ * #winmethod_Above, #winmethod_Below, #winmethod_Left, or #winmethod_Right
+ * OR'ed with #winmethod_Fixed or #winmethod_Proportional. If @wintype is
+ * #wintype_Blank, then #winmethod_Fixed is not allowed.
+ * @size: Size of the new window, in percentage points if @method is
+ * #winmethod_Proportional, otherwise in characters if @wintype is 
+ * #wintype_TextBuffer or #wintype_TextGrid, or pixels if @wintype is
+ * #wintype_Graphics.
+ * @wintype: Type of the new window. One of #wintype_Blank, #wintype_TextGrid,
+ * #wintype_TextBuffer, or #wintype_Graphics.
+ * @rock: The new window's rock value.
+ *
+ * If there are no windows, create a new root window. @split must be 0, and
+ * @method and @size are ignored. Otherwise, split window @split into two, with
+ * position, size, and type specified by @method, @size, and @wintype. See the
+ * Glk documentation for the window placement algorithm.
+ *
+ * Returns: the new window.
+ */
 winid_t
-glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype, glui32 rock)
+glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype, 
+                glui32 rock)
 {
 	extern GtkBuilder *builder;
 
@@ -19,7 +43,7 @@ glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype, glui3
 		g_warning("glk_window_open: there is already a window");
 		return NULL;
 	}
-
+	/* We only create one window and don't support any more than that */
 	winid_t new_window = g_new0(struct glk_window_struct, 1);
 	root_window = g_node_new(new_window);
 
@@ -37,6 +61,7 @@ glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype, glui3
 	{
 		case wintype_TextBuffer:
 		{
+			/* We need to put these declarations inside their own scope */
 			GtkWidget *scroll_window = gtk_scrolled_window_new(NULL, NULL);
 			GtkWidget *window = gtk_text_view_new();
 			gtk_container_add( GTK_CONTAINER(scroll_window), window );
@@ -50,7 +75,6 @@ glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype, glui3
 			new_window->line_input_buffer = NULL;
 			new_window->line_input_buffer_unicode = NULL;
 		}
-
 			break;
 		default:
 			g_warning("glk_window_open: unsupported window type");
@@ -63,13 +87,28 @@ glk_window_open(winid_t split, glui32 method, glui32 size, glui32 wintype, glui3
 	return new_window;
 }
 
+/**
+ * glk_set_window:
+ * @win: A window.
+ *
+ * Sets the current stream to @win's window stream.
+ */
 void
-glk_set_window(winid_t window)
+glk_set_window(winid_t win)
 {
-	glk_stream_set_current( glk_window_get_stream(window) );
+	glk_stream_set_current( glk_window_get_stream(win) );
 }
 
-strid_t glk_window_get_stream(winid_t window)
+/**
+ * glk_window_get_stream:
+ * @win: A window.
+ *
+ * Gets the stream associated with @win.
+ *
+ * Returns: The window stream.
+ */
+strid_t glk_window_get_stream(winid_t win)
 {
-	return window->window_stream;
+	return win->window_stream;
 }
+