Fixed ordering of the application of the styles
[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></para>
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  * CLASSid_t glk_CLASS_iterate(CLASSid_t obj, glui32 *rockptr);
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_CLASS_iterate(NULL, NULL);
207  * while (obj) {
208  *    /* ...do something with obj... *<!-- -->/
209  *    obj = glk_CLASS_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-mouse-events
487  * @short_description: Events representing a mouse click
488  * @include: libchimara/glk.h
489  *
490  * On some platforms, Glk can recognize when the mouse (or other pointer) is 
491  * used to select a spot in a window. You can request mouse input only in text 
492  * grid windows and graphics windows.
493  * 
494  * A window can have mouse input and character/line input pending at the same
495  * time.
496  * 
497  * If the player clicks in a window which has a mouse input event pending,
498  * glk_select() will return an event whose type is %evtype_MouseInput. Again,
499  * once this happens, the request is complete, and you must request another if
500  * you want further mouse input.
501  * 
502  * In the event structure, @win tells what window the event came from.
503  * 
504  * In a text grid window, the @val1 and @val2 fields are the x and y coordinates
505  * of the character that was clicked on. 
506  * <note><para>So @val1 is the column, and @val2 is the row.</para></note>
507  * The top leftmost character is considered to be (0,0).
508  * 
509  * In a graphics window, they are the x and y coordinates of the pixel that was
510  * clicked on. Again, the top left corner of the window is (0,0).
511  * 
512  * <note><para>
513  *   Most mouse-based idioms define standard functions for mouse hits in text
514  *   windows &mdash; typically selecting or copying text. It is up to the
515  *   library to separate this from Glk mouse input. The library may choose to
516  *   select text when it is clicked normally, and cause Glk mouse events when
517  *   text is control-clicked. Or the other way around. Or it may be the
518  *   difference between clicking and double-clicking. Or the library may
519  *   reserve a particular mouse button, on a multi-button mouse. It may even
520  *   specify a keyboard key to be the "mouse button", referring to wherever the
521  *   mouse cursor is when the key is hit. Or some even more esoteric positioning
522  *   system. You need only know that the user can do it, or not.
523  * </para></note> 
524  * <note><para>
525  *   However, since different platforms will handle this issue differently, you
526  *   should be careful how you instruct the player in your program. Do not tell
527  *   the player to <quote>double-click</quote>, <quote>right-click</quote>, or
528  *   <quote>control-click</quote> in a window. The preferred term is <quote>to
529  *   touch the window</quote>, or a spot in the window.
530  * </para></note>
531  * <note><para>
532  *   Goofy, but preferred.
533  * </para></note>
534  */
535
536 /**
537  * SECTION:glk-timer-events
538  * @short_description: Events sent at fixed intervals
539  * @include: libchimara/glk.h
540  *
541  * You can request that an event be sent at fixed intervals, regardless of what
542  * the player does. Unlike input events, timer events can be tested for with
543  * glk_select_poll() as well as glk_select().
544  *
545  * It is possible that the library does not support timer events. You can check
546  * this with the %gestalt_Timer selector.
547  */
548  
549 /**
550  * SECTION:glk-streams
551  * @short_description: Input and output abstractions
552  * @include: libchimara/glk.h
553  *
554  * All character output in Glk is done through streams. Every window has an
555  * output stream associated with it. You can also write to files on disk; every
556  * open file is represented by an output stream as well.
557  *
558  * There are also input streams; these are used for reading from files on disk.
559  * It is possible for a stream to be both an input and an output stream. 
560  *
561  * <note><para>
562  *   Player input is done through line and character input events, not streams.
563  *   This is a small inelegance in theory. In practice, player input is slow and
564  *   things can interrupt it, whereas file input is immediate. If a network
565  *   extension to Glk were proposed, it would probably use events and not
566  *   streams, since network communication is not immediate.
567  * </para></note>
568  *
569  * It is also possible to create a stream that reads or writes to a buffer in
570  * memory.
571  * 
572  * Finally, there may be platform-specific types of streams, which are created
573  * before your program starts running. 
574  *
575  * <note><para>
576  *   For example, a program running under Unix may have access to standard input
577  *   as a stream, even though there is no Glk call to explicitly open standard
578  *   input. On the Mac, data in a Mac resource may be available through a
579  *   resource-reading stream.
580  * </para></note>
581  *
582  * You do not need to worry about the origin of such streams; just read or write
583  * them as usual. For information about how platform-specific streams come to
584  * be, see <link linkend="chimara-Startup-Options">Startup Options</link>.
585  * 
586  * A stream is opened with a particular file mode, see the 
587  * <code>filemode_</code> constants below.
588  *
589  * For information on opening streams, see the discussion of each specific type
590  * of stream in <link linkend="chimara-The-Types-of-Streams">The Types of
591  * Streams</link>. Remember that it is always possible that opening a stream
592  * will fail, in which case the creation function will return %NULL.
593  * 
594  * Each stream remembers two character counts, the number of characters printed
595  * to and read from that stream. The write-count is exactly one per 
596  * glk_put_char() call; it is figured before any platform-dependent character
597  * cookery. 
598  *
599  * <note><para>
600  *   For example, if a newline character is converted to 
601  *   linefeed-plus-carriage-return, the stream's count still only goes up by
602  *   one; similarly if an accented character is displayed as two characters.
603  * </para></note>
604  * 
605  * The read-count is exactly one per glk_get_char_stream() call, as long as the
606  * call returns an actual character (as opposed to an end-of-file token.) 
607  *
608  * Glk has a notion of the <quote>current (output) stream</quote>. If you print
609  * text without specifying a stream, it goes to the current output stream. The
610  * current output stream may be %NULL, meaning that there isn't one. It is
611  * illegal to print text to stream %NULL, or to print to the current stream when
612  * there isn't one.
613  *
614  * If the stream which is the current stream is closed, the current stream
615  * becomes %NULL. 
616  */
617  
618 /**
619  * SECTION:glk-print
620  * @short_description: Printing to streams
621  * @include: libchimara/glk.h
622  *
623  * You can print Latin-1 and Unicode characters, null-terminated strings, or
624  * buffers to any stream. The characters will be converted into the appropriate
625  * format for that stream.
626  */
627  
628 /**
629  * SECTION:glk-read
630  * @short_description: Reading from streams
631  * @include: libchimara/glk.h
632  *
633  * You can read Latin-1 or Unicode characters, buffers, or whole lines from any
634  * stream. The characters will be converted into the form in which you request
635  * them.
636  */
637  
638 /**
639  * SECTION:glk-closing-streams
640  * @short_description: Closing streams and retrieving their character counts
641  * @include: libchimara/glk.h
642  *
643  * When you close a Glk stream, you have the opportunity to examine the
644  * character counts &mdash; the number of characters written to or read from the
645  * stream.
646  */
647
648 /**
649  * SECTION:glk-stream-positions
650  * @short_description: Moving the read/write mark
651  * @include: libchimara/glk.h
652  *
653  * You can set the position of the read/write mark in a stream.
654  *
655  * <note><para>
656  *   Which makes one wonder why they're called <quote>streams</quote> in the
657  *   first place. Oh well.
658  * </para></note>
659  */
660
661 /**
662  * SECTION:glk-styles
663  * @short_description: Changing the appearance of printed text
664  * @include: libchimara/glk.h
665  *
666  * You can send style-changing commands to an output stream. After a style
667  * change, new text which is printed to that stream will be given the new style,
668  * whatever that means for the stream in question. For a window stream, the text
669  * will appear in that style. For a memory stream, style changes have no effect.
670  * For a file stream, if the machine supports styled text files, the styles may
671  * be written to the file; more likely the style changes will have no effect.
672  * 
673  * Styles are exclusive. A character is shown with exactly one style, not a 
674  * subset of the possible styles.
675  *
676  * <note><para>
677  *  Note that every stream and window has its own idea of the <quote>current 
678  *  style.</quote> Sending a style command to one window or stream does not
679  *  affect any others.
680  * </para></note>
681  * <note><para>
682  *  Except for a window's echo stream; see <link 
683  *  linkend="chimara-Echo-Streams">Echo Streams</link>.
684  * </para></note>
685  * 
686  * The styles are intended to distinguish meaning and use, not formatting. There
687  * is no standard definition of what each style will look like. That is left up
688  * to the Glk library, which will choose an appearance appropriate for the
689  * platform's interface and the player's preferences.
690  * 
691  * There are currently eleven styles defined. More may be defined in the future.
692  * 
693  * Styles may be distinguished on screen by font, size, color, indentation,
694  * justification, and other attributes. Note that some attributes (notably
695  * justification and indentation) apply to entire paragraphs. If possible and
696  * relevant, you should apply a style to an entire paragraph &mdash; call 
697  * glk_set_style() immediately after printing the newline at the beginning of
698  * the text, and do the same at the end.
699  * 
700  * <note><para>
701  *  For example, %style_Header may well be centered text. If you print 
702  *  <quote>Welcome to Victim (a short interactive mystery)</quote>, and only the
703  *  word <quote>Victim</quote> is in the %style_Header, the center-justification
704  *  attribute will be lost. Similarly, a block quote is usually indented on both
705  *  sides, but indentation is only meaningful when applied to an entire line or
706  *  paragraph, so block quotes should take up an entire paragraph. Contrariwise,
707  *  %style_Emphasized need not be used on an entire paragraph. It is often used
708  *  for single emphasized words in normal text, so you can expect that it will
709  *  appear properly that way; it will be displayed in italics or underlining, 
710  *  not center-justified or indented.
711  * </para></note> 
712  * 
713  * <note><para>
714  *  Yes, this is all a matter of mutual agreement between game authors and game
715  *  players. It's not fixed by this specification. That's natural language for
716  *  you.
717  * </para></note>
718  */
719
720 /**
721  * SECTION:glk-stylehints
722  * @short_description: Setting style hints
723  * @include: libchimara/glk.h
724  *
725  * There are no guarantees of how styles will look, but you can make 
726  * suggestions.
727  *
728  * Initially, no hints are set for any window type or style. Note that having no
729  * hint set is not the same as setting a hint with value 0.
730  * 
731  * These functions do <emphasis>not</emphasis> affect 
732  * <emphasis>existing</emphasis> windows. They affect the windows which you
733  * create subsequently. If you want to set hints for all your game windows, call
734  * glk_stylehint_set() before you start creating windows. If you want different
735  * hints for different windows, change the hints before creating each window.
736  * 
737  * <note><para>
738  *  This policy makes life easier for the interpreter. It knows everything about
739  *  a particular window's appearance when the window is created, and it doesn't
740  *  have to change it while the window exists.
741  * </para></note>
742  * 
743  * Hints are hints. The interpreter may ignore them, or give the player a choice
744  * about whether to accept them. Also, it is never necessary to set hints. You
745  * don't have to suggest that %style_Preformatted be fixed-width, or 
746  * %style_Emphasized be boldface or italic; they will have appropriate defaults.
747  * Hints are for situations when you want to <emphasis>change</emphasis> the 
748  * appearance of a style from what it would ordinarily be. The most common case
749  * when this is appropriate is for the styles %style_User1 and %style_User2.
750  * 
751  * There are currently ten style hints defined. More may be defined in the 
752  * future. 
753  * 
754  * Again, when passing a style hint to a Glk function, any value is actually 
755  * legal. If the interpreter does not recognize the stylehint value, it will 
756  * ignore it. 
757  * <note><para>
758  *  This policy allows for the future definition of style hints without breaking
759  *  old Glk libraries.
760  * </para></note> 
761  */
762
763 /**
764  * SECTION:glk-style-measure
765  * @short_description: Finding out how the library displays your style hints
766  * @include: libchimara/glk.h
767  *
768  * You can suggest the appearance of a window's style before the window is
769  * created; after the window is created, you can test the style's actual
770  * appearance. These functions do not test the style hints; they test the
771  * attribute of the style as it appears to the player.
772  *
773  * Note that although you cannot change the appearance of a window's styles
774  * after the window is created, the library can. A platform may support dynamic
775  * preferences, which allow the player to change text formatting while your
776  * program is running.
777  * <note><para>
778  *   Changes that affect window size (such as font size changes) will be
779  *   signalled by an %evtype_Arrange event. However, more subtle changes (such
780  *   as text color differences) are not signalled. If you test the appearance of
781  *   styles at the beginning of your program, you must keep in mind the
782  *   possibility that the player will change them later.
783  * </para></note>
784  */
785
786 /**
787  * SECTION:glk-stream-types
788  * @short_description: Window, memory, and file streams
789  * @include: libchimara/glk.h
790  *
791  * <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
792  * <para>
793  * Every window has an output stream associated with it. This is created
794  * automatically, with %filemode_Write, when you open the window. You get it
795  * with glk_window_get_stream().
796  * 
797  * A window stream cannot be closed with glk_stream_close(). It is closed
798  * automatically when you close its window with glk_window_close().
799  * 
800  * Only printable characters (including newline) may be printed to a window
801  * stream. See <link linkend="chimara-Character-Encoding">Character 
802  * Encoding</link>.
803  * </para>
804  * </refsect2>
805  * <refsect2 id="chimara-Memory-Streams"><title>Memory Streams</title>
806  * <para>
807  * You can open a stream which reads from or writes to a space in memory. See
808  * glk_stream_open_memory() and glk_stream_open_memory_uni(). When opening a
809  * memory stream, you specify a buffer to which the stream's output will be
810  * written, and its length @buflen.
811  *
812  * When outputting, if more than @buflen characters are written to the stream,
813  * all of them beyond the buffer length will be thrown away, so as not to
814  * overwrite the buffer. (The character count of the stream will still be
815  * maintained correctly. That is, it will count the number of characters written
816  * into the stream, not the number that fit into the buffer.)
817  *
818  * If the buffer is %NULL, or for that matter if @buflen is zero, then 
819  * <emphasis>everything</emphasis> written to the stream is thrown away. This
820  * may be useful if you are interested in the character count.
821  *
822  * When inputting, if more than @buflen characters are read from the stream, the
823  * stream will start returning -1 (signalling end-of-file.) If the buffer is 
824  * %NULL, the stream will always return end-of-file.
825  *
826  * The data is written to the buffer exactly as it was passed to the printing
827  * functions (glk_put_char(), etc.); input functions will read the data exactly
828  * as it exists in memory. No platform-dependent cookery will be done on it.
829  *
830  * <note><para>
831  *   You can write a disk file in text mode, but a memory stream is effectively
832  *   always in binary mode.
833  * </para></note>
834  * 
835  * Whether reading or writing, the contents of the buffer are undefined until
836  * the stream is closed. The library may store the data there as it is written,
837  * or deposit it all in a lump when the stream is closed. It is illegal to
838  * change the contents of the buffer while the stream is open.
839  * </para>
840  * </refsect2>
841  * <refsect2 id="chimara-File-Streams"><title>File Streams</title>
842  * <para>
843  * You can open a stream which reads from or writes to a disk file. See 
844  * glk_stream_open_file() and glk_stream_open_file_uni().
845  *
846  * The file may be written in text or binary mode; this is determined by the
847  * file reference you open the stream with. Similarly, platform-dependent
848  * attributes such as file type are determined by the file reference. See <link
849  * linkend="chimara-File-References">File References</link>.
850  * </para>
851  * </refsect2>
852  */
853  
854 /**
855  * SECTION:glk-stream-other
856  * @short_description: Miscellaneous functions for streams
857  * @include: libchimara/glk.h
858  *
859  * This section includes functions for streams that don't fit anywhere else.
860  */
861
862 /**
863  * SECTION:glk-fileref
864  * @short_description: A platform-independent way to refer to disk files
865  * @include: libchimara/glk.h
866  *
867  * You deal with disk files using file references. Each fileref is an opaque C
868  * structure pointer; see <link linkend="chimara-Opaque-Objects">Opaque 
869  * Objects</link>.
870  * 
871  * A file reference contains platform-specific information about the name and
872  * location of the file, and possibly its type, if the platform has a notion of
873  * file type. It also includes a flag indication whether the file is a text file
874  * or binary file. 
875  *
876  * <note><para>
877  *   Note that this is different from the standard C I/O library, in which you
878  *   specify text or binary mode when the file is opened.
879  * </para></note>
880  * 
881  * A fileref does not have to refer to a file which actually exists. You can
882  * create a fileref for a nonexistent file, and then open it in write mode to
883  * create a new file.
884  * 
885  * You always provide a usage argument when you create a fileref. The usage is a
886  * mask of constants (see below) to indicate the file type and the mode (text or
887  * binary.) These values are used when you create a new file, and also to filter
888  * file lists when the player is selecting a file to load. 
889  * 
890  * In general, you should use text mode if the player expects to read the file
891  * with a platform-native text editor; you should use binary mode if the file is
892  * to be read back by your program, or if the data must be stored exactly. Text
893  * mode is appropriate for %fileusage_Transcript; binary mode is appropriate for
894  * %fileusage_SavedGame and probably for %fileusage_InputRecord. %fileusage_Data
895  * files may be text or binary, depending on what you use them for. 
896  */
897  
898 /**
899  * SECTION:glk-fileref-types
900  * @short_description: Four different ways to create a file reference
901  * @include: libchimara/glk.h
902  *
903  * There are four different functions for creating a fileref, depending on how
904  * you wish to specify it. Remember that it is always possible that a fileref
905  * creation will fail and return %NULL.
906  */
907  
908 /**
909  * SECTION:glk-fileref-other
910  * @short_description: Miscellaneous functions for file references
911  * @include: libchimara/glk.h
912  *
913  * This section includes functions for file references that don't fit anywhere
914  * else.
915  */
916
917 /**
918  * SECTION:glk-image-resources
919  * @short_description: Graphics in Glk
920  * @include: libchimara/glk.h
921  *
922  * In accordance with this modern age, Glk provides for a modicum of graphical
923  * flair. It does not attempt to be a complete graphical toolkit. Those already
924  * exist. Glk strikes the usual uncomfortable balance between power, 
925  * portability, and ease of implementation: commands for arranging pre-supplied
926  * images on the screen and intermixed with text.
927  * 
928  * Graphics is an optional capability in Glk; not all libraries support 
929  * graphics. This should not be a surprise.
930  * 
931  * Most of the graphics commands in Glk deal with image resources. Your program
932  * does not have to worry about how images are stored. Everything is a resource,
933  * and a resource is referred to by an integer identifier. You may, for example,
934  * call a function to display image number 17. The format, loading, and 
935  * displaying of that image is entirely up to the Glk library for the platform
936  * in question.
937  * 
938  * Of course, it is also desirable to have a platform-independent way to store
939  * sounds and images. Blorb is the official resource-storage format of Glk. A
940  * Glk library does not have to understand Blorb, but it is more likely to
941  * understand Blorb than any other format.
942  *
943  * <note><para>
944  *   Glk does not specify the exact format of images, but Blorb does. Images in 
945  *   a Blorb archive must be PNG or JPEG files. More formats may be added if 
946  *   real-world experience shows it to be desirable. However, that is in the 
947  *   domain of the Blorb specification. The Glk spec, and Glk programming, will
948  *   not change.
949  * </para></note>
950  * 
951  * At present, images can only be drawn in graphics windows and text buffer 
952  * windows. In fact, a library may not implement both of these possibilities.
953  * You should test each with the %gestalt_DrawImage selector if you plan to use
954  * it. See <link linkend="chimara-Testing-for-Graphics-Capabilities">Testing for
955  * Graphics Capabilities</link>. 
956  */
957
958 /**
959  * SECTION:glk-graphics-windows
960  * @short_description: Drawing graphics in graphics windows
961  * @include: libchimara/glk.h
962  *
963  * A graphics window is a rectangular canvas of pixels, upon which you can draw
964  * images. The contents are entirely under your control. You can draw as many
965  * images as you like, at any positions &mdash; overlapping if you like. If the
966  * window is resized, you are responsible for redrawing everything. See <link
967  * linkend="wintype-Graphics">Graphics Windows</link>.
968  * 
969  * <note><para>
970  *   Note that graphics windows do not support a full set of object-drawing 
971  *   commands, nor can you draw text in them. That may be available in a future 
972  *   Glk extension. For now, it seems reasonable to limit the task to a single 
973  *   primitive, the drawing of a raster image. And then there's the ability to
974  *   fill a rectangle with a solid color &mdash; a small extension, and 
975  *   hopefully no additional work for the library, since it can already clear 
976  *   with arbitrary background colors. In fact, if glk_window_fill_rect() did 
977  *   not exist, an author could invent it &mdash; by briefly setting the
978  *   background color, erasing a rectangle, and restoring.
979  * </para></note>
980  * 
981  * If you call glk_image_draw() or glk_image_draw_scaled() in a graphics window,
982  * @val1 and @val2 are interpreted as X and Y coordinates. The image will be 
983  * drawn with its upper left corner at this position.
984  * 
985  * It is legitimate for part of the image to fall outside the window; the excess
986  * is not drawn. Note that these are signed arguments, so you can draw an image
987  * which falls outside the left or top edge of the window, as well as the right
988  * or bottom.
989  * 
990  * There are a few other commands which apply to graphics windows.
991  */
992
993 /**
994  * SECTION:glk-graphics-text
995  * @short_description: Drawing graphics inside or beside text
996  * @include: libchimara/glk.h
997  *
998  * A text buffer is a linear text stream. You can draw images in-line with this
999  * text. If you are familiar with HTML, you already understand this model. You
1000  * draw images with flags indicating alignment. The library takes care of
1001  * scrolling, resizing, and reformatting text buffer windows.
1002  *
1003  * If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer
1004  * window, @val1 gives the image alignment. The @val2 argument is currently
1005  * unused, and should always be zero.
1006  *
1007  * The two <quote>margin</quote> alignments require some care. To allow proper 
1008  * positioning, images using %imagealign_MarginLeft and %imagealign_MarginRight 
1009  * must be placed at the beginning of a line. That is, you may only call 
1010  * glk_image_draw() (with these two alignments) in a window, if you have just 
1011  * printed a newline to the window's stream, or if the window is entirely empty.
1012  * If you margin-align an image in a line where text has already appeared, no 
1013  * image will appear at all.
1014  * 
1015  * Inline-aligned images count as <quote>text</quote> for the purpose of this 
1016  * rule.
1017  * 
1018  * You may have images in both margins at the same time.
1019  * 
1020  * It is also legal to have more than one image in the same margin (left or 
1021  * right.) However, this is not recommended. It is difficult to predict how text
1022  * will wrap in that situation, and libraries may err on the side of 
1023  * conservatism. 
1024  */
1025
1026 /**
1027  * SECTION:glk-graphics-testing
1028  * @short_description: Checking whether the library supports graphics
1029  * @include: libchimara/glk.h
1030  *
1031  * Before calling Glk graphics functions, you should use the gestalt selector
1032  * %gestalt_Graphics. To test for additional capabilities, you can also use the
1033  * %gestalt_DrawImage and %gestalt_GraphicsTransparency selectors.
1034  */
1035
1036 /**
1037  * SECTION:glk-sound-channels
1038  * @short_description: Creating new sound channels and closing them
1039  * @include: libchimara/glk.h
1040  *
1041  * Sounds in Glk are played through sound channels. Sound channels are another
1042  * type of opaque object, like windows, streams, and file references.
1043  */
1044
1045 /**
1046  * SECTION:glk-playing-sounds
1047  * @short_description: Producing noise
1048  * @include: libchimara/glk.h
1049  *
1050  * These functions play the actual sounds through the sound channels.
1051  */
1052
1053 /**
1054  * SECTION:glk-sound-other
1055  * @short_description: Miscellaneous functions for sound channels
1056  * @include: libchimara/glk.h
1057  *
1058  * This section includes functions for sound channels that don't fit anywhere
1059  * else.
1060  */
1061
1062 /**
1063  * SECTION:glk-sound-testing
1064  * @short_description: Checking whether the library supports sound
1065  * @include: libchimara/glk.h
1066  *
1067  * Before calling Glk sound functions, you should use the %gestalt_Sound
1068  * selector. To test for additional capabilities, you can use the 
1069  * %gestalt_SoundMusic, %gestalt_SoundVolume, and %gestalt_SoundNotify 
1070  * selectors.
1071  */
1072
1073 /**
1074  * SECTION:glk-creating-hyperlinks
1075  * @short_description: Printing text as a hyperlink
1076  * @include: libchimara/glk.h
1077  *
1078  * Some games may wish to mark up text in their windows with hyperlinks, which
1079  * can be selected by the player &mdash; most likely by mouse click. Glk allows
1080  * this in a manner similar to the way text styles are set.
1081  *
1082  * Hyperlinks are an optional capability in Glk.
1083  */
1084
1085 /**
1086  * SECTION:glk-accepting-hyperlinks
1087  * @short_description: Generating and catching hyperlink navigation events
1088  * @include: libchimara/glk.h
1089  *
1090  * When you request a hyperlink event in a window, you will receive a hyperlink
1091  * event when the player clicks on a hyperlink.
1092  */
1093
1094 /**
1095  * SECTION:glk-hyperlinks-testing
1096  * @short_description: Checking whether the library supports hyperlinks
1097  * @include: libchimara/glk.h
1098  *
1099  * Before calling Glk hyperlink functions, you should use the gestalt selectors
1100  * %gestalt_Hyperlinks and %gestalt_HyperlinkInput.
1101  */
1102  
1103 /**
1104  * SECTION:dispatch-interrogating
1105  * @short_description: Finding out what functions the Glk library exports
1106  * @include: libchimara/glk.h, libchimara/gi_dispa.h
1107  *
1108  * These are the ancilliary functions that let you enumerate.
1109  */
1110  
1111 /**
1112  * SECTION:dispatch-dispatching
1113  * @short_description: Dispatching the call to the Glk library
1114  * @include: libchimara/glk.h, libchimara/gi_dispa.h
1115  *
1116  * The function gidispatch_call() invokes a function from the Glk library.
1117  */
1118  
1119 /**
1120  * SECTION:dispatch-prototypes
1121  * @short_description: Querying Glk function prototypes
1122  * @include: libchimara/glk.h, libchimara/gi_dispa.h
1123  *
1124  * There are many possible ways to set up a #gluniversal_t array, and it's
1125  * illegal to call gidispatch_call() with an array which doesn't match the
1126  * function. Furthermore, some references are passed in, some passed out, and
1127  * some both. How do you know how to handle the argument list?
1128  * 
1129  * One possibility is to recognize each function selector, and set up the
1130  * arguments appropriately. However, this entails writing special code for each
1131  * Glk function; which is exactly what we don't want to do.
1132  * 
1133  * Instead, you can call gidispatch_prototype(). 
1134  */
1135
1136 /**
1137  * SECTION:dispatch-library-functions
1138  * @short_description: Platform-dependent dispatch layer functions
1139  * @include: libchimara/glk.h, libchimara/gi_dispa.h
1140  *
1141  * Ideally, the three layers &mdash; program, dispatch layer, Glk library
1142  * &mdash; would be completely modular; each would refer only to the layers
1143  * beneath it. Sadly, there are a few places where the library must notify the
1144  * program that something has happened. Worse, these situations are only
1145  * relevant to programs which use the dispatch layer, and then only some of
1146  * those.
1147  * 
1148  * Since C is uncomfortable with the concept of calling functions which may not
1149  * exist, Glk handles this with call-back function pointers. The program can
1150  * pass callbacks in to the library; if it does, the library will call them, and
1151  * if not, the library doesn't try.
1152  * 
1153  * These callbacks are optional, in the sense that the program may or may not
1154  * set them. However, any library which wants to interoperate with the dispatch
1155  * layer must <emphasis>allow</emphasis> the program to set them; it is the
1156  * program's choice. The library does this by implementing
1157  * <code>set_registry functions</code> &mdash; the functions to which the
1158  * program passes its callbacks.
1159  * 
1160  * <note><para>
1161  *   Even though these callbacks and the functions to set them are declared in
1162  *   <filename class="headerfile">gi_dispa.h</filename>, they are not defined in
1163  *   <filename>gi_dispa.c</filename>. The dispatch layer merely coordinates
1164  *   them. The program defines the callback functions; the library calls them.
1165  * </para></note>
1166  */
1167
1168 /** 
1169  * SECTION:blorb-program
1170  * @short_description: How to use the Blorb layer in your program
1171  * @include: libchimara/glk.h, libchimara/gi_blorb.h
1172  *
1173  * If you wish your program to load its resources from a Blorb file, you need to
1174  * find and open that file in your startup code. (See <link 
1175  * linkend="chimara-Startup-Options">Startup Options</link>.) Each platform will
1176  * have appropriate functions available for finding startup data. Be sure to
1177  * open the file in binary mode, not text mode. Once you have opened the file as
1178  * a Glk stream, pass it to giblorb_set_resource_map().
1179  *
1180  * If you do not call giblorb_set_resource_map() in your startup code, or if it
1181  * fails, the library is left to its own devices for finding resources. Some
1182  * libraries may try to load resources from individual files &mdash; 
1183  * <filename>PIC1</filename>, <filename>PIC2</filename>, 
1184  * <filename>PIC3</filename>, and so on. (See the Blorb specification for more 
1185  * on this approach.) Other libraries will not have any other loading mechanism
1186  * at all; no resources will be available. 
1187  */
1188
1189 /**
1190  * SECTION:blorb-layer
1191  * @short_description: The platform-independent functions in the Blorb layer
1192  * @include: libchimara/glk.h, libchimara/gi_blorb.h
1193  *
1194  * These are the functions which are implemented in 
1195  * <filename>gi_blorb.c</filename>. They will be compiled into the library, but
1196  * they are the same on every platform. In general, only the library needs to
1197  * call these functions. The Glk program should allow the library to do all the
1198  * resource handling.
1199  */ 
1200  
1201 /** 
1202  * SECTION:blorb-errors
1203  * @short_description: Error codes returned by the Blorb layer functions
1204  * @include: libchimara/glk.h, libchimara/gi_blorb.h
1205  *
1206  * All Blorb layer functions, including giblorb_set_resource_map(), return the
1207  * following error codes.
1208  */
1209
1210 /**
1211  * SECTION:glkext-startup
1212  * @short_description: Parsing startup options
1213  * @include: libchimara/glk.h, libchimara/glkstart.h
1214  *
1215  * This section describes an extension to Glk for parsing command-line startup
1216  * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and
1217  * GlkTerm. 
1218  *
1219  * When you compile a Glk program, you may define a function called 
1220  * <function>glkunix_startup_code&lpar;&rpar;</function>, and an array 
1221  * <code>glkunix_arguments[]</code>. These set up various Unix-specific options
1222  * used by the Glk library. There is a sample 
1223  * <quote><filename>glkstart.c</filename></quote> file included in this package;
1224  * you should modify it to your needs.
1225  * 
1226  * |[ extern glkunix_argumentlist_t glkunix_arguments[]; ]|
1227  *  
1228  * The <code>glkunix_arguments[]</code> array is a list of command-line 
1229  * arguments that your program can accept. The library will sort these out of 
1230  * the command line and pass them on to your code.
1231  */
1232
1233 /**
1234  * SECTION:glkext-unix
1235  * @short_description: Unix-specific functions
1236  * @include: libchimara/glk.h, libchimara/glkstart.h
1237  *
1238  * This section describes an extension to Glk for various Unix functions. It was
1239  * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm.
1240  *
1241  * You can put other startup code in glkunix_startup_code(). This should
1242  * generally be limited to finding and opening data files. There are a few Unix
1243  * Glk library functions which are convenient for this purpose.
1244  */
1245
1246 /**
1247  * SECTION:glkext-garglk
1248  * @short_description: Gargoyle extensions to Glk
1249  * @include: libchimara/glk.h, libchimara/garglk.h
1250  *
1251  * This section describes various extensions to Glk that were written for the
1252  * popular interpreter <ulink 
1253  * url="http://www.ccxvii.net/gargoyle/">Gargoyle</ulink> by Tor Andersson (now 
1254  * maintained by Ben Cressey).
1255  *
1256  * These functions mostly serve to close the gap between Glk's input/output
1257  * capabilities and what some interpreters expect. For example, 
1258  * garglk_set_zcolors() displays the colors defined in the Z-machine standard,
1259  * and garglk_set_story_name() can be used to give the host program a hint
1260  * about what to display in the title bar of its window.
1261  */ 
1262  
1263 /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/
1264
1265 /**
1266  * glui32:
1267  *
1268  * A 32-bit unsigned integer type, used wherever possible in Glk.
1269  */
1270  
1271 /**
1272  * glsi32:
1273  *
1274  * A 32-bit signed integer type, rarely used.
1275  */
1276
1277 /**
1278  * GLK_MODULE_UNICODE:
1279  *
1280  * If this preprocessor symbol is defined, so are all the Unicode functions and
1281  * constants (see %gestalt_Unicode). If not, not.
1282  */
1283
1284 /**
1285  * GLK_MODULE_IMAGE:
1286  *
1287  * If you are writing a C program, there is an additional complication. A
1288  * library which does not support graphics may not implement the graphics
1289  * functions at all. Even if you put gestalt tests around your graphics calls,
1290  * you may get link-time errors. If the <filename
1291  * class="headerfile">glk.h</filename> file is so old that it does not declare
1292  * the graphics functions and constants, you may even get compile-time errors.
1293  *
1294  * To avoid this, you can perform a preprocessor test for the existence of
1295  * %GLK_MODULE_IMAGE. If this is defined, so are all the functions and constants
1296  * described in this section. If not, not.
1297  *
1298  * <note><para>
1299  *   To be extremely specific, there are two ways this can happen. If the 
1300  *   <filename class="headerfile">glk.h</filename> file that comes with the
1301  *   library is too old to have the graphics declarations in it, it will of
1302  *   course lack %GLK_MODULE_IMAGE as well. If the <filename 
1303  *   class="headerfile">glk.h</filename> file is recent, but the library is old,
1304  *   the definition of %GLK_MODULE_IMAGE should be removed from <filename 
1305  *   class="headerfile">glk.h</filename>, to avoid link errors. This is not a
1306  *   great solution. A better one is for the library to implement the graphics
1307  *   functions as stubs that do nothing (or cause run-time errors). Since no
1308  *   program will call the stubs without testing %gestalt_Graphics, this is
1309  *   sufficient.
1310  * </para></note>
1311  */
1312
1313 /**
1314  * GLK_MODULE_SOUND:
1315  *
1316  * If you are writing a C program, there is an additional complication. A 
1317  * library which does not support sound may not implement the sound functions at
1318  * all. Even if you put gestalt tests around your sound calls, you may get 
1319  * link-time errors. If the <filename class="headerfile">glk.h</filename> file 
1320  * is so old that it does not declare the sound functions and constants, you may
1321  * even get compile-time errors.
1322  * 
1323  * To avoid this, you can perform a preprocessor test for the existence of
1324  * %GLK_MODULE_SOUND. If this is defined, so are all the functions and constants
1325  * described in this section. If not, not.
1326  */ 
1327  
1328 /**
1329  * GLK_MODULE_HYPERLINKS:
1330  * 
1331  * If you are writing a C program, you can perform a preprocessor test for the
1332  * existence of %GLK_MODULE_HYPERLINKS. If this is defined, so are all the
1333  * functions and constants described in this section. If not, not.
1334  */
1335
1336 /**
1337  * winid_t:
1338  *
1339  * Opaque structure representing a Glk window. It has no user-accessible 
1340  * members.
1341  */
1342  
1343 /**
1344  * strid_t:
1345  *
1346  * Opaque structure representing an input or output stream. It has no
1347  * user-accessible members.
1348  */
1349  
1350 /**
1351  * frefid_t:
1352  * 
1353  * Opaque structure representing a file reference. It has no user-accessible
1354  * members.
1355  */
1356
1357 /**
1358  * schanid_t:
1359  * 
1360  * Opaque structure representing a sound channel. It has no user-accessible
1361  * members.
1362  */
1363   
1364 /**
1365  * gestalt_Version:
1366  *
1367  * For an example of the gestalt mechanism, consider the selector
1368  * %gestalt_Version. If you do
1369  * |[
1370  * glui32 res;
1371  * res = glk_gestalt(gestalt_Version, 0);
1372  * ]|
1373  * <code>res</code> will be set to a 32-bit number which encodes the version of
1374  * the Glk spec which the library implements. The upper 16 bits stores the major
1375  * version number; the next 8 bits stores the minor version number; the low 8 
1376  * bits stores an even more minor version number, if any.
1377  *
1378  * <note><para>
1379  *   So the version number 78.2.11 would be encoded as 0x004E020B.
1380  * </para></note>
1381  *
1382  * The current Glk specification version is 0.7.0, so this selector will return
1383  * 0x00000700.
1384  *
1385  * |[
1386  * glui32 res;
1387  * res = glk_gestalt_ext(gestalt_Version, 0, NULL, 0);
1388  * ]|
1389  * does exactly the same thing. Note that, in either case, the second argument 
1390  * is not used; so you should always pass 0 to avoid future surprises.
1391  */
1392
1393 /**
1394  * gestalt_CharInput:
1395  *
1396  * If you set <code>ch</code> to a character code, or a special code (from
1397  * 0xFFFFFFFF down), and call
1398  * |[
1399  * glui32 res;
1400  * res = glk_gestalt(gestalt_CharInput, ch);
1401  * ]|
1402  * then <code>res</code> will be %TRUE (1) if that character can be typed by
1403  * the player in character input, and %FALSE (0) if not. See <link
1404  * linkend="chimara-Character-Input">Character Input</link>.
1405  */
1406
1407 /**
1408  * gestalt_LineInput:
1409  *
1410  * If you set <code>ch</code> to a character code, and call
1411  * |[
1412  * glui32 res;
1413  * res = glk_gestalt(gestalt_LineInput, ch);
1414  * ]|
1415  * then <code>res</code> will be %TRUE (1) if that character can be typed by the
1416  * player in line input, and %FALSE (0) if not. Note that if <code>ch</code> is 
1417  * a nonprintable Latin-1 character (0 to 31, 127 to 159), then this is 
1418  * guaranteed to return %FALSE. See <link linkend="chimara-Line-Input">Line
1419  * Input</link>.
1420  */
1421
1422 /**
1423  * gestalt_CharOutput:
1424  *
1425  * If you set <code>ch</code> to a character code (Latin-1 or higher), and call
1426  * |[
1427  * glui32 res, len;
1428  * res = glk_gestalt_ext(gestalt_CharOutput, ch, &amp;len, 1);
1429  * ]|
1430  * then <code>res</code> will be one of %gestalt_CharOutput_CannotPrint,
1431  * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see 
1432  * below.)
1433  * 
1434  * In all cases, <code>len</code> (the #glui32 value pointed at by the third
1435  * argument) will be the number of actual glyphs which will be used to represent
1436  * the character. In the case of %gestalt_CharOutput_ExactPrint, this will 
1437  * always be 1; for %gestalt_CharOutput_CannotPrint, it may be 0 (nothing 
1438  * printed) or higher; for %gestalt_CharOutput_ApproxPrint, it may be 1 or 
1439  * higher. This information may be useful when printing text in a fixed-width 
1440  * font.
1441  *
1442  * <note><para>
1443  *   As described in <link linkend="chimara-Other-API-Conventions">Other API
1444  *   Conventions</link>, you may skip this information by passing %NULL as the
1445  *   third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead.
1446  * </para></note>
1447  *
1448  * This selector will always return %gestalt_CharOutput_CannotPrint if 
1449  * <code>ch</code> is an unprintable eight-bit character (0 to 9, 11 to 31, 127 
1450  * to 159.)
1451  *
1452  * <note><para>
1453  *   Make sure you do not get confused by signed byte values. If you set a
1454  *   <quote><type>char</type></quote> variable <code>ch</code> to 0xFE, the 
1455  *   small-thorn character (&thorn;), and then call
1456  *   |[ res = glk_gestalt(gestalt_CharOutput, ch); ]|
1457  *   then (by the definition of C/C++) <code>ch</code> will be sign-extended to
1458  *   0xFFFFFFFE, which is not a legitimate character, even in Unicode. You 
1459  *   should write
1460  *   |[ res = glk_gestalt(gestalt_CharOutput, (unsigned char)ch); ]|
1461  *   instead.
1462  * </para></note>
1463  * <note><para>
1464  *   Unicode includes the concept of non-spacing or combining characters, which 
1465  *   do not represent glyphs; and double-width characters, whose glyphs take up
1466  *   two spaces in a fixed-width font. Future versions of this spec may 
1467  *   recognize these concepts by returning a <code>len</code> of 0 or 2 when
1468  *   %gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to 
1469  *   a policy of <quote>simple stuff first</quote>.
1470  * </para></note>
1471  */
1472  
1473 /**
1474  * gestalt_CharOutput_CannotPrint:
1475  *
1476  * When the %gestalt_CharOutput selector returns this for a character, the
1477  * character cannot be meaningfully printed. If you try, the player may see
1478  * nothing, or may see a placeholder.
1479  */
1480
1481 /**
1482  * gestalt_CharOutput_ApproxPrint:
1483  *
1484  * When the %gestalt_CharOutput selector returns this for a character, the 
1485  * library will print some approximation of the character. It will be more or 
1486  * less right, but it may not be precise, and it may not be distinguishable from
1487  * other, similar characters. (Examples: 
1488  * <quote><computeroutput>ae</computeroutput></quote> for the one-character
1489  * <quote>&aelig;</quote> ligature, 
1490  * <quote><computeroutput>e</computeroutput></quote> for 
1491  * <quote>&egrave;</quote>, <quote><computeroutput>|</computeroutput></quote> 
1492  * for a broken vertical bar (&brvbar;).)
1493  */
1494  
1495 /**
1496  * gestalt_CharOutput_ExactPrint:
1497  *
1498  * When the %gestalt_CharOutput selector returns this for a character, the
1499  * character will be printed exactly as defined.
1500  */
1501
1502 /**
1503  * gestalt_MouseInput:
1504  *
1505  * You can test whether mouse input is supported with the %gestalt_MouseInput 
1506  * selector.
1507  * |[ res = glk_gestalt(gestalt_MouseInput, windowtype); ]|
1508  * This will return %TRUE (1) if windows of the given type support mouse input.
1509  * If this returns %FALSE (0), it is still legal to call
1510  * glk_request_mouse_event(), but it will have no effect, and you will never get
1511  * mouse events.
1512  */ 
1513  
1514 /**
1515  * gestalt_Timer:
1516  *
1517  * You can test whether the library supports timer events:
1518  * |[ res = glk_gestalt(gestalt_Timer, 0); ]|
1519  * This returns 1 if timer events are supported, and 0 if they are not.
1520  */
1521
1522 /**
1523  * gestalt_Graphics:
1524  * 
1525  * Before calling Glk graphics functions, you should use the following gestalt
1526  * selector:
1527  * |[
1528  * glui32 res;
1529  * res = glk_gestalt(gestalt_Graphics, 0);
1530  * ]|
1531  * This returns 1 if the overall suite of graphics functions is available. This
1532  * includes glk_image_draw(), glk_image_draw_scaled(), glk_image_get_info(),
1533  * glk_window_erase_rect(), glk_window_fill_rect(),
1534  * glk_window_set_background_color(), and glk_window_flow_break(). It also
1535  * includes the capability to create graphics windows.
1536  * 
1537  * If this selector returns 0, you should not try to call these functions. They
1538  * may have no effect, or they may cause a run-time error. If you try to create
1539  * a graphics window, you will get %NULL. 
1540  */
1541
1542 /**
1543  * gestalt_DrawImage:
1544  * 
1545  * This selector returns 1 if images can be drawn in windows of the given type. 
1546  * If it returns 0, glk_image_draw() will fail and return %FALSE. You should 
1547  * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries 
1548  * may implement both, neither, or only one.  
1549  */
1550
1551 /**
1552  * gestalt_Sound:
1553  *
1554  * You can test whether the library supports sound: 
1555  * |[
1556  * glui32 res;
1557  * res = glk_gestalt(gestalt_Sound, 0);
1558  * ]|
1559  * This returns 1 if the overall suite of sound functions is available. This 
1560  * includes glk_schannel_create(), glk_schannel_destroy(), 
1561  * glk_schannel_iterate(), glk_schannel_get_rock(), glk_schannel_play(),
1562  * glk_schannel_play_ext(), glk_schannel_stop(), glk_schannel_set_volume(), and
1563  * glk_sound_load_hint().
1564  *
1565  * If this selector returns 0, you should not try to call these functions. They 
1566  * may have no effect, or they may cause a run-time error. 
1567  */
1568
1569 /**
1570  * gestalt_SoundVolume:
1571  *
1572  * You can test whether the library supports setting the volume of sound 
1573  * channels: 
1574  * |[
1575  * glui32 res;
1576  * res = glk_gestalt(gestalt_SoundVolume, 0);
1577  * ]|
1578  * This selector returns 1 if the glk_schannel_set_volume() function works. If 
1579  * it returns zero, glk_schannel_set_volume() has no effect.     
1580  */
1581
1582 /**
1583  * gestalt_SoundNotify:
1584  *
1585  * You can test whether the library supports sound notification events:
1586  * |[
1587  * glui32 res;
1588  * res = glk_gestalt(gestalt_SoundNotify, 0);
1589  * ]| 
1590  * This selector returns 1 if the library supports sound notification events. If
1591  * it returns zero, you will never get such events. 
1592  */
1593
1594 /**
1595  * gestalt_Hyperlinks:
1596  *
1597  * You can test whether the library supports hyperlinks:
1598  * |[ 
1599  * glui32 res;
1600  * res = glk_gestalt(gestalt_Hyperlinks, 0); 
1601  * ]|
1602  * This returns 1 if the overall suite of hyperlinks functions is available.
1603  * This includes glk_set_hyperlink(), glk_set_hyperlink_stream(),
1604  * glk_request_hyperlink_event(), glk_cancel_hyperlink_event().
1605  *
1606  * If this selector returns 0, you should not try to call these functions. They
1607  * may have no effect, or they may cause a run-time error.
1608  */
1609
1610 /**
1611  * gestalt_HyperlinkInput:
1612  *
1613  * You can test whether hyperlinks are supported with the 
1614  * %gestalt_HyperlinkInput selector:
1615  * |[ res = glk_gestalt(gestalt_HyperlinkInput, windowtype); ]|
1616  * This will return %TRUE (1) if windows of the given type support hyperlinks.
1617  * If this returns %FALSE (0), it is still legal to call glk_set_hyperlink() and
1618  * glk_request_hyperlink_event(), but they will have no effect, and you will
1619  * never get hyperlink events.
1620  */
1621
1622 /** 
1623  * gestalt_SoundMusic:
1624  *
1625  * You can test whether music resources are supported:
1626  * |[ res = glk_gestalt(gestalt_SoundMusic, 0); ]|
1627  * This returns 1 if the library is capable of playing music sound resources. If 
1628  * it returns 0, only sampled sounds can be played.
1629  * <note><para>
1630  *   <quote>Music sound resources</quote> means MOD songs &mdash; the only music
1631  *   format that Blorb currently supports. The presence of this selector is, of 
1632  *   course, an ugly hack. It is a concession to the current state of the Glk 
1633  *   libraries, some of which can handle AIFF but not MOD sounds.
1634  * </para></note>
1635  */ 
1636   
1637 /**
1638  * gestalt_GraphicsTransparency:
1639  *
1640  * This returns 1 if images with alpha channels can actually be drawn with the
1641  * appropriate degree of transparency. If it returns 0, the alpha channel is
1642  * ignored; fully transparent areas will be drawn in an implementation-defined
1643  * color.
1644  * <note><para>
1645  *   The JPEG format does not support transparency or alpha channels; the PNG 
1646  *   format does.
1647  * </para></note>
1648  */
1649
1650 /**
1651  * gestalt_Unicode:
1652  *
1653  * The basic text functions will be available in every Glk library. The Unicode
1654  * functions may or may not be available. Before calling them, you should use
1655  * the following gestalt selector:
1656  * |[
1657  * glui32 res;
1658  * res = glk_gestalt(gestalt_Unicode, 0);
1659  * ]|
1660  * 
1661  * This returns 1 if the Unicode functions are available. If it returns 0, you
1662  * should not try to call them. They may print nothing, print gibberish, or
1663  * cause a run-time error. The Unicode functions include
1664  * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),  
1665  * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
1666  * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
1667  * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
1668  * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
1669  * glk_request_char_event_uni(), glk_request_line_event_uni(),
1670  * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
1671  * 
1672  * If you are writing a C program, there is an additional complication. A
1673  * library which does not support Unicode may not implement the Unicode
1674  * functions at all. Even if you put gestalt tests around your Unicode calls,
1675  * you may get link-time errors. If the 
1676  * <filename class="headerfile">glk.h</filename> file is so old that it does not
1677  * declare the Unicode functions and constants, you may even get compile-time
1678  * errors.
1679  * 
1680  * To avoid this, you can perform a preprocessor test for the existence of
1681  * #GLK_MODULE_UNICODE. 
1682  */
1683  
1684 /**
1685  * evtype_None:
1686  *
1687  * No event. This is a placeholder, and glk_select() never returns it.
1688  */
1689
1690 /**
1691  * evtype_Timer:
1692  *
1693  * An event that repeats at fixed intervals. See <link 
1694  * linkend="chimara-Timer-Events">Timer Events</link>.
1695  */
1696  
1697 /**
1698  * evtype_CharInput:
1699  *
1700  * A keystroke event in a window. See <link 
1701  * linkend="chimara-Character-Input-Events">Character Input Events</link>.
1702  *
1703  * If a window has a pending request for character input, and the player hits a
1704  * key in that window, glk_select() will return an event whose type is
1705  * %evtype_CharInput. Once this happens, the request is complete; it is no 
1706  * longer pending. You must call glk_request_char_event() or
1707  * glk_request_char_event_uni() if you want another character from that window.
1708  * 
1709  * In the event structure, @win tells what window the event came from. @val1 
1710  * tells what character was entered; this will be a character code, or a special
1711  * keycode. (See <link linkend="chimara-Character-Input">Character 
1712  * Input</link>.) If you called glk_request_char_event(), @val1 will be in 
1713  * 0..255, or else a special keycode. In any case, @val2 will be 0.
1714  */
1715
1716 /**
1717  * evtype_LineInput:
1718  *
1719  * A full line of input completed in a window. See <link 
1720  * linkend="chimara-Line-Input-Events">Line Input Events</link>.
1721  *
1722  * If a window has a pending request for line input, and the player hits
1723  * <keycap>enter</keycap> in that window (or whatever action is appropriate to
1724  * enter his input), glk_select() will return an event whose type is
1725  * %evtype_LineInput. Once this happens, the request is complete; it is no 
1726  * longer pending. You must call glk_request_line_event() if you want another 
1727  * line of text from that window.
1728  * 
1729  * In the event structure, @win tells what window the event came from. @val1 
1730  * tells how many characters were entered. @val2 will be 0. The characters
1731  * themselves are stored in the buffer specified in the original
1732  * glk_request_line_event() or glk_request_line_event_uni() call. 
1733  *
1734  * <note><para>There is no null terminator stored in the buffer.</para></note>
1735  * 
1736  * It is illegal to print anything to a window which has line input pending. 
1737  *
1738  * <note><para>
1739  *   This is because the window may be displaying and editing the player's 
1740  *   input, and printing anything would make life unnecessarily complicated for
1741  *   the library.
1742  * </para></note>
1743  */
1744
1745 /**
1746  * evtype_MouseInput:
1747  *
1748  * A mouse click in a window. See <link 
1749  * linkend="chimara-Mouse-Input-Events">Mouse Input Events</link>.
1750  */
1751  
1752 /**
1753  * evtype_Arrange:
1754  *
1755  * An event signalling that the sizes of some windows have changed. 
1756  * 
1757  * Some platforms allow the player to resize the Glk window during play. This 
1758  * will naturally change the sizes of your windows. If this occurs, then
1759  * immediately after all the rearrangement, glk_select() will return an event
1760  * whose type is %evtype_Arrange. You can use this notification to redisplay the
1761  * contents of a graphics or text grid window whose size has changed.
1762  *
1763  * <note><para>
1764  *   The display of a text buffer window is entirely up to the library, so you
1765  *   don't need to worry about those.
1766  * </para></note>
1767  * 
1768  * In the event structure, @win will be %NULL if all windows are affected. If 
1769  * only some windows are affected, @win will refer to a window which contains 
1770  * all the affected windows. @val1 and @val2 will be 0.
1771  *
1772  * <note><para>
1773  *   You can always play it safe, ignore @win, and redraw every graphics and 
1774  *   text grid window.
1775  * </para></note>
1776  *
1777  * An arrangement event is guaranteed to occur whenever the player causes any
1778  * window to change size, as measured by its own metric. 
1779  *
1780  * <note><para>
1781  *   Size changes caused by you &mdash; for example, if you open, close, or 
1782  *   resize a window &mdash; do not trigger arrangement events. You must be 
1783  *   aware of the effects of your window management, and redraw the windows that
1784  *   you affect.
1785  * </para></note>
1786  * 
1787  * <note><para>
1788  *   It is possible that several different player actions can cause windows to
1789  *   change size. For example, if the player changes the screen resolution, an
1790  *   arrangement event might be triggered. This might also happen if the player
1791  *   changes his display font to a different size; the windows would then be
1792  *   different <quote>sizes</quote> in the metric of rows and columns, which is
1793  *   the important metric and the only one you have access to.
1794  * </para></note>
1795  * 
1796  * Arrangement events, like timer events, can be returned by glk_select_poll().
1797  * But this will not occur on all platforms. You must be ready to receive an
1798  * arrangement event when you call glk_select_poll(), but it is possible that it
1799  * will not arrive until the next time you call glk_select(). 
1800  *
1801  * <note><para>
1802  *   This is because on some platforms, window resizing is handled as part of
1803  *   player input; on others, it can be triggered by an external process such as 
1804  *   a window manager.
1805  * </para></note>
1806  */
1807
1808 /**
1809  * evtype_Redraw:
1810  *
1811  * An event signalling that graphics windows must be redrawn.
1812  *
1813  * On platforms that support graphics, it is possible that the contents of a
1814  * graphics window will be lost, and have to be redrawn from scratch. If this
1815  * occurs, then glk_select() will return an event whose type is %evtype_Redraw.
1816  *
1817  * In the event structure, @win will be %NULL if all windows are affected. If 
1818  * only some windows are affected, @win will refer to a window which contains 
1819  * all the affected windows. @val1 and @val2 will be 0.
1820  *
1821  * <note><para>
1822  *   You can always play it safe, ignore @win, and redraw every graphics window.
1823  * </para></note>
1824  *
1825  * Affected windows are already cleared to their background color when you 
1826  * receive the redraw event.
1827  * 
1828  * Redraw events can be returned by glk_select_poll(). But, like arrangement
1829  * events, this is platform-dependent. See %evtype_Arrange.
1830  *
1831  * For more about redraw events and how they affect graphics windows, see <link
1832  * linkend="wintype-Graphics">Graphics Windows</link>.
1833  */
1834
1835 /**
1836  * evtype_SoundNotify:
1837  *
1838  * On platforms that support sound, you can request to receive an 
1839  * %evtype_SoundNotify event when a sound finishes playing. See <link
1840  * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
1841  */
1842  
1843 /**
1844  * evtype_Hyperlink:
1845  * 
1846  * On platforms that support hyperlinks, you can request to receive an
1847  * %evtype_Hyperlink event when the player selects a link. See <link
1848  * linkend="chimara-Accepting-Hyperlink-Events">Accepting Hyperlink 
1849  * Events</link>.
1850  */
1851
1852 /**
1853  * event_t:
1854  * @type: the event type
1855  * @win: the window that spawned the event, or %NULL
1856  * @val1: information, the meaning of which depends on the type of event
1857  * @val2: more information, the meaning of which depends on the type of event
1858  *
1859  * The event structure is self-explanatory. @type is the event type. The window
1860  * that spawned the event, if relevant, is in @win. The remaining fields contain
1861  * more information specific to the event.
1862  *
1863  * The event types are described below. Note that %evtype_None is zero, and the
1864  * other values are positive. Negative event types (0x80000000 to 0xFFFFFFFF) 
1865  * are reserved for implementation-defined events. 
1866  */
1867
1868 /**
1869  * keycode_Unknown:
1870  *
1871  * Represents any key that has no Latin-1 or special code.
1872  */
1873
1874 /**
1875  * keycode_Left:
1876  *
1877  * Represents the <keycap function="left">left arrow</keycap> key.
1878  */
1879  
1880 /**
1881  * keycode_Right:
1882  *
1883  * Represents the <keycap function="right">right arrow</keycap> key.
1884  */
1885  
1886 /**
1887  * keycode_Up:
1888  *
1889  * Represents the <keycap function="up">up arrow</keycap> key.
1890  */
1891  
1892 /**
1893  * keycode_Down:
1894  *
1895  * Represents the <keycap function="down">down arrow</keycap> key.
1896  */
1897  
1898 /**
1899  * keycode_Return:
1900  *
1901  * Represents the <keycap function="enter">return</keycap> or <keycap 
1902  * function="enter">enter</keycap> keys.
1903  */
1904
1905 /**
1906  * keycode_Delete:
1907  *
1908  * Represents the <keycap function="delete">delete</keycap> or <keycap
1909  * function="backspace">backspace</keycap> keys.
1910  */
1911  
1912 /**
1913  * keycode_Escape:
1914  *
1915  * Represents the <keycap function="escape">escape</keycap> key.
1916  */
1917  
1918 /**
1919  * keycode_Tab:
1920  *
1921  * Represents the <keycap function="tab">tab</keycap> key.
1922  */
1923
1924 /**
1925  * keycode_PageUp:
1926  *
1927  * Represents the <keycap function="pageup">page up</keycap> key.
1928  */
1929
1930 /**
1931  * keycode_PageDown:
1932  *
1933  * Represents the <keycap function="pagedown">page down</keycap> key.
1934  */
1935
1936 /**
1937  * keycode_Home:
1938  *
1939  * Represents the <keycap function="home">home</keycap> key.
1940  */
1941  
1942 /**
1943  * keycode_End:
1944  *
1945  * Represents the <keycap function="end">end</keycap> key.
1946  */
1947
1948 /**
1949  * keycode_Func1:
1950  *
1951  * Represents the <keycap>F1</keycap> key.
1952  */
1953  
1954 /**
1955  * keycode_Func2:
1956  *
1957  * Represents the <keycap>F2</keycap> key.
1958  */
1959
1960 /**
1961  * keycode_Func3:
1962  *
1963  * Represents the <keycap>F3</keycap> key.
1964  */
1965
1966 /**
1967  * keycode_Func4:
1968  *
1969  * Represents the <keycap>F4</keycap> key.
1970  */
1971
1972 /**
1973  * keycode_Func5:
1974  *
1975  * Represents the <keycap>F5</keycap> key.
1976  */
1977  
1978 /**
1979  * keycode_Func6:
1980  *
1981  * Represents the <keycap>F6</keycap> key.
1982  */
1983
1984 /**
1985  * keycode_Func7:
1986  *
1987  * Represents the <keycap>F7</keycap> key.
1988  */
1989
1990 /**
1991  * keycode_Func8:
1992  *
1993  * Represents the <keycap>F8</keycap> key.
1994  */
1995
1996 /**
1997  * keycode_Func9:
1998  *
1999  * Represents the <keycap>F9</keycap> key.
2000  */
2001
2002 /**
2003  * keycode_Func10:
2004  *
2005  * Represents the <keycap>F10</keycap> key.
2006  */
2007
2008 /**
2009  * keycode_Func11:
2010  *
2011  * Represents the <keycap>F11</keycap> key.
2012  */
2013
2014 /**
2015  * keycode_Func12:
2016  *
2017  * Represents the <keycap>F12</keycap> key.
2018  */
2019
2020 /**
2021  * style_Normal: 
2022  *
2023  * The style of normal or body text. A new window or stream always starts with
2024  * %style_Normal as the current style.
2025  */
2026
2027 /**
2028  * style_Emphasized: 
2029  *
2030  * Text which is emphasized.
2031  */
2032
2033 /**
2034  * style_Preformatted: 
2035  *
2036  * Text which has a particular arrangement of characters.
2037  * <note><para>
2038  *  This style, unlike the others, does have a standard appearance; it will 
2039  *  always be a fixed-width font. This is a concession to practicality. Games 
2040  *  often want to display maps or diagrams using character graphics, and this is
2041  *  the style for that.
2042  * </para></note>
2043  */
2044  
2045 /**
2046  * style_Header: 
2047  * 
2048  * Text which introduces a large section. This is suitable for the title of an 
2049  * entire game, or a major division such as a chapter.
2050  */
2051
2052 /**
2053  * style_Subheader: 
2054  * 
2055  * Text which introduces a smaller section within a large section. 
2056  * <note><para>
2057  *  In a Colossal-Cave-style game, this is suitable for the name of a room (when
2058  *  the player looks around.)
2059  * </para></note>
2060  */
2061
2062 /**
2063  * style_Alert: 
2064  *
2065  * Text which warns of a dangerous condition, or one which the player should pay
2066  * attention to.
2067  */
2068
2069 /**
2070  * style_Note: 
2071  *
2072  * Text which notifies of an interesting condition.
2073  * <note><para>
2074  *  This is suitable for noting that the player's score has changed.
2075  * </para></note>
2076  */
2077
2078 /**
2079  * style_BlockQuote: 
2080  *
2081  * Text which forms a quotation or otherwise abstracted text.
2082  */
2083
2084 /**
2085  * style_Input: 
2086  *
2087  * Text which the player has entered. You should generally not use this style at
2088  * all; the library uses it for text which is typed during a line-input request.
2089  * One case when it is appropriate for you to use %style_Input is when you are 
2090  * simulating player input by reading commands from a text file.
2091  */
2092
2093 /**
2094  * style_User1: 
2095  * 
2096  * This style has no particular semantic meaning. You may define a meaning 
2097  * relevant to your own work, and use it as you see fit.
2098  */
2099
2100 /**
2101  * style_User2: 
2102  *
2103  * Another style available for your use. 
2104  */
2105
2106 /**
2107  * stream_result_t:
2108  * @readcount: Number of characters read from the stream.
2109  * @writecount: Number of characters printed to the stream, including ones that
2110  * were thrown away.
2111  *
2112  * If you are interested in the character counts of a stream (see <link
2113  * linkend="chimara-Streams">Streams</link>), then you can pass a pointer to
2114  * #stream_result_t as an argument of glk_stream_close() or glk_window_close().
2115  * The structure will be filled with the stream's final character counts.
2116  */
2117
2118 /**
2119  * wintype_AllTypes:
2120  *
2121  * A constant representing all window types, which may be used as the @wintype
2122  * argument in glk_stylehint_set().
2123  */
2124
2125 /** 
2126  * wintype_Pair:
2127  * 
2128  * A pair window is completely filled by the two windows it contains. It
2129  * supports no input and no output, and it has no size.
2130  * 
2131  * You cannot directly create a pair window; one is automatically created
2132  * every time you split a window with glk_window_open(). Pair windows are
2133  * always created with a rock value of 0.
2134  * 
2135  * You can close a pair window with glk_window_close(); this also closes every
2136  * window contained within the pair window.
2137  * 
2138  * It is legal to split a pair window when you call glk_window_open().
2139  */
2140  
2141 /**
2142  * wintype_Blank:
2143  * 
2144  * A blank window is always blank. It supports no input and no output. (You
2145  * can call glk_window_get_stream() on it, as you can with any window, but
2146  * printing to the resulting stream has no effect.) A blank window has no
2147  * size; glk_window_get_size() will return (0,0), and it is illegal to set a
2148  * window split with a fixed size in the measurement system of a blank window.
2149  * 
2150  * <note><para>
2151  *   A blank window is not the same as there being no windows. When Glk starts
2152  *   up, there are no windows at all, not even a window of the blank type.
2153  * </para></note>
2154  */
2155  
2156 /**
2157  * wintype_TextBuffer: 
2158  *
2159  * A text buffer window contains a linear stream of text. It supports output;
2160  * when you print to it, the new text is added to the end. There is no way for
2161  * you to affect text which has already been printed. There are no guarantees
2162  * about how much text the window keeps; old text may be stored forever, so
2163  * that the user can scroll back to it, or it may be thrown away as soon as it
2164  * scrolls out of the window. 
2165  * 
2166  * <note><para>
2167  *   Therefore, there may or may not be a player-controllable scroll bar or
2168  *   other scrolling widget.
2169  * </para></note>
2170  * 
2171  * The display of the text in a text buffer is up to the library. Lines will
2172  * probably not be broken in the middles of words &mdash; but if they are, the
2173  * library is not doing anything illegal, only ugly. Text selection and copying
2174  * to a clipboard, if available, are handled however is best on the player's
2175  * machine. Paragraphs (as defined by newline characters in the output) may be
2176  * indented. 
2177  * 
2178  * <note><para>
2179  *   You should not, in general, fake this by printing spaces before each
2180  *   paragraph of prose text. Let the library and player preferences handle
2181  *   that. Special cases (like indented lists) are of course up to you.
2182  * </para></note>
2183  * 
2184  * When a text buffer is cleared (with glk_window_clear()), the library will do
2185  * something appropriate; the details may vary. It may clear the window, with
2186  * later text appearing at the top &mdash; or the bottom. It may simply print
2187  * enough blank lines to scroll the current text out of the window. It may
2188  * display a distinctive page-break symbol or divider.
2189  * 
2190  * The size of a text buffer window is necessarily imprecise. Calling
2191  * glk_window_get_size() will return the number of rows and columns that would
2192  * be available <emphasis>if</emphasis> the window was filled with 
2193  * <quote>0</quote> (zero) characters in the <quote>normal</quote> font.
2194  * However, the window may use a non-fixed-width font, so that number of
2195  * characters in a line could vary. The window might even support 
2196  * variable-height text (say, if the player is using large text for emphasis);
2197  * that would make the number of lines in the window vary as well.
2198  * 
2199  * Similarly, when you set a fixed-size split in the measurement system of a
2200  * text buffer, you are setting a window which can handle a fixed number of rows
2201  * (or columns) of <quote>0</quote> characters. The number of rows (or
2202  * characters) that will actually be displayed depends on font variances.
2203  * 
2204  * A text buffer window supports both character and line input, but not mouse
2205  * input.
2206  * 
2207  * In character input, there will be some visible signal that the window is
2208  * waiting for a keystroke. (Typically, a cursor at the end of the text.) When
2209  * the player hits a key in that window, an event is generated, but the key is
2210  * <emphasis>not</emphasis> printed in the window.
2211  * 
2212  * In line input, again, there will be some visible signal. It is most common
2213  * for the player to compose input in the window itself, at the end of the text.
2214  * (This is how IF story input usually looks.) But it's not strictly required.
2215  * An alternative approach is the way MUD clients usually work: there is a
2216  * dedicated one-line input window, outside of Glk's window space, and the user
2217  * composes input there.
2218  * 
2219  * <note><para>
2220  *   If this approach is used, there will still be some way to handle input from
2221  *   two windows at once. It is the library's responsibility to make this
2222  *   available to the player. You only need request line input and  wait for the
2223  *   result.
2224  * </para></note>
2225  * 
2226  * When the player finishes his line of input, the library will display the
2227  * input text at the end of the buffer text (if it wasn't there already.) It
2228  * will be followed by a newline, so that the next text you print will start a
2229  * new line (paragraph) after the input.
2230  * 
2231  * If you call glk_cancel_line_event(), the same thing happens; whatever text
2232  * the user was composing is visible at the end of the buffer text, followed by
2233  * a newline.
2234  */
2235  
2236 /**
2237  * wintype_TextGrid: 
2238  * 
2239  * A text grid contains a rectangular array of characters, in a fixed-width
2240  * font. Its size is the number of columns and rows of the array.
2241  * 
2242  * A text grid window supports output. It maintains knowledge of an output
2243  * cursor position. When the window is opened, it is filled with blanks (space
2244  * characters), and the output cursor starts in the top left corner &mdash;
2245  * character (0,0). If the window is cleared with glk_window_clear(), the window
2246  * is filled with blanks again, and the cursor returns to the top left corner.
2247  * 
2248  * When you print, the characters of the output are laid into the array in
2249  * order, left to right and top to bottom. When the cursor reaches the end of a
2250  * line, it goes to the beginning of the next line. The library makes no attempt
2251  * to wrap lines at word breaks.
2252  * 
2253  * <note><para>
2254  *   Note that printing fancy characters may cause the cursor to advance more
2255  *   than one position per character. (For example, the <quote>&aelig;</quote>
2256  *   ligature may print as two characters.) See <link 
2257  *   linkend="chimara-Output">Output</link>, for how to test this situation.
2258  * </para></note>
2259  * 
2260  * You can set the cursor position with glk_window_move_cursor().
2261  * 
2262  * When a text grid window is resized smaller, the bottom or right area is
2263  * thrown away, but the remaining area stays unchanged. When it is resized
2264  * larger, the new bottom or right area is filled with blanks.
2265  * 
2266  * <note><para>
2267  *   You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
2268  *   text grid windows when you see them change size.
2269  * </para></note>
2270  * 
2271  * Text grid window support character and line input, as well as mouse input (if
2272  * a mouse is available.)
2273  * 
2274  * Mouse input returns the position of the character that was touched, from
2275  * (0,0) to 
2276  * <inlineequation>
2277  *   <alt>(width-1,height-1)</alt>
2278  *   <mathphrase>(width - 1, height - 1)</mathphrase>
2279  * </inlineequation>
2280  * .
2281  * 
2282  * Character input is as described in the previous section.
2283  * 
2284  * Line input is slightly different; it is guaranteed to take place in the
2285  * window, at the output cursor position. The player can compose input only to
2286  * the right edge of the window; therefore, the maximum input length is
2287  * <inlineequation>
2288  *   <alt>(windowwidth - 1 - cursorposition)</alt>
2289  *   <mathphrase>(windowwidth - 1 - cursorposition)</mathphrase>
2290  * </inlineequation>
2291  * . If the maxlen argument of glk_request_line_event() is smaller than this,
2292  * the library will not allow the input cursor to go more than maxlen characters
2293  * past its start point. 
2294  * 
2295  * <note><para>
2296  *   This allows you to enter text in a fixed-width field, without the player
2297  *   being able to overwrite other parts of the window.
2298  * </para></note>
2299  * 
2300  * When the player finishes his line of input, it will remain visible in the
2301  * window, and the output cursor will be positioned at the beginning of the 
2302  * <emphasis>next</emphasis> row. Again, if you glk_cancel_line_event(), the
2303  * same thing happens.
2304  */
2305  
2306 /**
2307  * wintype_Graphics: 
2308  * 
2309  * A graphics window contains a rectangular array of pixels. Its size is the
2310  * number of columns and rows of the array.
2311  * 
2312  * Each graphics window has a background color, which is initially white. You
2313  * can change this; see <link 
2314  * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics 
2315  * Windows</link>.
2316  * 
2317  * When a text grid window is resized smaller, the bottom or right area is
2318  * thrown away, but the remaining area stays unchanged. When it is resized
2319  * larger, the new bottom or right area is filled with the background color.
2320  * 
2321  * <note><para>
2322  *   You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
2323  *   graphics windows when you see them change size.
2324  * </para></note>
2325  * 
2326  * In some libraries, you can receive a graphics-redraw event (%evtype_Redraw)
2327  * at any time. This signifies that the window in question has been cleared to
2328  * its background color, and must be redrawn. If you create any graphics
2329  * windows, you <emphasis>must</emphasis> handle these events.
2330  * 
2331  * <note><para>
2332  *   Redraw events can be triggered when a Glk window is uncovered or made
2333  *   visible by the platform's window manager. On the other hand, some Glk
2334  *   libraries handle these problem automatically &mdash; for example, with a
2335  *   backing store &mdash; and do not send you redraw events. On the third hand,
2336  *   the backing store may be discarded if memory is low, or for other reasons
2337  *   &mdash; perhaps the screen's color depth has changed. So redraw events are
2338  *   always a possibility, even in clever libraries. This is why you must be
2339  *   prepared to handle them.
2340  * 
2341  *   However, you will not receive a redraw event when you create a graphics
2342  *   window. It is assumed that you will do the initial drawing of your own
2343  *   accord. You also do not get redraw events when a graphics window is
2344  *   enlarged. If you ordered the enlargement, you already know about it; if the
2345  *   player is responsible, you receive a window-arrangement event, which covers
2346  *   the situation.
2347  * </para></note>
2348  * 
2349  * For a description of the drawing functions that apply to graphics windows,
2350  * see <link linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
2351  * Windows</link>.
2352  * 
2353  * Graphics windows support no text input or output.
2354  * 
2355  * Not all libraries support graphics windows. You can test whether Glk graphics
2356  * are available using the gestalt system. In a C program, you can also test
2357  * whether the graphics functions are defined at compile-time. See <link 
2358  * linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics
2359  * Capabilities</link>. 
2360  *
2361  * <note><para>
2362  *   As with all windows, you should also test for %NULL when you create a
2363  *   graphics window.
2364  * </para></note>
2365  */
2366  
2367 /**
2368  * winmethod_Left:
2369  *
2370  * When calling glk_window_open() with this @method, the new window will be 
2371  * to the left of the old one which was split.
2372  */
2373
2374 /**
2375  * winmethod_Right:
2376  *
2377  * When calling glk_window_open() with this @method, the new window will be 
2378  * to the right of the old one which was split.
2379  */
2380
2381 /**
2382  * winmethod_Above:
2383  *
2384  * When calling glk_window_open() with this @method, the new window will be 
2385  * above the old one which was split.
2386  */
2387  
2388 /**
2389  * winmethod_Below:
2390  *
2391  * When calling glk_window_open() with this @method, the new window will be 
2392  * below the old one which was split.
2393  */
2394  
2395 /**
2396  * winmethod_Fixed:
2397  *
2398  * When calling glk_window_open() with this @method, the new window will be 
2399  * a fixed size. (See glk_window_open()).
2400  */
2401
2402 /**
2403  * winmethod_Proportional:
2404  *
2405  * When calling glk_window_open() with this @method, the new window will be 
2406  * a given proportion of the old window's size. (See glk_window_open()).
2407  */
2408  
2409 /** 
2410  * fileusage_Data: 
2411  *
2412  * Any other kind of file (preferences, statistics, arbitrary data.) 
2413  */
2414
2415 /**
2416  * fileusage_SavedGame: 
2417  * 
2418  * A file which stores game state.
2419  */
2420
2421 /**
2422  * fileusage_Transcript: 
2423  * 
2424  * A file which contains a stream of text from the game (often an echo stream
2425  * from a window.)
2426  */
2427  
2428 /** 
2429  * fileusage_InputRecord: 
2430  * 
2431  * A file which records player input.
2432  */
2433
2434 /** 
2435  * fileusage_TextMode: 
2436  *
2437  * The file contents will be transformed to a platform-native text file as they
2438  * are written out. Newlines may be converted to linefeeds or 
2439  * linefeed-plus-carriage-return combinations; Latin-1 characters may be
2440  * converted to native character codes. When reading a file in text mode, native
2441  * line breaks will be converted back to newline (0x0A) characters, and native
2442  * character codes may be converted to Latin-1. 
2443  *
2444  * <note><para>
2445  *   Line breaks will always be converted; other conversions are more
2446  *   questionable. If you write out a file in text mode, and then read it back
2447  *   in text mode, high-bit characters (128 to 255) may be transformed or lost.
2448  * </para></note>
2449  * <note><title>Chimara</title>
2450  * <para>
2451  * Text mode files in Chimara are in UTF-8, which is GTK+'s native file
2452  * encoding.
2453  * </para></note>
2454  */
2455
2456 /**
2457  * fileusage_BinaryMode: 
2458  *
2459  * The file contents will be stored exactly as they are written, and read back
2460  * in the same way. The resulting file may not be viewable on platform-native
2461  * text file viewers.
2462  */
2463
2464 /**
2465  * fileusage_TypeMask:
2466  *
2467  * Bitwise AND this value with a file usage argument to find whether the file
2468  * type is %fileusage_SavedGame, %fileusage_Transcript, %fileusage_InputRecord,
2469  * or %fileusage_Data.
2470  */
2471
2472 /**
2473  * filemode_Write: 
2474  *
2475  * An output stream.
2476  *
2477  * <note><para>
2478  *   Corresponds to mode <code>"w"</code> in the stdio library, using fopen().
2479  * </para></note>
2480  */
2481
2482 /** 
2483  * filemode_Read: 
2484  *
2485  * An input stream.
2486  *
2487  * <note><para>
2488  *   Corresponds to mode <code>"r"</code> in the stdio library, using fopen().
2489  * </para></note>
2490  */
2491
2492 /**
2493  * filemode_ReadWrite: 
2494  *
2495  * Both an input and an output stream.
2496  *
2497  * <note><para>
2498  *   Corresponds to mode <code>"r+"</code> in the stdio library, using fopen().
2499  * </para></note>
2500  */
2501
2502 /**
2503  * filemode_WriteAppend: 
2504  *
2505  * An output stream, but the data will added to the end of whatever already
2506  * existed in the destination, instead of replacing it. 
2507  *
2508  * <note><para>
2509  *   Corresponds to mode <code>"a"</code> in the stdio library, using fopen().
2510  * </para></note>
2511  */
2512  
2513 /**
2514  * seekmode_Start:
2515  *
2516  * In glk_stream_set_position(), signifies that @pos is counted in characters
2517  * after the beginning of the file.
2518  */
2519  
2520 /**
2521  * seekmode_Current: 
2522  *
2523  * In glk_stream_set_position(), signifies that @pos is counted in characters
2524  * after the current position (moving backwards if @pos is negative.)
2525  */
2526
2527 /** 
2528  * seekmode_End: 
2529  *
2530  * In glk_stream_set_position(), signifies that @pos is counted in characters
2531  * after the end of the file. (@pos should always be zero or negative, so that
2532  * this will move backwards to a  position within the file.
2533  */
2534
2535 /**
2536  * stylehint_Indentation: 
2537  *
2538  * How much to indent lines of text in the given style. May be a negative 
2539  * number, to shift the text out (left) instead of in (right). The exact metric
2540  * isn't precisely specified; you can assume that +1 is the smallest indentation
2541  * possible which is clearly visible to the player.
2542  */
2543
2544 /**
2545  * stylehint_ParaIndentation: 
2546  *
2547  * How much to indent the first line of each paragraph. This is in addition to 
2548  * the indentation specified by %stylehint_Indentation. This too may be 
2549  * negative, and is measured in the same units as %stylehint_Indentation.
2550  */
2551
2552 /**
2553  * stylehint_Justification: 
2554  *
2555  * The value of this hint must be one of the constants 
2556  * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification), 
2557  * %stylehint_just_Centered, or %stylehint_just_RightFlush.
2558  */
2559
2560 /** 
2561  * stylehint_Size: 
2562  *
2563  * How much to increase or decrease the font size. This is relative; 0 means the
2564  * interpreter's default font size will be used, positive numbers increase it, 
2565  * and negative numbers decrease it. Again, +1 is the smallest size increase 
2566  * which is easily visible. 
2567  * <note><para>
2568  *  The amount of this increase may not be constant. +1 might increase an 
2569  *  8-point font to 9-point, but a 16-point font to 18-point.
2570  * </para></note>
2571  */
2572
2573 /**
2574  * stylehint_Weight: 
2575  *
2576  * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for 
2577  * normal weight, and -1 for light-weight fonts.
2578  */
2579
2580 /**
2581  * stylehint_Oblique: 
2582  *
2583  * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal
2584  * angle.
2585  */
2586  
2587 /** 
2588  * stylehint_Proportional: 
2589  * 
2590  * The value of this hint must be 1 for proportional-width fonts, or 0 for 
2591  * fixed-width.
2592  */
2593
2594 /**
2595  * stylehint_TextColor: 
2596  * 
2597  * The foreground color of the text. This is encoded in the 32-bit hint value: 
2598  * the top 8 bits must be zero, the next 8 bits are the red value, the next 8 
2599  * bits are the green value, and the bottom 8 bits are the blue value. Color 
2600  * values range from 0 to 255. 
2601  * <note><para>
2602  *   So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.
2603  * </para></note>
2604  */
2605  
2606 /** 
2607  * stylehint_BackColor: 
2608  *
2609  * The background color behind the text. This is encoded the same way as 
2610  * %stylehint_TextColor.
2611  */
2612  
2613 /** 
2614  * stylehint_ReverseColor: 
2615  *
2616  * The value of this hint must be 0 for normal printing (%stylehint_TextColor on 
2617  * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on 
2618  * %stylehint_TextColor). 
2619  * <note><para>
2620  *  Some libraries may support this hint but not the %stylehint_TextColor and 
2621  *  %stylehint_BackColor hints. Other libraries may take the opposite tack; 
2622  *  others may support both, or neither.
2623  * </para></note>
2624  */
2625  
2626 /**
2627  * stylehint_just_LeftFlush:
2628  *
2629  * A value for %stylehint_Justification representing left-justified text.
2630  */ 
2631  
2632 /**
2633  * stylehint_just_LeftRight:
2634  *
2635  * A value for %stylehint_Justification representing fully justified text.
2636  */ 
2637  
2638 /**
2639  * stylehint_just_Centered:
2640  *
2641  * A value for %stylehint_Justification representing centered text.
2642  */ 
2643  
2644 /**
2645  * stylehint_just_RightFlush:
2646  *
2647  * A value for %stylehint_Justification representing right-justified text.
2648  */
2649
2650 /**
2651  * imagealign_InlineUp:
2652  *
2653  * The image appears at the current point in the text, sticking up. That is, the
2654  * bottom edge of the image is aligned with the baseline of the line of text.
2655  */
2656
2657 /**
2658  * imagealign_InlineDown:
2659  *
2660  * The image appears at the current point, and the top edge is aligned with the
2661  * top of the line of text.
2662  */
2663
2664 /**
2665  * imagealign_InlineCenter:
2666  *
2667  * The image appears at the current point, and it is centered between the top
2668  * and baseline of the line of text. If the image is taller than the line of
2669  * text, it will stick up and down equally.
2670  */
2671
2672 /**
2673  * imagealign_MarginLeft:
2674  * 
2675  * The image appears in the left margin. Subsequent text will be displayed to
2676  * the right of the image, and will flow around it &mdash; that is, it will be
2677  * left-indented for as many lines as it takes to pass the image.
2678  *
2679  * <warning><para>Margin images are not implemented yet.</para></warning>
2680  */
2681
2682 /**
2683  * imagealign_MarginRight:
2684  *
2685  * The image appears in the right margin, and subsequent text will flow around
2686  * it on the left.
2687  *
2688  * <warning><para>Margin images are not implemented yet.</para></warning>
2689  */
2690  
2691 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
2692
2693 /**
2694  * gidispatch_count_classes:
2695  * 
2696  * Returns the number of opaque object classes used by the library. You will
2697  * need to know this if you want to keep track of opaque objects as they are
2698  * created; see <link linkend="gidispatch-set-object-registry">Opaque Object
2699  * Registry</link>.
2700  * 
2701  * As of Glk API 0.7.0, there are four classes: windows, streams, filerefs, and
2702  * sound channels (numbered 0, 1, 2, and 3 respectively.)
2703  *
2704  * Returns: Number of opaque object classes used by the library.
2705  */
2706  
2707 /**
2708  * gidispatch_count_intconst:
2709  *
2710  * Returns the number of integer constants exported by the library.
2711  *
2712  * Returns: Number of integer constants exported by the library.
2713  */
2714  
2715 /**
2716  * gidispatch_get_intconst:
2717  * @index: Unique integer index of the integer constant.
2718  *
2719  * Returns a structure describing an integer constant which the library exports.
2720  * These are, roughly, all the constants defined in the <filename
2721  * class="headerfile">glk.h</filename> file. @index can range from 0 to
2722  * <inlineequation><mathphrase>N - 1</mathphrase><alt>N - 
2723  * 1</alt></inlineequation>, where N is the value returned by 
2724  * gidispatch_count_intconst().
2725  *
2726  * Returns: A #gidispatch_intconst_t structure describing the integer constant.
2727  */
2728
2729 /**
2730  * gidispatch_intconst_t:
2731  * @name: Symbolic name of the integer constant.
2732  * @val: Value of the integer constant.
2733  *
2734  * This structure simply contains a string and a value. The string is a
2735  * symbolic name of the value, and can be re-exported to anyone interested in
2736  * using Glk constants.
2737  */
2738  
2739 /**
2740  * gidispatch_count_functions:
2741  *
2742  * Returns the number of functions exported by the library.
2743  *
2744  * Returns: Number of functions exported by the library.
2745  */
2746  
2747 /**
2748  * gidispatch_get_function:
2749  * @index: Unique integer index of the function.
2750  *
2751  * Returns a structure describing a Glk function. @index can range from 0 to
2752  * <inlineequation><mathphrase>N - 1</mathphrase><alt>N - 
2753  * 1</alt></inlineequation>, where N is the value returned by 
2754  * gidispatch_count_functions().
2755  *
2756  * Returns: A #gidispatch_function_t structure describing the function.
2757  */
2758  
2759 /**
2760  * gidispatch_function_t:
2761  * @id: Dispatch selector of the function.
2762  * @fnptr: Pointer to the function.
2763  * @name: Name of the function, without the <code>glk_</code> prefix.
2764  *
2765  * The @id field is a selector &mdash; a numeric constant used to refer to the
2766  * function in question. @name is the function name, as it is given in the
2767  * <filename class="headerfile">glk.h</filename> file, but without the 
2768  * <quote><code>glk_</code></quote> prefix. And @fnptr is the address of the
2769  * function itself.
2770  *
2771  * <note><para>
2772  *   This is included because it might be useful, but it is not recommended. To
2773  *   call an arbitrary Glk function, you should use gidispatch_call().
2774  * </para></note>
2775  *
2776  * See <link linkend="chimara-Table-of-Selectors">Table of Selectors</link> for
2777  * the selector definitions. See <link 
2778  * linkend="chimara-Dispatching">Dispatching</link> for more about calling Glk
2779  * functions by selector.
2780  */
2781  
2782 /**
2783  * gidispatch_get_function_by_id:
2784  * @id: A selector.
2785  *
2786  * Returns a structure describing the Glk function with selector @id. If there 
2787  * is no such function in the library, this returns %NULL.
2788  *
2789  * Returns: a #gidispatch_function_t structure, or %NULL.
2790  */
2791  
2792 /**
2793  * gidispatch_call:
2794  * @funcnum: Selector of the function to call.
2795  * @numargs: Length of @arglist.
2796  * @arglist: List of arguments to pass to the function.
2797  *
2798  * @funcnum is the function number to invoke; see <link 
2799  * linkend="chimara-Table-of-Selectors">Table of Selectors</link>. @arglist is
2800  * the list of arguments, and @numargs is the length of the list.
2801  * 
2802  * The arguments are all stored as #gluniversal_t objects. 
2803  * </para><refsect3 id="chimara-Basic-Types"><title>Basic Types</title><para>
2804  * Numeric arguments are passed in the obvious way &mdash; one argument per
2805  * #gluniversal_t, with the @uint or @sint field set to the numeric value.
2806  * Characters and strings are also passed in this way &mdash; #char<!---->s in
2807  * the @uch, @sch, or @ch fields (depending on whether the #char is signed) and
2808  * strings in the @charstr field. Opaque objects (windows, streams, etc) are
2809  * passed in the @opaqueref field (which is <code>void*</code>, in order to
2810  * handle all opaque pointer types.)
2811  * 
2812  * However, pointers (other than C strings), arrays, and structures complicate
2813  * life. So do return values.
2814  * </para></refsect3>
2815  * <refsect3 id="chimara-References"><title>References</title><para>
2816  * A reference to a numeric type or object reference &mdash; that is,
2817  * <code>#glui32*</code>, <code>#winid_t*</code>, and so on &mdash; takes
2818  * <emphasis>one or two</emphasis> #gluniversal_t objects. The first is a flag
2819  * indicating whether the reference argument is %NULL or not. The @ptrflag field
2820  * of this #gluniversal_t should be %FALSE if the reference is %NULL, and %TRUE
2821  * otherwise. If %FALSE, that is the end of the argument; you should not use a
2822  * #gluniversal_t to explicitly store the %NULL reference. If the flag is %TRUE,
2823  * you must then put a #gluniversal_t storing the base type of the reference.
2824  *
2825  * For example, consider a hypothetical function, with selector 
2826  * <code>0xABCD</code>:
2827  * |[ 
2828  * void glk_glomp(glui32 num, winid_t win, glui32 *numref, strid_t *strref);
2829  * ]|
2830  * ...and the calls:
2831  * |[
2832  * glui32 value;
2833  * winid_t mainwin;
2834  * strid_t gamefile;
2835  * glk_glomp(5, mainwin, &value, &gamefile);
2836  * ]|
2837  *
2838  * To perform this through gidispatch_call(), you would do the following:
2839  * |[
2840  * gluniversal_t arglist[6];
2841  * arglist[0].uint = 5;
2842  * arglist[1].opaqueref = mainwin;
2843  * arglist[2].ptrflag = TRUE;
2844  * arglist[3].uint = value;
2845  * arglist[4].ptrflag = TRUE;
2846  * arglist[5].opaqueref = gamefile;
2847  * gidispatch_call(0xABCD, 6, arglist);
2848  * value = arglist[3].uint;
2849  * gamefile = arglist[5].opaqueref;
2850  * ]|
2851  * 
2852  * Note that you copy the value of the reference arguments into and out of
2853  * @arglist. Of course, it may be that 
2854  * <function>glk_glomp&lpar;&rpar;</function> only uses these as pass-out
2855  * references or pass-in references; if so, you could skip copying in or out.
2856  *
2857  * For further examples:
2858  * |[
2859  * glk_glomp(7, mainwin, NULL, NULL);
2860  * ...or...
2861  * gluniversal_t arglist[4];
2862  * arglist[0].uint = 7;
2863  * arglist[1].opaqueref = mainwin;
2864  * arglist[2].ptrflag = FALSE;
2865  * arglist[3].ptrflag = FALSE;
2866  * gidispatch_call(0xABCD, 4, arglist);
2867  * ]|
2868  *
2869  * |[
2870  * glk_glomp(13, NULL, NULL, &gamefile);
2871  * ...or...
2872  * gluniversal_t arglist[5];
2873  * arglist[0].uint = 13;
2874  * arglist[1].opaqueref = NULL;
2875  * arglist[2].ptrflag = FALSE;
2876  * arglist[3].ptrflag = TRUE;
2877  * arglist[4].opaqueref = gamefile;
2878  * gidispatch_call(0xABCD, 5, arglist);
2879  * gamefile = arglist[4].opaqueref;
2880  * ]|
2881  *
2882  * |[
2883  * glk_glomp(17, NULL, &value, NULL);
2884  * ...or...
2885  * gluniversal_t arglist[5];
2886  * arglist[0].uint = 17;
2887  * arglist[1].opaqueref = NULL;
2888  * arglist[2].ptrflag = TRUE;
2889  * arglist[3].uint = value;
2890  * arglist[4].ptrflag = FALSE;
2891  * gidispatch_call(0xABCD, 5, arglist);
2892  * value = arglist[3].uint;
2893  * ]|
2894  * 
2895  * As you see, the length of @arglist depends on how many of the reference
2896  * arguments are %NULL.
2897  * </para></refsect3>
2898  * <refsect3 id="chimara-Structures"><title>Structures</title><para>
2899  * A structure pointer is represented by a single @ptrflag, possibly followed by
2900  * a sequence of #gluniversal_t objects (one for each field of the structure.)
2901  * Again, if the structure pointer is non-%NULL, the @ptrflag should be %TRUE
2902  * and be followed by values; if not, the @ptrflag should be %NULL and stands
2903  * alone.
2904  * 
2905  * For example, the function glk_select() can be invoked as follows:
2906  * |[
2907  * event_t ev;
2908  * gluniversal_t arglist[5];
2909  * arglist[0].ptrflag = TRUE;
2910  * gidispatch_call(0x00C0, 5, arglist);
2911  * ev.type = arglist[1].uint;
2912  * ev.win = arglist[2].opaqueref;
2913  * ev.val1 = arglist[3].uint;
2914  * ev.val2 = arglist[4].uint;
2915  * ]|
2916  * 
2917  * Since the structure passed to glk_select() is a pass-out reference (the entry
2918  * values are ignored), you don't need to fill in <code>arglist[1..4]</code>
2919  * before calling gidispatch_call().
2920  * 
2921  * <note><para>
2922  *   Theoretically, you would invoke <code>#glk_select(%NULL)</code> by setting'
2923  *   <code>arglist[0].ptrflag</code> to %FALSE, and using a one-element @arglist
2924  *   instead of five-element. But it's illegal to pass %NULL to glk_select(). So
2925  *   you cannot actually do this.
2926  * </para></note></para></refsect3>
2927  * <refsect3 id="chimara-Arrays"><title>Arrays</title><para>
2928  * In the Glk API, an array argument is always followed by a numeric argument
2929  * giving the array's length. These two C arguments are a single logical
2930  * argument, which is represented by <emphasis>one or three</emphasis>
2931  * #gluniversal_t objects. The first is a @ptrflag, indicating whether the
2932  * argument is %NULL or not. The second is a pointer, stored in the @array
2933  * field. The third is the array length, stored in the @uint field. And again,
2934  * if the @ptrflag is %NULL, the following two are omitted.
2935  * 
2936  * For example, the function glk_put_buffer() can be invoked as follows:
2937  * |[
2938  * char buf[64];
2939  * glui32 len = 64;
2940  * glk_put_buffer(buf, len);
2941  * ...or...
2942  * gluniversal_t arglist[3];
2943  * arglist[0].ptrflag = TRUE;
2944  * arglist[1].array = buf;
2945  * arglist[2].uint = len;
2946  * gidispatch_call(0x0084, 3, arglist);
2947  * ]|
2948  * 
2949  * Since you are passing a C char array to gidispatch_call(), the contents will
2950  * be read directly from that. There is no need to copy data into @arglist, as
2951  * you would for a basic type.
2952  * 
2953  * If you are implementing a VM whose native representation of char arrays is
2954  * more complex, you will have to do more work. You should allocate a C char
2955  * array, copy your characters into it, make the call, and then free the array.
2956  *
2957  * <note><para>
2958  *   glk_put_buffer() does not modify the array passed to it, so there is no
2959  *   need to copy the characters out.
2960  * </para></note></para></refsect3>
2961  * <refsect3 id="chimara-Return-Values"><title>Return Values</title><para>
2962  * The return value of a function is not treated specially. It is simply
2963  * considered to be a pass-out reference argument which may not be %NULL. It
2964  * comes after all the other arguments of the function.
2965  * 
2966  * For example, the function glk_window_get_rock() can be invoked as follows:
2967  * |[
2968  * glui32 rock;
2969  * winid_t win;
2970  * rock = glk_window_get_rock(win);
2971  * ...or...
2972  * gluniversal_t arglist[3];
2973  * arglist[0].opaqueref = win;
2974  * arglist[1].ptrflag = TRUE;
2975  * gidispatch_call(0x0021, 3, arglist);
2976  * rock = arglist[2].uint;
2977  * ]|
2978  * </para></refsect3><para>
2979  */
2980
2981 /**
2982  * gluniversal_t:
2983  * @uint: Stores a #glui32.
2984  * @sint: Stores a #glsi32.
2985  * @opaqueref: Stores a #winid_t, #strid_t, #frefid_t, or #schanid_t.
2986  * @uch: Stores an #unsigned #char.
2987  * @sch: Stores a #signed #char.
2988  * @ch: Stores a #char with the default signedness.
2989  * @charstr: Stores a null-terminated string.
2990  * @unicharstr: Stores a zero-terminated string of #glui32 values representing
2991  * Unicode characters.
2992  * @array: Stores a pointer to an array, and should be followed by another 
2993  * #gluniversal_t with the array length stored in the @uint member.
2994  * @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL,
2995  * in which case it represents the entire argument. If %TRUE, should be followed
2996  * by another #gluniversal_t with the pointer in its @opaqueref or @array field.
2997  *
2998  * This is a union, encompassing all the types that can be passed to Glk
2999  * functions.
3000  */
3001  
3002 /**
3003  * gidispatch_prototype:
3004  * @funcnum: A selector for the function to be queried.
3005  *
3006  * This returns a string which encodes the proper argument list for the given
3007  * function. If there is no such function in the library, this returns %NULL.
3008  * 
3009  * The prototype string for the <function>glk_glomp&lpar;&rpar;</function> 
3010  * function described above would be: <code>"4IuQa&amp;Iu&amp;Qb:"</code>. The 
3011  * <code>"4"</code> is the number of arguments (including the return value, if 
3012  * there is one, which in this case there isn't.) <code>"Iu"</code> denotes an 
3013  * unsigned integer; <code>"Qa"</code> is an opaque object of class 0 (window).
3014  * <code>"&amp;Iu"</code> is a <emphasis>reference</emphasis> to an unsigned
3015  * integer, and <code>"&amp;Qb"</code> is a reference to a stream. The colon at
3016  * the end terminates the argument list; the return value would follow it, if
3017  * there was one.
3018  * 
3019  * Note that the initial number (<code>"4"</code> in this case) is the number of
3020  * logical arguments, not the number of #gluniversal_t objects which will be
3021  * passed to gidispatch_call(). The <function>glk_glomp&lpar;&rpar;</function> 
3022  * call uses anywhere from four to six #gluniversal_t objects, as demonstrated 
3023  * above.
3024  * 
3025  * The basic type codes:
3026  * <variablelist>
3027  * <varlistentry>
3028  *   <term><code>Iu, Is</code></term>
3029  *   <listitem><para>Unsigned and signed 32-bit integer.</para></listitem>
3030  * </varlistentry>
3031  * <varlistentry>
3032  *   <term><code>Cn, Cu, Cs</code></term>
3033  *   <listitem><para>Character, #unsigned #char, and #signed #char.</para>
3034  *     <note><para>Of course <code>Cn</code> will be the same as either 
3035  *     <code>Cu</code> or <code>Cs</code>, depending on the platform. For this
3036  *     reason, Glk avoids using it, but it is included here for completeness.
3037  *     </para></note>
3038  *   </listitem>
3039  * </varlistentry>
3040  * <varlistentry>
3041  *   <term><code>S</code></term>
3042  *   <listitem><para>A C-style string (null-terminated array of #char). In Glk,
3043  *   strings are always treated as read-only and used immediately; the library
3044  *   does not retain a reference to a string between Glk calls. A Glk call that
3045  *   wants to use writable char arrays will use an array type 
3046  *   (<code>"&num;C"</code>), not string (<code>"S"</code>).</para></listitem>
3047  * </varlistentry>
3048  * <varlistentry>
3049  *   <term><code>U</code></term>
3050  *   <listitem><para>A zero-terminated array of 32-bit integers. This is
3051  *   primarily intended as a Unicode equivalent of <code>"S"</code>. Like 
3052  *   <code>"S"</code> strings, <code>"U"</code> strings are read-only and used
3053  *   immediately. A Glk call that wants to use writable Unicode arrays will use
3054  *   an array type (<code>"&num;Iu"</code>) instead of <code>"U"</code>.</para>
3055  *   </listitem>
3056  * </varlistentry>
3057  * <varlistentry>
3058  *   <term><code>F</code></term>
3059  *   <listitem><para>A floating-point value. Glk does not currently use
3060  *   floating-point values, but we might as well define a code for them.</para>
3061  *   </listitem>
3062  * </varlistentry>
3063  * <varlistentry>
3064  *   <term><code>Qa, Qb, Qc...</code></term>
3065  *   <listitem><para>A reference to an opaque object. The second letter
3066  *   determines which class is involved. (The number of classes can be gleaned
3067  *   from gidispatch_count_classes(); see <link 
3068  *   linkend="chimara-Interrogating-the-Interface">Interrogating the
3069  *   Interface</link>).</para>
3070  *   <note><para>
3071  *     If Glk expands to have more than 26 classes, we'll think of something.
3072  *   </para></note></listitem>
3073  * </varlistentry>
3074  * </variablelist>
3075  * Any type code can be prefixed with one or more of the following characters
3076  * (order does not matter):
3077  * <variablelist>
3078  * <varlistentry>
3079  *   <term><code>&amp;</code></term>
3080  *   <listitem><para>A reference to the type; or, if you like, a variable passed
3081  *   by reference. The reference is passed both in and out, so you must copy the
3082  *   value in before calling gidispatch_call() and copy it out afterward.</para>
3083  *   </listitem>
3084  * </varlistentry>
3085  * <varlistentry>
3086  *   <term><code>&lt;</code></term>
3087  *   <listitem><para>A reference which is pass-out only. The initial value is
3088  *   ignored, so you only need copy out the value after the call.</para>
3089  *   </listitem>
3090  * </varlistentry>
3091  * <varlistentry>
3092  *   <term><code>&gt;</code></term>
3093  *   <listitem><para>A reference which is pass-in only.</para>
3094  *   <note><para>
3095  *     This is not generally used for simple types, but is useful for structures
3096  *     and arrays.
3097  *   </para></note></listitem>
3098  * </varlistentry>
3099  * <varlistentry>
3100  *   <term><code>+</code></term>
3101  *   <listitem><para>Combined with <code>"&"</code>, <code>"&lt;"</code>, or 
3102  *   <code>"&gt;"</code>, indicates that a valid reference is mandatory; %NULL
3103  *   cannot be passed.</para>
3104  *   <note><para>
3105  *     Note that even though the @ptrflag #gluniversal_t for a <code>"+"</code>
3106  *     reference is always %TRUE, it cannot be omitted.
3107  *   </para></note></listitem>
3108  * </varlistentry>
3109  * <varlistentry>
3110  *   <term><code>:</code></term>
3111  *   <listitem><para>The colon separates the arguments from the return value, or
3112  *   terminates the string if there is no return value. Since return values are
3113  *   always non-%NULL pass-out references, you may treat <code>":"</code> as
3114  *   equivalent to <code>"&lt;+"</code>. The colon is never combined with any
3115  *   other prefix character.</para></listitem>
3116  * </varlistentry>
3117  * <varlistentry>
3118  *   <term><code>[...]</code></term>
3119  *   <listitem><para>Combined with <code>"&amp;"</code>, <code>"&lt;"</code>, or 
3120  *   <code>"&gt;"</code>, indicates a structure reference. Between the brackets
3121  *   is a complete argument list encoding string, including the number of
3122  *   arguments.</para>
3123  *   <note><para>
3124  *     For example, the prototype string for glk_select() is
3125  *     <code>"1&lt;+[4IuQaIuIu]:"</code> &mdash; one argument, which is a
3126  *     pass-out non-%NULL reference to a structure, which contains four
3127  *     arguments.
3128  *   </para></note>
3129  *   <para>Currently, structures in Glk contain only basic types.</para>
3130  *   </listitem>
3131  * </varlistentry>
3132  * <varlistentry>
3133  *   <term><code>&num;</code></term>
3134  *   <listitem><para>Combined with <code>"&amp;"</code>, <code>"&lt;"</code>, or 
3135  *   <code>"&gt;"</code>, indicates an array reference. As described above, this
3136  *   encompasses up to three #gluniversal_t objects &mdash; @ptrflag, pointer,
3137  *   and integer length.</para>
3138  *   <note><para>
3139  *     Depending on the design of your program, you may wish to pass a pointer
3140  *     directly to your program's memory, or allocate an array and copy the
3141  *     contents in and out. See <link linkend="chimara-Arrays">Arrays</link>.
3142  *   </para></note></listitem>
3143  * </varlistentry>
3144  * <varlistentry>
3145  *   <term><code>!</code></term>
3146  *   <listitem><para>Combined with <code>"&num;"</code>, indicates that the
3147  *   array is retained by the library. The library will keep a reference to the
3148  *   array; the contents are undefined until further notice. You should not use
3149  *   or copy the contents of the array out after the call, even for 
3150  *   <code>"&amp;&num;!"</code> or <code>"&lt;&num;!"</code> arrays. Instead, do
3151  *   it when the library releases the array.</para>
3152  *   <note><para>
3153  *     For example, glk_stream_open_memory() retains the array that you pass it,
3154  *     and releases it when the stream is closed. The library can notify you
3155  *     automatically when arrays are retained and released; see <link
3156  *     linkend="gidispatch-set-retained-registry">Retained Array
3157  *     Registry</link>.
3158  *   </para></note></listitem>
3159  * </varlistentry>
3160  * </variablelist>
3161  *
3162  * Returns: A string which encodes the prototype of the specified Glk function.
3163  */
3164
3165 /**
3166  * gidisp_Class_Window:
3167  *
3168  * Represents a #winid_t opaque object.
3169  */
3170  
3171 /**
3172  * gidisp_Class_Stream:
3173  *
3174  * Represents a #strid_t opaque object.
3175  */
3176  
3177 /**
3178  * gidisp_Class_Fileref:
3179  *
3180  * Represents a #frefid_t opaque object.
3181  */
3182
3183 /**
3184  * gidisp_Class_Schannel:
3185  * 
3186  * Represents a #schanid_t opaque object.
3187  */
3188
3189 /**
3190  * gidispatch_rock_t:
3191  * @num: Space for storing an integer.
3192  * @ptr: Space for storing a pointer.
3193  *
3194  * You can store any value you want in this object; return it from your object
3195  * registry and retained array registry callbacks, and the library will stash it
3196  * away. You can retrieve it with gidispatch_get_objrock().
3197  */ 
3198
3199 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/
3200  
3201 /**
3202  * giblorb_err_t: 
3203  *
3204  * An integer type that can hold the Blorb error codes.
3205  */ 
3206  
3207 /**
3208  * giblorb_err_None:
3209  *
3210  * No error.
3211  */
3212  
3213 /**
3214  * giblorb_err_CompileTime: 
3215  *
3216  * Something is compiled wrong in the Blorb layer.
3217  */
3218  
3219 /**
3220  * giblorb_err_Alloc: 
3221  *
3222  * Memory could not be allocated.
3223  * <note><title>Chimara</title>
3224  * <para>
3225  *  The Blorb layer in the Chimara library should not return this error code;
3226  *  instead, the program aborts if memory allocation fails, in keeping with
3227  *  GLib practices.
3228  * </para></note> 
3229  */
3230  
3231 /**
3232  * giblorb_err_Read: 
3233  *
3234  * Data could not be read from the file.
3235  */
3236
3237 /** 
3238  * giblorb_err_NotAMap:
3239  *
3240  * The map parameter is invalid.
3241  */
3242
3243 /** 
3244  * giblorb_err_Format:
3245  *
3246  * The Blorb file is corrupted or invalid.
3247  */
3248  
3249 /**
3250  * giblorb_err_NotFound:
3251  *
3252  * The requested data could not be found.
3253  */
3254
3255 /**
3256  * giblorb_method_DontLoad:
3257  *
3258  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3259  * giblorb_load_resource() to obtain information about a chunk without actually
3260  * loading it.
3261  */
3262
3263 /**
3264  * giblorb_method_Memory:
3265  *
3266  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3267  * giblorb_load_resource() to load a chunk into memory.
3268  */
3269
3270 /**
3271  * giblorb_method_FilePos:
3272  *
3273  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3274  * giblorb_load_resource() to get the position in the Blorb file at which the
3275  * chunk data starts.
3276  */
3277
3278 /**
3279  * giblorb_ID_Snd:
3280  *
3281  * Resource usage constant representing a sound file.
3282  */
3283
3284 /**
3285  * giblorb_ID_Exec:
3286  *
3287  * Resource usage constant representing an executable program.
3288  */
3289  
3290 /**
3291  * giblorb_ID_Pict:
3292  *
3293  * Resource usage constant representing an image file.
3294  */
3295
3296 /**
3297  * giblorb_ID_Copyright:
3298  *
3299  * Resource usage constant representing the copyright message (date and holder, 
3300  * without the actual copyright symbol). There should only be one such chunk per
3301  * file.
3302  */
3303
3304 /**
3305  * giblorb_ID_AUTH:
3306  *
3307  * Resource usage constant representing the name of the author or creator of the
3308  * file. This could be a login name on multi-user systems, for example. There
3309  * should only be one such chunk per file.
3310  */
3311  
3312 /**
3313  * giblorb_ID_ANNO:
3314  *
3315  * Resource usage constant representing any textual annotation that the user or 
3316  * writing program sees fit to include.
3317  */ 
3318  
3319 /**
3320  * giblorb_map_t:
3321  *
3322  * Holds the complete description of an open Blorb file. This type is opaque for
3323  * normal interpreter use.
3324  */
3325  
3326 /**
3327  * giblorb_result_t:
3328  * @chunknum: The chunk number (for use in giblorb_unload_chunk(), etc.)
3329  * @data: A union containing a pointer to the data @ptr (if you used 
3330  * %giblorb_method_Memory) and the position in the file @startpos (if you used 
3331  * %giblorb_method_FilePos)
3332  * @length: The length of the data
3333  * @chunktype: The type of the chunk.
3334  *
3335  * Holds information about a chunk loaded from a Blorb file, and the method of
3336  * accessing the chunk data. See giblorb_load_chunk_by_type() and
3337  * giblorb_load_chunk_by_number(). 
3338  */
3339  
3340 /**
3341  * giblorb_create_map:
3342  * @file: An input stream pointing to a Blorb file.
3343  * @newmap: Return location for a Blorb resource map.
3344  *
3345  * Reads Blorb data out of a Glk stream. It does not load every resource at 
3346  * once; instead, it creates a map in memory which makes it easy to find 
3347  * resources. A pointer to the map is stored in @newmap. This is an opaque 
3348  * object; you pass it to the other Blorb-layer functions.
3349  *
3350  * Returns: a Blorb error code. 
3351  */
3352  
3353 /**
3354  * giblorb_destroy_map: 
3355  * @map: A Blorb resource map to deallocate.
3356  *
3357  * Deallocates @map and all associated memory. This does 
3358  * <emphasis>not</emphasis> close the original stream.
3359  *
3360  * Returns: a Blorb error code. 
3361  */
3362
3363 /**
3364  * giblorb_load_chunk_by_type:
3365  * @map: The Blorb resource map to load a chunk from.
3366  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
3367  * %giblorb_method_Memory, or %giblorb_method_FilePos.
3368  * @res: Return location for the result.
3369  * @chunktype: The type of chunk to load.
3370  * @count: The chunk number of type @chunktype to load.
3371  *
3372  * Loads a chunk of a given type. The @count parameter distinguishes between 
3373  * chunks of the same type. If @count is zero, the first chunk of that type is 
3374  * loaded, and so on.
3375  * 
3376  * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the 
3377  * form type, rather than FORM.
3378  * <note><para>
3379  *  This introduces a slight ambiguity &mdash; you cannot distiguish between a 
3380  *  FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is 
3381  *  almost certainly a mistake.
3382  * </para></note> 
3383  * 
3384  * The returned data is written into @res, according to @method.
3385  * 
3386  * The <structfield>chunknum</structfield> field is filled in with the number of
3387  * the chunk. (This value can then be passed to giblorb_load_chunk_by_number() 
3388  * or giblorb_unload_chunk().) The <structfield>length</structfield> field is 
3389  * filled in with the length of the chunk in bytes. The 
3390  * <structfield>chunktype</structfield> field is the chunk's type, which of 
3391  * course will be the type you asked for.
3392  * 
3393  * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You
3394  * can use this if you are only interested in whether a chunk exists, or in the
3395  * <structfield>chunknum</structfield> and <structfield>length</structfield> 
3396  * parameters.
3397  * 
3398  * If you specify %giblorb_method_FilePos, 
3399  * <structfield>data.startpos</structfield> is filled in with the file position
3400  * of the chunk data. You can use glk_stream_set_position() to read the data 
3401  * from the stream.
3402  * 
3403  * If you specify %giblorb_method_Memory, <structfield>data.ptr</structfield> is
3404  * filled with a pointer to allocated memory containing the chunk data. This 
3405  * memory is owned by the map, not you. If you load the chunk more than once 
3406  * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one
3407  * copy in memory. You should not deallocate this memory yourself; call 
3408  * giblorb_unload_chunk() instead.
3409  *
3410  * Returns: a Blorb error code.
3411  */
3412
3413 /** 
3414  * giblorb_load_chunk_by_number:
3415  * @map: The Blorb resource map to load a chunk from.
3416  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
3417  * %giblorb_method_Memory, or %giblorb_method_FilePos.
3418  * @res: Return location for the result.
3419  * @chunknum: The chunk number to load.
3420  *
3421  * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a
3422  * given chunk number. The type of the chunk can be found in the 
3423  * <structfield>chunktype</structfield> field of #giblorb_result_t. You can get
3424  * the chunk number from the <structfield>chunknum</structfield> field, after 
3425  * calling one of the other load functions.
3426  *
3427  * Returns: a Blorb error code. 
3428  */
3429
3430 /**
3431  * giblorb_unload_chunk:
3432  * @map: The Blorb resource map to unload a chunk from.
3433  * @chunknum: The chunk number to unload.
3434  *
3435  * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk
3436  * has never been loaded into memory, this has no effect. 
3437  *
3438  * Returns: a Blorb error code.
3439  */
3440
3441 /**
3442  * giblorb_load_resource:
3443  * @map: The Blorb resource map to load a resource from.
3444  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
3445  * %giblorb_method_Memory, or %giblorb_method_FilePos.
3446  * @res: Return location for the result.
3447  * @usage: The type of data resource to load.
3448  * @resnum: The resource number to load.
3449  *
3450  * Loads a resource, given its usage and resource number. Currently, the three
3451  * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and
3452  * %giblorb_ID_Exec (executable program). See the Blorb specification for more
3453  * information about the types of data that can be stored for these usages.
3454  * 
3455  * Note that a resource number is not the same as a chunk number. The resource
3456  * number is the sound or image number specified by a Glk program. Chunk number
3457  * is arbitrary, since chunks in a Blorb file can be in any order. To find the
3458  * chunk number of a given resource, call giblorb_load_resource() and look in
3459  * <structfield>res.chunknum</structfield>.
3460  *
3461  * Returns: a Blorb error code.
3462  */
3463
3464 /**
3465  * giblorb_count_resources:
3466  * @map: The Blorb resource map in which to count the resources.
3467  * @usage: The type of data resource to count.
3468  * @num: Return location for the number of chunks of @usage.
3469  * @min: Return location for the lowest resource number of @usage.
3470  * @max: Return location for the highest resource number of @usage.
3471  *
3472  * Counts the number of chunks with a given usage (image, sound, or executable.)
3473  * The total number of chunks of that usage is stored in @num. The lowest and 
3474  * highest resource number of that usage are stored in @min and @max. You can
3475  * leave any of the three pointers %NULL if you don't care about that
3476  * information. 
3477  *
3478  * Returns: a Blorb error code.
3479  */
3480
3481 /*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/
3482
3483 /**
3484  * glkunix_argumentlist_t:
3485  * @name: the option as it would appear on the command line (including the 
3486  * leading dash, if any.) 
3487  * @desc: a description of the argument; this is used when the library is 
3488  * printing a list of options.
3489  * @argtype: one of the <code>glkunix_arg_</code> constants.
3490  * 
3491  * <variablelist>
3492  * <varlistentry>
3493  *  <term>%glkunix_arg_NoValue</term>
3494  *  <listitem><para>The argument appears by itself.</para></listitem>
3495  * </varlistentry>
3496  * <varlistentry>
3497  *  <term>%glkunix_arg_ValueFollows</term>
3498  *  <listitem><para>The argument must be followed by another argument (the 
3499  *  value).</para></listitem>
3500  * </varlistentry>
3501  * <varlistentry>
3502  *  <term>%glkunix_arg_ValueCanFollow</term> 
3503  *  <listitem><para>The argument may be followed by a value, optionally. (If the
3504  *  next argument starts with a dash, it is taken to be a new argument, not the 
3505  *  value of this one.)</para></listitem>
3506  * </varlistentry>
3507  * <varlistentry>
3508  *  <term>%glkunix_arg_NumberValue</term>
3509  *  <listitem><para>The argument must be followed by a number, which may be the 
3510  *  next argument or part of this one. (That is, either <quote><code>-width 
3511  *  20</code></quote> or <quote><code>-width20</code></quote> will be accepted.)
3512  *  </para></listitem>
3513  * </varlistentry>
3514  * <varlistentry> 
3515  *  <term>%glkunix_arg_End</term>
3516  *  <listitem><para>The <code>glkunix_arguments[]</code> array must be 
3517  *  terminated with an entry containing this value.</para></listitem>
3518  * </varlistentry>
3519  * </variablelist>
3520  * 
3521  * To accept arbitrary arguments which lack dashes, specify a name of 
3522  * <code>""</code> and an argtype of %glkunix_arg_ValueFollows.
3523  *
3524  * If you don't care about command-line arguments, you must still define an
3525  * empty arguments list, as follows:
3526  * |[
3527  * glkunix_argumentlist_t glkunix_arguments[] = {
3528  *     { NULL, glkunix_arg_End, NULL }
3529  * };
3530  * ]|
3531  * 
3532  * Here is a more complete sample list:
3533  * |[
3534  * glkunix_argumentlist_t glkunix_arguments[] = {
3535  *     { "", glkunix_arg_ValueFollows, "filename: The game file to load." },
3536  *     { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
3537  *     { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
3538  *       the NUM, if given)." },
3539  *     { "-goo", glkunix_arg_NoValue, "-goo: Find goo." },
3540  *     { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
3541  *     { NULL, glkunix_arg_End, NULL }
3542  * };
3543  * ]|
3544  * This would match the arguments <quote><code>thingfile -goo -wob8 -bom -hum 
3545  * song</code></quote>.
3546  *
3547  * After the library parses the command line, it does various occult rituals of
3548  * initialization, and then calls glkunix_startup_code().
3549  *
3550  * |[ int glkunix_startup_code(glkunix_startup_t *data); ]|
3551  *
3552  * This should return %TRUE if everything initializes properly. If it returns
3553  * %FALSE, the library will shut down without ever calling your glk_main() 
3554  * function.
3555  */
3556
3557 /**
3558  * glkunix_startup_t: 
3559  * @argc: The number of arguments in @argv.
3560  * @argv: Strings representing command line arguments.
3561  * 
3562  * The fields are a standard Unix <code>(argc, argv)</code> list, which contain
3563  * the arguments you requested from the command line. In deference to custom,
3564  * <code>argv[0]</code> is always the program name.
3565  */
3566
3567 /**
3568  * glkunix_arg_End:
3569  *
3570  * Terminates a list of #glkunix_argumentlist_t.
3571  */
3572  
3573 /**
3574  * glkunix_arg_ValueFollows:
3575  *
3576  * Indicates an argument which must be followed by a value, as the next 
3577  * argument.
3578  */
3579
3580 /** 
3581  * glkunix_arg_NoValue:
3582  *
3583  * Indicates an argument which occurs by itself, without a value.
3584  */
3585  
3586 /**
3587  * glkunix_arg_ValueCanFollow:
3588  *
3589  * Indicates an argument which may be followed by a value, or may occur by 
3590  * itself.
3591  */
3592  
3593 /**
3594  * glkunix_arg_NumberValue:
3595  *
3596  * Indicates an argument which must be followed by a numerical value, either as 
3597  * the next argument or tacked onto the end of this argument.
3598  */