Wrote documentation for new functions
authorPhilip Chimento <philip.chimento@gmail.com>
Fri, 23 Oct 2009 23:09:57 +0000 (23:09 +0000)
committerPhilip Chimento <philip.chimento@gmail.com>
Fri, 23 Oct 2009 23:09:57 +0000 (23:09 +0000)
git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@148 ddfedd41-794f-dd11-ae45-00112f111e67

docs/reference/chimara-docs.sgml
docs/reference/chimara-sections.txt
libchimara/chimara-glk.c
libchimara/chimara-glk.h
libchimara/chimara-if.c
libchimara/chimara-if.h

index 1f8cf2db5f0c004b486fa2acbae341a29b17abcb..412d6a09303c39d52943f453ab63e1885dbe95d7 100644 (file)
@@ -16,6 +16,7 @@
   <reference>
     <title>Chimara API Reference</title>
     <xi:include href="xml/chimara-glk.xml"/>
   <reference>
     <title>Chimara API Reference</title>
     <xi:include href="xml/chimara-glk.xml"/>
+    <xi:include href="xml/chimara-if.xml"/>
   </reference>
   
   <reference>
   </reference>
   
   <reference>
index f933b2da9c8e198e3a7bef6cd8db305e2897a914..51b9c62a725894f2c57a94a19cffdf840574eda6 100644 (file)
@@ -2,6 +2,9 @@
 <FILE>chimara-glk</FILE>
 <TITLE>ChimaraGlk</TITLE>
 ChimaraGlk
 <FILE>chimara-glk</FILE>
 <TITLE>ChimaraGlk</TITLE>
 ChimaraGlk
+ChimaraError
+CHIMARA_ERROR
+chimara_error_quark
 chimara_glk_new
 chimara_glk_set_interactive
 chimara_glk_get_interactive
 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_run
 chimara_glk_stop
 chimara_glk_wait
+chimara_glk_get_running
 <SUBSECTION Standard>
 <SUBSECTION Standard>
-ChimaraGlkClass
 CHIMARA_GLK
 CHIMARA_IS_GLK
 CHIMARA_TYPE_GLK
 CHIMARA_GLK
 CHIMARA_IS_GLK
 CHIMARA_TYPE_GLK
@@ -29,6 +32,29 @@ CHIMARA_IS_GLK_CLASS
 CHIMARA_GLK_GET_CLASS
 </SECTION>
 
 CHIMARA_GLK_GET_CLASS
 </SECTION>
 
+<SECTION>
+<FILE>chimara-if</FILE>
+ChimaraIFFormat
+ChimaraIFInterpreter
+ChimaraIFZmachineVersion
+<TITLE>ChimaraIF</TITLE>
+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
+<SUBSECTION Standard>
+CHIMARA_IF
+CHIMARA_IS_IF
+CHIMARA_TYPE_IF
+chimara_if_get_type
+CHIMARA_IF_CLASS
+CHIMARA_IS_IF_CLASS
+CHIMARA_IF_GET_CLASS
+</SECTION>
+
 <SECTION>
 <FILE>glk-exiting</FILE>
 <TITLE>Exiting Your Program</TITLE>
 <SECTION>
 <FILE>glk-exiting</FILE>
 <TITLE>Exiting Your Program</TITLE>
index eae3988b1fb7a25afa9e29fee8e6640af49de289..45031d9178767b51c63bbf535d67c1a2c9552be3 100644 (file)
@@ -25,7 +25,7 @@
  * @stability: Unstable
  * @include: chimara/chimara-glk.h
  * 
  * @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 <function>glk_main()</function>
  * that the Glk library can hook into.
  *
  * compiled as a plugin module, with a function <function>glk_main()</function>
  * 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);
        
        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;
 
        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);
        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
      *
      * 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, 
      */ 
     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
         *
         * 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);
         */
        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);
        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 <link linkend="chimara-Rocks">Rocks</link>)
+        * @keysym: The key that was typed, in the form of a key symbol from 
+        * <filename class="headerfile">gdk/gdkkeysyms.h</filename>
+        * 
+        * 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);
        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
+        * <link linkend="chimara-Rocks">Rocks</link>)
+        * @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);
        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 <link
