Commentaar toegevoegd aan code en tevens Gtk-Doc comments voor alle
authorfliep <fliep@ddfedd41-794f-dd11-ae45-00112f111e67>
Sat, 12 Jul 2008 19:40:23 +0000 (19:40 +0000)
committerfliep <fliep@ddfedd41-794f-dd11-ae45-00112f111e67>
Sat, 12 Jul 2008 19:40:23 +0000 (19:40 +0000)
officiele Glk functies, mochten we ooit documentatie willen uitspugen

src/glk.c
src/glk.h
src/stream.c
src/stream.h
src/window.c
src/window.h

index 885f36f86fc94007926f16adaea048c7365d751d..c41497f29f24f84477f7ea8ec3d48f0ca122a281 100644 (file)
--- a/src/glk.c
+++ b/src/glk.c
@@ -2,17 +2,24 @@
 
 #include "glk.h"
 
+/**
+ * glk_exit:
+ * 
+ * End the Glk program. As far as the client program is concerned, this
+ * function does not return.
+ */
 void
 glk_exit(void)
 {
        gtk_main();
 }
 
+/*
 void
 glk_select(event_t *event)
 {
        gtk_main_iteration();
 }
-
+*/
 
 
index e9947b3195abb63be01c0ca46c765ae28a10adf8..4daa97168c6f7a4a0327a92d5336f518729ccfc2 100644 (file)
--- a/src/glk.h
+++ b/src/glk.h
@@ -1,8 +1,6 @@
 #ifndef GLK_H
 #define GLK_H
 
-#include <gtk/gtk.h>
-
 /* glk.h: Header file for Glk API, version 0.7.0.
     Designed by Andrew Plotkin <erkyrath@eblong.com>
     http://www.eblong.com/zarf/glk/index.html
 /* You may have to edit the definition of glui32 to make sure it's really a
     32-bit unsigned integer type, and glsi32 to make sure it's really a
     32-bit signed integer type. If they're not, horrible things will happen. */
+#include <gtk/gtk.h>
 typedef guint32 glui32;
 typedef gint32 glsi32;
 
 /* These are the compile-time conditionals that reveal various Glk optional
     modules. */
-#define GLK_MODULE_UNICODE
-#define GLK_MODULE_IMAGE
-#define GLK_MODULE_SOUND
-#define GLK_MODULE_HYPERLINKS
+/* #define GLK_MODULE_UNICODE */
+/* #define GLK_MODULE_IMAGE */
+/* #define GLK_MODULE_SOUND */
+/* #define GLK_MODULE_HYPERLINKS */
 
 /* These types are opaque object identifiers. They're pointers to opaque
     C structures, which are defined differently by each library. */
index e5a532aec374a3fb69ba36307a706ab22f97c45f..e32fb6f47a628c7747206abfe3eb1816b5e998d0 100644 (file)
@@ -2,35 +2,50 @@
 
 /* Global current stream */
 static strid_t current_stream = NULL;
+/* List of streams currently in existence */
 static GList *stream_list = NULL;
 
+/* Internal function: create a window stream to go with window. */
 strid_t
 window_stream_new(winid_t window)
 {
-
+       /* Create stream and connect it to window */
        strid_t s = g_new0(struct glk_stream_struct, 1);
        s->file_mode = filemode_Write;
        s->stream_type = STREAM_TYPE_WINDOW;
        s->window = window;
-
+       /* Add it to the global stream list */
        stream_list = g_list_prepend(stream_list, s);
        s->stream_list = stream_list;
 
        return s;
 }
 
+/**
+ * glk_stream_set_current:
+ * @str: An output stream, or NULL.
+ *
+ * Sets the current stream to @str, or to nothing if @str is #NULL.
+ */
 void
-glk_stream_set_current(strid_t stream)
+glk_stream_set_current(strid_t str)
 {
-       if(stream->file_mode != filemode_Write)
+       if(str != NULL && str->file_mode != filemode_Write)
        {
-               g_warning("glk_stream_set_current: Cannot set current stream to non output stream");
+               g_warning("glk_stream_set_current: "
+                       "Cannot set current stream to non output stream");
                return;
        }
 
-       current_stream = stream;
+       current_stream = str;
 }
 
+/**
+ * glk_put_string:
+ * @s: A null-terminated string in Latin-1 encoding.
+ *
+ * Prints @s to the current stream.
+ */
 void
 glk_put_string(char *s)
 {
@@ -44,11 +59,15 @@ glk_put_string(char *s)
 
                        if(utf8 == NULL)
                        {
-                               g_warning("glk_put_string: Error during latin1->utf8 conversion: %s", error->message);
+                               g_warning("glk_put_string: "
+                                       "Error during latin1->utf8 conversion: %s", 
+                                       error->message);
                                g_error_free(error);
+                               return;
                        }
 
-                       GtkTextBuffer *buffer = gtk_text_view_get_buffer( GTK_TEXT_VIEW(current_stream->window->widget) );
+                       GtkTextBuffer *buffer = gtk_text_view_get_buffer( 
+                               GTK_TEXT_VIEW(current_stream->window->widget) );
 
                        GtkTextIter iter;
                        gtk_text_buffer_get_end_iter(buffer, &iter);
@@ -58,6 +77,7 @@ glk_put_string(char *s)
                        g_free(utf8);
                        break;
                default:
-                       g_warning("glk_put_string: Writing to this kind of stream unsupported.");       
+                       g_warning("glk_put_string: "
+                               "Writing to this kind of stream unsupported."); 
        }
 }
index fb7eb8f7bc53814a376d897318bfa044315924b1..3fd4fcba07717fee0ec1b74f890d4cb0a31811a2 100644 (file)
@@ -11,25 +11,28 @@ enum StreamType
        STREAM_TYPE_MEMORY,
        STREAM_TYPE_FILE,
        STREAM_TYPE_UNICODE_MEMORY,
-       STREAM_TYPE_UNICODE_FILE,
+       STREAM_TYPE_UNICODE_FILE
 };
 
 struct glk_stream_struct
 {
-       GList* stream_list;
-
        glui32 rock;
+       /* Pointer to the list node in the global stream list that contains this
+       stream */
+       GList* stream_list;
+       /* Stream parameters */
        glui32 file_mode;
        glui32 read_count;
        glui32 write_count;
        enum StreamType stream_type;
+       /* Specific to window stream: the window this stream is connected to */
        winid_t window;
+       /* Specific to memory streams */
        gchar *memory_buffer;
        glui32 *memory_buffer_unicode;
        glui32 buffer_len;
 };
 
-
 strid_t window_stream_new(winid_t window);
 
 #endif
index 11e604dad50caea1d96e46d778926018663ae212..cfa066cf94b3a822a84d59ebe05a45f1e2ef9b8b 100644 (file)
@@ -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;
 }
+
index 4e705f2d69822bbf14a510b6691974d7e237a151..02afe78e377ac505e8c20fb6a390614427dfc6dd 100644 (file)
@@ -18,13 +18,15 @@ enum InputRequestType
 
 struct glk_window_struct
 {
-       GNode *window_node;
-
        glui32 rock;
+       /* Pointer to the node in the global tree that contains this window */
+       GNode *window_node;
+       /* Window parameters */
        glui32 window_type;
        GtkWidget *widget;
        strid_t window_stream;
        strid_t echo_stream;
+       /* Input request stuff */
        enum InputRequestType input_request_type;
        gchar *line_input_buffer;
        glui32 *line_input_buffer_unicode;