From: fliep Date: Fri, 30 Apr 2010 22:07:39 +0000 (+0000) Subject: Added stubs for all Gargoyle extensions and documented them X-Git-Tag: v0.9~214 X-Git-Url: https://git.stderr.nl/gitweb?a=commitdiff_plain;h=beda346223d81061b1c6f8aa444988650c105333;p=projects%2Fchimara%2Fchimara.git Added stubs for all Gargoyle extensions and documented them --- diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt index 7f4075d..d2e37f5 100644 --- a/docs/reference/chimara-sections.txt +++ b/docs/reference/chimara-sections.txt @@ -619,5 +619,32 @@ glkunix_set_base_file
glkext-garglk Gargoyle Extensions +GARGLK + +garglk_fileref_get_name +garglk_set_program_name +garglk_set_program_info +garglk_set_story_name +garglk_set_line_terminators +garglk_unput_string +garglk_unput_string_uni +garglk_set_zcolors garglk_set_reversevideo + +zcolor_Current +zcolor_Default +zcolor_Black +zcolor_Red +zcolor_Green +zcolor_Yellow +zcolor_Blue +zcolor_Magenta +zcolor_Cyan +zcolor_White +zcolor_LightGrey +zcolor_MediumGrey +zcolor_DarkGrey +keycode_Erase + +zcolor_NUMCOLORS
\ No newline at end of file diff --git a/libchimara/doc.c b/libchimara/doc.c index 3fd18ca..e599ff2 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -1229,6 +1229,23 @@ * generally be limited to finding and opening data files. There are a few Unix * Glk library functions which are convenient for this purpose. */ + +/** + * SECTION:glkext-garglk + * @short_description: Gargoyle extensions to Glk + * @include: libchimara/glk.h, libchimara/garglk.h + * + * This section describes various extensions to Glk that were written for the + * popular interpreter Gargoyle by Tor Andersson (now + * maintained by Ben Cressey). + * + * These functions mostly serve to close the gap between Glk's input/output + * capabilities and what some interpreters expect. For example, + * garglk_set_zcolors() displays the colors defined in the Z-machine standard, + * and garglk_set_story_name() can be used to give the host program a hint + * about what to display in the title bar of its window. + */ /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/ diff --git a/libchimara/garglk.c b/libchimara/garglk.c index 3631d67..b72fc59 100644 --- a/libchimara/garglk.c +++ b/libchimara/garglk.c @@ -1,19 +1,203 @@ +#include #include #include "chimara-glk-private.h" #include "stream.h" +#include "fileref.h" extern GPrivate *glk_data_key; +/** + * garglk_fileref_get_name: + * @fref: A file reference. + * + * Gets the actual disk filename that @fref refers to, in the platform's + * native filename encoding. The string is owned by @fref and must not be + * changed or freed. + * + * Returns: a string in filename encoding. + */ +char * +garglk_fileref_get_name(frefid_t fref) +{ + VALID_FILEREF(fref, return NULL); + return fref->filename; +} + +/** + * garglk_set_program_name: + * @name: Name of the Glk program that is running. + * + * This function is used to let the library know the name of the currently + * running Glk program, in case it wants to display this information somewhere + * — for example, in the title bar of a window. A typical use of this + * function would be: + * |[ garglk_set_program_name("SuperGlkFrotz 0.1"); ]| + * + * This function is not currently implemented. + */ +void +garglk_set_program_name(const char *name) +{ + WARNING(_("Not implemented")); +} + +/** + * garglk_set_program_info: + * @info: Information about the Glk program that is running. + * + * This function is used to provide the library with additional information + * about the currently running Glk program, in case it wants to display this + * information somewhere — for example, in an About box. A typical use of + * this function would be: + * |[ + * garglk_set_program_info("SuperGlkFrotz, version 0.1\n" + * "Original Frotz by Stefan Jokisch\n" + * "Unix port by Jim Dunleavy and David Griffith\n" + * "Glk port by Tor Andersson\n" + * "Animation, networking, and evil AI by Sven Metcalfe"); + * ]| + * + * This function is not currently implemented. + */ +void +garglk_set_program_info(const char *info) +{ + WARNING(_("Not implemented")); +} + +/** + * garglk_set_story_name: + * @name: Name of the story that the Glk program is currently interpreting. + * + * If the Glk program running is an interactive fiction interpreter, then this + * function can be used to let the library know the name of the story currently + * loaded in the interpreter, in case it wants to display this information + * anywhere — for example, in the title bar of a window. A typical use of + * this function would be: + * |[ garglk_set_story_name("Lighan Ses Lion, el Zarf"); ]| + * + * This function is not currently implemented. + */ +void +garglk_set_story_name(const char *name) +{ + WARNING(_("Not implemented")); +} + +/** + * garglk_set_line_terminators: + * @win: A window. + * @keycodes: An array of keycode_ constants. + * @numkeycodes: The length of @keycodes. + * + * Amends the current line input request of @win to include terminating key + * codes. Any of the specified key codes will terminate the line input request + * (without printing a newline). + * + * Usually, in the event structure returned from a line input request, @val2 is + * zero, but if garglk_set_line_terminators() has been called during that input + * request, @val2 will be filled in with the key code that terminated the input + * request. + * + * This function only applies to one input request; any subsequent line input + * requests on that window are treated normally. + * + * If @numkeycodes is zero, then any previous call to + * garglk_set_line_terminators() is cancelled and the input request is treated + * normally. + * + * This function is not currently implemented. + */ +void +garglk_set_line_terminators(winid_t win, const glui32 *keycodes, glui32 numkeycodes) +{ + VALID_WINDOW(win, return); + g_return_if_fail(win->type != wintype_TextBuffer || win->type != wintype_TextGrid); + + if(win->input_request_type != INPUT_REQUEST_LINE && win->input_request_type != INPUT_REQUEST_LINE_UNICODE) { + ILLEGAL(_("Tried to set the line terminators on a window without a line input request.")); + return; + } + + WARNING(_("Not implemented")); +} + +/** + * garglk_unput_string: + * @str: a null-terminated string. + * + * Removes @str from the end of the current stream, if indeed it is there. The + * stream's write count is decreased accordingly, and the stream's echo stream + * is also modified, if it has one. + * + * This function is not currently implemented. + */ +void +garglk_unput_string(char *str) +{ + ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key); + g_return_if_fail(glk_data->current_stream != NULL); + + WARNING(_("Not implemented")); +} + +/** + * garglk_unput_string_uni: + * @str: a zero-terminated array of Unicode code points. + * + * Like garglk_unput_string(), but for Unicode streams. + * + * This function is not currently implemented. + */ +void +garglk_unput_string_uni(glui32 *str) +{ + ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key); + g_return_if_fail(glk_data->current_stream != NULL); + + WARNING(_("Not implemented")); +} + +/** + * garglk_set_zcolors: + * @fg: one of the zcolor_ constants. + * @bg: one of the zcolor_ constants. + * + * Glk works with styles, not specific colors. This is not quite compatible with + * the Z-machine, so this Glk extension implements Z-machine style colors. + * + * This function changes the foreground color of the current stream to @fg and + * the background color to @bg. + * + * This function is not currently implemented. + */ +void +garglk_set_zcolors(glui32 fg, glui32 bg) +{ + ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key); + g_return_if_fail(glk_data->current_stream != NULL); + g_return_if_fail(glk_data->current_stream->window != NULL); + + WARNING(_("Not implemented")); +} + static void apply_reverse_color(GtkTextTag *tag, gpointer data) { g_object_set_data( G_OBJECT(tag), "reverse_color", data ); } +/** + * garglk_set_reversevideo: + * @reverse: nonzero for reverse colors, zero for normal colors. + * + * If @reverse is not zero, uses the foreground color of the current stream as + * its background and vice versa. If @reverse is zero, changes the colors of the + * current stream back to normal. + */ void garglk_set_reversevideo(glui32 reverse) { - printf("set_reversevideo(%d)\n", reverse); ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key); g_return_if_fail(glk_data->current_stream != NULL); g_return_if_fail(glk_data->current_stream->window != NULL); @@ -21,4 +205,3 @@ garglk_set_reversevideo(glui32 reverse) GtkTextTagTable *tags = gtk_text_buffer_get_tag_table( GTK_TEXT_BUFFER(glk_data->current_stream->window->widget) ); gtk_text_tag_table_foreach( tags, apply_reverse_color, GINT_TO_POINTER(reverse) ); } - diff --git a/libchimara/garglk.h b/libchimara/garglk.h index a4dfba6..1ca8fbe 100644 --- a/libchimara/garglk.h +++ b/libchimara/garglk.h @@ -1,6 +1,156 @@ #ifndef __GARGLK_H__ #define __GARGLK_H__ +/** + * GARGLK: + * + * To test at compile time whether the Gargoyle extensions are available, you + * can perform a preprocessor test for the existence of %GARGLK. If this + * macro is defined, then so are all the Gargoyle extensions. If not, not. + * + * Chimara + * Currently, in Chimara, the functions are defined, but most of them are + * not implemented. That is, you can call them, but they do nothing. + * + */ +#define GARGLK 1 + +extern char* garglk_fileref_get_name(frefid_t fref); + +extern void garglk_set_program_name(const char *name); +extern void garglk_set_program_info(const char *info); +extern void garglk_set_story_name(const char *name); + +/* + These functions are not implemented even in Gargoyle. Looks like they were + planned, but never added. +extern void garglk_set_config(const char *name); + +#define garglk_font_Roman (0) +#define garglk_font_Italic (1) +#define garglk_font_Bold (2) +#define garglk_font_BoldItalic (3) +#define garglk_font_MonoRoman (4) +#define garglk_font_MonoItalic (5) +#define garglk_font_MonoBold (6) +#define garglk_font_MonoBoldItalic (7) + +#define garglk_color_White (0) +#define garglk_color_Red (1) +#define garglk_color_Green (2) +#define garglk_color_Blue (3) +#define garglk_color_Cyan (4) +#define garglk_color_Magenta (5) +#define garglk_color_Yellow (6) +#define garglk_color_Black (7) + +extern void garglk_set_style_font(glui32 font); +extern void garglk_set_style_stream_font(strid_t str, glui32 font); +extern void garglk_set_style_color(glui32 bg, glui32 fg); +extern void garglk_set_style_stream_color(strid_t str, glui32 bg, glui32 fg); +*/ + +/* JM: functions added to support Z-machine features that aren't in the Glk standard */ + +extern void garglk_set_line_terminators(winid_t win, const glui32 *keycodes, glui32 numkeycodes); + +extern void garglk_unput_string(char *str); +extern void garglk_unput_string_uni(glui32 *str); + +/** + * zcolor_Current: + * + * Z-machine color constant representing the current color. + */ +#define zcolor_Current (0) +/** + * zcolor_Default: + * + * Z-machine color constant representing the default color. + */ +#define zcolor_Default (1) +/** + * zcolor_Black: + * + * Z-machine color constant representing black (0x000000). + */ +#define zcolor_Black (2) +/** + * zcolor_Red: + * + * Z-machine color constant representing red (0x0000E8). + */ +#define zcolor_Red (3) +/** + * zcolor_Green: + * + * Z-machine color constant representing green (0x00D000). + */ +#define zcolor_Green (4) +/** + * zcolor_Yellow: + * + * Z-machine color constant representing yellow (0x00E8E8). + */ +#define zcolor_Yellow (5) +/** + * zcolor_Blue: + * + * Z-machine color constant representing blue (0xB06800). + */ +#define zcolor_Blue (6) +/** + * zcolor_Magenta: + * + * Z-machine color constant representing magenta (0xFF00FF). + */ +#define zcolor_Magenta (7) +/** + * zcolor_Cyan: + * + * Z-machine color constant representing cyan (0xE8E800). + */ +#define zcolor_Cyan (8) +/** + * zcolor_White: + * + * Z-machine color constant representing white (0xFFFFFF). + */ +#define zcolor_White (9) +/** + * zcolor_LightGrey: + * + * Z-machine color constant representing light grey (0xB0B0B0). + */ +#define zcolor_LightGrey (10) +/** + * zcolor_MediumGrey: + * + * Z-machine color constant representing grey (0x888888). + */ +#define zcolor_MediumGrey (11) +/** + * zcolor_DarkGrey: + * + * Z-machine color constant representing dark grey (0x585858). + */ +#define zcolor_DarkGrey (12) +#define zcolor_NUMCOLORS (13) + +extern void garglk_set_zcolors(glui32 fg, glui32 bg); extern void garglk_set_reversevideo(glui32 reverse); +/* non standard keycodes */ +/** + * keycode_Erase: + * + * Since %keycode_Delete represents either the Delete or + * Backspace key, Gargoyle defines a separate constant + * %keycode_Erase to represent only the + * Delete key. In character input, Delete is + * still reported as %keycode_Delete, but the two are distinguished in + * garglk_set_line_terminators(). + */ +#define keycode_Erase (0xffffef7f) + #endif /* __GARGLK_H__ */