From b82a2337120f77f26cf3528a78ce64e55390a23f Mon Sep 17 00:00:00 2001 From: fliep Date: Fri, 30 Apr 2010 23:20:44 +0000 Subject: [PATCH] Added some explanatory documentation to ChimaraGlk and ChimaraIF --- 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 glk_main() @@ -49,6 +49,72 @@ * * Libtool manual). + * + * 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 before 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 + * #include + * #include + * + * 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