X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fdoc.c;h=3c04ce31abdf6c2ea348ff09ac02446588f4c7fe;hb=f19a194bd066ea4320c1c6b6b8c5a375f7787af5;hp=df84c6f2d942c95fbb480736578f2b2146464a6b;hpb=2da183ac47f1157560dcd2c417f7f6a24ae72352;p=projects%2Fchimara%2Fchimara.git diff --git a/libchimara/doc.c b/libchimara/doc.c index df84c6f..3c04ce3 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -138,7 +138,7 @@ * * When you create one of these objects, it is always possible that the creation * will fail (due to lack of memory, or some other OS error.) When this happens, - * the allocation function will return %NULL (0) instead of a valid pointer. You + * the allocation function will return %NULL instead of a valid pointer. You * should always test for this possibility. * * %NULL is never the identifier of any object (window, stream, file reference, @@ -375,6 +375,25 @@ * functions act on whole strings, since the length of the string may change. */ +/** + * SECTION:glk-normalize + * @short_description: Combining characters + * @include: libchimara/glk.h + * + * Comparing Unicode strings is difficult, because there can be several ways to + * represent a piece of text as a Unicode string. For example, the one-character + * string è (an accented e) will be + * displayed the same as the two-character string containing e + * followed by Unicode character 0x0300 (COMBINING GRAVE ACCENT). These strings + * should be considered equal. + * + * Therefore, a Glk program that accepts line input should convert its text to a + * normalized form before parsing it. These functions offer those conversions. + * The algorithms are defined by the Unicode spec (chapter 3.7) and Unicode Standard Annex + * #15. + */ + /** * SECTION:glk-window-opening * @short_description: Creating new windows and closing them @@ -793,7 +812,7 @@ * * Every window has an output stream associated with it. This is created * automatically, with %filemode_Write, when you open the window. You get it - * with glk_window_get_stream(). + * with glk_window_get_stream(). Window streams always have rock value 0. * * A window stream cannot be closed with glk_stream_close(). It is closed * automatically when you close its window with glk_window_close(). @@ -883,10 +902,11 @@ * create a fileref for a nonexistent file, and then open it in write mode to * create a new file. * - * You always provide a usage argument when you create a fileref. The usage is a - * mask of constants (see below) to indicate the file type and the mode (text or - * binary.) These values are used when you create a new file, and also to filter - * file lists when the player is selecting a file to load. + * You always provide a usage argument when you create a fileref. The usage + * indicates the file type and the mode (text or binary.) It must be the + * logical-or of a file-type constant and a mode constant. These values are used + * when you create a new file, and also to filter file lists when the player is + * selecting a file to load. * * In general, you should use text mode if the player expects to read the file * with a platform-native text editor; you should use binary mode if the file is @@ -1100,6 +1120,36 @@ * Before calling Glk hyperlink functions, you should use the gestalt selectors * %gestalt_Hyperlinks and %gestalt_HyperlinkInput. */ + +/** + * SECTION:glk-clock + * @short_description: Getting the current time from the system clock + * @include: libchimara/glk.h + * + * You can get the current time, either as a Unix timestamp (seconds since 1970) + * or as a broken-out structure of time elements (year, month, day, hour, + * minute, second). + * + * The system clock is not guaranteed to line up with timer events (see Timer Events). Timer events may be + * delivered late according to the system clock. + */ + +/** + * SECTION:glk-clock-conversions + * @short_description: Converting from timestamps to date structures and back + * @include: libchimara/glk.h + * + */ + +/** + * SECTION:glk-clock-testing + * @short_description: Checking whether the library supports the clock functions + * @include: libchimara/glk.h + * + * Before calling Glk date and time functions, you should use the following + * gestalt selector. + */ /** * SECTION:dispatch-interrogating @@ -1278,7 +1328,7 @@ /** * GLK_MODULE_UNICODE: * - * If this preprocessor symbol is defined, so are all the Unicode functions and + * If this preprocessor symbol is defined, so are the core Unicode functions and * constants (see %gestalt_Unicode). If not, not. */ @@ -1334,6 +1384,21 @@ * functions and constants described in this section. If not, not. */ +/** + * GLK_MODULE_UNICODE_NORM: + * + * If this preprocessor symbol is defined, so are the Unicode normalization + * functions (see %gestalt_UnicodeNorm). If not, not. + */ + +/** + * GLK_MODULE_DATETIME: + * + * If you are writing a C program, you can perform a preprocessor test for the + * existence of %GLK_MODULE_DATETIME. If this is defined, so are all the + * functions and data types described in this section. + */ + /** * winid_t: * @@ -1380,8 +1445,8 @@ * So the version number 78.2.11 would be encoded as 0x004E020B. * * - * The current Glk specification version is 0.7.0, so this selector will return - * 0x00000700. + * The current Glk specification version is 0.7.2, so this selector will return + * 0x00000702. * * |[ * glui32 res; @@ -1452,11 +1517,13 @@ * * * Make sure you do not get confused by signed byte values. If you set a - * char variable ch to 0xFE, the - * small-thorn character (þ), and then call + * signed char variable ch to 0xFE, + * the small-thorn character (þ), it will wind up as -2. (The same is + * true of a char variable, if your compiler + * treats char as signed!) If you then call * |[ res = glk_gestalt(gestalt_CharOutput, ch); ]| * then (by the definition of C/C++) ch will be sign-extended to - * 0xFFFFFFFE, which is not a legitimate character, even in Unicode. You + * 0xFFFFFFFE, which is not a legitimate character, even in Unicode. You * should write * |[ res = glk_gestalt(gestalt_CharOutput, (unsigned char)ch); ]| * instead. @@ -1517,7 +1584,8 @@ * * You can test whether the library supports timer events: * |[ res = glk_gestalt(gestalt_Timer, 0); ]| - * This returns 1 if timer events are supported, and 0 if they are not. + * This returns %TRUE (1) if timer events are supported, and %FALSE (0) if they + * are not. */ /** @@ -1544,7 +1612,7 @@ * gestalt_DrawImage: * * This selector returns 1 if images can be drawn in windows of the given type. - * If it returns 0, glk_image_draw() will fail and return %FALSE. You should + * If it returns 0, glk_image_draw() will fail and return %FALSE (0). You should * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries * may implement both, neither, or only one. */ @@ -1653,14 +1721,14 @@ * * The basic text functions will be available in every Glk library. The Unicode * functions may or may not be available. Before calling them, you should use - * the following gestalt selector: + * the %gestalt_Unicode and %gestalt_UnicodeNorm gestalt selectors. + * * |[ * glui32 res; * res = glk_gestalt(gestalt_Unicode, 0); * ]| - * - * This returns 1 if the Unicode functions are available. If it returns 0, you - * should not try to call them. They may print nothing, print gibberish, or + * This returns 1 if the core Unicode functions are available. If it returns 0, + * you should not try to call them. They may print nothing, print gibberish, or * cause a run-time error. The Unicode functions include * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(), * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(), @@ -1679,9 +1747,81 @@ * errors. * * To avoid this, you can perform a preprocessor test for the existence of - * #GLK_MODULE_UNICODE. + * %GLK_MODULE_UNICODE. */ - + +/** + * gestalt_UnicodeNorm: + * + * |[ + * glui32 res; + * res = glk_gestalt(gestalt_UnicodeNorm, 0); + * ]| + * This code returns 1 if the Unicode normalization functions are available. If + * it returns 0, you should not try to call them. The Unicode normalization + * functions include glk_buffer_canon_decompose_uni() and + * glk_buffer_canon_normalize_uni(). + * + * The equivalent preprocessor test for these functions is + * %GLK_MODULE_UNICODE_NORM. + */ + +/** + * gestalt_LineInputEcho: + * + * |[ + * res = glk_gestalt(gestalt_LineInputEcho, 0); + * ]| + * + * This returns 1 if glk_set_echo_line_event() is supported, and 0 if it is not. + * + * Remember that if it is not supported, the behavior is always the default, + * which is line echoing enabled. + * + */ + +/** + * gestalt_LineTerminators: + * + * |[ + * res = glk_gestalt(gestalt_LineTerminators, 0); + * ]| + * + * This returns 1 if glk_set_terminators_line_event() is supported, and 0 if it + * is not. + */ + +/** + * gestalt_LineTerminatorKey: + * + * |[ + * res = glk_gestalt(gestalt_LineTerminatorKey, ch); + * ]| + * + * This returns 1 if the keycode @ch can be passed to + * glk_set_terminators_line_event(). If it returns 0, that keycode will be + * ignored as a line terminator. Printable characters and %keycode_Return will + * always return 0. + */ + +/** + * gestalt_DateTime: + * + * |[ + * res = glk_gestalt(gestalt_DateTime, 0); + * ]| + * + * This returns 1 if the overall suite of system clock functions, as described + * in this chapter, is available. + * + * 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. + * + * + * Glk timer events are covered by a different selector. See %gestalt_Timer. + * + */ + /** * evtype_None: * @@ -1720,19 +1860,26 @@ * A full line of input completed in a window. See Line Input Events. * - * If a window has a pending request for line input, and the player hits - * enter in that window (or whatever action is appropriate to - * enter his input), glk_select() will return an event whose type is - * %evtype_LineInput. Once this happens, the request is complete; it is no - * longer pending. You must call glk_request_line_event() if you want another + * If a window has a pending request for line input, the player can generally + * hit the enter key (in that window) to complete line input. + * The details will depend on the platform's native user interface. + * + * When line input is completed, glk_select() will return an event whose type is + * %evtype_LineInput. Once this happens, the request is complete; it is no + * longer pending. You must call glk_request_line_event() if you want another * line of text from that window. - * - * In the event structure, @win tells what window the event came from. @val1 - * tells how many characters were entered. @val2 will be 0. The characters - * themselves are stored in the buffer specified in the original - * glk_request_line_event() or glk_request_line_event_uni() call. * - * There is no null terminator stored in the buffer. + * In the event structure, @win tells what window the event came from. @val1 + * tells how many characters were entered. @val2 will be 0 unless input was + * ended by a special terminator key, in which case @val2 will be the keycode + * (one of the values passed to glk_set_terminators_line_event()). + * + * The characters themselves are stored in the buffer specified in the original + * glk_request_line_event() or glk_request_line_event_uni() call. + * + * + * There is no null terminator or newline stored in the buffer. + * * * It is illegal to print anything to a window which has line input pending. * @@ -2224,14 +2371,22 @@ * result. * * - * When the player finishes his line of input, the library will display the - * input text at the end of the buffer text (if it wasn't there already.) It - * will be followed by a newline, so that the next text you print will start a - * new line (paragraph) after the input. + * By default, when the player finishes his line of input, the library will + * display the input text at the end of the buffer text (if it wasn't there + * already.) It will be followed by a newline, so that the next text you print + * will start a new line (paragraph) after the input. * * If you call glk_cancel_line_event(), the same thing happens; whatever text * the user was composing is visible at the end of the buffer text, followed by * a newline. + * + * However, this default behavior can be changed with the + * glk_set_echo_line_event() call. If the default echoing is disabled, the + * library will not display the input text (plus newline) + * after input is either completed or cancelled. The buffer will end with + * whatever prompt you displayed before requesting input. If you want the + * traditional input behavior, it is then your responsibility to print the text, + * using the Input text style, followed by a newline (in the original style). */ /** @@ -2248,8 +2403,10 @@ * * When you print, the characters of the output are laid into the array in * order, left to right and top to bottom. When the cursor reaches the end of a - * line, it goes to the beginning of the next line. The library makes no attempt - * to wrap lines at word breaks. + * line, or if a newline (0x0A) is printed, the cursor goes to the beginning of + * the next line. The library makes no attempt to wrap + * lines at word breaks. If the cursor reaches the end of the last line, further + * printing has no effect on the window until the cursor is moved. * * * Note that printing fancy characters may cause the cursor to advance more @@ -2301,7 +2458,8 @@ * When the player finishes his line of input, it will remain visible in the * window, and the output cursor will be positioned at the beginning of the * next row. Again, if you glk_cancel_line_event(), the - * same thing happens. + * same thing happens. The glk_set_echo_line_event() call has no effect in grid + * windows. */ /** @@ -2315,7 +2473,7 @@ * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics * Windows. * - * When a text grid window is resized smaller, the bottom or right area is + * When a graphics window is resized smaller, the bottom or right area is * thrown away, but the remaining area stays unchanged. When it is resized * larger, the new bottom or right area is filled with the background color. * @@ -2406,7 +2564,24 @@ * When calling glk_window_open() with this @method, the new window will be * a given proportion of the old window's size. (See glk_window_open()). */ - + +/** + * winmethod_Border: + * + * When calling glk_window_open() with this @method, it specifies that there + * should be a visible window border between the new window and its sibling. + * (This is a hint to the library.) + */ + +/** + * winmethod_NoBorder: + * + * When calling glk_window_open() with this @method, it specifies that there + * should not be a visible window border between the new window and its sibling. + * (This is a hint to the library; you might specify NoBorder between two + * graphics windows that should form a single image.) + */ + /** * fileusage_Data: * @@ -2507,7 +2682,15 @@ * existed in the destination, instead of replacing it. * * - * Corresponds to mode "a" in the stdio library, using fopen(). + * Confusingly, %filemode_WriteAppend cannot be mode "a", because + * the stdio spec says that when you open a file with mode "a", + * then fseek() doesn't work. So we have to use mode "r+" for + * appending. Then we run into the other stdio problem, + * which is that "r+" never creates a new file. So + * %filemode_WriteAppend has to first open the file with + * "a", close it, reopen with "r+", and then fseek() + * to the end of the file. For %filemode_ReadWrite, the process is the same, + * except without the fseek() — we begin at the beginning of the file. * */ @@ -2688,6 +2871,11 @@ * * Margin images are not implemented yet. */ + +/** + * glktimeval_t: + * + */ /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/ @@ -2735,6 +2923,13 @@ * This structure simply contains a string and a value. The string is a * symbolic name of the value, and can be re-exported to anyone interested in * using Glk constants. + * + * + * In the current gi_dispa.c library, these structures + * are static and immutable, and will never be deallocated. However, it is + * safer to assume that the structure may be reused in future + * gidispatch_get_intconst() calls. + * */ /** @@ -2754,6 +2949,11 @@ * 1, where N is the value returned by * gidispatch_count_functions(). * + * + * Again, it is safest to assume that the structure is only valid until the + * next gidispatch_get_function() or gidispatch_get_function_by_id() call. + * + * * Returns: A #gidispatch_function_t structure describing the function. */ @@ -2787,6 +2987,11 @@ * Returns a structure describing the Glk function with selector @id. If there * is no such function in the library, this returns %NULL. * + * + * Again, it is safest to assume that the structure is only valid until the + * next gidispatch_get_function() or gidispatch_get_function_by_id() call. + * + * * Returns: a #gidispatch_function_t structure, or %NULL. */ @@ -2801,7 +3006,8 @@ * the list of arguments, and @numargs is the length of the list. * * The arguments are all stored as #gluniversal_t objects. - * Basic Types + * Basic Dispatch + * Types * Numeric arguments are passed in the obvious way — one argument per * #gluniversal_t, with the @uint or @sint field set to the numeric value. * Characters and strings are also passed in this way — #chars in @@ -2818,10 +3024,11 @@ * #glui32*, #winid_t*, and so on — takes * one or two #gluniversal_t objects. The first is a flag * indicating whether the reference argument is %NULL or not. The @ptrflag field - * of this #gluniversal_t should be %FALSE if the reference is %NULL, and %TRUE - * otherwise. If %FALSE, that is the end of the argument; you should not use a - * #gluniversal_t to explicitly store the %NULL reference. If the flag is %TRUE, - * you must then put a #gluniversal_t storing the base type of the reference. + * of this #gluniversal_t should be %FALSE (0) if the reference is %NULL, and + * %TRUE (1) otherwise. If %FALSE, that is the end of the argument; you should + * not use a #gluniversal_t to explicitly store the %NULL reference. If the flag + * is %TRUE, you must then put a #gluniversal_t storing the base type of the + * reference. * * For example, consider a hypothetical function, with selector * 0xABCD: @@ -3073,8 +3280,7 @@ * * * - * Any type code can be prefixed with one or more of the following characters - * (order does not matter): + * Any type code can be prefixed with one or more of the following characters: * * * & @@ -3160,6 +3366,61 @@ * * * + * The order of these characters and prefixes is not completely arbitrary. Here + * is a formal grammar for the prototype strings. + * + * Thanks to Neil Cerutti for working this out. + * + * + * + * prototype + * ArgCount [ arg_list ] + * ':' [ arg ] EOL + * + * + * arg_list + * arg { arg } + * + * + * arg + * TypeName | ref_type + * + * + * + * ref_type + * RefType [ '+' ] target_type + * + * + * target_type + * TypeName | array | + * struct + * + * + * array + * '#' [ '!' ] TypeName + * + * + * struct + * '[' ArgCount [ arg_list + * ] ']' + * + * + * + * TypeName is I[us]|C[nus]|S|U|F|Q[a-z] + * + * + * + * ArgCount is \d+ + * + * + * RefType is &|<|> + * + * + * EOL is end of input + * + * * Returns: A string which encodes the prototype of the specified Glk function. */ @@ -3327,14 +3588,13 @@ /** * giblorb_result_t: * @chunknum: The chunk number (for use in giblorb_unload_chunk(), etc.) - * @data: A union containing a pointer to the data @ptr (if you used - * %giblorb_method_Memory) and the position in the file @startpos (if you used - * %giblorb_method_FilePos) * @length: The length of the data * @chunktype: The type of the chunk. * * Holds information about a chunk loaded from a Blorb file, and the method of - * accessing the chunk data. See giblorb_load_chunk_by_type() and + * accessing the chunk data. @data is a union of @ptr, a pointer to the data (if + * you used %giblorb_method_Memory) and @startpos, the position in the file (if + * you used %giblorb_method_FilePos). See giblorb_load_chunk_by_type() and * giblorb_load_chunk_by_number(). */