2 * doc.c - Contains the short and long descriptions of all the documentation
3 * sections in the Glk spec, as well as the GtkDoc comments for symbols
4 * defined only in glk.h.
9 * @short_description: How to terminate a Glk program cleanly
10 * @include: libchimara/glk.h
12 * A Glk program usually ends when the end of the glk_main() function is
13 * reached. You can also terminate it earlier.
17 * SECTION:glk-interrupt
18 * @short_description: Specifying an interrupt handler for cleaning up critical
20 * @include: libchimara/glk.h
22 * Most platforms have some provision for interrupting a program —
23 * <keycombo action="simul"><keycap function="command">command</keycap>
24 * <keycap>period</keycap></keycombo> on the Macintosh, <keycombo
25 * action="simul"><keycap function="control">control</keycap><keycap>C</keycap>
26 * </keycombo> in Unix, possibly a window manager item, or other possibilities.
27 * This can happen at any time, including while execution is nested inside one
28 * of your own functions, or inside a Glk library function.
30 * If you need to clean up critical resources, you can specify an interrupt
36 * @short_description: Yielding time to the operating system
37 * @include: libchimara/glk.h
39 * Many platforms have some annoying thing that has to be done every so often,
40 * or the gnurrs come from the voodvork out and eat your computer.
42 * Well, not really. But you should call glk_tick() every so often, just in
43 * case. It may be necessary to yield time to other applications in a
44 * cooperative-multitasking OS, or to check for player interrupts in an infinite
50 * @short_description: Basic types used in Glk
51 * @include: libchimara/glk.h
53 * For simplicity, all the arguments used in Glk calls are of a very few types.
56 * <term>32-bit unsigned integer</term>
57 * <listitem><para>Unsigned integers are used wherever possible, which is
58 * nearly everywhere. This type is called #glui32.</para></listitem>
61 * <term>32-bit signed integer</term>
62 * <listitem><para>This type is called #glsi32. Rarely used.</para>
66 * <term>References to library objects</term>
67 * <listitem><para>These are pointers to opaque C structures; each library
68 * will use different structures, so you can not and should not try to
69 * manipulate their contents. See <link
70 * linkend="chimara-Opaque-Objects">Opaque Objects</link>.</para></listitem>
73 * <term>Pointer to one of the above types</term>
74 * <listitem><para>Pointer to a structure which consists entirely of the
75 * above types.</para></listitem>
78 * <term><type>unsigned char</type></term>
79 * <listitem><para>This is used only for Latin-1 text characters; see
80 * <link linkend="chimara-Character-Encoding">Character Encoding</link>.
84 * <term>Pointer to <type>char</type></term>
85 * <listitem><para>Sometimes this means a null-terminated string; sometimes
86 * an unterminated buffer, with length as a separate #glui32 argument. The
87 * documentation says which.</para></listitem>
90 * <term>Pointer to <type>void</type></term>
91 * <listitem><para>When nothing else will do.</para></listitem>
97 * SECTION:glk-opaque-objects
98 * @short_description: Complex objects in Glk
99 * @include: libchimara/glk.h
101 * Glk keeps track of a few classes of special objects. These are opaque to your
102 * program; you always refer to them using pointers to opaque C structures.
104 * Currently, these classes are:
107 * <term>Windows</term>
108 * <listitem><para>Screen panels, used to input or output information.
112 * <term>Streams</term>
113 * <listitem><para>Data streams, to which you can input or output text.
115 * <note><para>There are file streams and window streams, since you can
116 * output data to windows or files.</para></note>
120 * <term>File references</term>
121 * <listitem><para>Pointers to files in permanent storage.</para>
122 * <note><para>In Unix a file reference is a pathname; on the Mac, an
123 * <type>FSSpec</type>. Actually there's a little more information included,
124 * such as file type and whether it is a text or binary file.</para></note>
128 * <term>Sound channels</term>
129 * <listitem><para>Audio output channels.</para>
130 * <note><para>Not all Glk libraries support sound.</para></note>
136 * Note that there may be more object classes in future versions of the Glk API.
139 * When you create one of these objects, it is always possible that the creation
140 * will fail (due to lack of memory, or some other OS error.) When this happens,
141 * the allocation function will return %NULL (0) instead of a valid pointer. You
142 * should always test for this possibility.
144 * %NULL is never the identifier of any object (window, stream, file reference,
145 * or sound channel). The value %NULL is often used to indicate <quote>no
146 * object</quote> or <quote>nothing</quote>, but it is not a valid reference. If
147 * a Glk function takes an object reference as an argument, it is illegal to
148 * pass in %NULL unless the function definition says otherwise.
150 * The <filename class="headerfile">glk.h</filename> file defines types
151 * #winid_t, #strid_t, #frefid_t, #schanid_t to store references. These are
152 * pointers to struct #glk_window_struct, #glk_stream_struct,
153 * #glk_fileref_struct, and #glk_schannel_struct respectively. It is, of course,
154 * illegal to pass one kind of pointer to a function which expects another.
157 * This is how you deal with opaque objects from a C program. If you are using
158 * Glk through a virtual machine, matters will probably be different. Opaque
159 * objects may be represented as integers, or as VM objects of some sort.
161 * <refsect2 id="chimara-Rocks"><!-- Indeed it does. -->
162 * <title>Rocks</title>
164 * Every one of these objects (window, stream, file reference, or sound channel)
165 * has a <quote>rock</quote> value. This is simply a 32-bit integer value which
166 * you provide, for your own purposes, when you create the object.
168 * <note><para>The library — so to speak — stuffs this value under a
169 * rock for safe-keeping, and gives it back to you when you ask for it.
171 * <note><para>If you don't know what to use the rocks for, provide 0 and forget
172 * about it.</para></note>
174 * <refsect2 id="chimara-Iterating-Through-Opaque-Objects">
175 * <title>Iteration Through Opaque Objects</title>
177 * For each class of opaque objects, there is an iterate function, which you can
178 * use to obtain a list of all existing objects of that class. It takes the form
180 * <replaceable>CLASS</replaceable>id_t glk_<replaceable>CLASS</replaceable>_iterate(<replaceable>CLASS</replaceable>id_t <parameter>obj</parameter>, #glui32 *<parameter>rockptr</parameter>);
182 * ...where <code><replaceable>CLASS</replaceable></code> represents one of the
183 * opaque object classes.
186 * So, at the current time, these are the functions glk_window_iterate(),
187 * glk_stream_iterate(), glk_fileref_iterate(), and glk_schannel_iterate().
188 * There may be more classes in future versions of the spec; they all behave
192 * Calling <code>glk_<replaceable>CLASS</replaceable>_iterate(%NULL, r)</code>
193 * returns the first object; calling
194 * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> returns
195 * the next object, until there aren't any more, at which time it returns %NULL.
198 * The @rockptr argument is a pointer to a location; whenever
199 * <code>glk_<replaceable>CLASS</replaceable>_iterate()</code> returns an
200 * object, the object's rock is stored in the location <code>(*@rockptr)</code>.
201 * If you don't want the rocks to be returned, you may set @rockptr to %NULL.
204 * You usually use this as follows:
206 * obj = glk_<replaceable>CLASS</replaceable>_iterate(NULL, NULL);
208 * /* ...do something with obj... *<!-- -->/
209 * obj = glk_<replaceable>CLASS</replaceable>_iterate(obj, NULL);
214 * If you create or destroy objects inside this loop, obviously, the results are
215 * unpredictable. However it is always legal to call
216 * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> as long as
217 * @obj is a valid object id, or %NULL.
220 * The order in which objects are returned is entirely arbitrary. The library
221 * may even rearrange the order every time you create or destroy an object of
222 * the given class. As long as you do not create or destroy any object, the rule
223 * is that <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> has
224 * a fixed result, and iterating through the results as above will list every
225 * object exactly once.
231 * SECTION:glk-gestalt
232 * @short_description: Testing Glk's capabilities
233 * @include: libchimara/glk.h
235 * The <quote>gestalt</quote> mechanism (cheerfully stolen from the Mac OS) is a
236 * system by which the Glk API can be upgraded without making your life
237 * impossible. New capabilities (graphics, sound, or so on) can be added without
238 * changing the basic specification. The system also allows for
239 * <quote>optional</quote> capabilities — those which not all Glk library
240 * implementations will support — and allows you to check for their
241 * presence without trying to infer them from a version number.
243 * The basic idea is that you can request information about the capabilities of
244 * the API, by calling the gestalt functions.
248 * SECTION:glk-character-input
249 * @short_description: Waiting for a single keystroke
250 * @include: libchimara/glk.h
252 * You can request that the player hit a single key. See <link
253 * linkend="chimara-Character-Input-Events">Character Input Events</link>.
255 * If you use the basic text API, the character code which is returned can be
256 * any value from 0 to 255. The printable character codes have already been
257 * described. The remaining codes are typically control codes: <keycombo
258 * action="simul"><keycap function="control">control</keycap>
259 * <keycap>A</keycap></keycombo> to <keycombo action="simul"><keycap
260 * function="control">control</keycap><keycap>Z</keycap></keycombo> and a few
263 * There are also a number of special codes, representing special keyboard
264 * keys, which can be returned from a char-input event. These are represented
265 * as 32-bit integers, starting with 4294967295 (0xFFFFFFFF) and working down.
266 * The special key codes are defined in the <filename
267 * class="headerfile">glk.h</filename> file. They include one code for <keycap
268 * function="enter">return</keycap> or <keycap function="enter">enter</keycap>,
269 * one for <keycap function="delete">delete</keycap> or <keycap
270 * function="backspace">backspace</keycap>, twelve function keys, and one code
271 * for any key which has no Latin-1 or special code. The full list of key codes
274 * Various implementations of Glk will vary widely in which characters the
275 * player can enter. The most obvious limitation is that some characters are
276 * mapped to others. For example, most keyboards return a <keycombo
277 * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
278 * </keycombo> code when the <keycap function="tab">tab</keycap> key is
279 * pressed. The Glk library, if it can recognize this at all, will generate a
280 * <keysym>%keycode_Tab</keysym> event (value 0xFFFFFFF7) when this occurs.
281 * Therefore, for these keyboards, no keyboard key will generate a <keycombo
282 * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
283 * </keycombo> event (value 9.) The Glk library will probably map many of the
284 * control codes to the other special keycodes.
287 * On the other hand, the library may be very clever and discriminate between
288 * <keycap>tab</keycap> and <keycombo action="simul"><keycap
289 * function="control">control</keycap><keycap>I</keycap></keycombo>. This is
290 * legal. The idea is, however, that if your program asks the player to
291 * <quote><computeroutput>press the <keycap function="tab">tab</keycap>
292 * key</computeroutput></quote>, you should check for a
293 * <keysym>%keycode_Tab</keysym> event as opposed to a <keycombo
294 * action="simul"><keycap function="control">control</keycap>
295 * <keycap>I</keycap></keycombo> event.
298 * Some characters may not be enterable simply because they do not exist.
301 * Not all keyboards have a <keycap function="home">home</keycap> or <keycap
302 * function="end">end</keycap> key. A pen-based platform may not recognize
303 * any control characters at all.
306 * Some characters may not be enterable because they are reserved for the
307 * purposes of the interface. For example, the Mac Glk library reserves the
308 * <keycap function="tab">tab</keycap> key for switching between different Glk
309 * windows. Therefore, on the Mac, the library will never generate a
310 * <keysym>%keycode_Tab</keysym> event or a <keycombo action="simul">
311 * <keycap function="control">control</keycap><keycap>I</keycap></keycombo>
315 * Note that the linefeed or <keycombo action="simul"><keycap
316 * function="control">control</keycap><keycap>J</keycap></keycombo>
317 * character, which is the only printable control character, is probably not
318 * typable. This is because, in most libraries, it will be converted to
319 * <keysym>%keycode_Return</keysym>. Again, you should check for
320 * <keysym>%keycode_Return</keysym> if your program asks the player to
321 * <quote><computeroutput>press the <keycap function="enter">return</keycap>
322 * key</computeroutput></quote>.
326 * The <keycap function="delete">delete</keycap> and <keycap
327 * function="backspace">backspace</keycap> keys are merged into a single
328 * keycode because they have such an astonishing history of being confused in
329 * the first place... this spec formally waives any desire to define the
330 * difference. Of course, a library is free to distinguish <keycap
331 * function="delete">delete</keycap> and <keycap
332 * function="backspace">backspace</keycap> during line input. This is when it
333 * matters most; conflating the two during character input should not be a
337 * You can test for this by using the %gestalt_CharInput selector.
340 * Glk porters take note: it is not a goal to be able to generate every
341 * single possible key event. If the library says that it can generate a
342 * particular keycode, then game programmers will assume that it is
343 * available, and ask players to use it. If a <keysym>%keycode_Home</keysym>
344 * event can only be generated by typing <keycombo action="seq"><keycap
345 * function="escape">escape</keycap><keycombo action="simul"><keycap
346 * function="control">control</keycap><keycap>A</keycap></keycombo>
347 * </keycombo>, and the player does not know this, the player will be lost
348 * when the game says <quote><computeroutput>Press the <keycap
349 * function="home">home</keycap> key to see the next
350 * hint.</computeroutput></quote> It is better for the library to say that it
351 * cannot generate a <keysym>%keycode_Home</keysym> event; that way the game
352 * can detect the situation and ask the user to type <keycap>H</keycap>
356 * Of course, it is better not to rely on obscure keys in any case. The arrow
357 * keys and <keycap function="enter">return</keycap> are nearly certain to be
358 * available; the others are of gradually decreasing reliability, and you
359 * (the game programmer) should not depend on them. You must be certain to
360 * check for the ones you want to use, including the arrow keys and <keycap
361 * function="enter">return</keycap>, and be prepared to use different keys in
362 * your interface if %gestalt_CharInput says they are not available.
368 * @short_description: Changing the case of strings
369 * @include: libchimara/glk.h
371 * Glk has functions to manipulate the case of both Latin-1 and Unicode strings.
372 * One Latin-1 lowercase character corresponds to one uppercase character, and
373 * vice versa, so the Latin-1 functions act on single characters. The Unicode
374 * functions act on whole strings, since the length of the string may change.
378 * SECTION:glk-window-opening
379 * @short_description: Creating new windows and closing them
380 * @include: libchimara/glk.h
382 * You can open a new window using glk_window_open() and close it again using
383 * glk_window_close().
387 * SECTION:glk-window-constraints
388 * @short_description: Manipulating the size of a window
389 * @include: libchimara/glk.h
391 * There are library functions to change and to measure the size of a window.
395 * SECTION:glk-window-types
396 * @short_description: Blank, pair, text grid, text buffer, and graphics windows
397 * @include: libchimara/glk.h
399 * A technical description of all the window types, and exactly how they behave.
403 * SECTION:glk-echo-streams
404 * @short_description: Creating a copy of a window's output
405 * @include: libchimara/glk.h
407 * Every window has an associated window stream; you print to the window by
408 * printing to this stream. However, it is possible to attach a second stream to
409 * a window. Any text printed to the window is also echoed to this second
410 * stream, which is called the window's <quote>echo stream.</quote>
412 * Effectively, any call to glk_put_char() (or the other output commands) which
413 * is directed to the window's window stream, is replicated to the window's echo
414 * stream. This also goes for the style commands such as glk_set_style().
416 * Note that the echoing is one-way. You can still print text directly to the
417 * echo stream, and it will go wherever the stream is bound, but it does not
418 * back up and appear in the window.
420 * An echo stream can be of any type, even another window's window stream.
423 * This would be somewhat silly, since it would mean that any text printed to
424 * the window would be duplicated in another window. More commonly, you would
425 * set a window's echo stream to be a file stream, in order to create a
426 * transcript file from that window.
429 * A window can only have one echo stream. But a single stream can be the echo
430 * stream of any number of windows, sequentially or simultaneously.
432 * If a window is closed, its echo stream remains open; it is not automatically
436 * Do not confuse the window's window stream with its echo stream. The window
437 * stream is <quote>owned</quote> by the window, and dies with it. The echo
438 * stream is merely temporarily associated with the window.
441 * If a stream is closed, and it is the echo stream of one or more windows,
442 * those windows are reset to not echo anymore. (So then calling
443 * glk_window_get_echo_stream() on them will return %NULL.)
447 * SECTION:glk-window-other
448 * @short_description: Miscellaneous functions for windows
449 * @include: libchimara/glk.h
451 * This section contains functions for windows that don't fit anywhere else.
456 * @short_description: Waiting for events
457 * @include: libchimara/glk.h
459 * As described in <link linkend="chimara-Your-Programs-Main-Function">Your
460 * Program's Main Function</link>, all player input is handed to your program by
461 * the glk_select() call, in the form of events. You should write at least one
462 * event loop to retrieve these events.
466 * SECTION:glk-character-input-events
467 * @short_description: Events representing a single keystroke
468 * @include: libchimara/glk.h
470 * You can request character input from text buffer and text grid windows. See
471 * %evtype_CharInput. There are separate functions for requesting Latin-1 input
472 * and Unicode input; see %gestalt_Unicode.
476 * SECTION:glk-line-input-events
477 * @short_description: Events representing a line of user input
478 * @include: libchimara/glk.h
480 * You can request line input from text buffer and text grid windows. See
481 * %evtype_LineInput. There are separate functions for requesting Latin-1 input
482 * and Unicode input; see %gestalt_Unicode.
486 * SECTION:glk-timer-events
487 * @short_description: Events sent at fixed intervals
488 * @include: libchimara/glk.h
490 * You can request that an event be sent at fixed intervals, regardless of what
491 * the player does. Unlike input events, timer events can be tested for with
492 * glk_select_poll() as well as glk_select().
494 * It is possible that the library does not support timer events. You can check
495 * this with the %gestalt_Timer selector.
499 * SECTION:glk-streams
500 * @short_description: Input and output abstractions
501 * @include: libchimara/glk.h
503 * All character output in Glk is done through streams. Every window has an
504 * output stream associated with it. You can also write to files on disk; every
505 * open file is represented by an output stream as well.
507 * There are also input streams; these are used for reading from files on disk.
508 * It is possible for a stream to be both an input and an output stream.
511 * Player input is done through line and character input events, not streams.
512 * This is a small inelegance in theory. In practice, player input is slow and
513 * things can interrupt it, whereas file input is immediate. If a network
514 * extension to Glk were proposed, it would probably use events and not
515 * streams, since network communication is not immediate.
518 * It is also possible to create a stream that reads or writes to a buffer in
521 * Finally, there may be platform-specific types of streams, which are created
522 * before your program starts running.
525 * For example, a program running under Unix may have access to standard input
526 * as a stream, even though there is no Glk call to explicitly open standard
527 * input. On the Mac, data in a Mac resource may be available through a
528 * resource-reading stream.
531 * You do not need to worry about the origin of such streams; just read or write
532 * them as usual. For information about how platform-specific streams come to
533 * be, see <link linkend="chimara-Startup-Options">Startup Options</link>.
535 * A stream is opened with a particular file mode, see the
536 * <code>filemode_</code> constants below.
538 * For information on opening streams, see the discussion of each specific type
539 * of stream in <link linkend="chimara-The-Types-of-Streams">The Types of
540 * Streams</link>. Remember that it is always possible that opening a stream
541 * will fail, in which case the creation function will return %NULL.
543 * Each stream remembers two character counts, the number of characters printed
544 * to and read from that stream. The write-count is exactly one per
545 * glk_put_char() call; it is figured before any platform-dependent character
549 * For example, if a newline character is converted to
550 * linefeed-plus-carriage-return, the stream's count still only goes up by
551 * one; similarly if an accented character is displayed as two characters.
554 * The read-count is exactly one per glk_get_char_stream() call, as long as the
555 * call returns an actual character (as opposed to an end-of-file token.)
557 * Glk has a notion of the <quote>current (output) stream</quote>. If you print
558 * text without specifying a stream, it goes to the current output stream. The
559 * current output stream may be %NULL, meaning that there isn't one. It is
560 * illegal to print text to stream %NULL, or to print to the current stream when
563 * If the stream which is the current stream is closed, the current stream
569 * @short_description: Printing to streams
570 * @include: libchimara/glk.h
572 * You can print Latin-1 and Unicode characters, null-terminated strings, or
573 * buffers to any stream. The characters will be converted into the appropriate
574 * format for that stream.
579 * @short_description: Reading from streams
580 * @include: libchimara/glk.h
582 * You can read Latin-1 or Unicode characters, buffers, or whole lines from any
583 * stream. The characters will be converted into the form in which you request
588 * SECTION:glk-closing-streams
589 * @short_description: Closing streams and retrieving their character counts
590 * @include: libchimara/glk.h
592 * When you close a Glk stream, you have the opportunity to examine the
593 * character counts — the number of characters written to or read from the
598 * SECTION:glk-stream-positions
599 * @short_description: Moving the read/write mark
600 * @include: libchimara/glk.h
602 * You can set the position of the read/write mark in a stream.
605 * Which makes one wonder why they're called <quote>streams</quote> in the
606 * first place. Oh well.
612 * @short_description: Changing the appearance of printed text
613 * @include: libchimara/glk.h
615 * You can send style-changing commands to an output stream. After a style
616 * change, new text which is printed to that stream will be given the new style,
617 * whatever that means for the stream in question. For a window stream, the text
618 * will appear in that style. For a memory stream, style changes have no effect.
619 * For a file stream, if the machine supports styled text files, the styles may
620 * be written to the file; more likely the style changes will have no effect.
622 * Styles are exclusive. A character is shown with exactly one style, not a
623 * subset of the possible styles.
626 * Note that every stream and window has its own idea of the <quote>current
627 * style.</quote> Sending a style command to one window or stream does not
631 * Except for a window's echo stream; see <link
632 * linkend="chimara-Echo-Streams">Echo Streams</link>.
635 * The styles are intended to distinguish meaning and use, not formatting. There
636 * is no standard definition of what each style will look like. That is left up
637 * to the Glk library, which will choose an appearance appropriate for the
638 * platform's interface and the player's preferences.
640 * There are currently eleven styles defined. More may be defined in the future.
642 * Styles may be distinguished on screen by font, size, color, indentation,
643 * justification, and other attributes. Note that some attributes (notably
644 * justification and indentation) apply to entire paragraphs. If possible and
645 * relevant, you should apply a style to an entire paragraph — call
646 * glk_set_style() immediately after printing the newline at the beginning of
647 * the text, and do the same at the end.
650 * For example, %style_Header may well be centered text. If you print
651 * <quote>Welcome to Victim (a short interactive mystery)</quote>, and only the
652 * word <quote>Victim</quote> is in the %style_Header, the center-justification
653 * attribute will be lost. Similarly, a block quote is usually indented on both
654 * sides, but indentation is only meaningful when applied to an entire line or
655 * paragraph, so block quotes should take up an entire paragraph. Contrariwise,
656 * %style_Emphasized need not be used on an entire paragraph. It is often used
657 * for single emphasized words in normal text, so you can expect that it will
658 * appear properly that way; it will be displayed in italics or underlining,
659 * not center-justified or indented.
663 * Yes, this is all a matter of mutual agreement between game authors and game
664 * players. It's not fixed by this specification. That's natural language for
670 * SECTION:glk-stylehints
671 * @short_description: Setting style hints
672 * @include: libchimara/glk.h
674 * There are no guarantees of how styles will look, but you can make
677 * Initially, no hints are set for any window type or style. Note that having no
678 * hint set is not the same as setting a hint with value 0.
680 * These functions do <emphasis>not</emphasis> affect
681 * <emphasis>existing</emphasis> windows. They affect the windows which you
682 * create subsequently. If you want to set hints for all your game windows, call
683 * glk_stylehint_set() before you start creating windows. If you want different
684 * hints for different windows, change the hints before creating each window.
687 * This policy makes life easier for the interpreter. It knows everything about
688 * a particular window's appearance when the window is created, and it doesn't
689 * have to change it while the window exists.
692 * Hints are hints. The interpreter may ignore them, or give the player a choice
693 * about whether to accept them. Also, it is never necessary to set hints. You
694 * don't have to suggest that %style_Preformatted be fixed-width, or
695 * %style_Emphasized be boldface or italic; they will have appropriate defaults.
696 * Hints are for situations when you want to <emphasis>change</emphasis> the
697 * appearance of a style from what it would ordinarily be. The most common case
698 * when this is appropriate is for the styles %style_User1 and %style_User2.
700 * There are currently ten style hints defined. More may be defined in the
703 * Again, when passing a style hint to a Glk function, any value is actually
704 * legal. If the interpreter does not recognize the stylehint value, it will
707 * This policy allows for the future definition of style hints without breaking
713 * SECTION:glk-stream-types
714 * @short_description: Window, memory, and file streams
715 * @include: libchimara/glk.h
717 * <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
719 * Every window has an output stream associated with it. This is created
720 * automatically, with %filemode_Write, when you open the window. You get it
721 * with glk_window_get_stream().
723 * A window stream cannot be closed with glk_stream_close(). It is closed
724 * automatically when you close its window with glk_window_close().
726 * Only printable characters (including newline) may be printed to a window
727 * stream. See <link linkend="chimara-Character-Encoding">Character
731 * <refsect2 id="chimara-Memory-Streams"><title>Memory Streams</title>
733 * You can open a stream which reads from or writes to a space in memory. See
734 * glk_stream_open_memory() and glk_stream_open_memory_uni(). When opening a
735 * memory stream, you specify a buffer to which the stream's output will be
736 * written, and its length @buflen.
738 * When outputting, if more than @buflen characters are written to the stream,
739 * all of them beyond the buffer length will be thrown away, so as not to
740 * overwrite the buffer. (The character count of the stream will still be
741 * maintained correctly. That is, it will count the number of characters written
742 * into the stream, not the number that fit into the buffer.)
744 * If the buffer is %NULL, or for that matter if @buflen is zero, then
745 * <emphasis>everything</emphasis> written to the stream is thrown away. This
746 * may be useful if you are interested in the character count.
748 * When inputting, if more than @buflen characters are read from the stream, the
749 * stream will start returning -1 (signalling end-of-file.) If the buffer is
750 * %NULL, the stream will always return end-of-file.
752 * The data is written to the buffer exactly as it was passed to the printing
753 * functions (glk_put_char(), etc.); input functions will read the data exactly
754 * as it exists in memory. No platform-dependent cookery will be done on it.
757 * You can write a disk file in text mode, but a memory stream is effectively
758 * always in binary mode.
761 * Whether reading or writing, the contents of the buffer are undefined until
762 * the stream is closed. The library may store the data there as it is written,
763 * or deposit it all in a lump when the stream is closed. It is illegal to
764 * change the contents of the buffer while the stream is open.
767 * <refsect2 id="chimara-File-Streams"><title>File Streams</title>
769 * You can open a stream which reads from or writes to a disk file. See
770 * glk_stream_open_file() and glk_stream_open_file_uni().
772 * The file may be written in text or binary mode; this is determined by the
773 * file reference you open the stream with. Similarly, platform-dependent
774 * attributes such as file type are determined by the file reference. See <link
775 * linkend="chimara-File-References">File References</link>.
781 * SECTION:glk-stream-other
782 * @short_description: Miscellaneous functions for streams
783 * @include: libchimara/glk.h
785 * This section includes functions for streams that don't fit anywhere else.
789 * SECTION:glk-fileref
790 * @short_description: A platform-independent way to refer to disk files
791 * @include: libchimara/glk.h
793 * You deal with disk files using file references. Each fileref is an opaque C
794 * structure pointer; see <link linkend="chimara-Opaque-Objects">Opaque
797 * A file reference contains platform-specific information about the name and
798 * location of the file, and possibly its type, if the platform has a notion of
799 * file type. It also includes a flag indication whether the file is a text file
803 * Note that this is different from the standard C I/O library, in which you
804 * specify text or binary mode when the file is opened.
807 * A fileref does not have to refer to a file which actually exists. You can
808 * create a fileref for a nonexistent file, and then open it in write mode to
811 * You always provide a usage argument when you create a fileref. The usage is a
812 * mask of constants (see below) to indicate the file type and the mode (text or
813 * binary.) These values are used when you create a new file, and also to filter
814 * file lists when the player is selecting a file to load.
816 * In general, you should use text mode if the player expects to read the file
817 * with a platform-native text editor; you should use binary mode if the file is
818 * to be read back by your program, or if the data must be stored exactly. Text
819 * mode is appropriate for %fileusage_Transcript; binary mode is appropriate for
820 * %fileusage_SavedGame and probably for %fileusage_InputRecord. %fileusage_Data
821 * files may be text or binary, depending on what you use them for.
825 * SECTION:glk-fileref-types
826 * @short_description: Four different ways to create a file reference
827 * @include: libchimara/glk.h
829 * There are four different functions for creating a fileref, depending on how
830 * you wish to specify it. Remember that it is always possible that a fileref
831 * creation will fail and return %NULL.
835 * SECTION:glk-fileref-other
836 * @short_description: Miscellaneous functions for file references
837 * @include: libchimara/glk.h
839 * This section includes functions for file references that don't fit anywhere
844 * SECTION:blorb-program
845 * @short_description: How to use the Blorb layer in your program
846 * @include: libchimara/glk.h, libchimara/gi_blorb.h
848 * If you wish your program to load its resources from a Blorb file, you need to
849 * find and open that file in your startup code. (See <link
850 * linkend="chimara-Startup-Options">Startup Options</link>.) Each platform will
851 * have appropriate functions available for finding startup data. Be sure to
852 * open the file in binary mode, not text mode. Once you have opened the file as
853 * a Glk stream, pass it to giblorb_set_resource_map().
855 * If you do not call giblorb_set_resource_map() in your startup code, or if it
856 * fails, the library is left to its own devices for finding resources. Some
857 * libraries may try to load resources from individual files —
858 * <filename>PIC1</filename>, <filename>PIC2</filename>,
859 * <filename>PIC3</filename>, and so on. (See the Blorb specification for more
860 * on this approach.) Other libraries will not have any other loading mechanism
861 * at all; no resources will be available.
865 * SECTION:blorb-layer
866 * @short_description: The platform-independent functions in the Blorb layer
867 * @include: libchimara/glk.h, libchimara/gi_blorb.h
869 * These are the functions which are implemented in
870 * <filename>gi_blorb.c</filename>. They will be compiled into the library, but
871 * they are the same on every platform. In general, only the library needs to
872 * call these functions. The Glk program should allow the library to do all the
877 * SECTION:blorb-errors
878 * @short_description: Error codes returned by the Blorb layer functions
879 * @include: libchimara/glk.h, libchimara/gi_blorb.h
881 * All Blorb layer functions, including giblorb_set_resource_map(), return the
882 * following error codes.
886 * SECTION:glkext-startup
887 * @short_description: Parsing startup options
888 * @include: libchimara/glk.h, libchimara/glkstart.h
890 * This section describes an extension to Glk for parsing command-line startup
891 * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and
894 * When you compile a Glk program, you may define a function called
895 * glkunix_startup_code(), and an array <code>glkunix_arguments[]</code>. These
896 * set up various Unix-specific options used by the Glk library. There is a
897 * sample <quote><filename>glkstart.c</filename></quote> file included in this
898 * package; you should modify it to your needs.
900 * |[ extern #glkunix_argumentlist_t glkunix_arguments[]; ]|
902 * The <code>glkunix_arguments[]</code> array is a list of command-line
903 * arguments that your program can accept. The library will sort these out of
904 * the command line and pass them on to your code.
908 * SECTION:glkext-unix
909 * @short_description: Unix-specific functions
910 * @include: libchimara/glk.h, libchimara/glkstart.h
912 * This section describes an extension to Glk for various Unix functions. It was
913 * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm.
915 * You can put other startup code in glkunix_startup_code(). This should
916 * generally be limited to finding and opening data files. There are a few Unix
917 * Glk library functions which are convenient for this purpose.
920 /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/
925 * A 32-bit unsigned integer type, used wherever possible in Glk.
931 * A 32-bit signed integer type, rarely used.
935 * GLK_MODULE_UNICODE:
937 * If this preprocessor symbol is defined, so are all the Unicode functions and
938 * constants (see %gestalt_Unicode). If not, not.
944 * Opaque structure representing a Glk window. It has no user-accessible
951 * Opaque structure representing an input or output stream. It has no
952 * user-accessible members.
958 * Opaque structure representing a file reference. It has no user-accessible
965 * For an example of the gestalt mechanism, consider the selector
966 * %gestalt_Version. If you do
969 * res = #glk_gestalt(#gestalt_Version, 0);
971 * <code>res</code> will be set to a 32-bit number which encodes the version of
972 * the Glk spec which the library implements. The upper 16 bits stores the major
973 * version number; the next 8 bits stores the minor version number; the low 8
974 * bits stores an even more minor version number, if any.
977 * So the version number 78.2.11 would be encoded as 0x004E020B.
980 * The current Glk specification version is 0.7.0, so this selector will return
985 * res = #glk_gestalt_ext(#gestalt_Version, 0, NULL, 0);
987 * does exactly the same thing. Note that, in either case, the second argument
988 * is not used; so you should always pass 0 to avoid future surprises.
994 * If you set <code>ch</code> to a character code, or a special code (from
995 * 0xFFFFFFFF down), and call
998 * res = #glk_gestalt(#gestalt_CharInput, ch);
1000 * then <code>res</code> will be %TRUE (1) if that character can be typed by
1001 * the player in character input, and %FALSE (0) if not. See <link
1002 * linkend="chimara-Character-Input">Character Input</link>.
1006 * gestalt_LineInput:
1008 * If you set <code>ch</code> to a character code, and call
1011 * res = #glk_gestalt(#gestalt_LineInput, ch);
1013 * then <code>res</code> will be %TRUE (1) if that character can be typed by the
1014 * player in line input, and %FALSE (0) if not. Note that if <code>ch</code> is
1015 * a nonprintable Latin-1 character (0 to 31, 127 to 159), then this is
1016 * guaranteed to return %FALSE. See <link linkend="chimara-Line-Input">Line
1021 * gestalt_CharOutput:
1023 * If you set <code>ch</code> to a character code (Latin-1 or higher), and call
1026 * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &len, 1);
1028 * then <code>res</code> will be one of %gestalt_CharOutput_CannotPrint,
1029 * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see
1032 * In all cases, <code>len</code> (the #glui32 value pointed at by the third
1033 * argument) will be the number of actual glyphs which will be used to represent
1034 * the character. In the case of %gestalt_CharOutput_ExactPrint, this will
1035 * always be 1; for %gestalt_CharOutput_CannotPrint, it may be 0 (nothing
1036 * printed) or higher; for %gestalt_CharOutput_ApproxPrint, it may be 1 or
1037 * higher. This information may be useful when printing text in a fixed-width
1041 * As described in <link linkend="chimara-Other-API-Conventions">Other API
1042 * Conventions</link>, you may skip this information by passing %NULL as the
1043 * third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead.
1046 * This selector will always return %gestalt_CharOutput_CannotPrint if
1047 * <code>ch</code> is an unprintable eight-bit character (0 to 9, 11 to 31, 127
1051 * Make sure you do not get confused by signed byte values. If you set a
1052 * <quote><type>char</type></quote> variable <code>ch</code> to 0xFE, the
1053 * small-thorn character (þ), and then call
1054 * |[ res = #glk_gestalt(#gestalt_CharOutput, ch); ]|
1055 * then (by the definition of C/C++) <code>ch</code> will be sign-extended to
1056 * 0xFFFFFFFE, which is not a legitimate character, even in Unicode. You
1058 * |[ res = #glk_gestalt(#gestalt_CharOutput, (unsigned char)ch); ]|
1062 * Unicode includes the concept of non-spacing or combining characters, which
1063 * do not represent glyphs; and double-width characters, whose glyphs take up
1064 * two spaces in a fixed-width font. Future versions of this spec may
1065 * recognize these concepts by returning a <code>len</code> of 0 or 2 when
1066 * %gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to
1067 * a policy of <quote>simple stuff first</quote>.
1072 * gestalt_CharOutput_CannotPrint:
1074 * When the %gestalt_CharOutput selector returns this for a character, the
1075 * character cannot be meaningfully printed. If you try, the player may see
1076 * nothing, or may see a placeholder.
1080 * gestalt_CharOutput_ApproxPrint:
1082 * When the %gestalt_CharOutput selector returns this for a character, the
1083 * library will print some approximation of the character. It will be more or
1084 * less right, but it may not be precise, and it may not be distinguishable from
1085 * other, similar characters. (Examples:
1086 * <quote><computeroutput>ae</computeroutput></quote> for the one-character
1087 * <quote>æ</quote> ligature,
1088 * <quote><computeroutput>e</computeroutput></quote> for
1089 * <quote>è</quote>, <quote><computeroutput>|</computeroutput></quote>
1090 * for a broken vertical bar (¦).)
1094 * gestalt_CharOutput_ExactPrint:
1096 * When the %gestalt_CharOutput selector returns this for a character, the
1097 * character will be printed exactly as defined.
1103 * The basic text functions will be available in every Glk library. The Unicode
1104 * functions may or may not be available. Before calling them, you should use
1105 * the following gestalt selector:
1108 * res = #glk_gestalt(#gestalt_Unicode, 0);
1111 * This returns 1 if the Unicode functions are available. If it returns 0, you
1112 * should not try to call them. They may print nothing, print gibberish, or
1113 * cause a run-time error. The Unicode functions include
1114 * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),
1115 * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
1116 * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
1117 * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
1118 * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
1119 * glk_request_char_event_uni(), glk_request_line_event_uni(),
1120 * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
1122 * If you are writing a C program, there is an additional complication. A
1123 * library which does not support Unicode may not implement the Unicode
1124 * functions at all. Even if you put gestalt tests around your Unicode calls,
1125 * you may get link-time errors. If the
1126 * <filename class="headerfile">glk.h</filename> file is so old that it does not
1127 * declare the Unicode functions and constants, you may even get compile-time
1130 * To avoid this, you can perform a preprocessor test for the existence of
1131 * #GLK_MODULE_UNICODE.
1137 * You can test whether the library supports timer events:
1138 * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]|
1139 * This returns 1 if timer events are supported, and 0 if they are not.
1145 * No event. This is a placeholder, and glk_select() never returns it.
1151 * An event that repeats at fixed intervals. See <link
1152 * linkend="chimara-Timer-Events">Timer Events</link>.
1158 * A keystroke event in a window. See <link
1159 * linkend="chimara-Character-Input-Events">Character Input Events</link>.
1161 * If a window has a pending request for character input, and the player hits a
1162 * key in that window, glk_select() will return an event whose type is
1163 * %evtype_CharInput. Once this happens, the request is complete; it is no
1164 * longer pending. You must call glk_request_char_event() or
1165 * glk_request_char_event_uni() if you want another character from that window.
1167 * In the event structure, @win tells what window the event came from. @val1
1168 * tells what character was entered; this will be a character code, or a special
1169 * keycode. (See <link linkend="chimara-Character-Input">Character
1170 * Input</link>.) If you called glk_request_char_event(), @val1 will be in
1171 * 0..255, or else a special keycode. In any case, @val2 will be 0.
1177 * A full line of input completed in a window. See <link
1178 * linkend="chimara-Line-Input-Events">Line Input Events</link>.
1180 * If a window has a pending request for line input, and the player hits
1181 * <keycap>enter</keycap> in that window (or whatever action is appropriate to
1182 * enter his input), glk_select() will return an event whose type is
1183 * %evtype_LineInput. Once this happens, the request is complete; it is no
1184 * longer pending. You must call glk_request_line_event() if you want another
1185 * line of text from that window.
1187 * In the event structure, @win tells what window the event came from. @val1
1188 * tells how many characters were entered. @val2 will be 0. The characters
1189 * themselves are stored in the buffer specified in the original
1190 * glk_request_line_event() or glk_request_line_event_uni() call.
1192 * <note><para>There is no null terminator stored in the buffer.</para></note>
1194 * It is illegal to print anything to a window which has line input pending.
1197 * This is because the window may be displaying and editing the player's
1198 * input, and printing anything would make life unnecessarily complicated for
1204 * evtype_MouseInput:
1206 * A mouse click in a window. See <link
1207 * linkend="chimara-Mouse-Input-Events">Mouse Input Events</link>.
1213 * An event signalling that the sizes of some windows have changed.
1215 * Some platforms allow the player to resize the Glk window during play. This
1216 * will naturally change the sizes of your windows. If this occurs, then
1217 * immediately after all the rearrangement, glk_select() will return an event
1218 * whose type is %evtype_Arrange. You can use this notification to redisplay the
1219 * contents of a graphics or text grid window whose size has changed.
1222 * The display of a text buffer window is entirely up to the library, so you
1223 * don't need to worry about those.
1226 * In the event structure, @win will be %NULL if all windows are affected. If
1227 * only some windows are affected, @win will refer to a window which contains
1228 * all the affected windows. @val1 and @val2 will be 0.
1231 * You can always play it safe, ignore @win, and redraw every graphics and
1235 * An arrangement event is guaranteed to occur whenever the player causes any
1236 * window to change size, as measured by its own metric.
1239 * Size changes caused by you — for example, if you open, close, or
1240 * resize a window — do not trigger arrangement events. You must be
1241 * aware of the effects of your window management, and redraw the windows that
1246 * It is possible that several different player actions can cause windows to
1247 * change size. For example, if the player changes the screen resolution, an
1248 * arrangement event might be triggered. This might also happen if the player
1249 * changes his display font to a different size; the windows would then be
1250 * different <quote>sizes</quote> in the metric of rows and columns, which is
1251 * the important metric and the only one you have access to.
1254 * Arrangement events, like timer events, can be returned by glk_select_poll().
1255 * But this will not occur on all platforms. You must be ready to receive an
1256 * arrangement event when you call glk_select_poll(), but it is possible that it
1257 * will not arrive until the next time you call glk_select().
1260 * This is because on some platforms, window resizing is handled as part of
1261 * player input; on others, it can be triggered by an external process such as
1269 * An event signalling that graphics windows must be redrawn.
1271 * On platforms that support graphics, it is possible that the contents of a
1272 * graphics window will be lost, and have to be redrawn from scratch. If this
1273 * occurs, then glk_select() will return an event whose type is %evtype_Redraw.
1275 * In the event structure, @win will be %NULL if all windows are affected. If
1276 * only some windows are affected, @win will refer to a window which contains
1277 * all the affected windows. @val1 and @val2 will be 0.
1280 * You can always play it safe, ignore @win, and redraw every graphics window.
1283 * Affected windows are already cleared to their background color when you
1284 * receive the redraw event.
1286 * Redraw events can be returned by glk_select_poll(). But, like arrangement
1287 * events, this is platform-dependent. See %evtype_Arrange.
1289 * For more about redraw events and how they affect graphics windows, see <link
1290 * linkend="chimara-Graphics-Windows">Graphics Windows</link>.
1294 * evtype_SoundNotify:
1296 * On platforms that support sound, you can request to receive an
1297 * %evtype_SoundNotify event when a sound finishes playing. See <link
1298 * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
1304 * On platforms that support hyperlinks, you can request to receive an
1305 * %evtype_Hyperlink event when the player selects a link. See <link
1306 * linkend="chimara-Accepting-Hyperlink-Events">Accepting Hyperlink
1312 * @type: the event type
1313 * @win: the window that spawned the event, or %NULL
1314 * @val1: information, the meaning of which depends on the type of event
1315 * @val2: more information, the meaning of which depends on the type of event
1317 * The event structure is self-explanatory. @type is the event type. The window
1318 * that spawned the event, if relevant, is in @win. The remaining fields contain
1319 * more information specific to the event.
1321 * The event types are described below. Note that %evtype_None is zero, and the
1322 * other values are positive. Negative event types (0x80000000 to 0xFFFFFFFF)
1323 * are reserved for implementation-defined events.
1329 * Represents any key that has no Latin-1 or special code.
1335 * Represents the <keycap function="left">left arrow</keycap> key.
1341 * Represents the <keycap function="right">right arrow</keycap> key.
1347 * Represents the <keycap function="up">up arrow</keycap> key.
1353 * Represents the <keycap function="down">down arrow</keycap> key.
1359 * Represents the <keycap function="enter">return</keycap> or <keycap
1360 * function="enter">enter</keycap> keys.
1366 * Represents the <keycap function="delete">delete</keycap> or <keycap
1367 * function="backspace">backspace</keycap> keys.
1373 * Represents the <keycap function="escape">escape</keycap> key.
1379 * Represents the <keycap function="tab">tab</keycap> key.
1385 * Represents the <keycap function="pageup">page up</keycap> key.
1391 * Represents the <keycap function="pagedown">page down</keycap> key.
1397 * Represents the <keycap function="home">home</keycap> key.
1403 * Represents the <keycap function="end">end</keycap> key.
1409 * Represents the <keycap>F1</keycap> key.
1415 * Represents the <keycap>F2</keycap> key.
1421 * Represents the <keycap>F3</keycap> key.
1427 * Represents the <keycap>F4</keycap> key.
1433 * Represents the <keycap>F5</keycap> key.
1439 * Represents the <keycap>F6</keycap> key.
1445 * Represents the <keycap>F7</keycap> key.
1451 * Represents the <keycap>F8</keycap> key.
1457 * Represents the <keycap>F9</keycap> key.
1463 * Represents the <keycap>F10</keycap> key.
1469 * Represents the <keycap>F11</keycap> key.
1475 * Represents the <keycap>F12</keycap> key.
1481 * This value is equal to the number of special keycodes. The last keycode is
1484 * <alt>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</alt>
1485 * <mathphrase>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</mathphrase>
1493 * The style of normal or body text. A new window or stream always starts with
1494 * %style_Normal as the current style.
1500 * Text which is emphasized.
1504 * style_Preformatted:
1506 * Text which has a particular arrangement of characters.
1508 * This style, unlike the others, does have a standard appearance; it will
1509 * always be a fixed-width font. This is a concession to practicality. Games
1510 * often want to display maps or diagrams using character graphics, and this is
1511 * the style for that.
1518 * Text which introduces a large section. This is suitable for the title of an
1519 * entire game, or a major division such as a chapter.
1525 * Text which introduces a smaller section within a large section.
1527 * In a Colossal-Cave-style game, this is suitable for the name of a room (when
1528 * the player looks around.)
1535 * Text which warns of a dangerous condition, or one which the player should pay
1542 * Text which notifies of an interesting condition.
1544 * This is suitable for noting that the player's score has changed.
1551 * Text which forms a quotation or otherwise abstracted text.
1557 * Text which the player has entered. You should generally not use this style at
1558 * all; the library uses it for text which is typed during a line-input request.
1559 * One case when it is appropriate for you to use %style_Input is when you are
1560 * simulating player input by reading commands from a text file.
1566 * This style has no particular semantic meaning. You may define a meaning
1567 * relevant to your own work, and use it as you see fit.
1573 * Another style available for your use.
1579 * The number of styles defined in this library.
1584 * @readcount: Number of characters read from the stream.
1585 * @writecount: Number of characters printed to the stream, including ones that
1588 * If you are interested in the character counts of a stream (see <link
1589 * linkend="chimara-Streams">Streams</link>), then you can pass a pointer to
1590 * #stream_result_t as an argument of glk_stream_close() or glk_window_close().
1591 * The structure will be filled with the stream's final character counts.
1597 * A constant representing all window types, which may be used as the @wintype
1598 * argument in glk_stylehint_set().
1604 * A pair window is completely filled by the two windows it contains. It
1605 * supports no input and no output, and it has no size.
1607 * You cannot directly create a pair window; one is automatically created
1608 * every time you split a window with glk_window_open(). Pair windows are
1609 * always created with a rock value of 0.
1611 * You can close a pair window with glk_window_close(); this also closes every
1612 * window contained within the pair window.
1614 * It is legal to split a pair window when you call glk_window_open().
1620 * A blank window is always blank. It supports no input and no output. (You
1621 * can call glk_window_get_stream() on it, as you can with any window, but
1622 * printing to the resulting stream has no effect.) A blank window has no
1623 * size; glk_window_get_size() will return (0,0), and it is illegal to set a
1624 * window split with a fixed size in the measurement system of a blank window.
1627 * A blank window is not the same as there being no windows. When Glk starts
1628 * up, there are no windows at all, not even a window of the blank type.
1633 * wintype_TextBuffer:
1635 * A text buffer window contains a linear stream of text. It supports output;
1636 * when you print to it, the new text is added to the end. There is no way for
1637 * you to affect text which has already been printed. There are no guarantees
1638 * about how much text the window keeps; old text may be stored forever, so
1639 * that the user can scroll back to it, or it may be thrown away as soon as it
1640 * scrolls out of the window.
1643 * Therefore, there may or may not be a player-controllable scroll bar or
1644 * other scrolling widget.
1647 * The display of the text in a text buffer is up to the library. Lines will
1648 * probably not be broken in the middles of words — but if they are, the
1649 * library is not doing anything illegal, only ugly. Text selection and copying
1650 * to a clipboard, if available, are handled however is best on the player's
1651 * machine. Paragraphs (as defined by newline characters in the output) may be
1655 * You should not, in general, fake this by printing spaces before each
1656 * paragraph of prose text. Let the library and player preferences handle
1657 * that. Special cases (like indented lists) are of course up to you.
1660 * When a text buffer is cleared (with glk_window_clear()), the library will do
1661 * something appropriate; the details may vary. It may clear the window, with
1662 * later text appearing at the top — or the bottom. It may simply print
1663 * enough blank lines to scroll the current text out of the window. It may
1664 * display a distinctive page-break symbol or divider.
1666 * The size of a text buffer window is necessarily imprecise. Calling
1667 * glk_window_get_size() will return the number of rows and columns that would
1668 * be available <emphasis>if</emphasis> the window was filled with
1669 * <quote>0</quote> (zero) characters in the <quote>normal</quote> font.
1670 * However, the window may use a non-fixed-width font, so that number of
1671 * characters in a line could vary. The window might even support
1672 * variable-height text (say, if the player is using large text for emphasis);
1673 * that would make the number of lines in the window vary as well.
1675 * Similarly, when you set a fixed-size split in the measurement system of a
1676 * text buffer, you are setting a window which can handle a fixed number of rows
1677 * (or columns) of <quote>0</quote> characters. The number of rows (or
1678 * characters) that will actually be displayed depends on font variances.
1680 * A text buffer window supports both character and line input, but not mouse
1683 * In character input, there will be some visible signal that the window is
1684 * waiting for a keystroke. (Typically, a cursor at the end of the text.) When
1685 * the player hits a key in that window, an event is generated, but the key is
1686 * <emphasis>not</emphasis> printed in the window.
1688 * In line input, again, there will be some visible signal. It is most common
1689 * for the player to compose input in the window itself, at the end of the text.
1690 * (This is how IF story input usually looks.) But it's not strictly required.
1691 * An alternative approach is the way MUD clients usually work: there is a
1692 * dedicated one-line input window, outside of Glk's window space, and the user
1693 * composes input there.
1696 * If this approach is used, there will still be some way to handle input from
1697 * two windows at once. It is the library's responsibility to make this
1698 * available to the player. You only need request line input and wait for the
1702 * When the player finishes his line of input, the library will display the
1703 * input text at the end of the buffer text (if it wasn't there already.) It
1704 * will be followed by a newline, so that the next text you print will start a
1705 * new line (paragraph) after the input.
1707 * If you call glk_cancel_line_event(), the same thing happens; whatever text
1708 * the user was composing is visible at the end of the buffer text, followed by
1715 * A text grid contains a rectangular array of characters, in a fixed-width
1716 * font. Its size is the number of columns and rows of the array.
1718 * A text grid window supports output. It maintains knowledge of an output
1719 * cursor position. When the window is opened, it is filled with blanks (space
1720 * characters), and the output cursor starts in the top left corner —
1721 * character (0,0). If the window is cleared with glk_window_clear(), the window
1722 * is filled with blanks again, and the cursor returns to the top left corner.
1724 * When you print, the characters of the output are laid into the array in
1725 * order, left to right and top to bottom. When the cursor reaches the end of a
1726 * line, it goes to the beginning of the next line. The library makes no attempt
1727 * to wrap lines at word breaks.
1730 * Note that printing fancy characters may cause the cursor to advance more
1731 * than one position per character. (For example, the <quote>æ</quote>
1732 * ligature may print as two characters.) See <link
1733 * linkend="chimara-Output">Output</link>, for how to test this situation.
1736 * You can set the cursor position with glk_window_move_cursor().
1738 * When a text grid window is resized smaller, the bottom or right area is
1739 * thrown away, but the remaining area stays unchanged. When it is resized
1740 * larger, the new bottom or right area is filled with blanks.
1743 * You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
1744 * text grid windows when you see them change size.
1747 * Text grid window support character and line input, as well as mouse input (if
1748 * a mouse is available.)
1750 * Mouse input returns the position of the character that was touched, from
1753 * <alt>(width-1,height-1)</alt>
1754 * <mathphrase>(width - 1, height - 1)</mathphrase>
1758 * Character input is as described in the previous section.
1760 * Line input is slightly different; it is guaranteed to take place in the
1761 * window, at the output cursor position. The player can compose input only to
1762 * the right edge of the window; therefore, the maximum input length is
1764 * <alt>(windowwidth - 1 - cursorposition)</alt>
1765 * <mathphrase>(windowwidth - 1 - cursorposition)</mathphrase>
1767 * . If the maxlen argument of glk_request_line_event() is smaller than this,
1768 * the library will not allow the input cursor to go more than maxlen characters
1769 * past its start point.
1772 * This allows you to enter text in a fixed-width field, without the player
1773 * being able to overwrite other parts of the window.
1776 * When the player finishes his line of input, it will remain visible in the
1777 * window, and the output cursor will be positioned at the beginning of the
1778 * <emphasis>next</emphasis> row. Again, if you glk_cancel_line_event(), the
1779 * same thing happens.
1785 * A graphics window contains a rectangular array of pixels. Its size is the
1786 * number of columns and rows of the array.
1788 * Each graphics window has a background color, which is initially white. You
1789 * can change this; see <link
1790 * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
1793 * When a text grid window is resized smaller, the bottom or right area is
1794 * thrown away, but the remaining area stays unchanged. When it is resized
1795 * larger, the new bottom or right area is filled with the background color.
1798 * You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
1799 * graphics windows when you see them change size.
1802 * In some libraries, you can receive a graphics-redraw event (%evtype_Redraw)
1803 * at any time. This signifies that the window in question has been cleared to
1804 * its background color, and must be redrawn. If you create any graphics
1805 * windows, you <emphasis>must</emphasis> handle these events.
1808 * Redraw events can be triggered when a Glk window is uncovered or made
1809 * visible by the platform's window manager. On the other hand, some Glk
1810 * libraries handle these problem automatically — for example, with a
1811 * backing store — and do not send you redraw events. On the third hand,
1812 * the backing store may be discarded if memory is low, or for other reasons
1813 * — perhaps the screen's color depth has changed. So redraw events are
1814 * always a possibility, even in clever libraries. This is why you must be
1815 * prepared to handle them.
1817 * However, you will not receive a redraw event when you create a graphics
1818 * window. It is assumed that you will do the initial drawing of your own
1819 * accord. You also do not get redraw events when a graphics window is
1820 * enlarged. If you ordered the enlargement, you already know about it; if the
1821 * player is responsible, you receive a window-arrangement event, which covers
1825 * For a description of the drawing functions that apply to graphics windows,
1826 * see <link linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
1829 * Graphics windows support no text input or output.
1831 * Not all libraries support graphics windows. You can test whether Glk graphics
1832 * are available using the gestalt system. In a C program, you can also test
1833 * whether the graphics functions are defined at compile-time. See <link
1834 * linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics
1835 * Capabilities</link>.
1838 * As with all windows, you should also test for %NULL when you create a
1846 * When calling glk_window_open() with this @method, the new window will be
1847 * to the left of the old one which was split.
1853 * When calling glk_window_open() with this @method, the new window will be
1854 * to the right of the old one which was split.
1860 * When calling glk_window_open() with this @method, the new window will be
1861 * above the old one which was split.
1867 * When calling glk_window_open() with this @method, the new window will be
1868 * below the old one which was split.
1872 * winmethod_DirMask:
1874 * Bitwise AND this value with a window splitting method argument to find
1875 * whether the split is %winmethod_Left, %winmethod_Right, %winmethod_Above, or
1882 * When calling glk_window_open() with this @method, the new window will be
1883 * a fixed size. (See glk_window_open()).
1887 * winmethod_Proportional:
1889 * When calling glk_window_open() with this @method, the new window will be
1890 * a given proportion of the old window's size. (See glk_window_open()).
1894 * winmethod_DivisionMask:
1896 * Bitwise AND this value with a window splitting method argument to find
1897 * whether the new window has %winmethod_Fixed or %winmethod_Proportional.
1903 * Any other kind of file (preferences, statistics, arbitrary data.)
1907 * fileusage_SavedGame:
1909 * A file which stores game state.
1913 * fileusage_Transcript:
1915 * A file which contains a stream of text from the game (often an echo stream
1920 * fileusage_InputRecord:
1922 * A file which records player input.
1926 * fileusage_TextMode:
1928 * The file contents will be transformed to a platform-native text file as they
1929 * are written out. Newlines may be converted to linefeeds or
1930 * linefeed-plus-carriage-return combinations; Latin-1 characters may be
1931 * converted to native character codes. When reading a file in text mode, native
1932 * line breaks will be converted back to newline (0x0A) characters, and native
1933 * character codes may be converted to Latin-1.
1936 * Line breaks will always be converted; other conversions are more
1937 * questionable. If you write out a file in text mode, and then read it back
1938 * in text mode, high-bit characters (128 to 255) may be transformed or lost.
1940 * <note><title>Chimara</title>
1942 * Text mode files in Chimara are in UTF-8, which is GTK+'s native file
1948 * fileusage_BinaryMode:
1950 * The file contents will be stored exactly as they are written, and read back
1951 * in the same way. The resulting file may not be viewable on platform-native
1952 * text file viewers.
1956 * fileusage_TypeMask:
1958 * Bitwise AND this value with a file usage argument to find whether the file
1959 * type is %fileusage_SavedGame, %fileusage_Transcript, %fileusage_InputRecord,
1960 * or %fileusage_Data.
1969 * Corresponds to mode <code>"w"</code> in the stdio library, using fopen().
1979 * Corresponds to mode <code>"r"</code> in the stdio library, using fopen().
1984 * filemode_ReadWrite:
1986 * Both an input and an output stream.
1989 * Corresponds to mode <code>"r+"</code> in the stdio library, using fopen().
1994 * filemode_WriteAppend:
1996 * An output stream, but the data will added to the end of whatever already
1997 * existed in the destination, instead of replacing it.
2000 * Corresponds to mode <code>"a"</code> in the stdio library, using fopen().
2007 * In glk_stream_set_position(), signifies that @pos is counted in characters
2008 * after the beginning of the file.
2014 * In glk_stream_set_position(), signifies that @pos is counted in characters
2015 * after the current position (moving backwards if @pos is negative.)
2021 * In glk_stream_set_position(), signifies that @pos is counted in characters
2022 * after the end of the file. (@pos should always be zero or negative, so that
2023 * this will move backwards to a position within the file.
2027 * stylehint_Indentation:
2029 * How much to indent lines of text in the given style. May be a negative
2030 * number, to shift the text out (left) instead of in (right). The exact metric
2031 * isn't precisely specified; you can assume that +1 is the smallest indentation
2032 * possible which is clearly visible to the player.
2036 * stylehint_ParaIndentation:
2038 * How much to indent the first line of each paragraph. This is in addition to
2039 * the indentation specified by %stylehint_Indentation. This too may be
2040 * negative, and is measured in the same units as %stylehint_Indentation.
2044 * stylehint_Justification:
2046 * The value of this hint must be one of the constants
2047 * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification),
2048 * %stylehint_just_Centered, or %stylehint_just_RightFlush.
2054 * How much to increase or decrease the font size. This is relative; 0 means the
2055 * interpreter's default font size will be used, positive numbers increase it,
2056 * and negative numbers decrease it. Again, +1 is the smallest size increase
2057 * which is easily visible.
2059 * The amount of this increase may not be constant. +1 might increase an
2060 * 8-point font to 9-point, but a 16-point font to 18-point.
2067 * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for
2068 * normal weight, and -1 for light-weight fonts.
2072 * stylehint_Oblique:
2074 * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal
2079 * stylehint_Proportional:
2081 * The value of this hint must be 1 for proportional-width fonts, or 0 for
2086 * stylehint_TextColor:
2088 * The foreground color of the text. This is encoded in the 32-bit hint value:
2089 * the top 8 bits must be zero, the next 8 bits are the red value, the next 8
2090 * bits are the green value, and the bottom 8 bits are the blue value. Color
2091 * values range from 0 to 255.
2093 * So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.
2098 * stylehint_BackColor:
2100 * The background color behind the text. This is encoded the same way as
2101 * %stylehint_TextColor.
2105 * stylehint_ReverseColor:
2107 * The value of this hint must be 0 for normal printing (%stylehint_TextColor on
2108 * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on
2109 * %stylehint_TextColor).
2111 * Some libraries may support this hint but not the %stylehint_TextColor and
2112 * %stylehint_BackColor hints. Other libraries may take the opposite tack;
2113 * others may support both, or neither.
2118 * stylehint_NUMHINTS:
2120 * The number of style hints defined in this library.
2124 * stylehint_just_LeftFlush:
2126 * A value for %stylehint_Justification representing left-justified text.
2130 * stylehint_just_LeftRight:
2132 * A value for %stylehint_Justification representing fully justified text.
2136 * stylehint_just_Centered:
2138 * A value for %stylehint_Justification representing centered text.
2142 * stylehint_just_RightFlush:
2144 * A value for %stylehint_Justification representing right-justified text.
2147 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/
2152 * An integer type that can hold the Blorb error codes.
2162 * giblorb_err_CompileTime:
2164 * Something is compiled wrong in the Blorb layer.
2168 * giblorb_err_Alloc:
2170 * Memory could not be allocated.
2171 * <note><title>Chimara</title>
2173 * The Blorb layer in the Chimara library should not return this error code;
2174 * instead, the program aborts if memory allocation fails, in keeping with
2182 * Data could not be read from the file.
2186 * giblorb_err_NotAMap:
2188 * The map parameter is invalid.
2192 * giblorb_err_Format:
2194 * The Blorb file is corrupted or invalid.
2198 * giblorb_err_NotFound:
2200 * The requested data could not be found.
2204 * giblorb_method_DontLoad:
2206 * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2207 * giblorb_load_resource() to obtain information about a chunk without actually
2212 * giblorb_method_Memory:
2214 * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2215 * giblorb_load_resource() to load a chunk into memory.
2219 * giblorb_method_DontLoad:
2221 * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2222 * giblorb_load_resource() to get the position in the Blorb file at which the
2223 * chunk data starts.
2229 * Resource usage constant representing a sound file.
2235 * Resource usage constant representing an executable program.
2241 * Resource usage constant representing an image file.
2245 * giblorb_ID_Copyright:
2247 * Resource usage constant representing the copyright message (date and holder,
2248 * without the actual copyright symbol). There should only be one such chunk per
2255 * Resource usage constant representing the name of the author or creator of the
2256 * file. This could be a login name on multi-user systems, for example. There
2257 * should only be one such chunk per file.
2263 * Resource usage constant representing any textual annotation that the user or
2264 * writing program sees fit to include.
2270 * Holds the complete description of an open Blorb file. This type is opaque for
2271 * normal interpreter use.
2277 * Holds information about a chunk loaded from a Blorb file, and the method of
2278 * accessing the chunk data. See giblorb_load_chunk_by_type() and
2279 * giblorb_load_chunk_by_number().
2283 * giblorb_create_map:
2284 * @file: An input stream pointing to a Blorb file.
2285 * @newmap: Return location for a Blorb resource map.
2287 * Reads Blorb data out of a Glk stream. It does not load every resource at
2288 * once; instead, it creates a map in memory which makes it easy to find
2289 * resources. A pointer to the map is stored in @newmap. This is an opaque
2290 * object; you pass it to the other Blorb-layer functions.
2292 * Returns: a Blorb error code.
2296 * giblorb_destroy_map:
2297 * @map: A Blorb resource map to deallocate.
2299 * Deallocates @map and all associated memory. This does
2300 * <emphasis>not</emphasis> close the original stream.
2302 * Returns: a Blorb error code.
2306 * giblorb_load_chunk_by_type:
2307 * @map: The Blorb resource map to load a chunk from.
2308 * @method: The loading method to use, one of %giblorb_method_DontLoad,
2309 * %giblorb_method_Memory, or %giblorb_method_FilePos.
2310 * @res: Return location for the result.
2311 * @chunktype: The type of chunk to load.
2312 * @count: The chunk number of type @chunktype to load.
2314 * Loads a chunk of a given type. The @count parameter distinguishes between
2315 * chunks of the same type. If @count is zero, the first chunk of that type is
2316 * loaded, and so on.
2318 * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the
2319 * form type, rather than FORM.
2321 * This introduces a slight ambiguity — you cannot distiguish between a
2322 * FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is
2323 * almost certainly a mistake.
2326 * The returned data is written into @res, according to @method.
2328 * The <structfield>chunknum</structfield> field is filled in with the number of
2329 * the chunk. (This value can then be passed to giblorb_load_chunk_by_number()
2330 * or giblorb_unload_chunk().) The <structfield>length</structfield> field is
2331 * filled in with the length of the chunk in bytes. The
2332 * <structfield>chunktype</structfield> field is the chunk's type, which of
2333 * course will be the type you asked for.
2335 * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You
2336 * can use this if you are only interested in whether a chunk exists, or in the
2337 * <structfield>chunknum</structfield> and <structfield>length</structfield>
2340 * If you specify %giblorb_method_FilePos,
2341 * <structfield>data.startpos</structfield> is filled in with the file position
2342 * of the chunk data. You can use glk_stream_set_position() to read the data
2345 * If you specify %giblorb_method_Memory, <structfield>data.ptr</structfield> is
2346 * filled with a pointer to allocated memory containing the chunk data. This
2347 * memory is owned by the map, not you. If you load the chunk more than once
2348 * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one
2349 * copy in memory. You should not deallocate this memory yourself; call
2350 * giblorb_unload_chunk() instead.
2352 * Returns: a Blorb error code.
2356 * giblorb_load_chunk_by_number:
2357 * @map: The Blorb resource map to load a chunk from.
2358 * @method: The loading method to use, one of %giblorb_method_DontLoad,
2359 * %giblorb_method_Memory, or %giblorb_method_FilePos.
2360 * @res: Return location for the result.
2361 * @chunknum: The chunk number to load.
2363 * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a
2364 * given chunk number. The type of the chunk can be found in the
2365 * <structfield>chunktype</structfield> field of #giblorb_result_t. You can get
2366 * the chunk number from the <structfield>chunknum</structfield> field, after
2367 * calling one of the other load functions.
2369 * Returns: a Blorb error code.
2373 * giblorb_unload_chunk:
2374 * @map: The Blorb resource map to unload a chunk from.
2375 * @chunknum: The chunk number to unload.
2377 * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk
2378 * has never been loaded into memory, this has no effect.
2380 * Returns: a Blorb error code.
2384 * giblorb_load_resource:
2385 * @map: The Blorb resource map to load a resource from.
2386 * @method: The loading method to use, one of %giblorb_method_DontLoad,
2387 * %giblorb_method_Memory, or %giblorb_method_FilePos.
2388 * @res: Return location for the result.
2389 * @usage: The type of data resource to load.
2390 * @resnum: The resource number to load.
2392 * Loads a resource, given its usage and resource number. Currently, the three
2393 * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and
2394 * %giblorb_ID_Exec (executable program). See the Blorb specification for more
2395 * information about the types of data that can be stored for these usages.
2397 * Note that a resource number is not the same as a chunk number. The resource
2398 * number is the sound or image number specified by a Glk program. Chunk number
2399 * is arbitrary, since chunks in a Blorb file can be in any order. To find the
2400 * chunk number of a given resource, call giblorb_load_resource() and look in
2401 * <structfield>res.chunknum</structfield>.
2403 * Returns: a Blorb error code.
2407 * giblorb_count_resources:
2408 * @map: The Blorb resource map in which to count the resources.
2409 * @usage: The type of data resource to count.
2410 * @num: Return location for the number of chunks of @usage.
2411 * @min: Return location for the lowest resource number of @usage.
2412 * @max: Return location for the highest resource number of @usage.
2414 * Counts the number of chunks with a given usage (image, sound, or executable.)
2415 * The total number of chunks of that usage is stored in @num. The lowest and
2416 * highest resource number of that usage are stored in @min and @max. You can
2417 * leave any of the three pointers %NULL if you don't care about that
2420 * Returns: a Blorb error code.
2423 /*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/
2426 * glkunix_argumentlist_t:
2428 * In each entry, name is the option as it would appear on the command line
2429 * (including the leading dash, if any.) The desc is a description of the
2430 * argument; this is used when the library is printing a list of options. And
2431 * argtype is one of the following constants:
2435 * <term>%glkunix_arg_NoValue</term>
2436 * <listitem><para>The argument appears by itself.</para></listitem>
2439 * <term>%glkunix_arg_ValueFollows</term>
2440 * <listitem><para>The argument must be followed by another argument (the
2441 * value).</para></listitem>
2444 * <term>%glkunix_arg_ValueCanFollow</term>
2445 * <listitem><para>The argument may be followed by a value, optionally. (If the
2446 * next argument starts with a dash, it is taken to be a new argument, not the
2447 * value of this one.)</para></listitem>
2450 * <term>%glkunix_arg_NumberValue</term>
2451 * <listitem><para>The argument must be followed by a number, which may be the
2452 * next argument or part of this one. (That is, either <quote><code>-width
2453 * 20</code></quote> or <quote><code>-width20</code></quote> will be accepted.)
2454 * </para></listitem>
2457 * <term>%glkunix_arg_End</term>
2458 * <listitem><para>The <code>glkunix_arguments[]</code> array must be
2459 * terminated with an entry containing this value.</para></listitem>
2463 * To accept arbitrary arguments which lack dashes, specify a name of
2464 * <code>""</code> and an argtype of %glkunix_arg_ValueFollows.
2466 * If you don't care about command-line arguments, you must still define an
2467 * empty arguments list, as follows:
2469 * #glkunix_argumentlist_t glkunix_arguments[] = {
2470 * { NULL, #glkunix_arg_End, NULL }
2474 * Here is a more complete sample list:
2476 * #glkunix_argumentlist_t glkunix_arguments[] = {
2477 * { "", #glkunix_arg_ValueFollows, "filename: The game file to load." },
2478 * { "-hum", #glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
2479 * { "-bom", #glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
2480 * the NUM, if given)." },
2481 * { "-goo", #glkunix_arg_NoValue, "-goo: Find goo." },
2482 * { "-wob", #glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
2483 * { NULL, #glkunix_arg_End, NULL }
2486 * This would match the arguments <quote><code>thingfile -goo -wob8 -bom -hum
2487 * song</code></quote>.
2489 * After the library parses the command line, it does various occult rituals of
2490 * initialization, and then calls glkunix_startup_code().
2492 * |[ int glkunix_startup_code(#glkunix_startup_t *data); ]|
2494 * This should return %TRUE if everything initializes properly. If it returns
2495 * %FALSE, the library will shut down without ever calling your glk_main()
2500 * glkunix_startup_t:
2502 * The fields are a standard Unix <code>(argc, argv)</code> list, which contain
2503 * the arguments you requested from the command line. In deference to custom,
2504 * <code>argv[0]</code> is always the program name.
2510 * Terminates a list of #glkunix_argumentlist_t.
2514 * glkunix_arg_ValueFollows:
2516 * Indicates an argument which must be followed by a value, as the next
2521 * glkunix_arg_NoValue:
2523 * Indicates an argument which occurs by itself, without a value.
2527 * glkunix_arg_ValueCanFollow:
2529 * Indicates an argument which may be followed by a value, or may occur by
2534 * glkunix_arg_NumberValue:
2536 * Indicates an argument which must be followed by a numerical value, either as
2537 * the next argument or tacked onto the end of this argument.