* 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
* 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:
*
* |[ 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:
* 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)
/**
* 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);
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)
{
}
+/**
+ * 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)
{
projects / rodin / chimara.git / commitdiff