From 1c04c8a0a43723e3de4a7f495b76cb26fd93e0c4 Mon Sep 17 00:00:00 2001
From: Philip Chimento <philip.chimento@gmail.com>
Date: Fri, 30 Apr 2010 23:20:44 +0000
Subject: [PATCH] Added some explanatory documentation to ChimaraGlk and
 ChimaraIF

git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@253 ddfedd41-794f-dd11-ae45-00112f111e67
---
 libchimara/chimara-glk.c | 68 +++++++++++++++++++++++++++++++++++++++-
 libchimara/chimara-if.c  |  8 ++++-
 2 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/libchimara/chimara-glk.c b/libchimara/chimara-glk.c
index f561770..f0d946d 100644
--- a/libchimara/chimara-glk.c
+++ b/libchimara/chimara-glk.c
@@ -30,7 +30,7 @@
  * SECTION:chimara-glk
  * @short_description: Widget which executes a Glk program
  * @stability: Unstable
- * @include: chimara/chimara-glk.h
+ * @include: libchimara/chimara-glk.h
  * 
  * The #ChimaraGlk widget opens and runs a Glk program. The program must be
  * compiled as a plugin module, with a function <function>glk_main()</function>
@@ -49,6 +49,72 @@
  * <ulink 
  * url="http://www.gnu.org/software/libtool/manual/html_node/Finding-the-dlname.html">
  * Libtool manual</ulink>).
+ *
+ * You need to initialize multithreading in any program you use a #ChimaraGlk
+ * widget in. This means including the following incantation at the beginning
+ * of your program:
+ * |[
+ * if(!g_thread_supported())
+ *     g_thread_init(NULL);
+ * gdk_threads_init();
+ * ]|
+ * This initialization must take place <emphasis>before</emphasis> the call to
+ * gtk_init(). In addition to this, you must also protect your call to 
+ * gtk_main() by calling gdk_threads_enter() right before it, and 
+ * gdk_threads_leave() right after it.
+ *
+ * The following sample program shows how to initialize and construct a simple 
+ * GTK window that runs a Glk program:
+ * |[
+ * #include <glib.h>
+ * #include <gtk/gtk.h>
+ * #include <libchimara/chimara-glk.h>
+ *
+ * static gboolean
+ * quit(void)
+ * {
+ *     gtk_main_quit();
+ *     return TRUE;
+ * }
+ *
+ * int
+ * main(int argc, char *argv[])
+ * {
+ *     GtkWidget *window, *glk;
+ *     GError *error = NULL;
+ *     gchar *plugin_argv[] = { "plugin.so", "-option" };
+ *
+ *     /<!---->* Initialize threads and GTK *<!---->/
+ *     if(!g_thread_supported())
+ *         g_thread_init(NULL);
+ *     gdk_threads_init();
+ *     gtk_init(&argc, &argv);
+ *     
+ *     /<!---->* Construct the window and its contents. We quit the GTK main loop
+ *      * when the window's close button is clicked. *<!---->/
+ *     window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
+ *     g_signal_connect(window, "delete-event", G_CALLBACK(quit), NULL);
+ *     glk = chimara_glk_new();
+ *     gtk_container_add(GTK_CONTAINER(window), glk);
+ *     gtk_widget_show_all(window);
+ *     
+ *     /<!---->* Start the Glk program in a separate thread *<!---->/
+ *     if(!chimara_glk_run(CHIMARA_GLK(glk), "./plugin.so", 2, plugin_argv, &error))
+ *         g_error("Error starting Glk library: %s\n", error->message);
+ *     
+ *     /<!---->* Start the GTK main loop *<!---->/
+ *     gdk_threads_enter();
+ *     gtk_main();
+ *     gdk_threads_leave();
+ *
+ *     /<!---->* After the GTK main loop exits, signal the Glk program to shut down if
+ *      * it is still running, and wait for it to exit. *<!---->/
+ *     chimara_glk_stop(CHIMARA_GLK(glk));
+ *     chimara_glk_wait(CHIMARA_GLK(glk));
+ *
+ *     return 0;
+ * }
+ * ]|
  */
 
 typedef void (* glk_main_t) (void);
diff --git a/libchimara/chimara-if.c b/libchimara/chimara-if.c
index 7b91830..cb0f425 100644
--- a/libchimara/chimara-if.c
+++ b/libchimara/chimara-if.c
@@ -13,11 +13,17 @@
  * SECTION:chimara-if
  * @short_description: Widget which plays an interactive fiction game
  * @stability: Unstable
- * @include: chimara/chimara-if.h
+ * @include: libchimara/chimara-if.h
  *
  * The #ChimaraIF widget, given an interactive fiction game file to run, selects
  * an appropriate interpreter plugin and runs it. Interpreter options are set by
  * setting properties on the widget.
+ *
+ * Using it in a GTK program is similar to using #ChimaraGlk (which see). 
+ * Threads must be initialized before using #ChimaraIF and the call to 
+ * gtk_main() must be bracketed between gdk_threads_enter() and 
+ * gdk_threads_leave(). Use chimara_if_run_game() to start playing an
+ * interactive fiction game.
  */
 
 static gboolean supported_formats[CHIMARA_IF_NUM_FORMATS][CHIMARA_IF_NUM_INTERPRETERS] = {
-- 
2.30.2