Updated Gargoyle extensions and documentation

Brought garglk.h to the latest revision of the Gargoyle extensions to
Glk - removed garglk_set_line_terminators(), added
garglk_set_story_title(), and updated the documentation.

diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt
index 4a4e2af79c0d15ca2e15a4356ec07a605399a780..e6fdae798f04479d8693cb7c3aec696b55c6dbd4 100644 (file)
--- a/docs/reference/chimara-sections.txt
+++ b/docs/reference/chimara-sections.txt
@@ -684,7 +684,7 @@ garglk_fileref_get_name
 garglk_set_program_name
 garglk_set_program_info
 garglk_set_story_name
-garglk_set_line_terminators
+garglk_set_story_title
 garglk_unput_string
 garglk_unput_string_uni
 garglk_set_zcolors
@@ -699,6 +699,4 @@ zcolor_Transparent
 keycode_Erase
 keycode_MouseWheelUp
 keycode_MouseWheelDown
-<SUBSECTION Private>
-zcolor_NUMCOLORS
 </SECTION>

diff --git a/libchimara/garglk.c b/libchimara/garglk.c
index 78bdfd5015033dce59d2ebd8edf14a1f7fe00597..a879ca85c2a104a765749d953128c298074d4c40 100644 (file)
--- a/libchimara/garglk.c
+++ b/libchimara/garglk.c
@@ -89,40 +89,19 @@ garglk_set_story_name(const char *name)
 }
 
 /**
- * garglk_set_line_terminators:
- * @win: A window.
- * @keycodes: An array of <code>keycode_</code> constants.
- * @numkeycodes: The length of @keycodes.
+ * garglk_set_story_title:
+ * @title: Title bar text for the currently running story.
  *
- * 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 a hint to the library to put @title in the title bar of the
+ * window that the Glk program is running in. It overrides
+ * garglk_set_program_name() and garglk_set_story_name(), if they were displayed
+ * in the title bar, although they may still be displayed somewhere else.
  *
  * <warning><para>This function is not currently implemented.</para></warning>
  */
-void 
-garglk_set_line_terminators(winid_t win, const glui32 *keycodes, glui32 numkeycodes)
+void
+garglk_set_story_title(const char *title)
 {
-       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"));
 }
 

diff --git a/libchimara/garglk.h b/libchimara/garglk.h
index 1e55f5b0d6b0f6d7c3892e4371382ae1c3c45e2f..9e4d68bd4708937308514a396ac17f6716b7f4bc 100644 (file)
--- a/libchimara/garglk.h
+++ b/libchimara/garglk.h
@@ -23,25 +23,36 @@ 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);
-
+extern void garglk_set_story_title(const char *title);
 /*
  This function is not implemented even in Gargoyle. Looks like it was planned, 
  but never added.
 extern void garglk_set_config(const char *name);
 */
 
-/* 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);
-
 /* garglk_unput_string - removes the specified string from the end of the output buffer, if
  * indeed it is there. */
 extern void garglk_unput_string(char *str);
 extern void garglk_unput_string_uni(glui32 *str);
 
-/* TODO document */
+/**
+ * zcolor_Transparent:
+ *
+ * Z-machine color constant representing no color, i.e. transparency.
+ *
+ * <warning><para>Passing this constant to garglk_set_zcolors() or
+ * garglk_set_zcolors_stream() is not currently implemented.</para></warning>
+ */
 #define zcolor_Transparent   (-4)
-/* TODO document */
+/**
+ * zcolor_Cursor:
+ *
+ * Z-machine color constant representing the color at the current position of
+ * the cursor.
+ *
+ * <warning><para>Passing this constant to garglk_set_zcolors() or
+ * garglk_set_zcolors_stream() is not currently implemented.</para></warning>
+ */
 #define zcolor_Cursor        (-3)
 /**
  * zcolor_Current:
@@ -70,12 +81,22 @@ extern void garglk_set_reversevideo_stream(strid_t str, glui32 reverse);
  * %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().
+ * glk_set_terminators_line_event().
  */
 #define keycode_Erase    (0xffffef7f)
-/* TODO document */
+/**
+ * keycode_MouseWheelUp:
+ *
+ * This key code represents the mouse wheel scrolling up in a window. It is
+ * never used in Chimara.
+ */
 #define keycode_MouseWheelUp        (0xffffeffe)
-/* TODO document */
+/**
+ * keycode_MouseWheelDown:
+ *
+ * This key code represents the mouse wheel scrolling down in a window. It is
+ * never used in Chimara.
+ */
 #define keycode_MouseWheelDown      (0xffffefff)
 
 #endif /* __GARGLK_H__ */