X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fdoc.c;h=c45859f7b5cb7e8535ed8aa3807158cc0d7bdad1;hb=cbb35cca;hp=e599ff22d3f928d331ac07ac4dc2cb80bcb9f821;hpb=beda346223d81061b1c6f8aa444988650c105333;p=projects%2Fchimara%2Fchimara.git diff --git a/libchimara/doc.c b/libchimara/doc.c index e599ff2..c45859f 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -7,7 +7,6 @@ /** * SECTION:glk-exiting * @short_description: How to terminate a Glk program cleanly - * @include: libchimara/glk.h * * A Glk program usually ends when the end of the glk_main() function is * reached. You can also terminate it earlier. @@ -17,7 +16,6 @@ * SECTION:glk-interrupt * @short_description: Specifying an interrupt handler for cleaning up critical * resources - * @include: libchimara/glk.h * * Most platforms have some provision for interrupting a program — * command @@ -34,7 +32,6 @@ /** * SECTION:glk-tick * @short_description: Yielding time to the operating system - * @include: libchimara/glk.h * * Many platforms have some annoying thing that has to be done every so often, * or the gnurrs come from the voodvork out and eat your computer. @@ -48,7 +45,6 @@ /** * SECTION:glk-types * @short_description: Basic types used in Glk - * @include: libchimara/glk.h * * For simplicity, all the arguments used in Glk calls are of a very few types. * @@ -96,7 +92,6 @@ /** * SECTION:glk-opaque-objects * @short_description: Complex objects in Glk - * @include: libchimara/glk.h * * Glk keeps track of a few classes of special objects. These are opaque to your * program; you always refer to them using pointers to opaque C structures. @@ -138,7 +133,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, @@ -158,6 +153,7 @@ * Glk through a virtual machine, matters will probably be different. Opaque * objects may be represented as integers, or as VM objects of some sort. * + * * * Rocks * @@ -230,7 +226,6 @@ /** * SECTION:glk-gestalt * @short_description: Testing Glk's capabilities - * @include: libchimara/glk.h * * The gestalt mechanism (cheerfully stolen from the Mac OS) is a * system by which the Glk API can be upgraded without making your life @@ -247,7 +242,6 @@ /** * SECTION:glk-character-input * @short_description: Waiting for a single keystroke - * @include: libchimara/glk.h * * You can request that the player hit a single key. See Character Input Events. @@ -366,7 +360,6 @@ /** * SECTION:glk-case * @short_description: Changing the case of strings - * @include: libchimara/glk.h * * Glk has functions to manipulate the case of both Latin-1 and Unicode strings. * One Latin-1 lowercase character corresponds to one uppercase character, and @@ -374,10 +367,27 @@ * functions act on whole strings, since the length of the string may change. */ +/** + * SECTION:glk-normalize + * @short_description: Combining characters + * + * 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 - * @include: libchimara/glk.h * * You can open a new window using glk_window_open() and close it again using * glk_window_close(). @@ -386,7 +396,6 @@ /** * SECTION:glk-window-constraints * @short_description: Manipulating the size of a window - * @include: libchimara/glk.h * * There are library functions to change and to measure the size of a window. */ @@ -394,7 +403,6 @@ /** * SECTION:glk-window-types * @short_description: Blank, pair, text grid, text buffer, and graphics windows - * @include: libchimara/glk.h * * A technical description of all the window types, and exactly how they behave. */ @@ -402,7 +410,6 @@ /** * SECTION:glk-echo-streams * @short_description: Creating a copy of a window's output - * @include: libchimara/glk.h * * Every window has an associated window stream; you print to the window by * printing to this stream. However, it is possible to attach a second stream to @@ -446,7 +453,6 @@ /** * SECTION:glk-window-other * @short_description: Miscellaneous functions for windows - * @include: libchimara/glk.h * * This section contains functions for windows that don't fit anywhere else. */ @@ -454,7 +460,6 @@ /** * SECTION:glk-events * @short_description: Waiting for events - * @include: libchimara/glk.h * * As described in Your * Program's Main Function, all player input is handed to your program by @@ -465,7 +470,6 @@ /** * SECTION:glk-character-input-events * @short_description: Events representing a single keystroke - * @include: libchimara/glk.h * * You can request character input from text buffer and text grid windows. See * %evtype_CharInput. There are separate functions for requesting Latin-1 input @@ -475,7 +479,6 @@ /** * SECTION:glk-line-input-events * @short_description: Events representing a line of user input - * @include: libchimara/glk.h * * You can request line input from text buffer and text grid windows. See * %evtype_LineInput. There are separate functions for requesting Latin-1 input @@ -485,7 +488,6 @@ /** * SECTION:glk-mouse-events * @short_description: Events representing a mouse click - * @include: libchimara/glk.h * * On some platforms, Glk can recognize when the mouse (or other pointer) is * used to select a spot in a window. You can request mouse input only in text @@ -536,7 +538,6 @@ /** * SECTION:glk-timer-events * @short_description: Events sent at fixed intervals - * @include: libchimara/glk.h * * You can request that an event be sent at fixed intervals, regardless of what * the player does. Unlike input events, timer events can be tested for with @@ -549,7 +550,6 @@ /** * SECTION:glk-streams * @short_description: Input and output abstractions - * @include: libchimara/glk.h * * All character output in Glk is done through streams. Every window has an * output stream associated with it. You can also write to files on disk; every @@ -586,6 +586,28 @@ * A stream is opened with a particular file mode, see the * filemode_ constants below. * + * + * In the stdio library, using fopen(), %filemode_Write would be mode + * "w"; %filemode_Read would be mode "r"; + * %filemode_ReadWrite would be mode "r+". 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. + * + * + * We must also obey an obscure geas of ANSI C "r+" files: you + * can't switch from reading to writing without doing an fseek() in between. + * Switching from writing to reading has the same restriction, except that an + * fflush() also works. + * + * * For information on opening streams, see the discussion of each specific type * of stream in The Types of * Streams. Remember that it is always possible that opening a stream @@ -618,7 +640,6 @@ /** * SECTION:glk-print * @short_description: Printing to streams - * @include: libchimara/glk.h * * You can print Latin-1 and Unicode characters, null-terminated strings, or * buffers to any stream. The characters will be converted into the appropriate @@ -628,7 +649,6 @@ /** * SECTION:glk-read * @short_description: Reading from streams - * @include: libchimara/glk.h * * You can read Latin-1 or Unicode characters, buffers, or whole lines from any * stream. The characters will be converted into the form in which you request @@ -638,7 +658,6 @@ /** * SECTION:glk-closing-streams * @short_description: Closing streams and retrieving their character counts - * @include: libchimara/glk.h * * When you close a Glk stream, you have the opportunity to examine the * character counts — the number of characters written to or read from the @@ -648,7 +667,6 @@ /** * SECTION:glk-stream-positions * @short_description: Moving the read/write mark - * @include: libchimara/glk.h * * You can set the position of the read/write mark in a stream. * @@ -661,7 +679,6 @@ /** * SECTION:glk-styles * @short_description: Changing the appearance of printed text - * @include: libchimara/glk.h * * You can send style-changing commands to an output stream. After a style * change, new text which is printed to that stream will be given the new style, @@ -720,7 +737,6 @@ /** * SECTION:glk-stylehints * @short_description: Setting style hints - * @include: libchimara/glk.h * * There are no guarantees of how styles will look, but you can make * suggestions. @@ -763,7 +779,6 @@ /** * SECTION:glk-style-measure * @short_description: Finding out how the library displays your style hints - * @include: libchimara/glk.h * * You can suggest the appearance of a window's style before the window is * created; after the window is created, you can test the style's actual @@ -785,14 +800,13 @@ /** * SECTION:glk-stream-types - * @short_description: Window, memory, and file streams - * @include: libchimara/glk.h + * @short_description: Window, memory, file, and resource streams * * Window Streams * * 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(). @@ -849,12 +863,35 @@ * linkend="chimara-File-References">File References. * * + * Resource Streams + * + * You can open a stream which reads from (but not writes to) a resource file. + * + * + * Typically this is embedded in a Blorb file, as Blorb is the official + * resource-storage format of Glk. A Blorb file can contain images and sounds, + * but it can also contain raw data files, which are accessed by + * glk_stream_open_resource() and glk_stream_open_resource_uni(). A data file + * is identified by number, not by a filename. The Blorb usage field will be + * 'Data'. The chunk type will be %giblorb_ID_TEXT for text + * resources, %giblorb_ID_BINA for binary resources. + * + * + * + * If the running program is not associated with a Blorb file, the library may + * look for data files as actual files instead. These would be named + * DATA1, DATA2, etc, with a suffix + * distinguishing text and binary files. See Other Resource + * Arrangements in the Blorb spec: + * + * + * */ /** * SECTION:glk-stream-other * @short_description: Miscellaneous functions for streams - * @include: libchimara/glk.h * * This section includes functions for streams that don't fit anywhere else. */ @@ -862,7 +899,6 @@ /** * SECTION:glk-fileref * @short_description: A platform-independent way to refer to disk files - * @include: libchimara/glk.h * * You deal with disk files using file references. Each fileref is an opaque C * structure pointer; see Opaque @@ -882,10 +918,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 @@ -898,7 +935,6 @@ /** * SECTION:glk-fileref-types * @short_description: Four different ways to create a file reference - * @include: libchimara/glk.h * * There are four different functions for creating a fileref, depending on how * you wish to specify it. Remember that it is always possible that a fileref @@ -908,7 +944,6 @@ /** * SECTION:glk-fileref-other * @short_description: Miscellaneous functions for file references - * @include: libchimara/glk.h * * This section includes functions for file references that don't fit anywhere * else. @@ -917,7 +952,6 @@ /** * SECTION:glk-image-resources * @short_description: Graphics in Glk - * @include: libchimara/glk.h * * In accordance with this modern age, Glk provides for a modicum of graphical * flair. It does not attempt to be a complete graphical toolkit. Those already @@ -958,7 +992,6 @@ /** * SECTION:glk-graphics-windows * @short_description: Drawing graphics in graphics windows - * @include: libchimara/glk.h * * A graphics window is a rectangular canvas of pixels, upon which you can draw * images. The contents are entirely under your control. You can draw as many @@ -993,7 +1026,6 @@ /** * SECTION:glk-graphics-text * @short_description: Drawing graphics inside or beside text - * @include: libchimara/glk.h * * A text buffer is a linear text stream. You can draw images in-line with this * text. If you are familiar with HTML, you already understand this model. You @@ -1026,7 +1058,6 @@ /** * SECTION:glk-graphics-testing * @short_description: Checking whether the library supports graphics - * @include: libchimara/glk.h * * Before calling Glk graphics functions, you should use the gestalt selector * %gestalt_Graphics. To test for additional capabilities, you can also use the @@ -1036,36 +1067,44 @@ /** * SECTION:glk-sound-channels * @short_description: Creating new sound channels and closing them - * @include: libchimara/glk.h + * + * Sounds in Glk are played through sound channels. Sound channels are another + * type of opaque object, like windows, streams, and file references. */ /** * SECTION:glk-playing-sounds * @short_description: Producing noise - * @include: libchimara/glk.h + * + * These functions play the actual sounds through the sound channels. */ /** * SECTION:glk-sound-other * @short_description: Miscellaneous functions for sound channels - * @include: libchimara/glk.h + * + * This section includes functions for sound channels that don't fit anywhere + * else. */ /** * SECTION:glk-sound-testing * @short_description: Checking whether the library supports sound - * @include: libchimara/glk.h * - * Before calling Glk sound functions, you should use the %gestalt_Sound - * selector. To test for additional capabilities, you can use the - * %gestalt_SoundMusic, %gestalt_SoundVolume, and %gestalt_SoundNotify - * selectors. + * Before calling Glk sound functions, you should use the %gestalt_Sound2 + * selector. + * + * Earlier versions of the Glk spec defined separate selectors for various + * optional capabilities. This has proven to be an unnecessarily confusing + * strategy, and is no longer used. The %gestalt_Sound, %gestalt_SoundMusic, + * %gestalt_SoundVolume, and %gestalt_SoundNotify selectors still exist, but you + * should not need to test them; the %gestalt_Sound2 selector covers all of + * them. */ /** * 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 @@ -1077,22 +1116,51 @@ /** * SECTION:glk-accepting-hyperlinks * @short_description: Generating and catching hyperlink navigation events - * @include: libchimara/glk.h + * + * When you request a hyperlink event in a window, you will receive a hyperlink + * event when the player clicks on a hyperlink. */ /** * 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:glk-clock + * @short_description: Getting the current time from the system clock + * + * 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 + * + * This section describes functions for converting timestamps to more + * human-readable date structures and back. + */ + +/** + * SECTION:glk-clock-testing + * @short_description: Checking whether the library supports the clock functions + * + * Before calling Glk date and time functions, you should use the + * %gestalt_DateTime selector. + */ /** * SECTION:dispatch-interrogating * @short_description: Finding out what functions the Glk library exports - * @include: libchimara/glk.h, libchimara/gi_dispa.h * * These are the ancilliary functions that let you enumerate. */ @@ -1100,13 +1168,13 @@ /** * SECTION:dispatch-dispatching * @short_description: Dispatching the call to the Glk library - * @include: libchimara/glk.h, libchimara/gi_dispa.h + * + * The function gidispatch_call() invokes a function from the Glk library. */ /** * SECTION:dispatch-prototypes * @short_description: Querying Glk function prototypes - * @include: libchimara/glk.h, libchimara/gi_dispa.h * * There are many possible ways to set up a #gluniversal_t array, and it's * illegal to call gidispatch_call() with an array which doesn't match the @@ -1123,7 +1191,6 @@ /** * SECTION:dispatch-library-functions * @short_description: Platform-dependent dispatch layer functions - * @include: libchimara/glk.h, libchimara/gi_dispa.h * * Ideally, the three layers — program, dispatch layer, Glk library * — would be completely modular; each would refer only to the layers @@ -1155,7 +1222,6 @@ /** * SECTION:blorb-program * @short_description: How to use the Blorb layer in your program - * @include: libchimara/glk.h, libchimara/gi_blorb.h * * If you wish your program to load its resources from a Blorb file, you need to * find and open that file in your startup code. (See gi_blorb.c. They will be compiled into the library, but @@ -1188,7 +1253,6 @@ /** * SECTION:blorb-errors * @short_description: Error codes returned by the Blorb layer functions - * @include: libchimara/glk.h, libchimara/gi_blorb.h * * All Blorb layer functions, including giblorb_set_resource_map(), return the * following error codes. @@ -1197,7 +1261,6 @@ /** * SECTION:glkext-startup * @short_description: Parsing startup options - * @include: libchimara/glk.h, libchimara/glkstart.h * * This section describes an extension to Glk for parsing command-line startup * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and @@ -1220,7 +1283,6 @@ /** * SECTION:glkext-unix * @short_description: Unix-specific functions - * @include: libchimara/glk.h, libchimara/glkstart.h * * This section describes an extension to Glk for various Unix functions. It was * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm. @@ -1233,7 +1295,6 @@ /** * SECTION:glkext-garglk * @short_description: Gargoyle extensions to Glk - * @include: libchimara/glk.h, libchimara/garglk.h * * This section describes various extensions to Glk that were written for the * popular interpreter * - * The current Glk specification version is 0.7.0, so this selector will return - * 0x00000700. + * The current Glk specification version is 0.7.4, so this selector will return + * 0x00000704. * * |[ * glui32 res; @@ -1438,11 +1536,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. @@ -1503,7 +1603,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. */ /** @@ -1530,15 +1631,29 @@ * 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. */ +/** + * gestalt_Sound2: + * + * You can test whether the library supports sound: + * |[ + * glui32 res; + * res = glk_gestalt(gestalt_Sound2, 0); + * ]| + * This returns 1 if the overall suite of sound functions is available. This + * includes all the functions defined in this chapter. It also includes the + * capabilities described below under %gestalt_SoundMusic, %gestalt_SoundVolume, + * and %gestalt_SoundNotify. + */ + /** * gestalt_Sound: * - * You can test whether the library supports sound: * |[ * glui32 res; * res = glk_gestalt(gestalt_Sound, 0); @@ -1550,7 +1665,9 @@ * glk_sound_load_hint(). * * 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. + * may have no effect, or they may cause a run-time error. + * + * This selector is guaranteed to return 1 if %gestalt_Sound2 does. */ /** @@ -1558,24 +1675,22 @@ * * You can test whether the library supports setting the volume of sound * channels: - * |[ - * glui32 res; - * res = glk_gestalt(gestalt_SoundVolume, 0); - * ]| + * |[ res = glk_gestalt(gestalt_SoundVolume, 0); ]| * This selector returns 1 if the glk_schannel_set_volume() function works. If - * it returns zero, glk_schannel_set_volume() has no effect. + * it returns zero, glk_schannel_set_volume() has no effect. + * + * This selector is guaranteed to return 1 if %gestalt_Sound2 does. */ /** * gestalt_SoundNotify: * * You can test whether the library supports sound notification events: - * |[ - * glui32 res; - * res = glk_gestalt(gestalt_SoundNotify, 0); - * ]| + * |[ res = glk_gestalt(gestalt_SoundNotify, 0); ]| * This selector returns 1 if the library supports sound notification events. If - * it returns zero, you will never get such events. + * it returns zero, you will never get such events. + * + * This selector is guaranteed to return 1 if %gestalt_Sound2 does. */ /** @@ -1619,6 +1734,8 @@ * course, an ugly hack. It is a concession to the current state of the Glk * libraries, some of which can handle AIFF but not MOD sounds. * + * + * This selector is guaranteed to return 1 if %gestalt_Sound2 does. */ /** @@ -1639,14 +1756,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(), @@ -1665,9 +1782,94 @@ * 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. + * + */ + +/** + * gestalt_ResourceStream: + * + * |[ + * res = glk_gestalt(gestalt_ResourceStream, 0); + * ]| + * + * This returns 1 if the glk_stream_open_resource() and + * glk_stream_open_resource_uni() functions are available. If it returns 0, you + * should not call them. + */ + /** * evtype_None: * @@ -1706,19 +1908,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. * @@ -1822,6 +2031,8 @@ /** * evtype_SoundNotify: * + * The completion of a sound being played in a sound channel. + * * On platforms that support sound, you can request to receive an * %evtype_SoundNotify event when a sound finishes playing. See Playing Sounds. @@ -1829,6 +2040,8 @@ /** * evtype_Hyperlink: + * + * The selection of a hyperlink in a window. * * On platforms that support hyperlinks, you can request to receive an * %evtype_Hyperlink event when the player selects a link. See . */ +/** + * evtype_VolumeNotify: + * + * The completion of a gradual volume change in a sound channel. + * + * On platforms that support sound, you can request to receive an + * %evtype_VolumeNotify event when a gradual volume change completes. See Playing Sounds. + */ + /** * event_t: * @type: the event type @@ -2210,14 +2433,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). */ /** @@ -2234,8 +2465,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 @@ -2287,7 +2520,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. */ /** @@ -2301,7 +2535,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. * @@ -2392,7 +2626,30 @@ * 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.) + * + * Chimara + * There will only be a visible border if the #ChimaraGlk:spacing property + * is nonzero. Setting #ChimaraGlk:spacing to zero disables all borders on Glk + * windows. + * + */ + +/** + * 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: * @@ -2426,7 +2683,7 @@ * linefeed-plus-carriage-return combinations; Latin-1 characters may be * converted to native character codes. When reading a file in text mode, native * line breaks will be converted back to newline (0x0A) characters, and native - * character codes may be converted to Latin-1. + * character codes may be converted to Latin-1 or UTF-8. * * * Line breaks will always be converted; other conversions are more @@ -2493,7 +2750,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. * */ @@ -2674,6 +2939,32 @@ * * Margin images are not implemented yet. */ + +/** + * glkdate_t: + * @year: The full (four-digit) year + * @month: The month number, ranging from 1-12, 1 is January + * @day: The day of the month, ranging from 1-31 + * @weekday: The day of the week, ranging from 0-6, 0 is Sunday + * @hour: The hour of the day, ranging from 0-23 + * @minute: The minute of the hour, ranging from 0-59 + * @second: The second of the minute, ranging from 0-59; may be 60 during a leap + * second + * @microsec: The fraction of the second in microseconds, ranging from 0-999999 + * + * This structure represents a human-readable date in a specific timezone. + */ + +/** + * glktimeval_t: + * @high_sec: The most significant 32 bits of the timestamp in seconds. + * @low_sec: The least significant 32 bits of the timestamp in seconds. + * @microsec: The fraction of the timestamp, in microseconds, ranging from + * 0-999999. + * + * This structure represents the Unix timestamp, i.e. the number of seconds + * since January 1, 1970. + */ /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/ @@ -2690,7 +2981,19 @@ * * Returns: Number of opaque object classes used by the library. */ - + +/** + * gidispatch_get_class: + * @index: Unique integer index of the class. + * + * Returns a structure describing an opaque class that the library exports. + * @index can range from 0 to N - + * 1N - 1, where N is the value + * returned by gidispatch_count_classes(). + * + * Returns: A #gidispatch_intconst_t structure describing the class. + */ + /** * gidispatch_count_intconst: * @@ -2721,6 +3024,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. + * */ /** @@ -2740,6 +3050,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. */ @@ -2773,6 +3088,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. */ @@ -2787,7 +3107,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 @@ -2804,10 +3125,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: @@ -3059,8 +3381,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: * * * & @@ -3146,6 +3467,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. */ @@ -3280,6 +3656,12 @@ * Resource usage constant representing an image file. */ +/** + * giblorb_ID_Data: + * + * Resource usage constant representing a data file. + */ + /** * giblorb_ID_Copyright: * @@ -3302,7 +3684,19 @@ * Resource usage constant representing any textual annotation that the user or * writing program sees fit to include. */ - + +/** + * giblorb_ID_TEXT: + * + * Resource usage constant representing a text data file. + */ + +/** + * giblorb_ID_BINA: + * + * Resource usage constant representing a binary data file. + */ + /** * giblorb_map_t: * @@ -3313,14 +3707,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(). */