From 96eba2611d3efe92e3cb22745cb2eca26fafc6c6 Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Sat, 5 Dec 2009 21:40:47 +0000 Subject: [PATCH] Brought documentation up to date git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@202 ddfedd41-794f-dd11-ae45-00112f111e67 --- docs/reference/chimara-docs.sgml | 4 +- libchimara/doc.c | 63 ++++++++++++++++++++++++++++ libchimara/hyperlink.c | 71 +++++++++++++++++++++++++------- 3 files changed, 122 insertions(+), 16 deletions(-) diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml index 412d6a0..422118c 100644 --- a/docs/reference/chimara-docs.sgml +++ b/docs/reference/chimara-docs.sgml @@ -116,13 +116,13 @@ --> - + diff --git a/libchimara/doc.c b/libchimara/doc.c index 092eda2..a3c3ead 100644 --- 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 e58f981..a2795bd 100644 --- 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) { -- 2.30.2