Brought documentation up to date

diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml
index 412d6a09303c39d52943f453ab63e1885dbe95d7..422118c6e76890f6ee3f294515d0a930534a47a2 100644 (file)
--- a/docs/reference/chimara-docs.sgml
+++ b/docs/reference/chimara-docs.sgml
@@ -116,13 +116,13 @@
     </chapter>
 -->    
     <!-- Chapter 9. Hyperlinks -->
-<!--    <chapter>
+    <chapter>
       <title>Hyperlinks</title>
       <xi:include href="xml/glk-creating-hyperlinks.xml"/>
       <xi:include href="xml/glk-accepting-hyperlinks.xml"/>
       <xi:include href="xml/glk-hyperlinks-testing.xml"/>
     </chapter>
--->    
+    
     <!-- Chapter 10. Porting, Adapting and Other Messy Bits -->
     <xi:include href="glk-porting.sgml"/>
    

diff --git a/libchimara/doc.c b/libchimara/doc.c
index 092eda2ee0fd874666dcc767d02f3acc4c082ddd..a3c3ead301026f6168af2877948058819574c67b 100644 (file)
--- a/libchimara/doc.c
+++ b/libchimara/doc.c
@@ -840,6 +840,33 @@
  * else.
  */
 
+/**
+ * SECTION:glk-creating-hyperlinks
+ * @short_description: Printing text as a hyperlink
+ * @include: libchimara/glk.h
+ *
+ * Some games may wish to mark up text in their windows with hyperlinks, which
+ * can be selected by the player — most likely by mouse click. Glk allows
+ * this in a manner similar to the way text styles are set.
+ *
+ * Hyperlinks are an optional capability in Glk.
+ */
+
+/**
+ * SECTION:glk-accepting-hyperlinks
+ * @short_description: Generating and catching hyperlink navigation events
+ * @include: libchimara/glk.h
+ */
+
+/**
+ * SECTION:glk-hyperlinks-testing
+ * @short_description: Checking whether the library supports hyperlinks
+ * @include: libchimara/glk.h
+ *
+ * Before calling Glk hyperlink functions, you should use the gestalt selectors
+ * %gestalt_Hyperlinks and %gestalt_HyperlinkInput.
+ */
+ 
 /**
  * SECTION:dispatch-interrogating
  * @short_description: Finding out what functions the Glk library exports
@@ -1001,6 +1028,14 @@
  * constants (see %gestalt_Unicode). If not, not.
  */
 
+/**
+ * GLK_MODULE_HYPERLINKS:
+ * 
+ * If you are writing a C program, you can perform a preprocessor test for the
+ * existence of %GLK_MODULE_HYPERLINKS. If this is defined, so are all the
+ * functions and constants described in this section. If not, not.
+ */
+
 /**
  * winid_t:
  *
@@ -1201,6 +1236,34 @@
  * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]|
  * This returns 1 if timer events are supported, and 0 if they are not.
  */
+
+/**
+ * gestalt_Hyperlinks:
+ *
+ * You can test whether the library supports hyperlinks:
+ * |[ 
+ * #glui32 res;
+ * res = #glk_gestalt(#gestalt_Hyperlinks, 0); 
+ * ]|
+ * This returns 1 if the overall suite of hyperlinks functions is available.
+ * This includes glk_set_hyperlink(), glk_set_hyperlink_stream(),
+ * glk_request_hyperlink_event(), glk_cancel_hyperlink_event().
+ *
+ * If this selector returns 0, you should not try to call these functions. They
+ * may have no effect, or they may cause a run-time error.
+ */
+
+/**
+ * gestalt_HyperlinkInput:
+ *
+ * You can test whether hyperlinks are supported with the 
+ * %gestalt_HyperlinkInput selector:
+ * |[ res = #glk_gestalt(#gestalt_HyperlinkInput, windowtype); ]|
+ * This will return %TRUE (1) if windows of the given type support hyperlinks.
+ * If this returns %FALSE (0), it is still legal to call glk_set_hyperlink() and
+ * glk_request_hyperlink_event(), but they will have no effect, and you will
+ * never get hyperlink events.
+ */
  
 /**
  * evtype_None:

diff --git a/libchimara/hyperlink.c b/libchimara/hyperlink.c
index e58f9818f8d58c8310ff2b000cd533ea630e76d0..a2795bdc83fb0861e598a3adaa626d1fcb04c884 100644 (file)
--- a/libchimara/hyperlink.c
+++ b/libchimara/hyperlink.c
@@ -8,13 +8,8 @@ extern GPrivate *glk_data_key;
  * glk_set_hyperlink:
  * @linkval: Set to nonzero to initiate hyperlink mode. Set to zero to disengage.
  *
- * Use this function to create hyperlinks in a textbuffer. It sets the current stream
- * to hyperlink mode, after which text will become a hyperlink until hyperlink mode
- * is turned off. If the current stream does not write to a textbuffer window, this function
- * does nothing.
- *
- * You can request hyperlink events with glk_request_hyperlink_event() to react
- * to clicks on the link.
+ * This call sets the current link value in the current output stream. See
+ * glk_set_hyperlink_stream().
  */
 void 
 glk_set_hyperlink(glui32 linkval)
