/**
* 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.
* 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 —
* <keycombo action="simul"><keycap function="command">command</keycap>
/**
* 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.
/**
* 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.
* <variablelist>
/**
* 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.
/**
* SECTION:glk-gestalt
* @short_description: Testing Glk's capabilities
- * @include: libchimara/glk.h
*
* The <quote>gestalt</quote> mechanism (cheerfully stolen from the Mac OS) is a
* system by which the Glk API can be upgraded without making your life
/**
* 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 <link
* linkend="chimara-Character-Input-Events">Character Input Events</link>.
/**
* 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
/**
* 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
/**
* 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().
/**
* 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.
*/
/**
* 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.
*/
/**
* 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
/**
* 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.
*/
/**
* SECTION:glk-events
* @short_description: Waiting for events
- * @include: libchimara/glk.h
*
* As described in <link linkend="chimara-Your-Programs-Main-Function">Your
* Program's Main Function</link>, all player input is handed to your program by
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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.
*
/**
* 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,
/**
* 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.
/**
* 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
/**
* SECTION:glk-stream-types
* @short_description: Window, memory, and file streams
- * @include: libchimara/glk.h
*
* <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
* <para>
/**
* 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.
*/
/**
* 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 <link linkend="chimara-Opaque-Objects">Opaque
/**
* 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
/**
* 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.
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
- * @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,
/**
* 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.
/**
* 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.
*/
/**
* 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
/**
* 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
/**
* 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 <link
/**
* SECTION:blorb-layer
* @short_description: The platform-independent functions in the Blorb layer
- * @include: libchimara/glk.h, libchimara/gi_blorb.h
*
* These are the functions which are implemented in
* <filename>gi_blorb.c</filename>. They will be compiled into the library, but
/**
* 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.
/**
* 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
/**
* 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.
/**
* 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 <ulink
projects / projects / chimara / chimara.git / commitdiff