From 9954832f5d51d217e4fd3c28cddedc85bb158d35 Mon Sep 17 00:00:00 2001 From: fliep Date: Fri, 23 Oct 2009 23:09:57 +0000 Subject: [PATCH] Wrote documentation for new functions --- docs/reference/chimara-docs.sgml | 1 + docs/reference/chimara-sections.txt | 28 +++- libchimara/chimara-glk.c | 60 ++++++-- libchimara/chimara-glk.h | 24 ++++ libchimara/chimara-if.c | 204 ++++++++++++++++++++++++++-- libchimara/chimara-if.h | 22 +++ 6 files changed, 319 insertions(+), 20 deletions(-) diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml index 1f8cf2d..412d6a0 100644 --- a/docs/reference/chimara-docs.sgml +++ b/docs/reference/chimara-docs.sgml @@ -16,6 +16,7 @@ Chimara API Reference + diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt index f933b2d..51b9c62 100644 --- a/docs/reference/chimara-sections.txt +++ b/docs/reference/chimara-sections.txt @@ -2,6 +2,9 @@ chimara-glk ChimaraGlk ChimaraGlk +ChimaraError +CHIMARA_ERROR +chimara_error_quark chimara_glk_new chimara_glk_set_interactive chimara_glk_get_interactive @@ -18,8 +21,8 @@ chimara_glk_get_spacing chimara_glk_run chimara_glk_stop chimara_glk_wait +chimara_glk_get_running -ChimaraGlkClass CHIMARA_GLK CHIMARA_IS_GLK CHIMARA_TYPE_GLK @@ -29,6 +32,29 @@ CHIMARA_IS_GLK_CLASS CHIMARA_GLK_GET_CLASS +
+chimara-if +ChimaraIFFormat +ChimaraIFInterpreter +ChimaraIFZmachineVersion +ChimaraIF +ChimaraIF +chimara_if_new +chimara_if_set_preferred_interpreter +chimara_if_get_preferred_interpreter +chimara_if_run_game +chimara_if_get_format +chimara_if_get_interpreter + +CHIMARA_IF +CHIMARA_IS_IF +CHIMARA_TYPE_IF +chimara_if_get_type +CHIMARA_IF_CLASS +CHIMARA_IS_IF_CLASS +CHIMARA_IF_GET_CLASS +
+
glk-exiting Exiting Your Program diff --git a/libchimara/chimara-glk.c b/libchimara/chimara-glk.c index eae3988..45031d9 100644 --- a/libchimara/chimara-glk.c +++ b/libchimara/chimara-glk.c @@ -25,7 +25,7 @@ * @stability: Unstable * @include: chimara/chimara-glk.h * - * The ChimaraGlk widget opens and runs a Glk program. The program must be + * The #ChimaraGlk widget opens and runs a Glk program. The program must be * compiled as a plugin module, with a function glk_main() * that the Glk library can hook into. * @@ -179,14 +179,14 @@ chimara_glk_finalize(GObject *object) g_mutex_unlock(priv->event_lock); g_mutex_free(priv->event_lock); - /* Free the abort signalling mechanism */ + /* Free the abort signaling mechanism */ g_mutex_lock(priv->abort_lock); /* Make sure no other thread is busy with this */ g_mutex_unlock(priv->abort_lock); g_mutex_free(priv->abort_lock); priv->abort_lock = NULL; - /* Free the window arrangement signalling */ + /* Free the window arrangement signaling */ g_mutex_lock(priv->arrange_lock); g_cond_free(priv->rearranged); g_mutex_unlock(priv->arrange_lock); @@ -610,8 +610,8 @@ chimara_glk_class_init(ChimaraGlkClass *klass) * ChimaraGlk::stopped: * @glk: The widget that received the signal * - * The ::stopped signal is emitted when the a Glk program finishes - * executing in the widget, whether it ended normally, or was interrupted. + * Emitted when the a Glk program finishes executing in the widget, whether + * it ended normally, or was interrupted. */ chimara_glk_signals[STOPPED] = g_signal_new("stopped", G_OBJECT_CLASS_TYPE(klass), 0, @@ -622,31 +622,60 @@ chimara_glk_class_init(ChimaraGlkClass *klass) * ChimaraGlk::started: * @glk: The widget that received the signal * - * The ::started signal is emitted when a Glk program starts executing in - * the widget. + * Emitted when a Glk program starts executing in the widget. */ chimara_glk_signals[STARTED] = g_signal_new ("started", G_OBJECT_CLASS_TYPE(klass), 0, G_STRUCT_OFFSET(ChimaraGlkClass, started), NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); - + /** + * ChimaraGlk::waiting: + * @glk: The widget that received the signal + * + * Emitted when glk_select() is called by the Glk program and the event + * queue is empty, which means that the widget is waiting for input. + */ chimara_glk_signals[WAITING] = g_signal_new("waiting", G_OBJECT_CLASS_TYPE(klass), 0, G_STRUCT_OFFSET(ChimaraGlkClass, waiting), NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); - + /** + * ChimaraGlk::char-input: + * @glk: The widget that received the signal + * @window_rock: The rock value of the window that received character input + * (see Rocks) + * @keysym: The key that was typed, in the form of a key symbol from + * gdk/gdkkeysyms.h + * + * Emitted when a Glk window receives character input. + */ 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, G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_UINT); - + /** + * ChimaraGlk::line-input: + * @glk: The widget that received the signal + * @window_rock: The rock value of the window that received line input (see + * Rocks) + * @text: The text that was typed + * + * Emitted when a Glk window receives 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, G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING); - + /** + * ChimaraGlk::text-buffer-output: + * @glk: The widget that received the signal + * @window_rock: The rock value of the window that was printed to (see Rocks) + * + * Emitted when text is printed to a text buffer window. + */ 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, @@ -1146,6 +1175,15 @@ chimara_glk_wait(ChimaraGlk *glk) g_thread_join(priv->thread); } +/** + * chimara_glk_get_running: + * @glk: a #ChimaraGlk widget + * + * Use this function to tell whether a program is currently running in the + * widget. + * + * Returns: %TRUE if @glk is executing a Glk program, %FALSE otherwise. + */ gboolean chimara_glk_get_running(ChimaraGlk *glk) { diff --git a/libchimara/chimara-glk.h b/libchimara/chimara-glk.h index ad7e2ec..b8ec38c 100644 --- a/libchimara/chimara-glk.h +++ b/libchimara/chimara-glk.h @@ -38,6 +38,30 @@ typedef struct _ChimaraGlkClass { void(* text_buffer_output) (ChimaraGlk *self, guint32 window_rock, gchar *text); } ChimaraGlkClass; +/** + * ChimaraError: + * + * Error codes returned by #ChimaraGlk widgets and subclasses. + * + * + * CHIMARA_LOAD_MODULE_ERROR + * There was an error opening the plugin containing the Glk + * program. The error message from g_module_error() is appended to the GError message. + * + * + * CHIMARA_NO_GLK_MAIN + * The plugin containing the Glk program did not export a + * glk_main() function. + * + * + * CHIMARA_PLUGIN_NOT_FOUND + * An appropriate interpreter plugin for the autodetected + * game file type could not be found. + * + * + */ typedef enum _ChimaraError { CHIMARA_LOAD_MODULE_ERROR, CHIMARA_NO_GLK_MAIN, diff --git a/libchimara/chimara-if.c b/libchimara/chimara-if.c index fb1d6b5..a5e0225 100644 --- a/libchimara/chimara-if.c +++ b/libchimara/chimara-if.c @@ -9,6 +9,17 @@ #include "chimara-marshallers.h" #include "init.h" +/** + * SECTION:chimara-if + * @short_description: Widget which plays an interactive fiction game + * @stability: Unstable + * @include: chimara/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. + */ + static gboolean supported_formats[CHIMARA_IF_NUM_FORMATS][CHIMARA_IF_NUM_INTERPRETERS] = { /* Frotz Nitfol Glulxe Git */ { TRUE, TRUE, FALSE, FALSE }, /* Z5 */ @@ -245,7 +256,17 @@ chimara_if_class_init(ChimaraIFClass *klass) /* Signals */ klass->command = chimara_if_command; - /* Gtk-Doc for command */ + /** + * ChimaraIF::command: + * @self: The widget that received the signal + * @input: The command typed into the game + * @response: The game's response to the command + * + * Emitted once for each input-response cycle of an interactive fiction + * game. Note that games with nontraditional input systems (i.e. not all + * taking place in the same text buffer window) may throw this signal for a + * loop. + */ chimara_if_signals[COMMAND] = g_signal_new("command", G_OBJECT_CLASS_TYPE(klass), 0, G_STRUCT_OFFSET(ChimaraIFClass, command), NULL, NULL, @@ -253,6 +274,18 @@ chimara_if_class_init(ChimaraIFClass *klass) G_TYPE_NONE, 2, G_TYPE_STRING, G_TYPE_STRING); /* Properties */ + /** + * ChimaraIF:piracy-mode: + * + * The Z-machine specification defines a facility for games to ask the + * interpreter they are running on whether this copy of the game is pirated. + * How the interpreter is supposed to magically determine that it is running + * pirate software is unclear, and so the majority of games and interpreters + * ignore this feature. Set this property to %TRUE if you want the + * interpreter to pretend it has detected a pirated game. + * + * Only affects Z-machine interpreters. + */ g_object_class_install_property(object_class, PROP_PIRACY_MODE, g_param_spec_boolean("piracy-mode", _("Piracy mode"), _("Pretend the game is pirated"), FALSE, @@ -266,39 +299,125 @@ chimara_if_class_init(ChimaraIFClass *klass) * url="http://www.ifarchive.org/if-archive/infocom/info/tandy_bits.html"> * http://www.ifarchive.org/if-archive/infocom/info/tandy_bits.html. * - * Only works on Z-machine interpreters. + * Only affects Z-machine interpreters. */ g_object_class_install_property(object_class, PROP_TANDY_BIT, g_param_spec_boolean("tandy-bit", _("Tandy bit"), _("Censor certain Infocom games"), FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_LAX_VALIDATION | G_PARAM_STATIC_STRINGS)); - + /** + * ChimaraIF:expand-abbreviations: + * + * Most Z-machine games, in particular ones compiled with the Inform + * library, support the following one-letter abbreviations: + * + * D — Down + * E — East + * G — aGain + * I — Inventory + * L — Look + * N — North + * O — Oops + * Q — Quit + * S — South + * U — Up + * W — West + * X — eXamine + * Y — Yes + * Z — wait (ZZZZ...) + * + * Some early Infocom games might not recognize these abbreviations. Setting + * this property to %TRUE will cause the interpreter to expand the + * abbreviations to the full words before passing the commands on to the + * game. Frotz only expands G, X, and Z; Nitfol expands all of the above + * plus the following nonstandard ones: + * + * C — Close + * K — attacK + * P — oPen + * R — dRop + * T — Take + * + * + * Only affects Z-machine interpreters. Behaves differently on Frotz and + * Nitfol. + */ g_object_class_install_property(object_class, PROP_EXPAND_ABBREVIATIONS, g_param_spec_boolean("expand-abbreviations", _("Expand abbreviations"), _("Expand abbreviations such as X for EXAMINE"), FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_LAX_VALIDATION | G_PARAM_STATIC_STRINGS)); - + /** + * ChimaraIF:ignore-errors: + * + * Setting this property to %TRUE will cause the interpreter to ignore + * certain Z-machine runtime errors. Frotz will ignore any fatal errors. + * Nitfol by default warns about any shady behavior, and this property will + * turn those warnings off. + * + * Only affects Z-machine interpreters. Behaves differently on Frotz and + * Nitfol. + */ g_object_class_install_property(object_class, PROP_IGNORE_ERRORS, g_param_spec_boolean("ignore-errors", _("Ignore errors"), _("Do not warn the user about Z-machine errors"), FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_LAX_VALIDATION | G_PARAM_STATIC_STRINGS)); - + /** + * ChimaraIF:typo-correction: + * + * Nitfol has an automatic typo-correction facility, where it searches the + * game dictionary for words which differ by one letter from any unknown + * input words. Set this property to %FALSE to turn this feature off. + * + * Only affects Nitfol. + */ g_object_class_install_property(object_class, PROP_TYPO_CORRECTION, g_param_spec_boolean("typo-correction", _("Typo correction"), _("Try to remedy typos if the interpreter supports it"), TRUE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_LAX_VALIDATION | G_PARAM_STATIC_STRINGS)); - + /** + * ChimaraIF:interpreter-number: + * + * Infocom gave each port of their interpreter a different number. The Frotz + * and Nitfol plugins can emulate any of these platforms. Some games behave + * slightly differently depending on what platform they are on. Set this + * property to a #ChimaraIFZmachineVersion value to emulate a certain + * platform. + * + * Note that Nitfol pretends to be an Apple IIe by default. + * + * Only affects Z-machine interpreters. + */ g_object_class_install_property(object_class, PROP_INTERPRETER_NUMBER, g_param_spec_uint("interpreter-number", _("Interpreter number"), _("Platform the Z-machine should pretend it is running on"), CHIMARA_IF_ZMACHINE_DEFAULT, CHIMARA_IF_ZMACHINE_MAXVAL, CHIMARA_IF_ZMACHINE_DEFAULT, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_LAX_VALIDATION | G_PARAM_STATIC_STRINGS)); - + /** + * ChimaraIF:random-seed: + * + * If the #ChimaraIF:random-seed-set property is %TRUE, then the interpreter + * will use the value of this property as a seed for the random number + * generator. Use this feature to duplicate sequences of random numbers + * for testing games. + * + * Note that the value -1 is a valid random number seed for + * Nitfol, whereas it will cause Frotz to pick an arbitrary seed even when + * #ChimaraIF:random-seed-set is %TRUE. + * + * Only affects Z-machine interpreters. Behaves slightly differently on + * Frotz and Nitfol. + */ g_object_class_install_property(object_class, PROP_RANDOM_SEED, g_param_spec_int("random-seed", _("Random seed"), _("Seed for the random number generator"), G_MININT, G_MAXINT, 0, G_PARAM_READWRITE | G_PARAM_LAX_VALIDATION | G_PARAM_STATIC_STRINGS)); - + /** + * ChimaraIF:random-seed-set: + * + * Whether to use or ignore the #ChimaraIF:random-seed property. + * + * Only affects Z-machine interpreters. + */ g_object_class_install_property(object_class, PROP_RANDOM_SEED_SET, g_param_spec_boolean("random-seed-set", _("Random seed set"), _("Whether the seed for the random number generator should be set manually"), FALSE, @@ -325,6 +444,18 @@ chimara_if_new(void) return GTK_WIDGET(g_object_new(CHIMARA_TYPE_IF, NULL)); } +/** + * chimara_if_set_preferred_interpreter: + * @self: A #ChimaraIF widget. + * @format: The game format to set the preferred interpreter plugin for. + * @interpreter: The preferred interpreter plugin for @format. + * + * The function chimara_if_run_game() picks an appropriate interpreter for the + * type of game file it is given. This function sets which interpreter is picked + * for a certain game file format. Most formats, notably the Z-machine, have + * had many different interpreters written for them over the years, all with + * slightly different quirks and capabilities, so there is plenty of choice. + */ void chimara_if_set_preferred_interpreter(ChimaraIF *self, ChimaraIFFormat format, ChimaraIFInterpreter interpreter) { @@ -340,6 +471,17 @@ chimara_if_set_preferred_interpreter(ChimaraIF *self, ChimaraIFFormat format, Ch g_warning("Format '%s' is not supported by interpreter '%s'", format_names[format], interpreter_names[interpreter]); } +/** + * chimara_if_get_preferred_interpreter: + * @self: A #ChimaraIF widget. + * @format: The game format to query the preferred interpreter plugin for. + * + * Looks up the preferred interpreter for the game file format @format. See + * chimara_if_set_preferred_interpreter(). + * + * Returns: a #ChimaraIFInterpreter value representing the preferred interpreter + * plugin for @format. + */ ChimaraIFInterpreter chimara_if_get_preferred_interpreter(ChimaraIF *self, ChimaraIFFormat format) { @@ -349,6 +491,20 @@ chimara_if_get_preferred_interpreter(ChimaraIF *self, ChimaraIFFormat format) return priv->preferred_interpreter[format]; } +/** + * chimara_if_run_game: + * @self: A #ChimaraIF widget. + * @gamefile: Path to an interactive fiction game file. + * @error: Return location for an error, or %NULL. + * + * Autodetects the type of a game file and runs it using an appropriate + * interpreter plugin. If there is more than one interpreter that supports the + * file format, the preferred one will be picked, according to + * chimara_if_set_preferred_interpreter(). + * + * Returns: %TRUE if the game was started successfully, %FALSE if not, in which + * case @error is set. + */ gboolean chimara_if_run_game(ChimaraIF *self, gchar *gamefile, GError **error) { @@ -475,3 +631,35 @@ chimara_if_run_game(ChimaraIF *self, gchar *gamefile, GError **error) } return retval; } + +/** + * chimara_if_get_format: + * @self: A #ChimaraIF widget. + * + * Returns the file format of the currently running game. + * + * Returns: a #ChimaraIFFormat constant. + */ +ChimaraIFFormat +chimara_if_get_format(ChimaraIF *self) +{ + g_return_val_if_fail(self && CHIMARA_IS_IF(self), CHIMARA_IF_FORMAT_NONE); + CHIMARA_IF_USE_PRIVATE(self, priv); + return priv->format; +} + +/** + * chimara_if_get_interpreter: + * @self: A #ChimaraIF widget. + * + * Returns the interpreter plugin currently running. + * + * Returns: a #ChimaraIFInterpreter constant. + */ +ChimaraIFInterpreter +chimara_if_get_interpreter(ChimaraIF *self) +{ + g_return_val_if_fail(self && CHIMARA_IS_IF(self), CHIMARA_IF_FORMAT_NONE); + CHIMARA_IF_USE_PRIVATE(self, priv); + return priv->interpreter; +} diff --git a/libchimara/chimara-if.h b/libchimara/chimara-if.h index 0068292..89ea5c8 100644 --- a/libchimara/chimara-if.h +++ b/libchimara/chimara-if.h @@ -13,6 +13,11 @@ G_BEGIN_DECLS #define CHIMARA_IS_IF_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), CHIMARA_TYPE_IF)) #define CHIMARA_IF_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), CHIMARA_TYPE_IF, ChimaraIFClass)) +/** + * ChimaraIFFormat: + * + * Constants representing all game formats supported by the Chimara system. + */ typedef enum _ChimaraIFFormat { CHIMARA_IF_FORMAT_NONE = -1, CHIMARA_IF_FORMAT_Z5, @@ -24,6 +29,11 @@ typedef enum _ChimaraIFFormat { CHIMARA_IF_NUM_FORMATS } ChimaraIFFormat; +/** + * ChimaraIFInterpreter: + * + * Constants representing the available interpreter plugins. + */ typedef enum _ChimaraIFInterpreter { CHIMARA_IF_INTERPRETER_NONE = -1, CHIMARA_IF_INTERPRETER_FROTZ, @@ -33,6 +43,11 @@ typedef enum _ChimaraIFInterpreter { CHIMARA_IF_NUM_INTERPRETERS } ChimaraIFInterpreter; +/** + * ChimaraIFZmachineVersion: + * + * Allowed values for the #ChimaraIF:interpreter-number property. + */ typedef enum _ChimaraIFZmachineVersion { CHIMARA_IF_ZMACHINE_DEFAULT = 0, CHIMARA_IF_ZMACHINE_DECSYSTEM_20, @@ -49,8 +64,15 @@ typedef enum _ChimaraIFZmachineVersion { CHIMARA_IF_ZMACHINE_MAXVAL = CHIMARA_IF_ZMACHINE_TANDY_COLOR } ChimaraIFZmachineVersion; +/** + * ChimaraIF: + * + * This structure contains no public members. + */ typedef struct _ChimaraIF { ChimaraGlk parent_instance; + + /*< public >*/ } ChimaraIF; typedef struct _ChimaraIFClass { -- 2.30.2