Implemented the signals 'char-input', 'line-input', and 'text-buffer-output' on the...
[rodin/chimara.git] / libchimara / doc.c
1 /*
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.
5  */
6
7 /**
8  * SECTION:glk-exiting
9  * @short_description: How to terminate a Glk program cleanly
10  * @include: libchimara/glk.h
11  *
12  * A Glk program usually ends when the end of the glk_main() function is 
13  * reached. You can also terminate it earlier.
14  */ 
15
16 /**
17  * SECTION:glk-interrupt
18  * @short_description: Specifying an interrupt handler for cleaning up critical
19  * resources
20  * @include: libchimara/glk.h
21  *
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.
29  *
30  * If you need to clean up critical resources, you can specify an interrupt
31  * handler function.
32  */
33
34 /**
35  * SECTION:glk-tick
36  * @short_description: Yielding time to the operating system
37  * @include: libchimara/glk.h
38  *
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.
41  * 
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
45  * loop.
46  */
47
48 /**
49  * SECTION:glk-types
50  * @short_description: Basic types used in Glk
51  * @include: libchimara/glk.h
52  *
53  * For simplicity, all the arguments used in Glk calls are of a very few types.
54  * <variablelist>
55  *  <varlistentry>
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>
59  *  </varlistentry>
60  *  <varlistentry>
61  *    <term>32-bit signed integer</term>
62  *    <listitem><para>This type is called #glsi32. Rarely used.</para>
63  *    </listitem>
64  *  </varlistentry>
65  *  <varlistentry>
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>
71  *  </varlistentry>
72  *  <varlistentry>
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>
76  *  </varlistentry>
77  *  <varlistentry>
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>.
81  *    </para></listitem>
82  *  </varlistentry>
83  *  <varlistentry>
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>
88  *  </varlistentry>
89  *  <varlistentry>
90  *    <term>Pointer to <type>void</type></term> 
91  *    <listitem><para>When nothing else will do.</para></listitem>
92  *  </varlistentry>
93  * </variablelist>
94  */
95
96 /**
97  * SECTION:glk-opaque-objects
98  * @short_description: Complex objects in Glk
99  * @include: libchimara/glk.h
100  *
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.
103  * 
104  * Currently, these classes are:
105  * <variablelist>
106  *  <varlistentry>
107  *    <term>Windows</term>
108  *    <listitem><para>Screen panels, used to input or output information.
109  *    </para></listitem>
110  *  </varlistentry>
111  *  <varlistentry>
112  *    <term>Streams</term>
113  *    <listitem><para>Data streams, to which you can input or output text.
114  *    </para>
115  *    <note><para>There are file streams and window streams, since you can
116  *    output data to windows or files.</para></note>
117  *    </listitem>
118  *  </varlistentry>
119  *  <varlistentry>
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>
125  *    </listitem>
126  *  </varlistentry>
127  *  <varlistentry>
128  *    <term>Sound channels</term>
129  *    <listitem><para>Audio output channels.</para>
130  *    <note><para>Not all Glk libraries support sound.</para></note>
131  *    </listitem>
132  *  </varlistentry>
133  * </variablelist>
134  *
135  * <note><para>
136  * Note that there may be more object classes in future versions of the Glk API.
137  * </para></note>
138  * 
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.
143  * 
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.
149  * 
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.
155  * 
156  * <note><para>
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.
160  * </para></note>
161  * <refsect2 id="chimara-Rocks"><!-- Indeed it does. -->
162  * <title>Rocks</title>
163  * <para>
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.
167  * </para>
168  * <note><para>The library &mdash; so to speak &mdash; stuffs this value under a
169  * rock for safe-keeping, and gives it back to you when you ask for it.
170  * </para></note>
171  * <note><para>If you don't know what to use the rocks for, provide 0 and forget
172  * about it.</para></note>
173  * </refsect2>
174  * <refsect2 id="chimara-Iterating-Through-Opaque-Objects">
175  * <title>Iteration Through Opaque Objects</title>
176  * <para>
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
179  * |[
180  * <replaceable>CLASS</replaceable>id_t glk_<replaceable>CLASS</replaceable>_iterate(<replaceable>CLASS</replaceable>id_t <parameter>obj</parameter>, #glui32 *<parameter>rockptr</parameter>);
181  * ]|
182  * ...where <code><replaceable>CLASS</replaceable></code> represents one of the
183  * opaque object classes. 
184  * </para>
185  * <note><para>
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
189  *   the same.
190  * </para></note>
191  * <para>
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.
196  * </para>
197  * <para>
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.
202  * </para>
203  * <para>
204  * You usually use this as follows:
205  * |[
206  * obj = glk_<replaceable>CLASS</replaceable>_iterate(NULL, NULL);
207  * while (obj) {
208  *    /* ...do something with obj... *<!-- -->/
209  *    obj = glk_<replaceable>CLASS</replaceable>_iterate(obj, NULL);
210  * }
211  * ]|
212  * </para>
213  * <para>
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.
218  * </para>
219  * <para>
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. 
226  * </para>
227  * </refsect2>
228  */
229
230 /**
231  * SECTION:glk-gestalt
232  * @short_description: Testing Glk's capabilities
233  * @include: libchimara/glk.h
234  *
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 &mdash; those which not all Glk library
240  * implementations will support &mdash; and allows you to check for their
241  * presence without trying to infer them from a version number.
242  * 
243  * The basic idea is that you can request information about the capabilities of
244  * the API, by calling the gestalt functions.
245  */
246
247 /**
248  * SECTION:glk-character-input
249  * @short_description: Waiting for a single keystroke
250  * @include: libchimara/glk.h
251  *
252  * You can request that the player hit a single key. See <link 
253  * linkend="chimara-Character-Input-Events">Character Input Events</link>.
254  * 
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
261  * others.
262  * 
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
272  * is included below.
273  * 
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.
285  * 
286  * <note><para>
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.
296  * </para></note>
297  * 
298  * Some characters may not be enterable simply because they do not exist.
299  * 
300  * <note><para>
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.
304  * </para></note>
305  * 
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>
312  * event.
313  * 
314  * <note><para>
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>.
323  * </para></note>
324  * 
325  * <note><para>
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
334  *   large problem.
335  * </para></note>
336  *
337  * You can test for this by using the %gestalt_CharInput selector.
338  * 
339  * <note><para>
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>
353  *   instead.
354  * </para>
355  * <para>
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.
363  * </para></note>
364  */
365
366 /**
367  * SECTION:glk-case
368  * @short_description: Changing the case of strings
369  * @include: libchimara/glk.h
370  *
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.
375  */
376
377 /**
378  * SECTION:glk-window-opening
379  * @short_description: Creating new windows and closing them
380  * @include: libchimara/glk.h
381  *
382  * You can open a new window using glk_window_open() and close it again using
383  * glk_window_close().
384  */
385
386 /**
387  * SECTION:glk-window-constraints
388  * @short_description: Manipulating the size of a window
389  * @include: libchimara/glk.h
390  *
391  * There are library functions to change and to measure the size of a window.
392  */
393
394 /**
395  * SECTION:glk-window-types
396  * @short_description: Blank, pair, text grid, text buffer, and graphics windows
397  * @include: libchimara/glk.h
398  * 
399  * A technical description of all the window types, and exactly how they behave.
400  */
401
402 /**
403  * SECTION:glk-echo-streams
404  * @short_description: Creating a copy of a window's output
405  * @include: libchimara/glk.h
406  *
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>
411  * 
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().
415  * 
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. 
419  *
420  * An echo stream can be of any type, even another window's window stream.
421  * 
422  * <note><para>
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.
427  * </para></note>
428  *
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.
431  *
432  * If a window is closed, its echo stream remains open; it is not automatically
433  * closed. 
434  *
435  * <note><para>
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.
439  * </para></note>
440  * 
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.) 
444  */
445
446 /**
447  * SECTION:glk-window-other
448  * @short_description: Miscellaneous functions for windows
449  * @include: libchimara/glk.h
450  *
451  * This section contains functions for windows that don't fit anywhere else.
452  */
453
454 /**
455  * SECTION:glk-events
456  * @short_description: Waiting for events
457  * @include: libchimara/glk.h
458  *
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.
463  */
464
465 /**
466  * SECTION:glk-character-input-events
467  * @short_description: Events representing a single keystroke
468  * @include: libchimara/glk.h
469  *
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.
473  */
474
475 /**
476  * SECTION:glk-line-input-events
477  * @short_description: Events representing a line of user input
478  * @include: libchimara/glk.h
479  *
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.
483  */
484
485 /**
486  * SECTION:glk-timer-events
487  * @short_description: Events sent at fixed intervals
488  * @include: libchimara/glk.h
489  *
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().
493  *
494  * It is possible that the library does not support timer events. You can check
495  * this with the %gestalt_Timer selector.
496  */
497  
498 /**
499  * SECTION:glk-streams
500  * @short_description: Input and output abstractions
501  * @include: libchimara/glk.h
502  *
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.
506  *
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. 
509  *
510  * <note><para>
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.
516  * </para></note>
517  *
518  * It is also possible to create a stream that reads or writes to a buffer in
519  * memory.
520  * 
521  * Finally, there may be platform-specific types of streams, which are created
522  * before your program starts running. 
523  *
524  * <note><para>
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.
529  * </para></note>
530  *
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>.
534  * 
535  * A stream is opened with a particular file mode, see the 
536  * <code>filemode_</code> constants below.
537  *
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.
542  * 
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
546  * cookery. 
547  *
548  * <note><para>
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.
552  * </para></note>
553  * 
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.) 
556  *
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
561  * there isn't one.
562  *
563  * If the stream which is the current stream is closed, the current stream
564  * becomes %NULL. 
565  */
566  
567 /**
568  * SECTION:glk-print
569  * @short_description: Printing to streams
570  * @include: libchimara/glk.h
571  *
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.
575  */
576  
577 /**
578  * SECTION:glk-read
579  * @short_description: Reading from streams
580  * @include: libchimara/glk.h
581  *
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
584  * them.
585  */
586  
587 /**
588  * SECTION:glk-closing-streams
589  * @short_description: Closing streams and retrieving their character counts
590  * @include: libchimara/glk.h
591  *
592  * When you close a Glk stream, you have the opportunity to examine the
593  * character counts &mdash; the number of characters written to or read from the
594  * stream.
595  */
596
597 /**
598  * SECTION:glk-stream-positions
599  * @short_description: Moving the read/write mark
600  * @include: libchimara/glk.h
601  *
602  * You can set the position of the read/write mark in a stream.
603  *
604  * <note><para>
605  *   Which makes one wonder why they're called <quote>streams</quote> in the
606  *   first place. Oh well.
607  * </para></note>
608  */
609
610 /**
611  * SECTION:glk-styles
612  * @short_description: Changing the appearance of printed text
613  * @include: libchimara/glk.h
614  *
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.
621  * 
622  * Styles are exclusive. A character is shown with exactly one style, not a 
623  * subset of the possible styles.
624  *
625  * <note><para>
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
628  *  affect any others.
629  * </para></note>
630  * <note><para>
631  *  Except for a window's echo stream; see <link 
632  *  linkend="chimara-Echo-Streams">Echo Streams</link>.
633  * </para></note>
634  * 
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.
639  * 
640  * There are currently eleven styles defined. More may be defined in the future.
641  * 
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 &mdash; call 
646  * glk_set_style() immediately after printing the newline at the beginning of
647  * the text, and do the same at the end.
648  * 
649  * <note><para>
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.
660  * </para></note> 
661  * 
662  * <note><para>
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
665  *  you.
666  * </para></note>
667  */
668
669 /**
670  * SECTION:glk-stylehints
671  * @short_description: Setting style hints
672  * @include: libchimara/glk.h
673  *
674  * There are no guarantees of how styles will look, but you can make 
675  * suggestions.
676  *
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.
679  * 
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.
685  * 
686  * <note><para>
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.
690  * </para></note>
691  * 
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.
699  * 
700  * There are currently ten style hints defined. More may be defined in the 
701  * future. 
702  * 
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 
705  * ignore it. 
706  * <note><para>
707  *  This policy allows for the future definition of style hints without breaking
708  *  old Glk libraries.
709  * </para></note> 
710  */
711
712 /**
713  * SECTION:glk-stream-types
714  * @short_description: Window, memory, and file streams
715  * @include: libchimara/glk.h
716  *
717  * <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
718  * <para>
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().
722  * 
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().
725  * 
726  * Only printable characters (including newline) may be printed to a window
727  * stream. See <link linkend="chimara-Character-Encoding">Character 
728  * Encoding</link>.
729  * </para>
730  * </refsect2>
731  * <refsect2 id="chimara-Memory-Streams"><title>Memory Streams</title>
732  * <para>
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.
737  *
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.)
743  *
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.
747  *
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.
751  *
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.
755  *
756  * <note><para>
757  *   You can write a disk file in text mode, but a memory stream is effectively
758  *   always in binary mode.
759  * </para></note>
760  * 
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.
765  * </para>
766  * </refsect2>
767  * <refsect2 id="chimara-File-Streams"><title>File Streams</title>
768  * <para>
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().
771  *
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>.
776  * </para>
777  * </refsect2>
778  */
779  
780 /**
781  * SECTION:glk-stream-other
782  * @short_description: Miscellaneous functions for streams
783  * @include: libchimara/glk.h
784  *
785  * This section includes functions for streams that don't fit anywhere else.
786  */
787
788 /**
789  * SECTION:glk-fileref
790  * @short_description: A platform-independent way to refer to disk files
791  * @include: libchimara/glk.h
792  *
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 
795  * Objects</link>.
796  * 
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
800  * or binary file. 
801  *
802  * <note><para>
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.
805  * </para></note>
806  * 
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
809  * create a new file.
810  * 
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. 
815  * 
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. 
822  */
823  
824 /**
825  * SECTION:glk-fileref-types
826  * @short_description: Four different ways to create a file reference
827  * @include: libchimara/glk.h
828  *
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.
832  */
833  
834 /**
835  * SECTION:glk-fileref-other
836  * @short_description: Miscellaneous functions for file references
837  * @include: libchimara/glk.h
838  *
839  * This section includes functions for file references that don't fit anywhere
840  * else.
841  */
842
843 /**
844  * SECTION:dispatch-interrogating
845  * @short_description: Finding out what functions the Glk library exports
846  * @include: libchimara/glk.h, libchimara/gi_dispa.h
847  *
848  * These are the ancilliary functions that let you enumerate.
849  */
850  
851 /**
852  * SECTION:dispatch-dispatching
853  * @short_description: Dispatching the call to the Glk library
854  * @include: libchimara/glk.h, libchimara/gi_dispa.h
855  */
856  
857 /**
858  * SECTION:dispatch-prototypes
859  * @short_description: Querying Glk function prototypes
860  * @include: libchimara/glk.h, libchimara/gi_dispa.h
861  *
862  * There are many possible ways to set up a #gluniversal_t array, and it's
863  * illegal to call gidispatch_call() with an array which doesn't match the
864  * function. Furthermore, some references are passed in, some passed out, and
865  * some both. How do you know how to handle the argument list?
866  * 
867  * One possibility is to recognize each function selector, and set up the
868  * arguments appropriately. However, this entails writing special code for each
869  * Glk function; which is exactly what we don't want to do.
870  * 
871  * Instead, you can call gidispatch_prototype(). 
872  */
873
874 /**
875  * SECTION:dispatch-library-functions
876  * @short_description: Platform-dependent dispatch layer functions
877  * @include: libchimara/glk.h, libchimara/gi_dispa.h
878  *
879  * Ideally, the three layers &mdash; program, dispatch layer, Glk library
880  * &mdash; would be completely modular; each would refer only to the layers
881  * beneath it. Sadly, there are a few places where the library must notify the
882  * program that something has happened. Worse, these situations are only
883  * relevant to programs which use the dispatch layer, and then only some of
884  * those.
885  * 
886  * Since C is uncomfortable with the concept of calling functions which may not
887  * exist, Glk handles this with call-back function pointers. The program can
888  * pass callbacks in to the library; if it does, the library will call them, and
889  * if not, the library doesn't try.
890  * 
891  * These callbacks are optional, in the sense that the program may or may not
892  * set them. However, any library which wants to interoperate with the dispatch
893  * layer must <emphasis>allow</emphasis> the program to set them; it is the
894  * program's choice. The library does this by implementing
895  * <code>set_registry functions</code> &mdash; the functions to which the
896  * program passes its callbacks.
897  * 
898  * <note><para>
899  *   Even though these callbacks and the functions to set them are declared in
900  *   <filename class="headerfile">gi_dispa.h</filename>, they are not defined in
901  *   <filename>gi_dispa.c</filename>. The dispatch layer merely coordinates
902  *   them. The program defines the callback functions; the library calls them.
903  * </para></note>
904  */
905
906 /** 
907  * SECTION:blorb-program
908  * @short_description: How to use the Blorb layer in your program
909  * @include: libchimara/glk.h, libchimara/gi_blorb.h
910  *
911  * If you wish your program to load its resources from a Blorb file, you need to
912  * find and open that file in your startup code. (See <link 
913  * linkend="chimara-Startup-Options">Startup Options</link>.) Each platform will
914  * have appropriate functions available for finding startup data. Be sure to
915  * open the file in binary mode, not text mode. Once you have opened the file as
916  * a Glk stream, pass it to giblorb_set_resource_map().
917  *
918  * If you do not call giblorb_set_resource_map() in your startup code, or if it
919  * fails, the library is left to its own devices for finding resources. Some
920  * libraries may try to load resources from individual files &mdash; 
921  * <filename>PIC1</filename>, <filename>PIC2</filename>, 
922  * <filename>PIC3</filename>, and so on. (See the Blorb specification for more 
923  * on this approach.) Other libraries will not have any other loading mechanism
924  * at all; no resources will be available. 
925  */
926
927 /**
928  * SECTION:blorb-layer
929  * @short_description: The platform-independent functions in the Blorb layer
930  * @include: libchimara/glk.h, libchimara/gi_blorb.h
931  *
932  * These are the functions which are implemented in 
933  * <filename>gi_blorb.c</filename>. They will be compiled into the library, but
934  * they are the same on every platform. In general, only the library needs to
935  * call these functions. The Glk program should allow the library to do all the
936  * resource handling.
937  */ 
938  
939 /** 
940  * SECTION:blorb-errors
941  * @short_description: Error codes returned by the Blorb layer functions
942  * @include: libchimara/glk.h, libchimara/gi_blorb.h
943  *
944  * All Blorb layer functions, including giblorb_set_resource_map(), return the
945  * following error codes.
946  */
947
948 /**
949  * SECTION:glkext-startup
950  * @short_description: Parsing startup options
951  * @include: libchimara/glk.h, libchimara/glkstart.h
952  *
953  * This section describes an extension to Glk for parsing command-line startup
954  * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and
955  * GlkTerm. 
956  *
957  * When you compile a Glk program, you may define a function called 
958  * glkunix_startup_code(), and an array <code>glkunix_arguments[]</code>. These
959  * set up various Unix-specific options used by the Glk library. There is a
960  * sample <quote><filename>glkstart.c</filename></quote> file included in this 
961  * package; you should modify it to your needs.
962  * 
963  * |[ extern #glkunix_argumentlist_t glkunix_arguments[]; ]|
964  *  
965  * The <code>glkunix_arguments[]</code> array is a list of command-line 
966  * arguments that your program can accept. The library will sort these out of 
967  * the command line and pass them on to your code.
968  */
969
970 /**
971  * SECTION:glkext-unix
972  * @short_description: Unix-specific functions
973  * @include: libchimara/glk.h, libchimara/glkstart.h
974  *
975  * This section describes an extension to Glk for various Unix functions. It was
976  * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm.
977  *
978  * You can put other startup code in glkunix_startup_code(). This should
979  * generally be limited to finding and opening data files. There are a few Unix
980  * Glk library functions which are convenient for this purpose.
981  */
982  
983 /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/
984
985 /**
986  * glui32:
987  *
988  * A 32-bit unsigned integer type, used wherever possible in Glk.
989  */
990  
991 /**
992  * glsi32:
993  *
994  * A 32-bit signed integer type, rarely used.
995  */
996
997 /**
998  * GLK_MODULE_UNICODE:
999  *
1000  * If this preprocessor symbol is defined, so are all the Unicode functions and
1001  * constants (see %gestalt_Unicode). If not, not.
1002  */
1003
1004 /**
1005  * winid_t:
1006  *
1007  * Opaque structure representing a Glk window. It has no user-accessible 
1008  * members.
1009  */
1010  
1011 /**
1012  * strid_t:
1013  *
1014  * Opaque structure representing an input or output stream. It has no
1015  * user-accessible members.
1016  */
1017  
1018 /**
1019  * frefid_t:
1020  * 
1021  * Opaque structure representing a file reference. It has no user-accessible
1022  * members.
1023  */
1024
1025 /**
1026  * gestalt_Version:
1027  *
1028  * For an example of the gestalt mechanism, consider the selector
1029  * %gestalt_Version. If you do
1030  * |[
1031  * #glui32 res;
1032  * res = #glk_gestalt(#gestalt_Version, 0);
1033  * ]|
1034  * <code>res</code> will be set to a 32-bit number which encodes the version of
1035  * the Glk spec which the library implements. The upper 16 bits stores the major
1036  * version number; the next 8 bits stores the minor version number; the low 8 
1037  * bits stores an even more minor version number, if any.
1038  *
1039  * <note><para>
1040  *   So the version number 78.2.11 would be encoded as 0x004E020B.
1041  * </para></note>
1042  *
1043  * The current Glk specification version is 0.7.0, so this selector will return
1044  * 0x00000700.
1045  *
1046  * |[
1047  * #glui32 res;
1048  * res = #glk_gestalt_ext(#gestalt_Version, 0, NULL, 0);
1049  * ]|
1050  * does exactly the same thing. Note that, in either case, the second argument 
1051  * is not used; so you should always pass 0 to avoid future surprises.
1052  */
1053
1054 /**
1055  * gestalt_CharInput:
1056  *
1057  * If you set <code>ch</code> to a character code, or a special code (from
1058  * 0xFFFFFFFF down), and call
1059  * |[
1060  * #glui32 res;
1061  * res = #glk_gestalt(#gestalt_CharInput, ch);
1062  * ]|
1063  * then <code>res</code> will be %TRUE (1) if that character can be typed by
1064  * the player in character input, and %FALSE (0) if not. See <link
1065  * linkend="chimara-Character-Input">Character Input</link>.
1066  */
1067
1068 /**
1069  * gestalt_LineInput:
1070  *
1071  * If you set <code>ch</code> to a character code, and call
1072  * |[
1073  * #glui32 res;
1074  * res = #glk_gestalt(#gestalt_LineInput, ch);
1075  * ]|
1076  * then <code>res</code> will be %TRUE (1) if that character can be typed by the
1077  * player in line input, and %FALSE (0) if not. Note that if <code>ch</code> is 
1078  * a nonprintable Latin-1 character (0 to 31, 127 to 159), then this is 
1079  * guaranteed to return %FALSE. See <link linkend="chimara-Line-Input">Line
1080  * Input</link>.
1081  */
1082
1083 /**
1084  * gestalt_CharOutput:
1085  *
1086  * If you set <code>ch</code> to a character code (Latin-1 or higher), and call
1087  * |[
1088  * #glui32 res, len;
1089  * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &amp;len, 1);
1090  * ]|
1091  * then <code>res</code> will be one of %gestalt_CharOutput_CannotPrint,
1092  * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see 
1093  * below.)
1094  * 
1095  * In all cases, <code>len</code> (the #glui32 value pointed at by the third
1096  * argument) will be the number of actual glyphs which will be used to represent
1097  * the character. In the case of %gestalt_CharOutput_ExactPrint, this will 
1098  * always be 1; for %gestalt_CharOutput_CannotPrint, it may be 0 (nothing 
1099  * printed) or higher; for %gestalt_CharOutput_ApproxPrint, it may be 1 or 
1100  * higher. This information may be useful when printing text in a fixed-width 
1101  * font.
1102  *
1103  * <note><para>
1104  *   As described in <link linkend="chimara-Other-API-Conventions">Other API
1105  *   Conventions</link>, you may skip this information by passing %NULL as the
1106  *   third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead.
1107  * </para></note>
1108  *
1109  * This selector will always return %gestalt_CharOutput_CannotPrint if 
1110  * <code>ch</code> is an unprintable eight-bit character (0 to 9, 11 to 31, 127 
1111  * to 159.)
1112  *
1113  * <note><para>
1114  *   Make sure you do not get confused by signed byte values. If you set a
1115  *   <quote><type>char</type></quote> variable <code>ch</code> to 0xFE, the 
1116  *   small-thorn character (&thorn;), and then call
1117  *   |[ res = #glk_gestalt(#gestalt_CharOutput, ch); ]|
1118  *   then (by the definition of C/C++) <code>ch</code> will be sign-extended to
1119  *   0xFFFFFFFE, which is not a legitimate character, even in Unicode. You 
1120  *   should write
1121  *   |[ res = #glk_gestalt(#gestalt_CharOutput, (unsigned char)ch); ]|
1122  *   instead.
1123  * </para></note>
1124  * <note><para>
1125  *   Unicode includes the concept of non-spacing or combining characters, which 
1126  *   do not represent glyphs; and double-width characters, whose glyphs take up
1127  *   two spaces in a fixed-width font. Future versions of this spec may 
1128  *   recognize these concepts by returning a <code>len</code> of 0 or 2 when
1129  *   %gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to 
1130  *   a policy of <quote>simple stuff first</quote>.
1131  * </para></note>
1132  */
1133  
1134 /**
1135  * gestalt_CharOutput_CannotPrint:
1136  *
1137  * When the %gestalt_CharOutput selector returns this for a character, the
1138  * character cannot be meaningfully printed. If you try, the player may see
1139  * nothing, or may see a placeholder.
1140  */
1141
1142 /**
1143  * gestalt_CharOutput_ApproxPrint:
1144  *
1145  * When the %gestalt_CharOutput selector returns this for a character, the 
1146  * library will print some approximation of the character. It will be more or 
1147  * less right, but it may not be precise, and it may not be distinguishable from
1148  * other, similar characters. (Examples: 
1149  * <quote><computeroutput>ae</computeroutput></quote> for the one-character
1150  * <quote>&aelig;</quote> ligature, 
1151  * <quote><computeroutput>e</computeroutput></quote> for 
1152  * <quote>&egrave;</quote>, <quote><computeroutput>|</computeroutput></quote> 
1153  * for a broken vertical bar (&brvbar;).)
1154  */
1155  
1156 /**
1157  * gestalt_CharOutput_ExactPrint:
1158  *
1159  * When the %gestalt_CharOutput selector returns this for a character, the
1160  * character will be printed exactly as defined.
1161  */
1162
1163 /**
1164  * gestalt_Unicode:
1165  *
1166  * The basic text functions will be available in every Glk library. The Unicode
1167  * functions may or may not be available. Before calling them, you should use
1168  * the following gestalt selector:
1169  * |[
1170  * glui32 res;
1171  * res = #glk_gestalt(#gestalt_Unicode, 0);
1172  * ]|
1173  * 
1174  * This returns 1 if the Unicode functions are available. If it returns 0, you
1175  * should not try to call them. They may print nothing, print gibberish, or
1176  * cause a run-time error. The Unicode functions include
1177  * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),  
1178  * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
1179  * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
1180  * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
1181  * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
1182  * glk_request_char_event_uni(), glk_request_line_event_uni(),
1183  * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
1184  * 
1185  * If you are writing a C program, there is an additional complication. A
1186  * library which does not support Unicode may not implement the Unicode
1187  * functions at all. Even if you put gestalt tests around your Unicode calls,
1188  * you may get link-time errors. If the 
1189  * <filename class="headerfile">glk.h</filename> file is so old that it does not
1190  * declare the Unicode functions and constants, you may even get compile-time
1191  * errors.
1192  * 
1193  * To avoid this, you can perform a preprocessor test for the existence of
1194  * #GLK_MODULE_UNICODE. 
1195  */
1196
1197 /**
1198  * gestalt_Timer:
1199  *
1200  * You can test whether the library supports timer events:
1201  * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]|
1202  * This returns 1 if timer events are supported, and 0 if they are not.
1203  */
1204  
1205 /**
1206  * evtype_None:
1207  *
1208  * No event. This is a placeholder, and glk_select() never returns it.
1209  */
1210
1211 /**
1212  * evtype_Timer:
1213  *
1214  * An event that repeats at fixed intervals. See <link 
1215  * linkend="chimara-Timer-Events">Timer Events</link>.
1216  */
1217  
1218 /**
1219  * evtype_CharInput:
1220  *
1221  * A keystroke event in a window. See <link 
1222  * linkend="chimara-Character-Input-Events">Character Input Events</link>.
1223  *
1224  * If a window has a pending request for character input, and the player hits a
1225  * key in that window, glk_select() will return an event whose type is
1226  * %evtype_CharInput. Once this happens, the request is complete; it is no 
1227  * longer pending. You must call glk_request_char_event() or
1228  * glk_request_char_event_uni() if you want another character from that window.
1229  * 
1230  * In the event structure, @win tells what window the event came from. @val1 
1231  * tells what character was entered; this will be a character code, or a special
1232  * keycode. (See <link linkend="chimara-Character-Input">Character 
1233  * Input</link>.) If you called glk_request_char_event(), @val1 will be in 
1234  * 0..255, or else a special keycode. In any case, @val2 will be 0.
1235  */
1236
1237 /**
1238  * evtype_LineInput:
1239  *
1240  * A full line of input completed in a window. See <link 
1241  * linkend="chimara-Line-Input-Events">Line Input Events</link>.
1242  *
1243  * If a window has a pending request for line input, and the player hits
1244  * <keycap>enter</keycap> in that window (or whatever action is appropriate to
1245  * enter his input), glk_select() will return an event whose type is
1246  * %evtype_LineInput. Once this happens, the request is complete; it is no 
1247  * longer pending. You must call glk_request_line_event() if you want another 
1248  * line of text from that window.
1249  * 
1250  * In the event structure, @win tells what window the event came from. @val1 
1251  * tells how many characters were entered. @val2 will be 0. The characters
1252  * themselves are stored in the buffer specified in the original
1253  * glk_request_line_event() or glk_request_line_event_uni() call. 
1254  *
1255  * <note><para>There is no null terminator stored in the buffer.</para></note>
1256  * 
1257  * It is illegal to print anything to a window which has line input pending. 
1258  *
1259  * <note><para>
1260  *   This is because the window may be displaying and editing the player's 
1261  *   input, and printing anything would make life unnecessarily complicated for
1262  *   the library.
1263  * </para></note>
1264  */
1265
1266 /**
1267  * evtype_MouseInput:
1268  *
1269  * A mouse click in a window. See <link 
1270  * linkend="chimara-Mouse-Input-Events">Mouse Input Events</link>.
1271  */
1272  
1273 /**
1274  * evtype_Arrange:
1275  *
1276  * An event signalling that the sizes of some windows have changed. 
1277  * 
1278  * Some platforms allow the player to resize the Glk window during play. This 
1279  * will naturally change the sizes of your windows. If this occurs, then
1280  * immediately after all the rearrangement, glk_select() will return an event
1281  * whose type is %evtype_Arrange. You can use this notification to redisplay the
1282  * contents of a graphics or text grid window whose size has changed.
1283  *
1284  * <note><para>
1285  *   The display of a text buffer window is entirely up to the library, so you
1286  *   don't need to worry about those.
1287  * </para></note>
1288  * 
1289  * In the event structure, @win will be %NULL if all windows are affected. If 
1290  * only some windows are affected, @win will refer to a window which contains 
1291  * all the affected windows. @val1 and @val2 will be 0.
1292  *
1293  * <note><para>
1294  *   You can always play it safe, ignore @win, and redraw every graphics and 
1295  *   text grid window.
1296  * </para></note>
1297  *
1298  * An arrangement event is guaranteed to occur whenever the player causes any
1299  * window to change size, as measured by its own metric. 
1300  *
1301  * <note><para>
1302  *   Size changes caused by you &mdash; for example, if you open, close, or 
1303  *   resize a window &mdash; do not trigger arrangement events. You must be 
1304  *   aware of the effects of your window management, and redraw the windows that
1305  *   you affect.
1306  * </para></note>
1307  * 
1308  * <note><para>
1309  *   It is possible that several different player actions can cause windows to
1310  *   change size. For example, if the player changes the screen resolution, an
1311  *   arrangement event might be triggered. This might also happen if the player
1312  *   changes his display font to a different size; the windows would then be
1313  *   different <quote>sizes</quote> in the metric of rows and columns, which is
1314  *   the important metric and the only one you have access to.
1315  * </para></note>
1316  * 
1317  * Arrangement events, like timer events, can be returned by glk_select_poll().
1318  * But this will not occur on all platforms. You must be ready to receive an
1319  * arrangement event when you call glk_select_poll(), but it is possible that it
1320  * will not arrive until the next time you call glk_select(). 
1321  *
1322  * <note><para>
1323  *   This is because on some platforms, window resizing is handled as part of
1324  *   player input; on others, it can be triggered by an external process such as 
1325  *   a window manager.
1326  * </para></note>
1327  */
1328
1329 /**
1330  * evtype_Redraw:
1331  *
1332  * An event signalling that graphics windows must be redrawn.
1333  *
1334  * On platforms that support graphics, it is possible that the contents of a
1335  * graphics window will be lost, and have to be redrawn from scratch. If this
1336  * occurs, then glk_select() will return an event whose type is %evtype_Redraw.
1337  *
1338  * In the event structure, @win will be %NULL if all windows are affected. If 
1339  * only some windows are affected, @win will refer to a window which contains 
1340  * all the affected windows. @val1 and @val2 will be 0.
1341  *
1342  * <note><para>
1343  *   You can always play it safe, ignore @win, and redraw every graphics window.
1344  * </para></note>
1345  *
1346  * Affected windows are already cleared to their background color when you 
1347  * receive the redraw event.
1348  * 
1349  * Redraw events can be returned by glk_select_poll(). But, like arrangement
1350  * events, this is platform-dependent. See %evtype_Arrange.
1351  *
1352  * For more about redraw events and how they affect graphics windows, see <link
1353  * linkend="chimara-Graphics-Windows">Graphics Windows</link>.
1354  */
1355
1356 /**
1357  * evtype_SoundNotify:
1358  *
1359  * On platforms that support sound, you can request to receive an 
1360  * %evtype_SoundNotify event when a sound finishes playing. See <link
1361  * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
1362  */
1363  
1364 /**
1365  * evtype_Hyperlink:
1366  * 
1367  * On platforms that support hyperlinks, you can request to receive an
1368  * %evtype_Hyperlink event when the player selects a link. See <link
1369  * linkend="chimara-Accepting-Hyperlink-Events">Accepting Hyperlink 
1370  * Events</link>.
1371  */
1372
1373 /**
1374  * event_t:
1375  * @type: the event type
1376  * @win: the window that spawned the event, or %NULL
1377  * @val1: information, the meaning of which depends on the type of event
1378  * @val2: more information, the meaning of which depends on the type of event
1379  *
1380  * The event structure is self-explanatory. @type is the event type. The window
1381  * that spawned the event, if relevant, is in @win. The remaining fields contain
1382  * more information specific to the event.
1383  *
1384  * The event types are described below. Note that %evtype_None is zero, and the
1385  * other values are positive. Negative event types (0x80000000 to 0xFFFFFFFF) 
1386  * are reserved for implementation-defined events. 
1387  */
1388
1389 /**
1390  * keycode_Unknown:
1391  *
1392  * Represents any key that has no Latin-1 or special code.
1393  */
1394
1395 /**
1396  * keycode_Left:
1397  *
1398  * Represents the <keycap function="left">left arrow</keycap> key.
1399  */
1400  
1401 /**
1402  * keycode_Right:
1403  *
1404  * Represents the <keycap function="right">right arrow</keycap> key.
1405  */
1406  
1407 /**
1408  * keycode_Up:
1409  *
1410  * Represents the <keycap function="up">up arrow</keycap> key.
1411  */
1412  
1413 /**
1414  * keycode_Down:
1415  *
1416  * Represents the <keycap function="down">down arrow</keycap> key.
1417  */
1418  
1419 /**
1420  * keycode_Return:
1421  *
1422  * Represents the <keycap function="enter">return</keycap> or <keycap 
1423  * function="enter">enter</keycap> keys.
1424  */
1425
1426 /**
1427  * keycode_Delete:
1428  *
1429  * Represents the <keycap function="delete">delete</keycap> or <keycap
1430  * function="backspace">backspace</keycap> keys.
1431  */
1432  
1433 /**
1434  * keycode_Escape:
1435  *
1436  * Represents the <keycap function="escape">escape</keycap> key.
1437  */
1438  
1439 /**
1440  * keycode_Tab:
1441  *
1442  * Represents the <keycap function="tab">tab</keycap> key.
1443  */
1444
1445 /**
1446  * keycode_PageUp:
1447  *
1448  * Represents the <keycap function="pageup">page up</keycap> key.
1449  */
1450
1451 /**
1452  * keycode_PageDown:
1453  *
1454  * Represents the <keycap function="pagedown">page down</keycap> key.
1455  */
1456
1457 /**
1458  * keycode_Home:
1459  *
1460  * Represents the <keycap function="home">home</keycap> key.
1461  */
1462  
1463 /**
1464  * keycode_End:
1465  *
1466  * Represents the <keycap function="end">end</keycap> key.
1467  */
1468
1469 /**
1470  * keycode_Func1:
1471  *
1472  * Represents the <keycap>F1</keycap> key.
1473  */
1474  
1475 /**
1476  * keycode_Func2:
1477  *
1478  * Represents the <keycap>F2</keycap> key.
1479  */
1480
1481 /**
1482  * keycode_Func3:
1483  *
1484  * Represents the <keycap>F3</keycap> key.
1485  */
1486
1487 /**
1488  * keycode_Func4:
1489  *
1490  * Represents the <keycap>F4</keycap> key.
1491  */
1492
1493 /**
1494  * keycode_Func5:
1495  *
1496  * Represents the <keycap>F5</keycap> key.
1497  */
1498  
1499 /**
1500  * keycode_Func6:
1501  *
1502  * Represents the <keycap>F6</keycap> key.
1503  */
1504
1505 /**
1506  * keycode_Func7:
1507  *
1508  * Represents the <keycap>F7</keycap> key.
1509  */
1510
1511 /**
1512  * keycode_Func8:
1513  *
1514  * Represents the <keycap>F8</keycap> key.
1515  */
1516
1517 /**
1518  * keycode_Func9:
1519  *
1520  * Represents the <keycap>F9</keycap> key.
1521  */
1522
1523 /**
1524  * keycode_Func10:
1525  *
1526  * Represents the <keycap>F10</keycap> key.
1527  */
1528
1529 /**
1530  * keycode_Func11:
1531  *
1532  * Represents the <keycap>F11</keycap> key.
1533  */
1534
1535 /**
1536  * keycode_Func12:
1537  *
1538  * Represents the <keycap>F12</keycap> key.
1539  */
1540
1541 /**
1542  * keycode_MAXVAL:
1543  *
1544  * This value is equal to the number of special keycodes. The last keycode is
1545  * always 
1546  * <inlineequation>
1547  *   <alt>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</alt>
1548  *   <mathphrase>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</mathphrase>
1549  * </inlineequation>
1550  * .
1551  */
1552
1553 /**
1554  * style_Normal: 
1555  *
1556  * The style of normal or body text. A new window or stream always starts with
1557  * %style_Normal as the current style.
1558  */
1559
1560 /**
1561  * style_Emphasized: 
1562  *
1563  * Text which is emphasized.
1564  */
1565
1566 /**
1567  * style_Preformatted: 
1568  *
1569  * Text which has a particular arrangement of characters.
1570  * <note><para>
1571  *  This style, unlike the others, does have a standard appearance; it will 
1572  *  always be a fixed-width font. This is a concession to practicality. Games 
1573  *  often want to display maps or diagrams using character graphics, and this is
1574  *  the style for that.
1575  * </para></note>
1576  */
1577  
1578 /**
1579  * style_Header: 
1580  * 
1581  * Text which introduces a large section. This is suitable for the title of an 
1582  * entire game, or a major division such as a chapter.
1583  */
1584
1585 /**
1586  * style_Subheader: 
1587  * 
1588  * Text which introduces a smaller section within a large section. 
1589  * <note><para>
1590  *  In a Colossal-Cave-style game, this is suitable for the name of a room (when
1591  *  the player looks around.)
1592  * </para></note>
1593  */
1594
1595 /**
1596  * style_Alert: 
1597  *
1598  * Text which warns of a dangerous condition, or one which the player should pay
1599  * attention to.
1600  */
1601
1602 /**
1603  * style_Note: 
1604  *
1605  * Text which notifies of an interesting condition.
1606  * <note><para>
1607  *  This is suitable for noting that the player's score has changed.
1608  * </para></note>
1609  */
1610
1611 /**
1612  * style_BlockQuote: 
1613  *
1614  * Text which forms a quotation or otherwise abstracted text.
1615  */
1616
1617 /**
1618  * style_Input: 
1619  *
1620  * Text which the player has entered. You should generally not use this style at
1621  * all; the library uses it for text which is typed during a line-input request.
1622  * One case when it is appropriate for you to use %style_Input is when you are 
1623  * simulating player input by reading commands from a text file.
1624  */
1625
1626 /**
1627  * style_User1: 
1628  * 
1629  * This style has no particular semantic meaning. You may define a meaning 
1630  * relevant to your own work, and use it as you see fit.
1631  */
1632
1633 /**
1634  * style_User2: 
1635  *
1636  * Another style available for your use. 
1637  */
1638  
1639 /**
1640  * style_NUMSTYLES:
1641  * 
1642  * The number of styles defined in this library.
1643  */
1644
1645 /**
1646  * stream_result_t:
1647  * @readcount: Number of characters read from the stream.
1648  * @writecount: Number of characters printed to the stream, including ones that
1649  * were thrown away.
1650  *
1651  * If you are interested in the character counts of a stream (see <link
1652  * linkend="chimara-Streams">Streams</link>), then you can pass a pointer to
1653  * #stream_result_t as an argument of glk_stream_close() or glk_window_close().
1654  * The structure will be filled with the stream's final character counts.
1655  */
1656
1657 /**
1658  * wintype_AllTypes:
1659  *
1660  * A constant representing all window types, which may be used as the @wintype
1661  * argument in glk_stylehint_set().
1662  */
1663
1664 /** 
1665  * wintype_Pair:
1666  * 
1667  * A pair window is completely filled by the two windows it contains. It
1668  * supports no input and no output, and it has no size.
1669  * 
1670  * You cannot directly create a pair window; one is automatically created
1671  * every time you split a window with glk_window_open(). Pair windows are
1672  * always created with a rock value of 0.
1673  * 
1674  * You can close a pair window with glk_window_close(); this also closes every
1675  * window contained within the pair window.
1676  * 
1677  * It is legal to split a pair window when you call glk_window_open().
1678  */
1679  
1680 /**
1681  * wintype_Blank:
1682  * 
1683  * A blank window is always blank. It supports no input and no output. (You
1684  * can call glk_window_get_stream() on it, as you can with any window, but
1685  * printing to the resulting stream has no effect.) A blank window has no
1686  * size; glk_window_get_size() will return (0,0), and it is illegal to set a
1687  * window split with a fixed size in the measurement system of a blank window.
1688  * 
1689  * <note><para>
1690  *   A blank window is not the same as there being no windows. When Glk starts
1691  *   up, there are no windows at all, not even a window of the blank type.
1692  * </para></note>
1693  */
1694  
1695 /**
1696  * wintype_TextBuffer: 
1697  *
1698  * A text buffer window contains a linear stream of text. It supports output;
1699  * when you print to it, the new text is added to the end. There is no way for
1700  * you to affect text which has already been printed. There are no guarantees
1701  * about how much text the window keeps; old text may be stored forever, so
1702  * that the user can scroll back to it, or it may be thrown away as soon as it
1703  * scrolls out of the window. 
1704  * 
1705  * <note><para>
1706  *   Therefore, there may or may not be a player-controllable scroll bar or
1707  *   other scrolling widget.
1708  * </para></note>
1709  * 
1710  * The display of the text in a text buffer is up to the library. Lines will
1711  * probably not be broken in the middles of words &mdash; but if they are, the
1712  * library is not doing anything illegal, only ugly. Text selection and copying
1713  * to a clipboard, if available, are handled however is best on the player's
1714  * machine. Paragraphs (as defined by newline characters in the output) may be
1715  * indented. 
1716  * 
1717  * <note><para>
1718  *   You should not, in general, fake this by printing spaces before each
1719  *   paragraph of prose text. Let the library and player preferences handle
1720  *   that. Special cases (like indented lists) are of course up to you.
1721  * </para></note>
1722  * 
1723  * When a text buffer is cleared (with glk_window_clear()), the library will do
1724  * something appropriate; the details may vary. It may clear the window, with
1725  * later text appearing at the top &mdash; or the bottom. It may simply print
1726  * enough blank lines to scroll the current text out of the window. It may
1727  * display a distinctive page-break symbol or divider.
1728  * 
1729  * The size of a text buffer window is necessarily imprecise. Calling
1730  * glk_window_get_size() will return the number of rows and columns that would
1731  * be available <emphasis>if</emphasis> the window was filled with 
1732  * <quote>0</quote> (zero) characters in the <quote>normal</quote> font.
1733  * However, the window may use a non-fixed-width font, so that number of
1734  * characters in a line could vary. The window might even support 
1735  * variable-height text (say, if the player is using large text for emphasis);
1736  * that would make the number of lines in the window vary as well.
1737  * 
1738  * Similarly, when you set a fixed-size split in the measurement system of a
1739  * text buffer, you are setting a window which can handle a fixed number of rows
1740  * (or columns) of <quote>0</quote> characters. The number of rows (or
1741  * characters) that will actually be displayed depends on font variances.
1742  * 
1743  * A text buffer window supports both character and line input, but not mouse
1744  * input.
1745  * 
1746  * In character input, there will be some visible signal that the window is
1747  * waiting for a keystroke. (Typically, a cursor at the end of the text.) When
1748  * the player hits a key in that window, an event is generated, but the key is
1749  * <emphasis>not</emphasis> printed in the window.
1750  * 
1751  * In line input, again, there will be some visible signal. It is most common
1752  * for the player to compose input in the window itself, at the end of the text.
1753  * (This is how IF story input usually looks.) But it's not strictly required.
1754  * An alternative approach is the way MUD clients usually work: there is a
1755  * dedicated one-line input window, outside of Glk's window space, and the user
1756  * composes input there.
1757  * 
1758  * <note><para>
1759  *   If this approach is used, there will still be some way to handle input from
1760  *   two windows at once. It is the library's responsibility to make this
1761  *   available to the player. You only need request line input and  wait for the
1762  *   result.
1763  * </para></note>
1764  * 
1765  * When the player finishes his line of input, the library will display the
1766  * input text at the end of the buffer text (if it wasn't there already.) It
1767  * will be followed by a newline, so that the next text you print will start a
1768  * new line (paragraph) after the input.
1769  * 
1770  * If you call glk_cancel_line_event(), the same thing happens; whatever text
1771  * the user was composing is visible at the end of the buffer text, followed by
1772  * a newline.
1773  */
1774  
1775 /**
1776  * wintype_TextGrid: 
1777  * 
1778  * A text grid contains a rectangular array of characters, in a fixed-width
1779  * font. Its size is the number of columns and rows of the array.
1780  * 
1781  * A text grid window supports output. It maintains knowledge of an output
1782  * cursor position. When the window is opened, it is filled with blanks (space
1783  * characters), and the output cursor starts in the top left corner &mdash;
1784  * character (0,0). If the window is cleared with glk_window_clear(), the window
1785  * is filled with blanks again, and the cursor returns to the top left corner.
1786  * 
1787  * When you print, the characters of the output are laid into the array in
1788  * order, left to right and top to bottom. When the cursor reaches the end of a
1789  * line, it goes to the beginning of the next line. The library makes no attempt
1790  * to wrap lines at word breaks.
1791  * 
1792  * <note><para>
1793  *   Note that printing fancy characters may cause the cursor to advance more
1794  *   than one position per character. (For example, the <quote>&aelig;</quote>
1795  *   ligature may print as two characters.) See <link 
1796  *   linkend="chimara-Output">Output</link>, for how to test this situation.
1797  * </para></note>
1798  * 
1799  * You can set the cursor position with glk_window_move_cursor().
1800  * 
1801  * When a text grid window is resized smaller, the bottom or right area is
1802  * thrown away, but the remaining area stays unchanged. When it is resized
1803  * larger, the new bottom or right area is filled with blanks.
1804  * 
1805  * <note><para>
1806  *   You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
1807  *   text grid windows when you see them change size.
1808  * </para></note>
1809  * 
1810  * Text grid window support character and line input, as well as mouse input (if
1811  * a mouse is available.)
1812  * 
1813  * Mouse input returns the position of the character that was touched, from
1814  * (0,0) to 
1815  * <inlineequation>
1816  *   <alt>(width-1,height-1)</alt>
1817  *   <mathphrase>(width - 1, height - 1)</mathphrase>
1818  * </inlineequation>
1819  * .
1820  * 
1821  * Character input is as described in the previous section.
1822  * 
1823  * Line input is slightly different; it is guaranteed to take place in the
1824  * window, at the output cursor position. The player can compose input only to
1825  * the right edge of the window; therefore, the maximum input length is
1826  * <inlineequation>
1827  *   <alt>(windowwidth - 1 - cursorposition)</alt>
1828  *   <mathphrase>(windowwidth - 1 - cursorposition)</mathphrase>
1829  * </inlineequation>
1830  * . If the maxlen argument of glk_request_line_event() is smaller than this,
1831  * the library will not allow the input cursor to go more than maxlen characters
1832  * past its start point. 
1833  * 
1834  * <note><para>
1835  *   This allows you to enter text in a fixed-width field, without the player
1836  *   being able to overwrite other parts of the window.
1837  * </para></note>
1838  * 
1839  * When the player finishes his line of input, it will remain visible in the
1840  * window, and the output cursor will be positioned at the beginning of the 
1841  * <emphasis>next</emphasis> row. Again, if you glk_cancel_line_event(), the
1842  * same thing happens.
1843  */
1844  
1845 /**
1846  * wintype_Graphics: 
1847  * 
1848  * A graphics window contains a rectangular array of pixels. Its size is the
1849  * number of columns and rows of the array.
1850  * 
1851  * Each graphics window has a background color, which is initially white. You
1852  * can change this; see <link 
1853  * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics 
1854  * Windows</link>.
1855  * 
1856  * When a text grid window is resized smaller, the bottom or right area is
1857  * thrown away, but the remaining area stays unchanged. When it is resized
1858  * larger, the new bottom or right area is filled with the background color.
1859  * 
1860  * <note><para>
1861  *   You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
1862  *   graphics windows when you see them change size.
1863  * </para></note>
1864  * 
1865  * In some libraries, you can receive a graphics-redraw event (%evtype_Redraw)
1866  * at any time. This signifies that the window in question has been cleared to
1867  * its background color, and must be redrawn. If you create any graphics
1868  * windows, you <emphasis>must</emphasis> handle these events.
1869  * 
1870  * <note><para>
1871  *   Redraw events can be triggered when a Glk window is uncovered or made
1872  *   visible by the platform's window manager. On the other hand, some Glk
1873  *   libraries handle these problem automatically &mdash; for example, with a
1874  *   backing store &mdash; and do not send you redraw events. On the third hand,
1875  *   the backing store may be discarded if memory is low, or for other reasons
1876  *   &mdash; perhaps the screen's color depth has changed. So redraw events are
1877  *   always a possibility, even in clever libraries. This is why you must be
1878  *   prepared to handle them.
1879  * 
1880  *   However, you will not receive a redraw event when you create a graphics
1881  *   window. It is assumed that you will do the initial drawing of your own
1882  *   accord. You also do not get redraw events when a graphics window is
1883  *   enlarged. If you ordered the enlargement, you already know about it; if the
1884  *   player is responsible, you receive a window-arrangement event, which covers
1885  *   the situation.
1886  * </para></note>
1887  * 
1888  * For a description of the drawing functions that apply to graphics windows,
1889  * see <link linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
1890  * Windows</link>.
1891  * 
1892  * Graphics windows support no text input or output.
1893  * 
1894  * Not all libraries support graphics windows. You can test whether Glk graphics
1895  * are available using the gestalt system. In a C program, you can also test
1896  * whether the graphics functions are defined at compile-time. See <link 
1897  * linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics
1898  * Capabilities</link>. 
1899  *
1900  * <note><para>
1901  *   As with all windows, you should also test for %NULL when you create a
1902  *   graphics window.
1903  * </para></note>
1904  */
1905  
1906 /**
1907  * winmethod_Left:
1908  *
1909  * When calling glk_window_open() with this @method, the new window will be 
1910  * to the left of the old one which was split.
1911  */
1912
1913 /**
1914  * winmethod_Right:
1915  *
1916  * When calling glk_window_open() with this @method, the new window will be 
1917  * to the right of the old one which was split.
1918  */
1919
1920 /**
1921  * winmethod_Above:
1922  *
1923  * When calling glk_window_open() with this @method, the new window will be 
1924  * above the old one which was split.
1925  */
1926  
1927 /**
1928  * winmethod_Below:
1929  *
1930  * When calling glk_window_open() with this @method, the new window will be 
1931  * below the old one which was split.
1932  */
1933
1934 /**
1935  * winmethod_DirMask:
1936  *
1937  * Bitwise AND this value with a window splitting method argument to find
1938  * whether the split is %winmethod_Left, %winmethod_Right, %winmethod_Above, or
1939  * %winmethod_Below.
1940  */
1941  
1942 /**
1943  * winmethod_Fixed:
1944  *
1945  * When calling glk_window_open() with this @method, the new window will be 
1946  * a fixed size. (See glk_window_open()).
1947  */
1948
1949 /**
1950  * winmethod_Proportional:
1951  *
1952  * When calling glk_window_open() with this @method, the new window will be 
1953  * a given proportion of the old window's size. (See glk_window_open()).
1954  */
1955  
1956 /**
1957  * winmethod_DivisionMask:
1958  *
1959  * Bitwise AND this value with a window splitting method argument to find
1960  * whether the new window has %winmethod_Fixed or %winmethod_Proportional.
1961  */
1962  
1963 /** 
1964  * fileusage_Data: 
1965  *
1966  * Any other kind of file (preferences, statistics, arbitrary data.) 
1967  */
1968
1969 /**
1970  * fileusage_SavedGame: 
1971  * 
1972  * A file which stores game state.
1973  */
1974
1975 /**
1976  * fileusage_Transcript: 
1977  * 
1978  * A file which contains a stream of text from the game (often an echo stream
1979  * from a window.)
1980  */
1981  
1982 /** 
1983  * fileusage_InputRecord: 
1984  * 
1985  * A file which records player input.
1986  */
1987
1988 /** 
1989  * fileusage_TextMode: 
1990  *
1991  * The file contents will be transformed to a platform-native text file as they
1992  * are written out. Newlines may be converted to linefeeds or 
1993  * linefeed-plus-carriage-return combinations; Latin-1 characters may be
1994  * converted to native character codes. When reading a file in text mode, native
1995  * line breaks will be converted back to newline (0x0A) characters, and native
1996  * character codes may be converted to Latin-1. 
1997  *
1998  * <note><para>
1999  *   Line breaks will always be converted; other conversions are more
2000  *   questionable. If you write out a file in text mode, and then read it back
2001  *   in text mode, high-bit characters (128 to 255) may be transformed or lost.
2002  * </para></note>
2003  * <note><title>Chimara</title>
2004  * <para>
2005  * Text mode files in Chimara are in UTF-8, which is GTK+'s native file
2006  * encoding.
2007  * </para></note>
2008  */
2009
2010 /**
2011  * fileusage_BinaryMode: 
2012  *
2013  * The file contents will be stored exactly as they are written, and read back
2014  * in the same way. The resulting file may not be viewable on platform-native
2015  * text file viewers.
2016  */
2017
2018 /**
2019  * fileusage_TypeMask:
2020  *
2021  * Bitwise AND this value with a file usage argument to find whether the file
2022  * type is %fileusage_SavedGame, %fileusage_Transcript, %fileusage_InputRecord,
2023  * or %fileusage_Data.
2024  */
2025
2026 /**
2027  * filemode_Write: 
2028  *
2029  * An output stream.
2030  *
2031  * <note><para>
2032  *   Corresponds to mode <code>"w"</code> in the stdio library, using fopen().
2033  * </para></note>
2034  */
2035
2036 /** 
2037  * filemode_Read: 
2038  *
2039  * An input stream.
2040  *
2041  * <note><para>
2042  *   Corresponds to mode <code>"r"</code> in the stdio library, using fopen().
2043  * </para></note>
2044  */
2045
2046 /**
2047  * filemode_ReadWrite: 
2048  *
2049  * Both an input and an output stream.
2050  *
2051  * <note><para>
2052  *   Corresponds to mode <code>"r+"</code> in the stdio library, using fopen().
2053  * </para></note>
2054  */
2055
2056 /**
2057  * filemode_WriteAppend: 
2058  *
2059  * An output stream, but the data will added to the end of whatever already
2060  * existed in the destination, instead of replacing it. 
2061  *
2062  * <note><para>
2063  *   Corresponds to mode <code>"a"</code> in the stdio library, using fopen().
2064  * </para></note>
2065  */
2066  
2067 /**
2068  * seekmode_Start:
2069  *
2070  * In glk_stream_set_position(), signifies that @pos is counted in characters
2071  * after the beginning of the file.
2072  */
2073  
2074 /**
2075  * seekmode_Current: 
2076  *
2077  * In glk_stream_set_position(), signifies that @pos is counted in characters
2078  * after the current position (moving backwards if @pos is negative.)
2079  */
2080
2081 /** 
2082  * seekmode_End: 
2083  *
2084  * In glk_stream_set_position(), signifies that @pos is counted in characters
2085  * after the end of the file. (@pos should always be zero or negative, so that
2086  * this will move backwards to a  position within the file.
2087  */
2088
2089 /**
2090  * stylehint_Indentation: 
2091  *
2092  * How much to indent lines of text in the given style. May be a negative 
2093  * number, to shift the text out (left) instead of in (right). The exact metric
2094  * isn't precisely specified; you can assume that +1 is the smallest indentation
2095  * possible which is clearly visible to the player.
2096  */
2097
2098 /**
2099  * stylehint_ParaIndentation: 
2100  *
2101  * How much to indent the first line of each paragraph. This is in addition to 
2102  * the indentation specified by %stylehint_Indentation. This too may be 
2103  * negative, and is measured in the same units as %stylehint_Indentation.
2104  */
2105
2106 /**
2107  * stylehint_Justification: 
2108  *
2109  * The value of this hint must be one of the constants 
2110  * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification), 
2111  * %stylehint_just_Centered, or %stylehint_just_RightFlush.
2112  */
2113
2114 /** 
2115  * stylehint_Size: 
2116  *
2117  * How much to increase or decrease the font size. This is relative; 0 means the
2118  * interpreter's default font size will be used, positive numbers increase it, 
2119  * and negative numbers decrease it. Again, +1 is the smallest size increase 
2120  * which is easily visible. 
2121  * <note><para>
2122  *  The amount of this increase may not be constant. +1 might increase an 
2123  *  8-point font to 9-point, but a 16-point font to 18-point.
2124  * </para></note>
2125  */
2126
2127 /**
2128  * stylehint_Weight: 
2129  *
2130  * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for 
2131  * normal weight, and -1 for light-weight fonts.
2132  */
2133
2134 /**
2135  * stylehint_Oblique: 
2136  *
2137  * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal
2138  * angle.
2139  */
2140  
2141 /** 
2142  * stylehint_Proportional: 
2143  * 
2144  * The value of this hint must be 1 for proportional-width fonts, or 0 for 
2145  * fixed-width.
2146  */
2147
2148 /**
2149  * stylehint_TextColor: 
2150  * 
2151  * The foreground color of the text. This is encoded in the 32-bit hint value: 
2152  * the top 8 bits must be zero, the next 8 bits are the red value, the next 8 
2153  * bits are the green value, and the bottom 8 bits are the blue value. Color 
2154  * values range from 0 to 255. 
2155  * <note><para>
2156  *   So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.
2157  * </para></note>
2158  */
2159  
2160 /** 
2161  * stylehint_BackColor: 
2162  *
2163  * The background color behind the text. This is encoded the same way as 
2164  * %stylehint_TextColor.
2165  */
2166  
2167 /** 
2168  * stylehint_ReverseColor: 
2169  *
2170  * The value of this hint must be 0 for normal printing (%stylehint_TextColor on 
2171  * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on 
2172  * %stylehint_TextColor). 
2173  * <note><para>
2174  *  Some libraries may support this hint but not the %stylehint_TextColor and 
2175  *  %stylehint_BackColor hints. Other libraries may take the opposite tack; 
2176  *  others may support both, or neither.
2177  * </para></note>
2178  */
2179
2180 /**
2181  * stylehint_NUMHINTS:
2182  *
2183  * The number of style hints defined in this library.
2184  */ 
2185  
2186 /**
2187  * stylehint_just_LeftFlush:
2188  *
2189  * A value for %stylehint_Justification representing left-justified text.
2190  */ 
2191  
2192 /**
2193  * stylehint_just_LeftRight:
2194  *
2195  * A value for %stylehint_Justification representing fully justified text.
2196  */ 
2197  
2198 /**
2199  * stylehint_just_Centered:
2200  *
2201  * A value for %stylehint_Justification representing centered text.
2202  */ 
2203  
2204 /**
2205  * stylehint_just_RightFlush:
2206  *
2207  * A value for %stylehint_Justification representing right-justified text.
2208  */
2209
2210 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
2211
2212 /**
2213  * gidispatch_count_classes:
2214  * 
2215  * Returns the number of opaque object classes used by the library. You will
2216  * need to know this if you want to keep track of opaque objects as they are
2217  * created; see <link linkend="gidispatch-set-object-registry">Opaque Object
2218  * Registry</link>.
2219  * 
2220  * As of Glk API 0.7.0, there are four classes: windows, streams, filerefs, and
2221  * sound channels (numbered 0, 1, 2, and 3 respectively.)
2222  *
2223  * Returns: Number of opaque object classes used by the library.
2224  */
2225  
2226 /**
2227  * gidispatch_count_intconst:
2228  *
2229  * Returns the number of integer constants exported by the library.
2230  *
2231  * Returns: Number of integer constants exported by the library.
2232  */
2233  
2234 /**
2235  * gidispatch_get_intconst:
2236  * @index: Unique integer index of the integer constant.
2237  *
2238  * Returns a structure describing an integer constant which the library exports.
2239  * These are, roughly, all the constants defined in the <filename
2240  * class="headerfile">glk.h</filename> file. @index can range from 0 to
2241  * <inlineequation><mathphrase>N - 1</mathphrase><alt>N - 
2242  * 1</alt></inlineequation>, where N is the value returned by 
2243  * gidispatch_count_intconst().
2244  *
2245  * Returns: A #gidispatch_intconst_t structure describing the integer constant.
2246  */
2247
2248 /**
2249  * gidispatch_intconst_t:
2250  * @name: Symbolic name of the integer constant.
2251  * @val: Value of the integer constant.
2252  *
2253  * This structure simply contains a string and a value. The string is a
2254  * symbolic name of the value, and can be re-exported to anyone interested in
2255  * using Glk constants.
2256  */
2257  
2258 /**
2259  * gidispatch_count_functions:
2260  *
2261  * Returns the number of functions exported by the library.
2262  *
2263  * Returns: Number of functions exported by the library.
2264  */
2265  
2266 /**
2267  * gidispatch_get_function:
2268  * @index: Unique integer index of the function.
2269  *
2270  * Returns a structure describing a Glk function. @index can range from 0 to
2271  * <inlineequation><mathphrase>N - 1</mathphrase><alt>N - 
2272  * 1</alt></inlineequation>, where N is the value returned by 
2273  * gidispatch_count_functions().
2274  *
2275  * Returns: A #gidispatch_function_t structure describing the function.
2276  */
2277  
2278 /**
2279  * gidispatch_function_t:
2280  * @id: Dispatch selector of the function.
2281  * @fnptr: Pointer to the function.
2282  * @name: Name of the function, without the <code>glk_</code> prefix.
2283  *
2284  * The @id field is a selector &mdash; a numeric constant used to refer to the
2285  * function in question. @name is the function name, as it is given in the
2286  * <filename class="headerfile">glk.h</filename> file, but without the 
2287  * <quote><code>glk_</code></quote> prefix. And @fnptr is the address of the
2288  * function itself.
2289  *
2290  * <note><para>
2291  *   This is included because it might be useful, but it is not recommended. To
2292  *   call an arbitrary Glk function, you should use gidispatch_call().
2293  * </para></note>
2294  *
2295  * See <link linkend="chimara-Table-of-Selectors">Table of Selectors</link> for
2296  * the selector definitions. See <link 
2297  * linkend="chimara-Dispatching">Dispatching</link> for more about calling Glk
2298  * functions by selector.
2299  */
2300  
2301 /**
2302  * gidispatch_get_function_by_id:
2303  * @id: A selector.
2304  *
2305  * Returns a structure describing the Glk function with selector @id. If there 
2306  * is no such function in the library, this returns %NULL.
2307  *
2308  * Returns: a #gidispatch_function_t structure, or %NULL.
2309  */
2310  
2311 /**
2312  * gidispatch_call:
2313  * @funcnum: Selector of the function to call.
2314  * @numargs: Length of @arglist.
2315  * @arglist: List of arguments to pass to the function.
2316  *
2317  * @funcnum is the function number to invoke; see <link 
2318  * linkend="chimara-Table-of-Selectors">Table of Selectors</link>. @arglist is
2319  * the list of arguments, and @numargs is the length of the list.
2320  * 
2321  * The arguments are all stored as #gluniversal_t objects. 
2322  * </para><refsect3 id="chimara-Basic-Types"><title>Basic Types</title><para>
2323  * Numeric arguments are passed in the obvious way &mdash; one argument per
2324  * #gluniversal_t, with the @uint or @sint field set to the numeric value.
2325  * Characters and strings are also passed in this way &mdash; #char<!---->s in
2326  * the @uch, @sch, or @ch fields (depending on whether the #char is signed) and
2327  * strings in the @charstr field. Opaque objects (windows, streams, etc) are
2328  * passed in the @opaqueref field (which is <code>void*</code>, in order to
2329  * handle all opaque pointer types.)
2330  * 
2331  * However, pointers (other than C strings), arrays, and structures complicate
2332  * life. So do return values.
2333  * </para></refsect3>
2334  * <refsect3 id="chimara-References"><title>References</title><para>
2335  * A reference to a numeric type or object reference &mdash; that is,
2336  * <code>#glui32*</code>, <code>#winid_t*</code>, and so on &mdash; takes
2337  * <emphasis>one or two</emphasis> #gluniversal_t objects. The first is a flag
2338  * indicating whether the reference argument is %NULL or not. The @ptrflag field
2339  * of this #gluniversal_t should be %FALSE if the reference is %NULL, and %TRUE
2340  * otherwise. If %FALSE, that is the end of the argument; you should not use a
2341  * #gluniversal_t to explicitly store the %NULL reference. If the flag is %TRUE,
2342  * you must then put a #gluniversal_t storing the base type of the reference.
2343  *
2344  * For example, consider a hypothetical function, with selector 
2345  * <code>0xABCD</code>:
2346  * |[ 
2347  * void glk_glomp(#glui32 num, #winid_t win, #glui32 *numref, #strid_t *strref);
2348  * ]|
2349  * ...and the calls:
2350  * |[
2351  * #glui32 value;
2352  * #winid_t mainwin;
2353  * #strid_t gamefile;
2354  * glk_glomp(5, mainwin, &value, &gamefile);
2355  * ]|
2356  *
2357  * To perform this through gidispatch_call(), you would do the following:
2358  * |[
2359  * #gluniversal_t arglist[6];
2360  * arglist[0].uint = 5;
2361  * arglist[1].opaqueref = mainwin;
2362  * arglist[2].ptrflag = TRUE;
2363  * arglist[3].uint = value;
2364  * arglist[4].ptrflag = TRUE;
2365  * arglist[5].opaqueref = gamefile;
2366  * #gidispatch_call(0xABCD, 6, arglist);
2367  * value = arglist[3].uint;
2368  * gamefile = arglist[5].opaqueref;
2369  * ]|
2370  * 
2371  * Note that you copy the value of the reference arguments into and out of
2372  * @arglist. Of course, it may be that glk_glomp() only uses these as pass-out
2373  * references or pass-in references; if so, you could skip copying in or out.
2374  *
2375  * For further examples:
2376  * |[
2377  * glk_glomp(7, mainwin, NULL, NULL);
2378  * ...or...
2379  * #gluniversal_t arglist[4];
2380  * arglist[0].uint = 7;
2381  * arglist[1].opaqueref = mainwin;
2382  * arglist[2].ptrflag = FALSE;
2383  * arglist[3].ptrflag = FALSE;
2384  * #gidispatch_call(0xABCD, 4, arglist);
2385  * ]|
2386  *
2387  * |[
2388  * glk_glomp(13, NULL, NULL, &gamefile);
2389  * ...or...
2390  * #gluniversal_t arglist[5];
2391  * arglist[0].uint = 13;
2392  * arglist[1].opaqueref = NULL;
2393  * arglist[2].ptrflag = FALSE;
2394  * arglist[3].ptrflag = TRUE;
2395  * arglist[4].opaqueref = gamefile;
2396  * #gidispatch_call(0xABCD, 5, arglist);
2397  * gamefile = arglist[4].opaqueref;
2398  * ]|
2399  *
2400  * |[
2401  * glk_glomp(17, NULL, &value, NULL);
2402  * ...or...
2403  * #gluniversal_t arglist[5];
2404  * arglist[0].uint = 17;
2405  * arglist[1].opaqueref = NULL;
2406  * arglist[2].ptrflag = TRUE;
2407  * arglist[3].uint = value;
2408  * arglist[4].ptrflag = FALSE;
2409  * #gidispatch_call(0xABCD, 5, arglist);
2410  * value = arglist[3].uint;
2411  * ]|
2412  * 
2413  * As you see, the length of @arglist depends on how many of the reference
2414  * arguments are %NULL.
2415  * </para></refsect3>
2416  * <refsect3 id="chimara-Structures"><title>Structures</title><para>
2417  * A structure pointer is represented by a single @ptrflag, possibly followed by
2418  * a sequence of #gluniversal_t objects (one for each field of the structure.)
2419  * Again, if the structure pointer is non-%NULL, the @ptrflag should be %TRUE
2420  * and be followed by values; if not, the @ptrflag should be %NULL and stands
2421  * alone.
2422  * 
2423  * For example, the function glk_select() can be invoked as follows:
2424  * |[
2425  * #event_t ev;
2426  * #gluniversal_t arglist[5];
2427  * arglist[0].ptrflag = TRUE;
2428  * #gidispatch_call(0x00C0, 5, arglist);
2429  * ev.type = arglist[1].uint;
2430  * ev.win = arglist[2].opaqueref;
2431  * ev.val1 = arglist[3].uint;
2432  * ev.val2 = arglist[4].uint;
2433  * ]|
2434  * 
2435  * Since the structure passed to glk_select() is a pass-out reference (the entry
2436  * values are ignored), you don't need to fill in <code>arglist[1..4]</code>
2437  * before calling gidispatch_call().
2438  * 
2439  * <note><para>
2440  *   Theoretically, you would invoke <code>#glk_select(%NULL)</code> by setting'
2441  *   <code>arglist[0].ptrflag</code> to %FALSE, and using a one-element @arglist
2442  *   instead of five-element. But it's illegal to pass %NULL to glk_select(). So
2443  *   you cannot actually do this.
2444  * </para></note></para></refsect3>
2445  * <refsect3 id="chimara-Arrays"><title>Arrays</title><para>
2446  * In the Glk API, an array argument is always followed by a numeric argument
2447  * giving the array's length. These two C arguments are a single logical
2448  * argument, which is represented by <emphasis>one or three</emphasis>
2449  * #gluniversal_t objects. The first is a @ptrflag, indicating whether the
2450  * argument is %NULL or not. The second is a pointer, stored in the @array
2451  * field. The third is the array length, stored in the @uint field. And again,
2452  * if the @ptrflag is %NULL, the following two are omitted.
2453  * 
2454  * For example, the function glk_put_buffer() can be invoked as follows:
2455  * |[
2456  * #char buf[64];
2457  * #glui32 len = 64;
2458  * #glk_put_buffer(buf, len);
2459  * ...or...
2460  * #gluniversal_t arglist[3];
2461  * arglist[0].ptrflag = TRUE;
2462  * arglist[1].array = buf;
2463  * arglist[2].uint = len;
2464  * #gidispatch_call(0x0084, 3, arglist);
2465  * ]|
2466  * 
2467  * Since you are passing a C char array to gidispatch_call(), the contents will
2468  * be read directly from that. There is no need to copy data into @arglist, as
2469  * you would for a basic type.
2470  * 
2471  * If you are implementing a VM whose native representation of char arrays is
2472  * more complex, you will have to do more work. You should allocate a C char
2473  * array, copy your characters into it, make the call, and then free the array.
2474  *
2475  * <note><para>
2476  *   glk_put_buffer() does not modify the array passed to it, so there is no
2477  *   need to copy the characters out.
2478  * </para></note></para></refsect3>
2479  * <refsect3 id="chimara-Return-Values"><title>Return Values</title><para>
2480  * The return value of a function is not treated specially. It is simply
2481  * considered to be a pass-out reference argument which may not be %NULL. It
2482  * comes after all the other arguments of the function.
2483  * 
2484  * For example, the function glk_window_get_rock() can be invoked as follows:
2485  * |[
2486  * #glui32 rock;
2487  * #winid_t win;
2488  * rock = #glk_window_get_rock(win);
2489  * ...or...
2490  * #gluniversal_t arglist[3];
2491  * arglist[0].opaqueref = win;
2492  * arglist[1].ptrflag = TRUE;
2493  * #gidispatch_call(0x0021, 3, arglist);
2494  * rock = arglist[2].uint;
2495  * ]|
2496  * </para></refsect3><para>
2497  */
2498
2499 /**
2500  * gluniversal_t:
2501  * @uint: Stores a #glui32.
2502  * @sint: Stores a #glsi32.
2503  * @opaqueref: Stores a #winid_t, #strid_t, #frefid_t, or #schanid_t.
2504  * @uch: Stores an #unsigned #char.
2505  * @sch: Stores a #signed #char.
2506  * @ch: Stores a #char with the default signedness.
2507  * @charstr: Stores a %NULL-terminated string.
2508  * @array: Stores a pointer to an array, and should be followed by another 
2509  * #gluniversal_t with the array length stored in the @uint member.
2510  * @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL,
2511  * in which case it represents the entire argument. If %TRUE, should be followed
2512  * by another #gluniversal_t with the pointer in its @opaqueref or @array field.
2513  *
2514  * This is a union, encompassing all the types that can be passed to Glk
2515  * functions.
2516  */
2517  
2518 /**
2519  * gidispatch_prototype:
2520  * @funcnum: A selector for the function to be queried.
2521  *
2522  * This returns a string which encodes the proper argument list for the given
2523  * function. If there is no such function in the library, this returns %NULL.
2524  * 
2525  * The prototype string for the glk_glomp() function described above would be:
2526  * <code>"4IuQa&amp;Iu&amp;Qb:"</code>. The <code>"4"</code> is the number of
2527  * arguments (including the return value, if there is one, which in this case
2528  * there isn't.) <code>"Iu"</code> denotes an unsigned integer;
2529  * <code>"Qa"</code> is an opaque object of class 0 (window).
2530  * <code>"&amp;Iu"</code> is a <emphasis>reference</emphasis> to an unsigned
2531  * integer, and <code>"&amp;Qb"</code> is a reference to a stream. The colon at
2532  * the end terminates the argument list; the return value would follow it, if
2533  * there was one.
2534  * 
2535  * Note that the initial number (<code>"4"</code> in this case) is the number of
2536  * logical arguments, not the number of #gluniversal_t objects which will be
2537  * passed to gidispatch_call(). The glk_glomp() call uses anywhere from four to
2538  * six #gluniversal_t objects, as demonstrated above.
2539  * 
2540  * The basic type codes:
2541  * <variablelist>
2542  * <varlistentry>
2543  *   <term><code>Iu, Is</code></term>
2544  *   <listitem><para>Unsigned and signed 32-bit integer.</para></listitem>
2545  * </varlistentry>
2546  * <varlistentry>
2547  *   <term><code>Cn, Cu, Cs</code></term>
2548  *   <listitem><para>Character, #unsigned #char, and #signed #char.</para>
2549  *     <note><para>Of course <code>Cn</code> will be the same as either 
2550  *     <code>Cu</code> or <code>Cs</code>, depending on the platform. For this
2551  *     reason, Glk avoids using it, but it is included here for completeness.
2552  *     </para></note>
2553  *   </listitem>
2554  * </varlistentry>
2555  * <varlistentry>
2556  *   <term><code>S</code></term>
2557  *   <listitem><para>A C-style string (null-terminated array of #char). In Glk,
2558  *   strings are always treated as read-only and used immediately; the library
2559  *   does not retain a reference to a string between Glk calls. A Glk call that
2560  *   wants to use writable char arrays will use an array type 
2561  *   (<code>"&num;C"</code>), not string (<code>"S"</code>).</para></listitem>
2562  * </varlistentry>
2563  * <varlistentry>
2564  *   <term><code>U</code></term>
2565  *   <listitem><para>A zero-terminated array of 32-bit integers. This is
2566  *   primarily intended as a Unicode equivalent of <code>"S"</code>. Like 
2567  *   <code>"S"</code> strings, <code>"U"</code> strings are read-only and used
2568  *   immediately. A Glk call that wants to use writable Unicode arrays will use
2569  *   an array type (<code>"&num;Iu"</code>) instead of <code>"U"</code>.</para>
2570  *   </listitem>
2571  * </varlistentry>
2572  * <varlistentry>
2573  *   <term><code>F</code></term>
2574  *   <listitem><para>A floating-point value. Glk does not currently use
2575  *   floating-point values, but we might as well define a code for them.</para>
2576  *   </listitem>
2577  * </varlistentry>
2578  * <varlistentry>
2579  *   <term><code>Qa, Qb, Qc...</code></term>
2580  *   <listitem><para>A reference to an opaque object. The second letter
2581  *   determines which class is involved. (The number of classes can be gleaned
2582  *   from gidispatch_count_classes(); see <link 
2583  *   linkend="chimara-Interrogating-the-Interface">Interrogating the
2584  *   Interface</link>).</para>
2585  *   <note><para>
2586  *     If Glk expands to have more than 26 classes, we'll think of something.
2587  *   </para></note></listitem>
2588  * </varlistentry>
2589  * </variablelist>
2590  * Any type code can be prefixed with one or more of the following characters
2591  * (order does not matter):
2592  * <variablelist>
2593  * <varlistentry>
2594  *   <term><code>&amp;</code></term>
2595  *   <listitem><para>A reference to the type; or, if you like, a variable passed
2596  *   by reference. The reference is passed both in and out, so you must copy the
2597  *   value in before calling gidispatch_call() and copy it out afterward.</para>
2598  *   </listitem>
2599  * </varlistentry>
2600  * <varlistentry>
2601  *   <term><code>&lt;</code></term>
2602  *   <listitem><para>A reference which is pass-out only. The initial value is
2603  *   ignored, so you only need copy out the value after the call.</para>
2604  *   </listitem>
2605  * </varlistentry>
2606  * <varlistentry>
2607  *   <term><code>&gt;</code></term>
2608  *   <listitem><para>A reference which is pass-in only.</para>
2609  *   <note><para>
2610  *     This is not generally used for simple types, but is useful for structures
2611  *     and arrays.
2612  *   </para></note></listitem>
2613  * </varlistentry>
2614  * <varlistentry>
2615  *   <term><code>+</code></term>
2616  *   <listitem><para>Combined with <code>"&"</code>, <code>"&lt;"</code>, or 
2617  *   <code>"&gt;"</code>, indicates that a valid reference is mandatory; %NULL
2618  *   cannot be passed.</para>
2619  *   <note><para>
2620  *     Note that even though the @ptrflag #gluniversal_t for a <code>"+"</code>
2621  *     reference is always %TRUE, it cannot be omitted.
2622  *   </para></note></listitem>
2623  * </varlistentry>
2624  * <varlistentry>
2625  *   <term><code>:</code></term>
2626  *   <listitem><para>The colon separates the arguments from the return value, or
2627  *   terminates the string if there is no return value. Since return values are
2628  *   always non-%NULL pass-out references, you may treat <code>":"</code> as
2629  *   equivalent to <code>"&lt;+"</code>. The colon is never combined with any
2630  *   other prefix character.</para></listitem>
2631  * </varlistentry>
2632  * <varlistentry>
2633  *   <term><code>[...]</code></term>
2634  *   <listitem><para>Combined with <code>"&amp;"</code>, <code>"&lt;"</code>, or 
2635  *   <code>"&gt;"</code>, indicates a structure reference. Between the brackets
2636  *   is a complete argument list encoding string, including the number of
2637  *   arguments.</para>
2638  *   <note><para>
2639  *     For example, the prototype string for glk_select() is
2640  *     <code>"1&lt;+[4IuQaIuIu]:"</code> &mdash; one argument, which is a
2641  *     pass-out non-%NULL reference to a structure, which contains four
2642  *     arguments.
2643  *   </para></note>
2644  *   <para>Currently, structures in Glk contain only basic types.</para>
2645  *   </listitem>
2646  * </varlistentry>
2647  * <varlistentry>
2648  *   <term><code>&num;</code></term>
2649  *   <listitem><para>Combined with <code>"&amp;"</code>, <code>"&lt;"</code>, or 
2650  *   <code>"&gt;"</code>, indicates an array reference. As described above, this
2651  *   encompasses up to three #gluniversal_t objects &mdash; @ptrflag, pointer,
2652  *   and integer length.</para>
2653  *   <note><para>
2654  *     Depending on the design of your program, you may wish to pass a pointer
2655  *     directly to your program's memory, or allocate an array and copy the
2656  *     contents in and out. See <link linkend="chimara-Arrays">Arrays</link>.
2657  *   </para></note></listitem>
2658  * </varlistentry>
2659  * <varlistentry>
2660  *   <term><code>!</code></term>
2661  *   <listitem><para>Combined with <code>"&num;"</code>, indicates that the
2662  *   array is retained by the library. The library will keep a reference to the
2663  *   array; the contents are undefined until further notice. You should not use
2664  *   or copy the contents of the array out after the call, even for 
2665  *   <code>"&amp;&num;!"</code> or <code>"&lt;&num;!"</code> arrays. Instead, do
2666  *   it when the library releases the array.</para>
2667  *   <note><para>
2668  *     For example, glk_stream_open_memory() retains the array that you pass it,
2669  *     and releases it when the stream is closed. The library can notify you
2670  *     automatically when arrays are retained and released; see <link
2671  *     linkend="gidispatch-set-retained-registry">Retained Array
2672  *     Registry</link>.
2673  *   </para></note></listitem>
2674  * </varlistentry>
2675  * </variablelist>
2676  *
2677  * Returns: A string which encodes the prototype of the specified Glk function.
2678  */
2679
2680 /**
2681  * gidisp_Class_Window:
2682  *
2683  * Represents a #winid_t opaque object.
2684  */
2685  
2686 /**
2687  * gidisp_Class_Stream:
2688  *
2689  * Represents a #strid_t opaque object.
2690  */
2691  
2692 /**
2693  * gidisp_Class_Fileref:
2694  *
2695  * Represents a #frefid_t opaque object.
2696  */
2697
2698 /**
2699  * gidisp_Class_Schannel:
2700  * 
2701  * Represents a #schanid_t opaque object.
2702  */
2703
2704 /**
2705  * gidispatch_rock_t:
2706  * @num: Space for storing an integer.
2707  * @ptr: Space for storing a pointer.
2708  *
2709  * You can store any value you want in this object; return it from your object
2710  * registry and retained array registry callbacks, and the library will stash it
2711  * away. You can retrieve it with gidispatch_get_objrock().
2712  */ 
2713
2714 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/
2715  
2716 /**
2717  * giblorb_err_t: 
2718  *
2719  * An integer type that can hold the Blorb error codes.
2720  */ 
2721  
2722 /**
2723  * giblorb_err_None:
2724  *
2725  * No error.
2726  */
2727  
2728 /**
2729  * giblorb_err_CompileTime: 
2730  *
2731  * Something is compiled wrong in the Blorb layer.
2732  */
2733  
2734 /**
2735  * giblorb_err_Alloc: 
2736  *
2737  * Memory could not be allocated.
2738  * <note><title>Chimara</title>
2739  * <para>
2740  *  The Blorb layer in the Chimara library should not return this error code;
2741  *  instead, the program aborts if memory allocation fails, in keeping with
2742  *  GLib practices.
2743  * </para></note> 
2744  */
2745  
2746 /**
2747  * giblorb_err_Read: 
2748  *
2749  * Data could not be read from the file.
2750  */
2751
2752 /** 
2753  * giblorb_err_NotAMap:
2754  *
2755  * The map parameter is invalid.
2756  */
2757
2758 /** 
2759  * giblorb_err_Format:
2760  *
2761  * The Blorb file is corrupted or invalid.
2762  */
2763  
2764 /**
2765  * giblorb_err_NotFound:
2766  *
2767  * The requested data could not be found.
2768  */
2769
2770 /**
2771  * giblorb_method_DontLoad:
2772  *
2773  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2774  * giblorb_load_resource() to obtain information about a chunk without actually
2775  * loading it.
2776  */
2777
2778 /**
2779  * giblorb_method_Memory:
2780  *
2781  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2782  * giblorb_load_resource() to load a chunk into memory.
2783  */
2784
2785 /**
2786  * giblorb_method_DontLoad:
2787  *
2788  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2789  * giblorb_load_resource() to get the position in the Blorb file at which the
2790  * chunk data starts.
2791  */
2792
2793 /**
2794  * giblorb_ID_Snd:
2795  *
2796  * Resource usage constant representing a sound file.
2797  */
2798
2799 /**
2800  * giblorb_ID_Exec:
2801  *
2802  * Resource usage constant representing an executable program.
2803  */
2804  
2805 /**
2806  * giblorb_ID_Pict:
2807  *
2808  * Resource usage constant representing an image file.
2809  */
2810
2811 /**
2812  * giblorb_ID_Copyright:
2813  *
2814  * Resource usage constant representing the copyright message (date and holder, 
2815  * without the actual copyright symbol). There should only be one such chunk per
2816  * file.
2817  */
2818
2819 /**
2820  * giblorb_ID_AUTH:
2821  *
2822  * Resource usage constant representing the name of the author or creator of the
2823  * file. This could be a login name on multi-user systems, for example. There
2824  * should only be one such chunk per file.
2825  */
2826  
2827 /**
2828  * giblorb_ID_ANNO:
2829  *
2830  * Resource usage constant representing any textual annotation that the user or 
2831  * writing program sees fit to include.
2832  */ 
2833  
2834 /**
2835  * giblorb_map_t:
2836  *
2837  * Holds the complete description of an open Blorb file. This type is opaque for
2838  * normal interpreter use.
2839  */
2840  
2841 /**
2842  * giblorb_result_t:
2843  *
2844  * Holds information about a chunk loaded from a Blorb file, and the method of
2845  * accessing the chunk data. See giblorb_load_chunk_by_type() and
2846  * giblorb_load_chunk_by_number(). 
2847  */
2848  
2849 /**
2850  * giblorb_create_map:
2851  * @file: An input stream pointing to a Blorb file.
2852  * @newmap: Return location for a Blorb resource map.
2853  *
2854  * Reads Blorb data out of a Glk stream. It does not load every resource at 
2855  * once; instead, it creates a map in memory which makes it easy to find 
2856  * resources. A pointer to the map is stored in @newmap. This is an opaque 
2857  * object; you pass it to the other Blorb-layer functions.
2858  *
2859  * Returns: a Blorb error code. 
2860  */
2861  
2862 /**
2863  * giblorb_destroy_map: 
2864  * @map: A Blorb resource map to deallocate.
2865  *
2866  * Deallocates @map and all associated memory. This does 
2867  * <emphasis>not</emphasis> close the original stream.
2868  *
2869  * Returns: a Blorb error code. 
2870  */
2871
2872 /**
2873  * giblorb_load_chunk_by_type:
2874  * @map: The Blorb resource map to load a chunk from.
2875  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
2876  * %giblorb_method_Memory, or %giblorb_method_FilePos.
2877  * @res: Return location for the result.
2878  * @chunktype: The type of chunk to load.
2879  * @count: The chunk number of type @chunktype to load.
2880  *
2881  * Loads a chunk of a given type. The @count parameter distinguishes between 
2882  * chunks of the same type. If @count is zero, the first chunk of that type is 
2883  * loaded, and so on.
2884  * 
2885  * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the 
2886  * form type, rather than FORM.
2887  * <note><para>
2888  *  This introduces a slight ambiguity &mdash; you cannot distiguish between a 
2889  *  FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is 
2890  *  almost certainly a mistake.
2891  * </para></note> 
2892  * 
2893  * The returned data is written into @res, according to @method.
2894  * 
2895  * The <structfield>chunknum</structfield> field is filled in with the number of
2896  * the chunk. (This value can then be passed to giblorb_load_chunk_by_number() 
2897  * or giblorb_unload_chunk().) The <structfield>length</structfield> field is 
2898  * filled in with the length of the chunk in bytes. The 
2899  * <structfield>chunktype</structfield> field is the chunk's type, which of 
2900  * course will be the type you asked for.
2901  * 
2902  * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You
2903  * can use this if you are only interested in whether a chunk exists, or in the
2904  * <structfield>chunknum</structfield> and <structfield>length</structfield> 
2905  * parameters.
2906  * 
2907  * If you specify %giblorb_method_FilePos, 
2908  * <structfield>data.startpos</structfield> is filled in with the file position
2909  * of the chunk data. You can use glk_stream_set_position() to read the data 
2910  * from the stream.
2911  * 
2912  * If you specify %giblorb_method_Memory, <structfield>data.ptr</structfield> is
2913  * filled with a pointer to allocated memory containing the chunk data. This 
2914  * memory is owned by the map, not you. If you load the chunk more than once 
2915  * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one
2916  * copy in memory. You should not deallocate this memory yourself; call 
2917  * giblorb_unload_chunk() instead.
2918  *
2919  * Returns: a Blorb error code.
2920  */
2921
2922 /** 
2923  * giblorb_load_chunk_by_number:
2924  * @map: The Blorb resource map to load a chunk from.
2925  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
2926  * %giblorb_method_Memory, or %giblorb_method_FilePos.
2927  * @res: Return location for the result.
2928  * @chunknum: The chunk number to load.
2929  *
2930  * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a
2931  * given chunk number. The type of the chunk can be found in the 
2932  * <structfield>chunktype</structfield> field of #giblorb_result_t. You can get
2933  * the chunk number from the <structfield>chunknum</structfield> field, after 
2934  * calling one of the other load functions.
2935  *
2936  * Returns: a Blorb error code. 
2937  */
2938
2939 /**
2940  * giblorb_unload_chunk:
2941  * @map: The Blorb resource map to unload a chunk from.
2942  * @chunknum: The chunk number to unload.
2943  *
2944  * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk
2945  * has never been loaded into memory, this has no effect. 
2946  *
2947  * Returns: a Blorb error code.
2948  */
2949
2950 /**
2951  * giblorb_load_resource:
2952  * @map: The Blorb resource map to load a resource from.
2953  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
2954  * %giblorb_method_Memory, or %giblorb_method_FilePos.
2955  * @res: Return location for the result.
2956  * @usage: The type of data resource to load.
2957  * @resnum: The resource number to load.
2958  *
2959  * Loads a resource, given its usage and resource number. Currently, the three
2960  * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and
2961  * %giblorb_ID_Exec (executable program). See the Blorb specification for more
2962  * information about the types of data that can be stored for these usages.
2963  * 
2964  * Note that a resource number is not the same as a chunk number. The resource
2965  * number is the sound or image number specified by a Glk program. Chunk number
2966  * is arbitrary, since chunks in a Blorb file can be in any order. To find the
2967  * chunk number of a given resource, call giblorb_load_resource() and look in
2968  * <structfield>res.chunknum</structfield>.
2969  *
2970  * Returns: a Blorb error code.
2971  */
2972
2973 /**
2974  * giblorb_count_resources:
2975  * @map: The Blorb resource map in which to count the resources.
2976  * @usage: The type of data resource to count.
2977  * @num: Return location for the number of chunks of @usage.
2978  * @min: Return location for the lowest resource number of @usage.
2979  * @max: Return location for the highest resource number of @usage.
2980  *
2981  * Counts the number of chunks with a given usage (image, sound, or executable.)
2982  * The total number of chunks of that usage is stored in @num. The lowest and 
2983  * highest resource number of that usage are stored in @min and @max. You can
2984  * leave any of the three pointers %NULL if you don't care about that
2985  * information. 
2986  *
2987  * Returns: a Blorb error code.
2988  */
2989
2990 /*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/
2991
2992 /**
2993  * glkunix_argumentlist_t:
2994  * 
2995  * In each entry, name is the option as it would appear on the command line
2996  * (including the leading dash, if any.) The desc is a description of the
2997  * argument; this is used when the library is printing a list of options. And
2998  * argtype is one of the following constants:
2999  * 
3000  * <variablelist>
3001  * <varlistentry>
3002  *  <term>%glkunix_arg_NoValue</term>
3003  *  <listitem><para>The argument appears by itself.</para></listitem>
3004  * </varlistentry>
3005  * <varlistentry>
3006  *  <term>%glkunix_arg_ValueFollows</term>
3007  *  <listitem><para>The argument must be followed by another argument (the 
3008  *  value).</para></listitem>
3009  * </varlistentry>
3010  * <varlistentry>
3011  *  <term>%glkunix_arg_ValueCanFollow</term> 
3012  *  <listitem><para>The argument may be followed by a value, optionally. (If the
3013  *  next argument starts with a dash, it is taken to be a new argument, not the 
3014  *  value of this one.)</para></listitem>
3015  * </varlistentry>
3016  * <varlistentry>
3017  *  <term>%glkunix_arg_NumberValue</term>
3018  *  <listitem><para>The argument must be followed by a number, which may be the 
3019  *  next argument or part of this one. (That is, either <quote><code>-width 
3020  *  20</code></quote> or <quote><code>-width20</code></quote> will be accepted.)
3021  *  </para></listitem>
3022  * </varlistentry>
3023  * <varlistentry> 
3024  *  <term>%glkunix_arg_End</term>
3025  *  <listitem><para>The <code>glkunix_arguments[]</code> array must be 
3026  *  terminated with an entry containing this value.</para></listitem>
3027  * </varlistentry>
3028  * </variablelist>
3029  * 
3030  * To accept arbitrary arguments which lack dashes, specify a name of 
3031  * <code>""</code> and an argtype of %glkunix_arg_ValueFollows.
3032  *
3033  * If you don't care about command-line arguments, you must still define an
3034  * empty arguments list, as follows:
3035  * |[
3036  * #glkunix_argumentlist_t glkunix_arguments[] = {
3037  *  { NULL, #glkunix_arg_End, NULL }
3038  * };
3039  * ]|
3040  * 
3041  * Here is a more complete sample list:
3042  * |[
3043  * #glkunix_argumentlist_t glkunix_arguments[] = {
3044  *  { "", #glkunix_arg_ValueFollows, "filename: The game file to load." },
3045  *  { "-hum", #glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
3046  *  { "-bom", #glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
3047  *   the NUM, if given)." },
3048  *  { "-goo", #glkunix_arg_NoValue, "-goo: Find goo." },
3049  *  { "-wob", #glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
3050  *  { NULL, #glkunix_arg_End, NULL }
3051  * };
3052  * ]|
3053  * This would match the arguments <quote><code>thingfile -goo -wob8 -bom -hum 
3054  * song</code></quote>.
3055  *
3056  * After the library parses the command line, it does various occult rituals of
3057  * initialization, and then calls glkunix_startup_code().
3058  *
3059  * |[ int glkunix_startup_code(#glkunix_startup_t *data); ]|
3060  *
3061  * This should return %TRUE if everything initializes properly. If it returns
3062  * %FALSE, the library will shut down without ever calling your glk_main() 
3063  * function.
3064  */
3065
3066 /**
3067  * glkunix_startup_t: 
3068  * 
3069  * The fields are a standard Unix <code>(argc, argv)</code> list, which contain
3070  * the arguments you requested from the command line. In deference to custom,
3071  * <code>argv[0]</code> is always the program name.
3072  */
3073
3074 /**
3075  * glkunix_arg_End:
3076  *
3077  * Terminates a list of #glkunix_argumentlist_t.
3078  */
3079  
3080 /**
3081  * glkunix_arg_ValueFollows:
3082  *
3083  * Indicates an argument which must be followed by a value, as the next 
3084  * argument.
3085  */
3086
3087 /** 
3088  * glkunix_arg_NoValue:
3089  *
3090  * Indicates an argument which occurs by itself, without a value.
3091  */
3092  
3093 /**
3094  * glkunix_arg_ValueCanFollow:
3095  *
3096  * Indicates an argument which may be followed by a value, or may occur by 
3097  * itself.
3098  */
3099  
3100 /**
3101  * glkunix_arg_NumberValue:
3102  *
3103  * Indicates an argument which must be followed by a numerical value, either as 
3104  * the next argument or tacked onto the end of this argument.
3105  */