X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fchimara-glk.c;h=f0d946d87a9f7be77df5c74cdb51d08dd1e0d84d;hb=510af770653094e2740bb693e269ae04864651f7;hp=dbd89c2cd5c21567f61e652030f10e83409cd7bc;hpb=ae1a5770d142aa0900f1a4d4c7e7732a38aaafa9;p=rodin%2Fchimara.git
diff --git a/libchimara/chimara-glk.c b/libchimara/chimara-glk.c
index dbd89c2..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);
@@ -714,7 +780,8 @@ chimara_glk_class_init(ChimaraGlkClass *klass)
*
* Sets whether the widget is interactive. A Glk widget is normally
* interactive, but in non-interactive mode, keyboard and mouse input are
- * ignored and the Glk program is controlled by chimara_glk_feed_text().
+ * ignored and the Glk program is controlled by
+ * chimara_glk_feed_char_input() and chimara_glk_feed_line_input().
* 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.
@@ -862,6 +929,9 @@ chimara_glk_get_protect(ChimaraGlk *glk)
* @glk: a #ChimaraGlk widget
*
* Resets the styles for text buffer and text grid windows to their defaults.
+ *
+ * This function is not implemented yet.
+ *
*/
void
chimara_glk_set_css_to_default(ChimaraGlk *glk)
@@ -873,8 +943,8 @@ chimara_glk_set_css_to_default(ChimaraGlk *glk)
* chimara_glk_set_css_from_file:
* @glk: a #ChimaraGlk widget
* @filename: path to a CSS file, or %NULL
- * @error: location to store a GError, or
- * %NULL
+ * @error: location to store a GError, or %NULL
*
* Sets the styles for text buffer and text grid windows according to the CSS
* file @filename. Note that the styles are set cumulatively on top of whatever
@@ -918,12 +988,12 @@ chimara_glk_set_css_from_file(ChimaraGlk *glk, const gchar *filename, GError **e
/**
* chimara_glk_set_css_from_string:
* @glk: a #ChimaraGlk widget
- * @filename: a string containing CSS code
+ * @css: a string containing CSS code
*
- * Sets the styles for text buffer and text grid windows according to @css. Note
- * that the styles are set cumulatively on top of whatever the styles are at the
- * time this function is called; to reset the styles to their defaults, use
- * chimara_glk_set_css_to_default().
+ * Sets the styles for text buffer and text grid windows according to the CSS
+ * code @css. Note that the styles are set cumulatively on top of whatever the
+ * styles are at the time this function is called; to reset the styles to their
+ * defaults, use chimara_glk_set_css_to_default().
*/
void
chimara_glk_set_css_from_string(ChimaraGlk *glk, const gchar *css)
@@ -1028,8 +1098,8 @@ glk_enter(struct StartupData *startup)
* class="header">glk.h
* @argc: Number of command line arguments in @argv
* @argv: Array of command line arguments to pass to the plugin
- * @error: location to store a GError, or
- * %NULL
+ * @error: location to store a GError, or %NULL
*
* Opens a Glk program compiled as a plugin. Sorts out its command line
* arguments from #glkunix_arguments, calls its startup function