X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fdoc.c;h=c45859f7b5cb7e8535ed8aa3807158cc0d7bdad1;hb=cbb35cca2d0a87a664e5d72fe71dce45c3030823;hp=3c04ce31abdf6c2ea348ff09ac02446588f4c7fe;hpb=f19a194bd066ea4320c1c6b6b8c5a375f7787af5;p=projects%2Fchimara%2Fchimara.git diff --git a/libchimara/doc.c b/libchimara/doc.c index 3c04ce3..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. @@ -231,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 @@ -248,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. @@ -367,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 @@ -378,7 +370,6 @@ /** * 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 @@ -397,7 +388,6 @@ /** * 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(). @@ -406,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. */ @@ -414,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. */ @@ -422,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 @@ -466,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. */ @@ -474,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 @@ -485,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 @@ -495,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 @@ -505,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 @@ -556,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 @@ -569,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 @@ -606,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 @@ -638,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 @@ -648,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 @@ -658,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 @@ -668,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. * @@ -681,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, @@ -740,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. @@ -783,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 @@ -805,8 +800,7 @@ /** * 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 * @@ -869,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. */ @@ -882,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 @@ -919,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 @@ -929,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. @@ -938,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 @@ -979,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 @@ -1014,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 @@ -1047,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 @@ -1057,7 +1067,6 @@ /** * 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. @@ -1066,7 +1075,6 @@ /** * SECTION:glk-playing-sounds * @short_description: Producing noise - * @include: libchimara/glk.h * * These functions play the actual sounds through the sound channels. */ @@ -1074,7 +1082,6 @@ /** * 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. @@ -1083,18 +1090,21 @@ /** * 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 @@ -1106,7 +1116,6 @@ /** * 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. @@ -1115,7 +1124,6 @@ /** * 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. @@ -1124,7 +1132,6 @@ /** * 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, @@ -1138,23 +1145,22 @@ /** * SECTION:glk-clock-conversions * @short_description: Converting from timestamps to date structures and back - * @include: libchimara/glk.h * + * 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 - * @include: libchimara/glk.h * - * Before calling Glk date and time functions, you should use the following - * gestalt selector. + * 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. */ @@ -1162,7 +1168,6 @@ /** * 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. */ @@ -1170,7 +1175,6 @@ /** * 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 @@ -1187,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 @@ -1219,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 @@ -1252,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. @@ -1261,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 @@ -1284,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. @@ -1297,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.2, so this selector will return - * 0x00000702. + * The current Glk specification version is 0.7.4, so this selector will return + * 0x00000704. * * |[ * glui32 res; @@ -1617,10 +1636,24 @@ * 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); @@ -1632,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. */ /** @@ -1640,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. */ /** @@ -1701,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. */ /** @@ -1812,7 +1847,8 @@ * ]| * * This returns 1 if the overall suite of system clock functions, as described - * in this chapter, is available. + * 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. @@ -1822,6 +1858,18 @@ * */ +/** + * 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: * @@ -1983,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. @@ -1990,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 @@ -2571,6 +2633,12 @@ * 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. + * */ /** @@ -2615,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 @@ -2872,9 +2940,30 @@ * 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 ------------------*/ @@ -2892,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: * @@ -3555,6 +3656,12 @@ * Resource usage constant representing an image file. */ +/** + * giblorb_ID_Data: + * + * Resource usage constant representing a data file. + */ + /** * giblorb_ID_Copyright: * @@ -3577,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: *