* @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.
*
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);
* 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,
* 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 <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);
-
+ /**
+ * 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);
-
+ /**
+ * 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,
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)
{
#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 */
/* 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,
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,
* 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));
-
+ /**
+ * ChimaraIF:expand-abbreviations:
+ *
+ * Most Z-machine games, in particular ones compiled with the Inform
+ * library, support the following one-letter abbreviations:
+ * <simplelist>
+ * <member>D — Down</member>
+ * <member>E — East</member>
+ * <member>G — aGain</member>
+ * <member>I — Inventory</member>
+ * <member>L — Look</member>
+ * <member>N — North</member>
+ * <member>O — Oops</member>
+ * <member>Q — Quit</member>
+ * <member>S — South</member>
+ * <member>U — Up</member>
+ * <member>W — West</member>
+ * <member>X — eXamine</member>
+ * <member>Y — Yes</member>
+ * <member>Z — 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 — Close</member>
+ * <member>K — attacK</member>
+ * <member>P — oPen</member>
+ * <member>R — dRop</member>
+ * <member>T — 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));
-
+ /**
+ * 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,
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)
{
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)
{
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)
{
}
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;
+}
projects / rodin / chimara.git / commitdiff