X-Git-Url: https://git.stderr.nl/gitweb?p=rodin%2Fchimara.git;a=blobdiff_plain;f=libchimara%2Fchimara-if.c;h=7b91830acdce059d12ab64193a28355cbf6c75df;hp=fb1d6b52f4a5ad12dddef5c21b809e9bdcbc72b5;hb=7ef4ef1fecab7ae0f724e59f7de1315a96822152;hpb=92895be4421d350eb674093c1789d8703c2d8f94 diff --git a/libchimara/chimara-if.c b/libchimara/chimara-if.c index fb1d6b5..7b91830 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 */ @@ -85,9 +96,9 @@ chimara_if_waiting(ChimaraGlk *glk) gchar *response = g_string_free(priv->response, FALSE); priv->response = g_string_new(""); - + g_signal_emit_by_name(glk, "command", priv->input, response); - + g_free(priv->input); g_free(response); priv->input = NULL; @@ -97,10 +108,10 @@ static void chimara_if_stopped(ChimaraGlk *glk) { CHIMARA_IF_USE_PRIVATE(glk, priv); - + if(priv->input || priv->response->len > 0) chimara_if_waiting(glk); /* Send one last command signal */ - + priv->format = CHIMARA_IF_FORMAT_NONE; priv->interpreter = CHIMARA_IF_INTERPRETER_NONE; } @@ -137,7 +148,7 @@ chimara_if_init(ChimaraIF *self) priv->random_seed_set = FALSE; priv->input = NULL; priv->response = g_string_new(""); - + /* Connect to signals of ChimaraGlk parent */ g_signal_connect(self, "stopped", G_CALLBACK(chimara_if_stopped), NULL); g_signal_connect(self, "waiting", G_CALLBACK(chimara_if_waiting), NULL); @@ -155,27 +166,35 @@ chimara_if_set_property(GObject *object, guint prop_id, const GValue *value, GPa { case PROP_PIRACY_MODE: PROCESS_FLAG(priv->flags, CHIMARA_IF_PIRACY_MODE, g_value_get_boolean(value)); + g_object_notify(object, "piracy-mode"); break; case PROP_TANDY_BIT: PROCESS_FLAG(priv->flags, CHIMARA_IF_TANDY_BIT, g_value_get_boolean(value)); + g_object_notify(object, "tandy-bit"); break; case PROP_EXPAND_ABBREVIATIONS: PROCESS_FLAG(priv->flags, CHIMARA_IF_EXPAND_ABBREVIATIONS, g_value_get_boolean(value)); + g_object_notify(object, "expand-abbreviations"); break; case PROP_IGNORE_ERRORS: PROCESS_FLAG(priv->flags, CHIMARA_IF_IGNORE_ERRORS, g_value_get_boolean(value)); + g_object_notify(object, "ignore-errors"); break; case PROP_TYPO_CORRECTION: PROCESS_FLAG(priv->flags, CHIMARA_IF_TYPO_CORRECTION, g_value_get_boolean(value)); + g_object_notify(object, "typo-correction"); break; case PROP_INTERPRETER_NUMBER: priv->interpreter_number = g_value_get_uint(value); + g_object_notify(object, "interpreter-number"); break; case PROP_RANDOM_SEED: priv->random_seed = g_value_get_int(value); + g_object_notify(object, "random-seed"); break; case PROP_RANDOM_SEED_SET: priv->random_seed_set = g_value_get_boolean(value); + g_object_notify(object, "random-seed-set"); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec); @@ -229,9 +248,16 @@ chimara_if_command(ChimaraIF *self, gchar *input, gchar *response) /* Default signal handler */ } -/* G_PARAM_STATIC_STRINGS only appeared in GTK 2.13.0 */ +/* COMPAT: G_PARAM_STATIC_STRINGS only appeared in GTK 2.13.0 */ #ifndef G_PARAM_STATIC_STRINGS + +/* COMPAT: G_PARAM_STATIC_NAME and friends only appeared in GTK 2.8 */ +#if GTK_CHECK_VERSION(2,8,0) #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB) +#else +#define G_PARAM_STATIC_STRINGS (0) +#endif + #endif static void @@ -245,7 +271,16 @@ 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 confuse this signal. + */ chimara_if_signals[COMMAND] = g_signal_new("command", G_OBJECT_CLASS_TYPE(klass), 0, G_STRUCT_OFFSET(ChimaraIFClass, command), NULL, NULL, @@ -253,52 +288,150 @@ 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"), + g_param_spec_boolean("piracy-mode", _("Piracy mode"), _("Pretend the game is pirated"), FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_LAX_VALIDATION | G_PARAM_STATIC_STRINGS)); /** * ChimaraIF:tandy-bit: - * + * * Some early Infocom games were sold by the Tandy Corporation. Setting this - * property to %TRUE changes the wording of some Version 3 Infocom games - * slightly, so as to be less offensive. See * 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_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"), + 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"), + _("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,12 +458,24 @@ 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) { g_return_if_fail(self && CHIMARA_IS_IF(self)); g_return_if_fail(format < CHIMARA_IF_NUM_FORMATS); - g_return_if_fail(format < CHIMARA_IF_NUM_INTERPRETERS); + g_return_if_fail(interpreter < CHIMARA_IF_NUM_INTERPRETERS); CHIMARA_IF_USE_PRIVATE(self, priv); @@ -340,6 +485,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,12 +505,26 @@ chimara_if_get_preferred_interpreter(ChimaraIF *self, ChimaraIFFormat format) return priv->preferred_interpreter[format]; } -gboolean +/** + * 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) { g_return_val_if_fail(self && CHIMARA_IS_IF(self), FALSE); g_return_val_if_fail(gamefile, FALSE); - + CHIMARA_IF_USE_PRIVATE(self, priv); /* Find out what format the game is */ @@ -372,25 +542,33 @@ chimara_if_run_game(ChimaraIF *self, gchar *gamefile, GError **error) format = CHIMARA_IF_FORMAT_GLULX; else if(g_str_has_suffix(gamefile, ".blb") || g_str_has_suffix(gamefile, ".blorb") || g_str_has_suffix(gamefile, ".glb") || g_str_has_suffix(gamefile, ".gblorb")) format = CHIMARA_IF_FORMAT_GLULX_BLORB; - + /* Now decide what interpreter to use */ ChimaraIFInterpreter interpreter = priv->preferred_interpreter[format]; gchar *pluginfile = g_strconcat(plugin_names[interpreter], "." G_MODULE_SUFFIX, NULL); + gchar *pluginpath; +#ifdef DEBUG +#ifndef LT_OBJDIR +#define LT_OBJDIR ".libs" /* Pre-2.2 libtool, so take a wild guess */ +#endif /* LT_OBJDIR */ /* If there is a plugin in the source tree, use that */ - gchar *pluginpath = g_build_filename("..", "interpreters", plugin_names[interpreter], LT_OBJDIR, pluginfile, NULL); - if( !g_file_test(pluginpath, G_FILE_TEST_EXISTS) ) + pluginpath = g_build_filename(PLUGINSOURCEDIR, plugin_names[interpreter], LT_OBJDIR, pluginfile, NULL); + if( !g_file_test(pluginpath, G_FILE_TEST_EXISTS) ) { g_free(pluginpath); +#endif /* DEBUG */ pluginpath = g_build_filename(PLUGINDIR, pluginfile, NULL); - if( !g_file_test(pluginpath, G_FILE_TEST_EXISTS) ) + if( !g_file_test(pluginpath, G_FILE_TEST_EXISTS) ) { g_free(pluginpath); g_free(pluginfile); g_set_error(error, CHIMARA_ERROR, CHIMARA_PLUGIN_NOT_FOUND, _("No appropriate %s interpreter plugin was found"), interpreter_names[interpreter]); return FALSE; } +#ifdef DEBUG } +#endif g_free(pluginfile); /* Decide what arguments to pass to the interpreters; currently only the @@ -446,19 +624,19 @@ chimara_if_run_game(ChimaraIF *self, gchar *gamefile, GError **error) default: ; } - + /* Allocate argv to hold the arguments */ int argc = g_slist_length(args); args = g_slist_prepend(args, NULL); char **argv = g_new0(char *, argc + 1); - + /* Fill argv */ args = g_slist_reverse(args); int count; GSList *ptr; for(count = 0, ptr = args; ptr; count++, ptr = g_slist_next(ptr)) argv[count] = ptr->data; - + gboolean retval = chimara_glk_run(CHIMARA_GLK(self), pluginpath, argc, argv, error); g_free(argv); if(terpnumstr) @@ -466,7 +644,7 @@ chimara_if_run_game(ChimaraIF *self, gchar *gamefile, GError **error) if(randomstr) g_free(randomstr); g_free(pluginpath); - + /* Set current format and interpreter if plugin was started successfully */ if(retval) { @@ -475,3 +653,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; +}