* 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>
* <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);
PROP_INTERACTIVE,
PROP_PROTECT,
PROP_SPACING,
+ PROP_PROGRAM_NAME,
+ PROP_PROGRAM_INFO,
+ PROP_STORY_NAME
};
enum {
priv->resource_loaded = g_cond_new();
priv->resource_info_available = g_cond_new();
priv->image_cache = NULL;
+ priv->program_name = NULL;
+ priv->program_info = NULL;
+ priv->story_name = NULL;
priv->interrupt_handler = NULL;
priv->root_window = NULL;
priv->fileref_list = NULL;
case PROP_SPACING:
g_value_set_uint(value, priv->spacing);
break;
- default:
+ case PROP_PROGRAM_NAME:
+ g_value_set_string(value, priv->program_name);
+ break;
+ case PROP_PROGRAM_INFO:
+ g_value_set_string(value, priv->program_info);
+ break;
+ case PROP_STORY_NAME:
+ g_value_set_string(value, priv->story_name);
+ break;
+ default:
G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
}
}
/* Free other stuff */
g_free(priv->current_dir);
+ g_free(priv->program_name);
+ g_free(priv->program_info);
+ g_free(priv->story_name);
/* Chain up to parent */
G_OBJECT_CLASS(chimara_glk_parent_class)->finalize(object);
{
CHIMARA_GLK_USE_PRIVATE(self, priv);
priv->running = FALSE;
+ priv->program_name = NULL;
+ g_object_notify(G_OBJECT(self), "program-name");
+ priv->program_info = NULL;
+ g_object_notify(G_OBJECT(self), "program-info");
+ priv->story_name = NULL;
+ g_object_notify(G_OBJECT(self), "story-name");
}
static void
chimara_glk_signals[CHAR_INPUT] = g_signal_new("char-input",
G_OBJECT_CLASS_TYPE(klass), 0,
G_STRUCT_OFFSET(ChimaraGlkClass, char_input), NULL, NULL,
- chimara_marshal_VOID__UINT_UINT,
+ _chimara_marshal_VOID__UINT_UINT,
G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_UINT);
/**
* ChimaraGlk::line-input:
chimara_glk_signals[LINE_INPUT] = g_signal_new("line-input",
G_OBJECT_CLASS_TYPE(klass), 0,
G_STRUCT_OFFSET(ChimaraGlkClass, line_input), NULL, NULL,
- chimara_marshal_VOID__UINT_STRING,
+ _chimara_marshal_VOID__UINT_STRING,
G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING);
/**
* ChimaraGlk::text-buffer-output:
chimara_glk_signals[TEXT_BUFFER_OUTPUT] = g_signal_new("text-buffer-output",
G_OBJECT_CLASS_TYPE(klass), 0,
G_STRUCT_OFFSET(ChimaraGlkClass, text_buffer_output), NULL, NULL,
- chimara_marshal_VOID__UINT_STRING,
+ _chimara_marshal_VOID__UINT_STRING,
G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING);
/* Properties */
0, G_MAXUINT, 0,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_LAX_VALIDATION | G_PARAM_STATIC_STRINGS) );
- /* Private data */
+ /**
+ * ChimaraGlk:program-name:
+ *
+ * The name of the currently running Glk program. You cannot set this
+ * property yourself. It is set to the filename of the plugin when you call
+ * chimara_glk_run(), but the plugin can change it by calling
+ * garglk_set_program_name(). To find out when this information changes,
+ * for example to put the program name in the title bar of a window, connect
+ * to the <code>::notify::program-name</code> signal.
+ */
+ g_object_class_install_property(object_class, PROP_PROGRAM_NAME,
+ g_param_spec_string("program-name", _("Program name"),
+ _("Name of the currently running program"),
+ NULL,
+ G_PARAM_READABLE | G_PARAM_STATIC_STRINGS) );
+
+ /**
+ * ChimaraGlk:program-info:
+ *
+ * Information about the currently running Glk program. You cannot set this
+ * property yourself. The plugin can change it by calling
+ * garglk_set_program_info(). See also #ChimaraGlk:program-name.
+ */
+ g_object_class_install_property(object_class, PROP_PROGRAM_INFO,
+ g_param_spec_string("program-info", _("Program info"),
+ _("Information about the currently running program"),
+ NULL,
+ G_PARAM_READABLE | G_PARAM_STATIC_STRINGS) );
+
+ /**
+ * ChimaraGlk:story-name:
+ *
+ * The name of the story currently running in the Glk interpreter. You
+ * cannot set this property yourself. It is set to the story filename when
+ * you call chimara_if_run_game(), but the plugin can change it by calling
+ * garglk_set_story_name().
+ *
+ * Strictly speaking, this should be a property of #ChimaraIF, but it is
+ * legal for any Glk program to call garglk_set_story_name(), even if it is
+ * not an interpreter and does not load story files.
+ */
+ g_object_class_install_property(object_class, PROP_STORY_NAME,
+ g_param_spec_string("story-name", _("Story name"),
+ _("Name of the story currently loaded in the interpreter"),
+ NULL,
+ G_PARAM_READABLE | G_PARAM_STATIC_STRINGS) );
+
+ /* Private data */
g_type_class_add_private(klass, sizeof(ChimaraGlkPrivate));
}
startup->args.argv = g_new0(gchar *, 1);
}
- /* Set the program name */
+ /* Set the program invocation name */
startup->args.argv[0] = g_strdup(plugin);
}
startup->glk_data = priv;
+ /* Set the program name */
+ priv->program_name = g_path_get_basename(plugin);
+ g_object_notify(G_OBJECT(glk), "program-name");
+
/* Run in a separate thread */
priv->thread = g_thread_create((GThreadFunc)glk_enter, startup, TRUE, error);
projects / rodin / chimara.git / blobdiff