+        * linkend="chimara-Rocks">Rocks</link>)
+        * 
+        * 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,
        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);
 }
 
     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)
 {
 gboolean
 chimara_glk_get_running(ChimaraGlk *glk)
 {
index ad7e2ec55f15da3f3a0add093b33b0f73c02bab3..b8ec38cfbc90c7426df96e355d396681a97de6ad 100644 (file)
@@ -38,6 +38,30 @@ typedef struct _ChimaraGlkClass {
        void(* text_buffer_output) (ChimaraGlk *self, guint32 window_rock, gchar *text);
 } ChimaraGlkClass;
 
        void(* text_buffer_output) (ChimaraGlk *self, guint32 window_rock, gchar *text);
 } ChimaraGlkClass;
 
+/**
+ * ChimaraError:
+ * 
+ * Error codes returned by #ChimaraGlk widgets and subclasses.
+ * <variablelist>
+ * <varlistentry>
+ *   <term>CHIMARA_LOAD_MODULE_ERROR</term>
+ *   <listitem><para>There was an error opening the plugin containing the Glk
+ *   program. The error message from <link 
+ *   linkend="g-module-error">g_module_error()</link> is appended to the <link
+ *   linkend="GError">GError</link> message.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>CHIMARA_NO_GLK_MAIN</term>
+ *   <listitem><para>The plugin containing the Glk program did not export a 
+ *   glk_main() function.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>CHIMARA_PLUGIN_NOT_FOUND</term>
+ *   <listitem><para>An appropriate interpreter plugin for the autodetected
+ *   game file type could not be found.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ */
 typedef enum _ChimaraError {
        CHIMARA_LOAD_MODULE_ERROR,
        CHIMARA_NO_GLK_MAIN,
 typedef enum _ChimaraError {
        CHIMARA_LOAD_MODULE_ERROR,
        CHIMARA_NO_GLK_MAIN,
index fb1d6b52f4a5ad12dddef5c21b809e9bdcbc72b5..a5e0225600408c845bd626ad1e3e1948f9f597af 100644 (file)
@@ -9,6 +9,17 @@
 #include "chimara-marshallers.h"
 #include "init.h"
 
 #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 */
 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;
 
        /* 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,
        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 */
                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,
        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</ulink>.
         * 
         * url="http://www.ifarchive.org/if-archive/infocom/info/tandy_bits.html">
         * http://www.ifarchive.org/if-archive/infocom/info/tandy_bits.html</ulink>.
         * 
-        * 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));
         */
        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:
+        * <simplelist>
+        * <member>D &mdash; Down</member>
+        * <member>E &mdash; East</member>
+        * <member>G &mdash; aGain</member>
+        * <member>I &mdash; Inventory</member>
+        * <member>L &mdash; Look</member>
+        * <member>N &mdash; North</member>
+        * <member>O &mdash; Oops</member>
+        * <member>Q &mdash; Quit</member>
+        * <member>S &mdash; South</member>
+        * <member>U &mdash; Up</member>
+        * <member>W &mdash; West</member>
+        * <member>X &mdash; eXamine</member>
+        * <member>Y &mdash; Yes</member>
+        * <member>Z &mdash; wait (ZZZZ...)</member>
+        * </simplelist>
+        * 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:
+        * <simplelist>
+        * <member>C &mdash; Close</member>
+        * <member>K &mdash; attacK</member>
+        * <member>P &mdash; oPen</member>
+        * <member>R &mdash; dRop</member>
+        * <member>T &mdash; Take</member>
+        * </simplelist>
+        * 
+        * 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));
        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));
        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));
        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));
        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));
        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,
        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));
 }
 
     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)
 {
 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]);
 }
 
                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)
 {
 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];
 }
 
        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)
 {
 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;
 }
        }
        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;
+}
index 006829206867586dc859eb68d96050b80a3fcf7d..89ea5c8538c8e1846ce3ef9b3558db599e73d88e 100644 (file)
@@ -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))
 
 #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,
 typedef enum _ChimaraIFFormat {
        CHIMARA_IF_FORMAT_NONE = -1,
        CHIMARA_IF_FORMAT_Z5,
@@ -24,6 +29,11 @@ typedef enum _ChimaraIFFormat {
        CHIMARA_IF_NUM_FORMATS
 } 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,
 typedef enum _ChimaraIFInterpreter {
        CHIMARA_IF_INTERPRETER_NONE = -1,
        CHIMARA_IF_INTERPRETER_FROTZ,
@@ -33,6 +43,11 @@ typedef enum _ChimaraIFInterpreter {
        CHIMARA_IF_NUM_INTERPRETERS
 } 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,
 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;
 
        CHIMARA_IF_ZMACHINE_MAXVAL = CHIMARA_IF_ZMACHINE_TANDY_COLOR
 } ChimaraIFZmachineVersion;
 
+/**
+ * ChimaraIF:
+ * 
+ * This structure contains no public members.
+ */
 typedef struct _ChimaraIF {
        ChimaraGlk parent_instance;
 typedef struct _ChimaraIF {
        ChimaraGlk parent_instance;
+       
+       /*< public >*/
 } ChimaraIF;
 
 typedef struct _ChimaraIFClass {
 } ChimaraIF;
 
 typedef struct _ChimaraIFClass {