From d723ff5bb5fbb4d93723e8814a44179ef75e20e7 Mon Sep 17 00:00:00 2001 From: fliep Date: Sat, 12 Jul 2008 19:40:23 +0000 Subject: [PATCH] Commentaar toegevoegd aan code en tevens Gtk-Doc comments voor alle officiele Glk functies, mochten we ooit documentatie willen uitspugen --- src/glk.c | 9 ++++++++- src/glk.h | 11 +++++------ src/stream.c | 38 +++++++++++++++++++++++++++--------- src/stream.h | 11 +++++++---- src/window.c | 55 ++++++++++++++++++++++++++++++++++++++++++++-------- src/window.h | 6 ++++-- 6 files changed, 100 insertions(+), 30 deletions(-) diff --git a/src/glk.c b/src/glk.c index 885f36f..c41497f 100644 --- 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(); } - +*/ diff --git a/src/glk.h b/src/glk.h index e9947b3..4daa971 100644 --- a/src/glk.h +++ b/src/glk.h @@ -1,8 +1,6 @@ #ifndef GLK_H #define GLK_H -#include - /* glk.h: Header file for Glk API, version 0.7.0. Designed by Andrew Plotkin http://www.eblong.com/zarf/glk/index.html @@ -19,15 +17,16 @@ /* 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 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. */ diff --git a/src/stream.c b/src/stream.c index e5a532a..e32fb6f 100644 --- a/src/stream.c +++ b/src/stream.c @@ -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."); } } diff --git a/src/stream.h b/src/stream.h index fb7eb8f..3fd4fcb 100644 --- a/src/stream.h +++ b/src/stream.h @@ -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 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; } + diff --git a/src/window.h b/src/window.h index 4e705f2..02afe78 100644 --- a/src/window.h +++ b/src/window.h @@ -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; -- 2.30.2