@@ -27,20 +22,39 @@ glk_set_hyperlink(glui32 linkval)
 /**
  * glk_set_hyperlink_stream:
  * @str: The stream to set the hyperlink mode on.
- * @linkval: Set to nonzero to initiate hyperlink mode. Set to zero to disengage.
+ * @linkval: Set to non-zero to initiate hyperlink mode. Set to zero to 
+ * disengage.
+ *
+ * This call sets the current link value on the specified output stream. A link
+ * value is any non-zero integer; zero indicates no link. Subsequent text output
+ * is considered to make up the body of the link, which continues until the link
+ * value is changed (or set to zero).
  *
- * Use this function to create hyperlinks in a textbuffer. It sets a stream to a textbuffer
- * window to hyperlink mode, after which text will become a hyperlink until hyperlink mode
- * is turned off. Calling this function on a stream that does not write to a textbuffer does
- * nothing.
+ * Note that it is almost certainly useless to change the link value of a stream
+ * twice with no intervening text. The result will be a zero-length link, which 
+ * the player probably cannot see or select; the library may optimize it out 
+ * entirely.
  *
- * You can request hyperlink events with glk_request_hyperlink_event() to react
- * to clicks on the link.
+ * Setting the link value of a stream to the value it already has, has no 
+ * effect.
+ *
+ * If the library supports images, they take on the current link value as they 
+ * are output, just as text does. The player can select an image in a link just 
+ * as he does text. (This includes margin-aligned images, which can lead to some 
+ * peculiar situations, since a right-margin image may not appear directly 
+ * adjacent to the text it was output with.)
+ * 
+ * The library will attempt to display links in some distinctive way (and it 
+ * will do this whether or not hyperlink input has actually been requested for 
+ * the window). Naturally, blue underlined text is most likely. Link images may 
+ * not be distinguished from non-link images, so it is best not to use a 
+ * particular image both ways. 
  */
 void 
 glk_set_hyperlink_stream(strid_t str, glui32 linkval)
 {
        g_return_if_fail(str != NULL);
+       g_return_if_fail(str->type == STREAM_TYPE_WINDOW);
        g_return_if_fail(str->window != NULL);
        g_return_if_fail(str->window->type == wintype_TextBuffer);
 
@@ -97,6 +111,28 @@ hyperlink_block_event_handler(gpointer key, gpointer value, gpointer user_data)
        g_signal_handler_block(link->tag, link->event_handler);
 }
 
+/**
+ * glk_request_hyperlink_event:
+ * @win: The window to request a hyperlink event on.
+ *
+ * This call works like glk_request_char_event(), glk_request_line_event() and
+ * glk_request_mouse_event(). A pending request on a window remains pending 
+ * until the player selects a link, or the request is cancelled.
+ *
+ * A window can have hyperlink input and mouse, character, or line input pending
+ * at the same time. However, if hyperlink and mouse input are requested at the
+ * same time, the library may not provide an intuitive way for the player to 
+ * distingish which a mouse click represents. Therefore, this combination should
+ * be avoided.
+ *
+ * When a link is selected in a window with a pending request, glk_select() will
+ * return an event of type %evtype_Hyperlink. In the event structure, @win tells
+ * what window the event came from, and @val1 gives the (non-zero) link value.
+ * 
+ * If no hyperlink request is pending in a window, the library will ignore 
+ * attempts to select a link. No %evtype_Hyperlink event will be generated 
+ * unless it has been requested. 
+ */
 void 
 glk_request_hyperlink_event(winid_t win)
 {
@@ -108,6 +144,13 @@ glk_request_hyperlink_event(winid_t win)
 
 }
 
+/**
+ * glk_cancel_hyperlink_event:
+ * @win: The window in which to cancel the hyperlink event request.
+ *
+ * This call works like glk_cancel_char_event(), glk_cancel_line_event(), and
+ * glk_cancel_mouse_event(). See glk_request_hyperlink_event().
+ */
 void 
 glk_cancel_hyperlink_event(winid_t win)
 {