From: fliep Date: Mon, 29 Dec 2008 22:46:02 +0000 (+0000) Subject: Added gtk-doc comments to the ChimaraGlk widget. X-Git-Tag: v0.9~446 X-Git-Url: https://git.stderr.nl/gitweb?a=commitdiff_plain;ds=inline;h=d0d426fe52bd4bed53f13a4740c153648d68ac21;p=projects%2Fchimara%2Fchimara.git Added gtk-doc comments to the ChimaraGlk widget. --- diff --git a/src/chimara-glk.c b/src/chimara-glk.c index 3580623..5a62517 100644 --- a/src/chimara-glk.c +++ b/src/chimara-glk.c @@ -236,6 +236,13 @@ chimara_glk_class_init(ChimaraGlkClass *klass) /* PUBLIC FUNCTIONS */ +/** + * chimara_glk_new: + * + * Creates and initializes a new #ChimaraGlk widget. + * + * Return value: a #ChimaraGlk widget, with a floating reference. + */ GtkWidget * chimara_glk_new(void) { @@ -251,6 +258,18 @@ chimara_glk_new(void) return GTK_WIDGET(self); } +/** + * chimara_glk_set_interactive: + * @glk: a #ChimaraGlk widget + * @interactive: whether the widget should expect user input + * + * Sets the #ChimaraGlk:interactive property of @glk. A Glk widget is normally + * interactive, but in non-interactive mode, keyboard and mouse input is ignored + * and the Glk program is controlled by chimara_glk_feed_text(). "More" prompts + * when a lot of text is printed to a text buffer are also disabled. This is + * typically used when you wish to control an interpreter program by feeding it + * a predefined list of commands. + */ void chimara_glk_set_interactive(ChimaraGlk *glk, gboolean interactive) { @@ -260,6 +279,15 @@ chimara_glk_set_interactive(ChimaraGlk *glk, gboolean interactive) priv->interactive = interactive; } +/** + * chimara_glk_get_interactive: + * @glk: a #ChimaraGlk widget + * + * Returns whether @glk is interactive (expecting user input). See + * chimara_glk_set_interactive(). + * + * Return value: %TRUE if @glk is interactive. + */ gboolean chimara_glk_get_interactive(ChimaraGlk *glk) { @@ -269,6 +297,15 @@ chimara_glk_get_interactive(ChimaraGlk *glk) return priv->interactive; } +/** + * chimara_glk_set_protect: + * @glk: a #ChimaraGlk widget + * @protect: whether the widget should allow the Glk program to do file + * operations + * + * Sets the #ChimaraGlk:protect property of @glk. In protect mode, the Glk + * program is not allowed to do file operations. + */ void chimara_glk_set_protect(ChimaraGlk *glk, gboolean protect) { @@ -278,6 +315,15 @@ chimara_glk_set_protect(ChimaraGlk *glk, gboolean protect) priv->protect = protect; } +/** + * chimara_glk_get_protect: + * @glk: a #ChimaraGlk widget + * + * Returns whether @glk is in protect mode (banned from doing file operations). + * See chimara_glk_set_protect(). + * + * Return value: %TRUE if @glk is in protect mode. + */ gboolean chimara_glk_get_protect(ChimaraGlk *glk) { @@ -298,6 +344,17 @@ glk_enter(gpointer glk_main) return NULL; } +/** + * chimara_glk_run: + * @glk: a #ChimaraGlk widget + * @plugin: path to a plugin module compiled with glk.h + * @error: location to store a #GError, or %NULL + * + * Opens a Glk program compiled as a plugin and runs its glk_main() function in + * a separate thread. On failure, returns %FALSE and sets @error. + * + * Return value: %TRUE if the Glk program was started successfully. + */ gboolean chimara_glk_run(ChimaraGlk *glk, gchar *plugin, GError **error) { @@ -333,17 +390,34 @@ chimara_glk_run(ChimaraGlk *glk, gchar *plugin, GError **error) return !(priv->thread == NULL); } +/** + * chimara_glk_stop: + * @glk: a #ChimaraGlk widget + * + * Signals the Glk program running in @glk to abort. Note that if the program is + * caught in an infinite loop in which glk_tick() is not called, this may not + * work. + */ void chimara_glk_stop(ChimaraGlk *glk) { g_return_if_fail(glk || CHIMARA_IS_GLK(glk)); - + /* TODO: check if glk is actually running a program */ signal_abort(); } +/** + * chimara_glk_wait: + * @glk: a #ChimaraGlk widget + * + * Holds up the main thread and waits for the Glk program running in @glk to + * finish. + */ void chimara_glk_wait(ChimaraGlk *glk) { + g_return_if_fail(glk || CHIMARA_IS_GLK(glk)); + ChimaraGlkPrivate *priv = CHIMARA_GLK_PRIVATE(glk); g_thread_join(priv->thread); } \ No newline at end of file diff --git a/src/window.h b/src/window.h index 6f83744..3395bb4 100644 --- a/src/window.h +++ b/src/window.h @@ -42,6 +42,7 @@ struct glk_window_struct glui32 *line_input_buffer_unicode; glui32 line_input_buffer_max_len; gboolean mouse_input_requested; + /* Signal handlers */ gulong keypress_handler; gulong insert_text_handler; };