Added stubs for all Gargoyle extensions and documented them
authorPhilip Chimento <philip.chimento@gmail.com>
Fri, 30 Apr 2010 22:07:39 +0000 (22:07 +0000)
committerPhilip Chimento <philip.chimento@gmail.com>
Fri, 30 Apr 2010 22:07:39 +0000 (22:07 +0000)
git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@251 ddfedd41-794f-dd11-ae45-00112f111e67

docs/reference/chimara-sections.txt
libchimara/doc.c
libchimara/garglk.c
libchimara/garglk.h

index 7f4075dd393fc26208c685c75c36f6eda38ed741..d2e37f5cf0f0c3a09aa8ed1e4137e49cfa7adc19 100644 (file)
@@ -619,5 +619,32 @@ glkunix_set_base_file
 <SECTION>
 <FILE>glkext-garglk</FILE>
 <TITLE>Gargoyle Extensions</TITLE>
+GARGLK
+<SUBSECTION Functions>
+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
+<SUBSECTION Constants>
+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
+<SUBSECTION Private>
+zcolor_NUMCOLORS
 </SECTION>
\ No newline at end of file
index 3fd18ca0f55778eb8c719b9a28fc5bcc2bd337b8..e599ff22d3f928d331ac07ac4dc2cb80bcb9f821 100644 (file)
  * 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 <ulink 
+ * url="http://www.ccxvii.net/gargoyle/">Gargoyle</ulink> 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 ----------------------------*/
 
index 3631d67a865a2ea1531be389364a2a6d0bdd2048..b72fc5979e8d1c1929d442e9fffa28a45e5e81f8 100644 (file)
+#include <glib/gi18n.h>
 #include <libchimara/glk.h>
 #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
+ * &mdash; for example, in the title bar of a window. A typical use of this
+ * function would be:
+ * |[ garglk_set_program_name("SuperGlkFrotz 0.1"); ]|
+ *
+ * <warning><para>This function is not currently implemented.</para></warning>
+ */
+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 &mdash; 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");
+ * ]|
+ *
+ * <warning><para>This function is not currently implemented.</para></warning>
+ */
+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 &mdash; 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"); ]|
+ *
+ * <warning><para>This function is not currently implemented.</para></warning>
+ */
+void 
+garglk_set_story_name(const char *name)
+{
+       WARNING(_("Not implemented"));
+}
+
+/**
+ * garglk_set_line_terminators:
+ * @win: A window.
+ * @keycodes: An array of <code>keycode_</code> 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.
+ *
+ * <warning><para>This function is not currently implemented.</para></warning>
+ */
+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.
+ *
+ * <warning><para>This function is not currently implemented.</para></warning>
+ */
+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.
+ *
+ * <warning><para>This function is not currently implemented.</para></warning>
+ */
+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 <code>zcolor_</code> constants.
+ * @bg: one of the <code>zcolor_</code> 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.
+ *
+ * <warning><para>This function is not currently implemented.</para></warning>
+ */
+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) );
 }
-
index a4dfba6a3a503ee191c9173577e6923a8867c324..1ca8fbe2e1a549903594706085c018ed91238685 100644 (file)
@@ -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.
+ *
+ * <note><title>Chimara</title><para>
+ *   Currently, in Chimara, the functions are defined, but most of them are
+ *   not implemented. That is, you can call them, but they do nothing.
+ * </para></note>
+ */
+#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 <keycap>Delete</keycap> or 
+ * <keycap>Backspace</keycap> key, Gargoyle defines a separate constant
+ * %keycode_Erase to represent <emphasis>only</emphasis> the 
+ * <keycap>Delete</keycap> key. In character input, <keycap>Delete</keycap> is
+ * still reported as %keycode_Delete, but the two are distinguished in 
+ * garglk_set_line_terminators().
+ */
+#define keycode_Erase    (0xffffef7f)
+
 #endif /* __GARGLK_H__ */