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().
*/