Disabled libtool C++ and Fortran support, so configure runs a lot faster
[rodin/chimara.git] / libchimara / doc.c
1 /*
2  * doc.c - Contains the short and long descriptions of all the documentation
3  *         sections in the Glk spec, as well as the GtkDoc comments for symbols
4  *         defined only in glk.h.
5  */
6
7 /**
8  * SECTION:glk-exiting
9  * @short_description: How to terminate a Glk program cleanly
10  * @include: libchimara/glk.h
11  *
12  * A Glk program usually ends when the end of the glk_main() function is 
13  * reached. You can also terminate it earlier.
14  */ 
15
16 /**
17  * SECTION:glk-interrupt
18  * @short_description: Specifying an interrupt handler for cleaning up critical
19  * resources
20  * @include: libchimara/glk.h
21  *
22  * Most platforms have some provision for interrupting a program —
23  * <keycombo action="simul"><keycap function="command">command</keycap>
24  * <keycap>period</keycap></keycombo> on the Macintosh, <keycombo 
25  * action="simul"><keycap function="control">control</keycap><keycap>C</keycap>
26  * </keycombo> in Unix, possibly a window manager item, or other possibilities.
27  * This can happen at any time, including while execution is nested inside one 
28  * of your own functions, or inside a Glk library function.
29  *
30  * If you need to clean up critical resources, you can specify an interrupt
31  * handler function.
32  */
33
34 /**
35  * SECTION:glk-tick
36  * @short_description: Yielding time to the operating system
37  * @include: libchimara/glk.h
38  *
39  * Many platforms have some annoying thing that has to be done every so often,
40  * or the gnurrs come from the voodvork out and eat your computer.
41  * 
42  * Well, not really. But you should call glk_tick() every so often, just in
43  * case. It may be necessary to yield time to other applications in a
44  * cooperative-multitasking OS, or to check for player interrupts in an infinite
45  * loop.
46  */
47
48 /**
49  * SECTION:glk-types
50  * @short_description: Basic types used in Glk
51  * @include: libchimara/glk.h
52  *
53  * For simplicity, all the arguments used in Glk calls are of a very few types.
54  * <variablelist>
55  *  <varlistentry>
56  *    <term>32-bit unsigned integer</term>
57  *    <listitem><para>Unsigned integers are used wherever possible, which is
58  *    nearly everywhere. This type is called #glui32.</para></listitem>
59  *  </varlistentry>
60  *  <varlistentry>
61  *    <term>32-bit signed integer</term>
62  *    <listitem><para>This type is called #glsi32. Rarely used.</para>
63  *    </listitem>
64  *  </varlistentry>
65  *  <varlistentry>
66  *    <term>References to library objects</term>
67  *    <listitem><para>These are pointers to opaque C structures; each library
68  *    will use different structures, so you can not and should not try to
69  *    manipulate their contents. See <link 
70  *    linkend="chimara-Opaque-Objects">Opaque Objects</link>.</para></listitem>
71  *  </varlistentry>
72  *  <varlistentry>
73  *    <term>Pointer to one of the above types</term>
74  *    <listitem><para>Pointer to a structure which consists entirely of the
75  *    above types.</para></listitem>
76  *  </varlistentry>
77  *  <varlistentry>
78  *    <term><type>unsigned char</type></term> 
79  *    <listitem><para>This is used only for Latin-1 text characters; see 
80  *    <link linkend="chimara-Character-Encoding">Character Encoding</link>.
81  *    </para></listitem>
82  *  </varlistentry>
83  *  <varlistentry>
84  *    <term>Pointer to <type>char</type></term> 
85  *    <listitem><para>Sometimes this means a null-terminated string; sometimes
86  *    an unterminated buffer, with length as a separate #glui32 argument. The
87  *    documentation says which.</para></listitem>
88  *  </varlistentry>
89  *  <varlistentry>
90  *    <term>Pointer to <type>void</type></term> 
91  *    <listitem><para>When nothing else will do.</para></listitem>
92  *  </varlistentry>
93  * </variablelist>
94  */
95
96 /**
97  * SECTION:glk-opaque-objects
98  * @short_description: Complex objects in Glk
99  * @include: libchimara/glk.h
100  *
101  * Glk keeps track of a few classes of special objects. These are opaque to your
102  * program; you always refer to them using pointers to opaque C structures.
103  * 
104  * Currently, these classes are:
105  * <variablelist>
106  *  <varlistentry>
107  *    <term>Windows</term>
108  *    <listitem><para>Screen panels, used to input or output information.
109  *    </para></listitem>
110  *  </varlistentry>
111  *  <varlistentry>
112  *    <term>Streams</term>
113  *    <listitem><para>Data streams, to which you can input or output text.
114  *    </para>
115  *    <note><para>There are file streams and window streams, since you can
116  *    output data to windows or files.</para></note>
117  *    </listitem>
118  *  </varlistentry>
119  *  <varlistentry>
120  *    <term>File references</term>
121  *    <listitem><para>Pointers to files in permanent storage.</para>
122  *    <note><para>In Unix a file reference is a pathname; on the Mac, an
123  *    <type>FSSpec</type>. Actually there's a little more information included,
124  *    such as file type and whether it is a text or binary file.</para></note>
125  *    </listitem>
126  *  </varlistentry>
127  *  <varlistentry>
128  *    <term>Sound channels</term>
129  *    <listitem><para>Audio output channels.</para>
130  *    <note><para>Not all Glk libraries support sound.</para></note>
131  *    </listitem>
132  *  </varlistentry>
133  * </variablelist>
134  *
135  * <note><para>
136  * Note that there may be more object classes in future versions of the Glk API.
137  * </para></note>
138  * 
139  * When you create one of these objects, it is always possible that the creation
140  * will fail (due to lack of memory, or some other OS error.) When this happens,
141  * the allocation function will return %NULL (0) instead of a valid pointer. You
142  * should always test for this possibility.
143  * 
144  * %NULL is never the identifier of any object (window, stream, file reference,
145  * or sound channel). The value %NULL is often used to indicate <quote>no
146  * object</quote> or <quote>nothing</quote>, but it is not a valid reference. If
147  * a Glk function takes an object reference as an argument, it is illegal to
148  * pass in %NULL unless the function definition says otherwise.
149  * 
150  * The <filename class="headerfile">glk.h</filename> file defines types
151  * #winid_t, #strid_t, #frefid_t, #schanid_t to store references. These are
152  * pointers to struct #glk_window_struct, #glk_stream_struct, 
153  * #glk_fileref_struct, and #glk_schannel_struct respectively. It is, of course,
154  * illegal to pass one kind of pointer to a function which expects another.
155  * 
156  * <note><para>
157  * This is how you deal with opaque objects from a C program. If you are using
158  * Glk through a virtual machine, matters will probably be different. Opaque
159  * objects may be represented as integers, or as VM objects of some sort.
160  * </para></note>
161  * <refsect2 id="chimara-Rocks"><!-- Indeed it does. -->
162  * <title>Rocks</title>
163  * <para>
164  * Every one of these objects (window, stream, file reference, or sound channel)
165  * has a <quote>rock</quote> value. This is simply a 32-bit integer value which
166  * you provide, for your own purposes, when you create the object.
167  * </para>
168  * <note><para>The library &mdash; so to speak &mdash; stuffs this value under a
169  * rock for safe-keeping, and gives it back to you when you ask for it.
170  * </para></note>
171  * <note><para>If you don't know what to use the rocks for, provide 0 and forget
172  * about it.</para></note>
173  * </refsect2>
174  * <refsect2 id="chimara-Iterating-Through-Opaque-Objects">
175  * <title>Iteration Through Opaque Objects</title>
176  * <para>
177  * For each class of opaque objects, there is an iterate function, which you can
178  * use to obtain a list of all existing objects of that class. It takes the form
179  * |[
180  * <replaceable>CLASS</replaceable>id_t glk_<replaceable>CLASS</replaceable>_iterate(<replaceable>CLASS</replaceable>id_t <parameter>obj</parameter>, #glui32 *<parameter>rockptr</parameter>);
181  * ]|
182  * ...where <code><replaceable>CLASS</replaceable></code> represents one of the
183  * opaque object classes. 
184  * </para>
185  * <note><para>
186  *   So, at the current time, these are the functions glk_window_iterate(),
187  *   glk_stream_iterate(), glk_fileref_iterate(), and glk_schannel_iterate().  
188  *   There may be more classes in future versions of the spec; they all behave
189  *   the same.
190  * </para></note>
191  * <para>
192  * Calling <code>glk_<replaceable>CLASS</replaceable>_iterate(%NULL, r)</code>
193  * returns the first object; calling 
194  * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> returns
195  * the next object, until there aren't any more, at which time it returns %NULL.
196  * </para>
197  * <para>
198  * The @rockptr argument is a pointer to a location; whenever  
199  * <code>glk_<replaceable>CLASS</replaceable>_iterate()</code> returns an
200  * object, the object's rock is stored in the location <code>(*@rockptr)</code>.
201  * If you don't want the rocks to be returned, you may set @rockptr to %NULL.
202  * </para>
203  * <para>
204  * You usually use this as follows:
205  * |[
206  * obj = glk_<replaceable>CLASS</replaceable>_iterate(NULL, NULL);
207  * while (obj) {
208  *    /* ...do something with obj... *<!-- -->/
209  *    obj = glk_<replaceable>CLASS</replaceable>_iterate(obj, NULL);
210  * }
211  * ]|
212  * </para>
213  * <para>
214  * If you create or destroy objects inside this loop, obviously, the results are
215  * unpredictable. However it is always legal to call 
216  * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> as long as
217  * @obj is a valid object id, or %NULL.
218  * </para>
219  * <para>
220  * The order in which objects are returned is entirely arbitrary. The library
221  * may even rearrange the order every time you create or destroy an object of
222  * the given class. As long as you do not create or destroy any object, the rule
223  * is that <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> has
224  * a fixed result, and iterating through the results as above will list every
225  * object exactly once. 
226  * </para>
227  * </refsect2>
228  */
229
230 /**
231  * SECTION:glk-gestalt
232  * @short_description: Testing Glk's capabilities
233  * @include: libchimara/glk.h
234  *
235  * The <quote>gestalt</quote> mechanism (cheerfully stolen from the Mac OS) is a
236  * system by which the Glk API can be upgraded without making your life
237  * impossible. New capabilities (graphics, sound, or so on) can be added without
238  * changing the basic specification. The system also allows for 
239  * <quote>optional</quote> capabilities &mdash; those which not all Glk library
240  * implementations will support &mdash; and allows you to check for their
241  * presence without trying to infer them from a version number.
242  * 
243  * The basic idea is that you can request information about the capabilities of
244  * the API, by calling the gestalt functions.
245  */
246
247 /**
248  * SECTION:glk-character-input
249  * @short_description: Waiting for a single keystroke
250  * @include: libchimara/glk.h
251  *
252  * You can request that the player hit a single key. See <link 
253  * linkend="chimara-Character-Input-Events">Character Input Events</link>.
254  * 
255  * If you use the basic text API, the character code which is returned can be
256  * any value from 0 to 255. The printable character codes have already been
257  * described. The remaining codes are typically control codes: <keycombo  
258  * action="simul"><keycap function="control">control</keycap>
259  * <keycap>A</keycap></keycombo> to <keycombo action="simul"><keycap 
260  * function="control">control</keycap><keycap>Z</keycap></keycombo> and a few
261  * others.
262  * 
263  * There are also a number of special codes, representing special keyboard
264  * keys, which can be returned from a char-input event. These are represented
265  * as 32-bit integers, starting with 4294967295 (0xFFFFFFFF) and working down.
266  * The special key codes are defined in the <filename 
267  * class="headerfile">glk.h</filename> file. They include one code for <keycap
268  * function="enter">return</keycap> or <keycap function="enter">enter</keycap>,
269  * one for <keycap function="delete">delete</keycap> or <keycap
270  * function="backspace">backspace</keycap>, twelve function keys, and one code
271  * for any key which has no Latin-1 or special code. The full list of key codes
272  * is included below.
273  * 
274  * Various implementations of Glk will vary widely in which characters the
275  * player can enter. The most obvious limitation is that some characters are
276  * mapped to others. For example, most keyboards return a <keycombo
277  * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
278  * </keycombo> code when the <keycap function="tab">tab</keycap> key is
279  * pressed. The Glk library, if it can recognize this at all, will generate a
280  * <keysym>%keycode_Tab</keysym> event (value 0xFFFFFFF7) when this occurs.
281  * Therefore, for these keyboards, no keyboard key will generate a <keycombo
282  * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
283  * </keycombo> event (value 9.) The Glk library will probably map many of the
284  * control codes to the other special keycodes.
285  * 
286  * <note><para>
287  *   On the other hand, the library may be very clever and discriminate between
288  *   <keycap>tab</keycap> and <keycombo action="simul"><keycap
289  *   function="control">control</keycap><keycap>I</keycap></keycombo>. This is
290  *   legal. The idea is, however, that if your program asks the player to
291  *   <quote><computeroutput>press the <keycap function="tab">tab</keycap>
292  *   key</computeroutput></quote>, you should check for a 
293  *   <keysym>%keycode_Tab</keysym> event as opposed to a <keycombo 
294  *   action="simul"><keycap function="control">control</keycap>
295  *   <keycap>I</keycap></keycombo> event.
296  * </para></note>
297  * 
298  * Some characters may not be enterable simply because they do not exist.
299  * 
300  * <note><para>
301  *   Not all keyboards have a <keycap function="home">home</keycap> or <keycap
302  *   function="end">end</keycap> key. A pen-based platform may not recognize
303  *   any control characters at all.
304  * </para></note>
305  * 
306  * Some characters may not be enterable because they are reserved for the
307  * purposes of the interface. For example, the Mac Glk library reserves the 
308  * <keycap function="tab">tab</keycap> key for switching between different Glk
309  * windows. Therefore, on the Mac, the library will never generate a
310  * <keysym>%keycode_Tab</keysym> event or a <keycombo action="simul">
311  * <keycap function="control">control</keycap><keycap>I</keycap></keycombo>
312  * event.
313  * 
314  * <note><para>
315  *   Note that the linefeed or <keycombo action="simul"><keycap  
316  *   function="control">control</keycap><keycap>J</keycap></keycombo> 
317  *   character, which is the only printable control character, is probably not
318  *   typable. This is because, in most libraries, it will be converted to
319  *   <keysym>%keycode_Return</keysym>. Again, you should check for
320  *   <keysym>%keycode_Return</keysym> if your program asks the player to 
321  *   <quote><computeroutput>press the <keycap function="enter">return</keycap>
322  *   key</computeroutput></quote>.
323  * </para></note>
324  * 
325  * <note><para>
326  *   The <keycap function="delete">delete</keycap> and <keycap
327  *   function="backspace">backspace</keycap> keys are merged into a single
328  *   keycode because they have such an astonishing history of being confused in
329  *   the first place... this spec formally waives any desire to define the
330  *   difference. Of course, a library is free to distinguish <keycap
331  *   function="delete">delete</keycap> and <keycap
332  *   function="backspace">backspace</keycap> during line input. This is when it
333  *   matters most; conflating the two during character input should not be a
334  *   large problem.
335  * </para></note>
336  *
337  * You can test for this by using the %gestalt_CharInput selector.
338  * 
339  * <note><para>
340  *   Glk porters take note: it is not a goal to be able to generate every
341  *   single possible key event. If the library says that it can generate a
342  *   particular keycode, then game programmers will assume that it is
343  *   available, and ask players to use it. If a <keysym>%keycode_Home</keysym>
344  *   event can only be generated by typing <keycombo action="seq"><keycap
345  *   function="escape">escape</keycap><keycombo action="simul"><keycap
346  *   function="control">control</keycap><keycap>A</keycap></keycombo>
347  *   </keycombo>, and the player does not know this, the player will be lost
348  *   when the game says <quote><computeroutput>Press the <keycap
349  *   function="home">home</keycap> key to see the next 
350  *   hint.</computeroutput></quote> It is better for the library to say that it
351  *   cannot generate a <keysym>%keycode_Home</keysym> event; that way the game
352  *   can detect the situation and ask the user to type <keycap>H</keycap>
353  *   instead.
354  * </para>
355  * <para>
356  *   Of course, it is better not to rely on obscure keys in any case. The arrow
357  *   keys and <keycap function="enter">return</keycap> are nearly certain to be
358  *   available; the others are of gradually decreasing reliability, and you
359  *   (the game programmer) should not depend on them. You must be certain to
360  *   check for the ones you want to use, including the arrow keys and <keycap
361  *   function="enter">return</keycap>, and be prepared to use different keys in
362  *   your interface if %gestalt_CharInput says they are not available.
363  * </para></note>
364  */
365
366 /**
367  * SECTION:glk-case
368  * @short_description: Changing the case of strings
369  * @include: libchimara/glk.h
370  *
371  * Glk has functions to manipulate the case of both Latin-1 and Unicode strings.
372  * One Latin-1 lowercase character corresponds to one uppercase character, and
373  * vice versa, so the Latin-1 functions act on single characters. The Unicode
374  * functions act on whole strings, since the length of the string may change.
375  */
376
377 /**
378  * SECTION:glk-window-opening
379  * @short_description: Creating new windows and closing them
380  * @include: libchimara/glk.h
381  *
382  * You can open a new window using glk_window_open() and close it again using
383  * glk_window_close().
384  */
385
386 /**
387  * SECTION:glk-window-constraints
388  * @short_description: Manipulating the size of a window
389  * @include: libchimara/glk.h
390  *
391  * There are library functions to change and to measure the size of a window.
392  */
393
394 /**
395  * SECTION:glk-window-types
396  * @short_description: Blank, pair, text grid, text buffer, and graphics windows
397  * @include: libchimara/glk.h
398  * 
399  * A technical description of all the window types, and exactly how they behave.
400  */
401
402 /**
403  * SECTION:glk-echo-streams
404  * @short_description: Creating a copy of a window's output
405  * @include: libchimara/glk.h
406  *
407  * Every window has an associated window stream; you print to the window by
408  * printing to this stream. However, it is possible to attach a second stream to
409  * a window. Any text printed to the window is also echoed to this second
410  * stream, which is called the window's <quote>echo stream.</quote>
411  * 
412  * Effectively, any call to glk_put_char() (or the other output commands) which
413  * is directed to the window's window stream, is replicated to the window's echo
414  * stream. This also goes for the style commands such as glk_set_style().
415  * 
416  * Note that the echoing is one-way. You can still print text directly to the
417  * echo stream, and it will go wherever the stream is bound, but it does not
418  * back up and appear in the window. 
419  *
420  * An echo stream can be of any type, even another window's window stream.
421  * 
422  * <note><para>
423  *   This would be somewhat silly, since it would mean that any text printed to
424  *   the window would be duplicated in another window. More commonly, you would
425  *   set a window's echo stream to be a file stream, in order to create a
426  *   transcript file from that window.
427  * </para></note>
428  *
429  * A window can only have one echo stream. But a single stream can be the echo
430  * stream of any number of windows, sequentially or simultaneously.
431  *
432  * If a window is closed, its echo stream remains open; it is not automatically
433  * closed. 
434  *
435  * <note><para>
436  *   Do not confuse the window's window stream with its echo stream. The window
437  *   stream is <quote>owned</quote> by the window, and dies with it. The echo
438  *   stream is merely temporarily associated with the window.
439  * </para></note>
440  * 
441  * If a stream is closed, and it is the echo stream of one or more windows,
442  * those windows are reset to not echo anymore. (So then calling
443  * glk_window_get_echo_stream() on them will return %NULL.) 
444  */
445
446 /**
447  * SECTION:glk-window-other
448  * @short_description: Miscellaneous functions for windows
449  * @include: libchimara/glk.h
450  *
451  * This section contains functions for windows that don't fit anywhere else.
452  */
453
454 /**
455  * SECTION:glk-events
456  * @short_description: Waiting for events
457  * @include: libchimara/glk.h
458  *
459  * As described in <link linkend="chimara-Your-Programs-Main-Function">Your
460  * Program's Main Function</link>, all player input is handed to your program by
461  * the glk_select() call, in the form of events. You should write at least one
462  * event loop to retrieve these events.
463  */
464
465 /**
466  * SECTION:glk-character-input-events
467  * @short_description: Events representing a single keystroke
468  * @include: libchimara/glk.h
469  *
470  * You can request character input from text buffer and text grid windows. See 
471  * %evtype_CharInput. There are separate functions for requesting Latin-1 input
472  * and Unicode input; see %gestalt_Unicode.
473  */
474
475 /**
476  * SECTION:glk-line-input-events
477  * @short_description: Events representing a line of user input
478  * @include: libchimara/glk.h
479  *
480  * You can request line input from text buffer and text grid windows. See
481  * %evtype_LineInput. There are separate functions for requesting Latin-1 input
482  * and Unicode input; see %gestalt_Unicode.
483  */
484
485 /**
486  * SECTION:glk-timer-events
487  * @short_description: Events sent at fixed intervals
488  * @include: libchimara/glk.h
489  *
490  * You can request that an event be sent at fixed intervals, regardless of what
491  * the player does. Unlike input events, timer events can be tested for with
492  * glk_select_poll() as well as glk_select().
493  *
494  * It is possible that the library does not support timer events. You can check
495  * this with the %gestalt_Timer selector.
496  */
497  
498 /**
499  * SECTION:glk-streams
500  * @short_description: Input and output abstractions
501  * @include: libchimara/glk.h
502  *
503  * All character output in Glk is done through streams. Every window has an
504  * output stream associated with it. You can also write to files on disk; every
505  * open file is represented by an output stream as well.
506  *
507  * There are also input streams; these are used for reading from files on disk.
508  * It is possible for a stream to be both an input and an output stream. 
509  *
510  * <note><para>
511  *   Player input is done through line and character input events, not streams.
512  *   This is a small inelegance in theory. In practice, player input is slow and
513  *   things can interrupt it, whereas file input is immediate. If a network
514  *   extension to Glk were proposed, it would probably use events and not
515  *   streams, since network communication is not immediate.
516  * </para></note>
517  *
518  * It is also possible to create a stream that reads or writes to a buffer in
519  * memory.
520  * 
521  * Finally, there may be platform-specific types of streams, which are created
522  * before your program starts running. 
523  *
524  * <note><para>
525  *   For example, a program running under Unix may have access to standard input
526  *   as a stream, even though there is no Glk call to explicitly open standard
527  *   input. On the Mac, data in a Mac resource may be available through a
528  *   resource-reading stream.
529  * </para></note>
530  *
531  * You do not need to worry about the origin of such streams; just read or write
532  * them as usual. For information about how platform-specific streams come to
533  * be, see <link linkend="chimara-Startup-Options">Startup Options</link>.
534  * 
535  * A stream is opened with a particular file mode, see the 
536  * <code>filemode_</code> constants below.
537  *
538  * For information on opening streams, see the discussion of each specific type
539  * of stream in <link linkend="chimara-The-Types-of-Streams">The Types of
540  * Streams</link>. Remember that it is always possible that opening a stream
541  * will fail, in which case the creation function will return %NULL.
542  * 
543  * Each stream remembers two character counts, the number of characters printed
544  * to and read from that stream. The write-count is exactly one per 
545  * glk_put_char() call; it is figured before any platform-dependent character
546  * cookery. 
547  *
548  * <note><para>
549  *   For example, if a newline character is converted to 
550  *   linefeed-plus-carriage-return, the stream's count still only goes up by
551  *   one; similarly if an accented character is displayed as two characters.
552  * </para></note>
553  * 
554  * The read-count is exactly one per glk_get_char_stream() call, as long as the
555  * call returns an actual character (as opposed to an end-of-file token.) 
556  *
557  * Glk has a notion of the <quote>current (output) stream</quote>. If you print
558  * text without specifying a stream, it goes to the current output stream. The
559  * current output stream may be %NULL, meaning that there isn't one. It is
560  * illegal to print text to stream %NULL, or to print to the current stream when
561  * there isn't one.
562  *
563  * If the stream which is the current stream is closed, the current stream
564  * becomes %NULL. 
565  */
566  
567 /**
568  * SECTION:glk-print
569  * @short_description: Printing to streams
570  * @include: libchimara/glk.h
571  *
572  * You can print Latin-1 and Unicode characters, null-terminated strings, or
573  * buffers to any stream. The characters will be converted into the appropriate
574  * format for that stream.
575  */
576  
577 /**
578  * SECTION:glk-read
579  * @short_description: Reading from streams
580  * @include: libchimara/glk.h
581  *
582  * You can read Latin-1 or Unicode characters, buffers, or whole lines from any
583  * stream. The characters will be converted into the form in which you request
584  * them.
585  */
586  
587 /**
588  * SECTION:glk-closing-streams
589  * @short_description: Closing streams and retrieving their character counts
590  * @include: libchimara/glk.h
591  *
592  * When you close a Glk stream, you have the opportunity to examine the
593  * character counts &mdash; the number of characters written to or read from the
594  * stream.
595  */
596
597 /**
598  * SECTION:glk-stream-positions
599  * @short_description: Moving the read/write mark
600  * @include: libchimara/glk.h
601  *
602  * You can set the position of the read/write mark in a stream.
603  *
604  * <note><para>
605  *   Which makes one wonder why they're called <quote>streams</quote> in the
606  *   first place. Oh well.
607  * </para></note>
608  */
609
610 /**
611  * SECTION:glk-styles
612  * @short_description: Changing the appearance of printed text
613  * @include: libchimara/glk.h
614  *
615  * You can send style-changing commands to an output stream. After a style
616  * change, new text which is printed to that stream will be given the new style,
617  * whatever that means for the stream in question. For a window stream, the text
618  * will appear in that style. For a memory stream, style changes have no effect.
619  * For a file stream, if the machine supports styled text files, the styles may
620  * be written to the file; more likely the style changes will have no effect.
621  * 
622  * Styles are exclusive. A character is shown with exactly one style, not a 
623  * subset of the possible styles.
624  *
625  * <note><para>
626  *  Note that every stream and window has its own idea of the <quote>current 
627  *  style.</quote> Sending a style command to one window or stream does not
628  *  affect any others.
629  * </para></note>
630  * <note><para>
631  *  Except for a window's echo stream; see <link 
632  *  linkend="chimara-Echo-Streams">Echo Streams</link>.
633  * </para></note>
634  * 
635  * The styles are intended to distinguish meaning and use, not formatting. There
636  * is no standard definition of what each style will look like. That is left up
637  * to the Glk library, which will choose an appearance appropriate for the
638  * platform's interface and the player's preferences.
639  * 
640  * There are currently eleven styles defined. More may be defined in the future.
641  * 
642  * Styles may be distinguished on screen by font, size, color, indentation,
643  * justification, and other attributes. Note that some attributes (notably
644  * justification and indentation) apply to entire paragraphs. If possible and
645  * relevant, you should apply a style to an entire paragraph &mdash; call 
646  * glk_set_style() immediately after printing the newline at the beginning of
647  * the text, and do the same at the end.
648  * 
649  * <note><para>
650  *  For example, %style_Header may well be centered text. If you print 
651  *  <quote>Welcome to Victim (a short interactive mystery)</quote>, and only the
652  *  word <quote>Victim</quote> is in the %style_Header, the center-justification
653  *  attribute will be lost. Similarly, a block quote is usually indented on both
654  *  sides, but indentation is only meaningful when applied to an entire line or
655  *  paragraph, so block quotes should take up an entire paragraph. Contrariwise,
656  *  %style_Emphasized need not be used on an entire paragraph. It is often used
657  *  for single emphasized words in normal text, so you can expect that it will
658  *  appear properly that way; it will be displayed in italics or underlining, 
659  *  not center-justified or indented.
660  * </para></note> 
661  * 
662  * <note><para>
663  *  Yes, this is all a matter of mutual agreement between game authors and game
664  *  players. It's not fixed by this specification. That's natural language for
665  *  you.
666  * </para></note>
667  */
668
669 /**
670  * SECTION:glk-stylehints
671  * @short_description: Setting style hints
672  * @include: libchimara/glk.h
673  *
674  * There are no guarantees of how styles will look, but you can make 
675  * suggestions.
676  *
677  * Initially, no hints are set for any window type or style. Note that having no
678  * hint set is not the same as setting a hint with value 0.
679  * 
680  * These functions do <emphasis>not</emphasis> affect 
681  * <emphasis>existing</emphasis> windows. They affect the windows which you
682  * create subsequently. If you want to set hints for all your game windows, call
683  * glk_stylehint_set() before you start creating windows. If you want different
684  * hints for different windows, change the hints before creating each window.
685  * 
686  * <note><para>
687  *  This policy makes life easier for the interpreter. It knows everything about
688  *  a particular window's appearance when the window is created, and it doesn't
689  *  have to change it while the window exists.
690  * </para></note>
691  * 
692  * Hints are hints. The interpreter may ignore them, or give the player a choice
693  * about whether to accept them. Also, it is never necessary to set hints. You
694  * don't have to suggest that %style_Preformatted be fixed-width, or 
695  * %style_Emphasized be boldface or italic; they will have appropriate defaults.
696  * Hints are for situations when you want to <emphasis>change</emphasis> the 
697  * appearance of a style from what it would ordinarily be. The most common case
698  * when this is appropriate is for the styles %style_User1 and %style_User2.
699  * 
700  * There are currently ten style hints defined. More may be defined in the 
701  * future. 
702  * 
703  * Again, when passing a style hint to a Glk function, any value is actually 
704  * legal. If the interpreter does not recognize the stylehint value, it will 
705  * ignore it. 
706  * <note><para>
707  *  This policy allows for the future definition of style hints without breaking
708  *  old Glk libraries.
709  * </para></note> 
710  */
711
712 /**
713  * SECTION:glk-stream-types
714  * @short_description: Window, memory, and file streams
715  * @include: libchimara/glk.h
716  *
717  * <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
718  * <para>
719  * Every window has an output stream associated with it. This is created
720  * automatically, with %filemode_Write, when you open the window. You get it
721  * with glk_window_get_stream().
722  * 
723  * A window stream cannot be closed with glk_stream_close(). It is closed
724  * automatically when you close its window with glk_window_close().
725  * 
726  * Only printable characters (including newline) may be printed to a window
727  * stream. See <link linkend="chimara-Character-Encoding">Character 
728  * Encoding</link>.
729  * </para>
730  * </refsect2>
731  * <refsect2 id="chimara-Memory-Streams"><title>Memory Streams</title>
732  * <para>
733  * You can open a stream which reads from or writes to a space in memory. See
734  * glk_stream_open_memory() and glk_stream_open_memory_uni(). When opening a
735  * memory stream, you specify a buffer to which the stream's output will be
736  * written, and its length @buflen.
737  *
738  * When outputting, if more than @buflen characters are written to the stream,
739  * all of them beyond the buffer length will be thrown away, so as not to
740  * overwrite the buffer. (The character count of the stream will still be
741  * maintained correctly. That is, it will count the number of characters written
742  * into the stream, not the number that fit into the buffer.)
743  *
744  * If the buffer is %NULL, or for that matter if @buflen is zero, then 
745  * <emphasis>everything</emphasis> written to the stream is thrown away. This
746  * may be useful if you are interested in the character count.
747  *
748  * When inputting, if more than @buflen characters are read from the stream, the
749  * stream will start returning -1 (signalling end-of-file.) If the buffer is 
750  * %NULL, the stream will always return end-of-file.
751  *
752  * The data is written to the buffer exactly as it was passed to the printing
753  * functions (glk_put_char(), etc.); input functions will read the data exactly
754  * as it exists in memory. No platform-dependent cookery will be done on it.
755  *
756  * <note><para>
757  *   You can write a disk file in text mode, but a memory stream is effectively
758  *   always in binary mode.
759  * </para></note>
760  * 
761  * Whether reading or writing, the contents of the buffer are undefined until
762  * the stream is closed. The library may store the data there as it is written,
763  * or deposit it all in a lump when the stream is closed. It is illegal to
764  * change the contents of the buffer while the stream is open.
765  * </para>
766  * </refsect2>
767  * <refsect2 id="chimara-File-Streams"><title>File Streams</title>
768  * <para>
769  * You can open a stream which reads from or writes to a disk file. See 
770  * glk_stream_open_file() and glk_stream_open_file_uni().
771  *
772  * The file may be written in text or binary mode; this is determined by the
773  * file reference you open the stream with. Similarly, platform-dependent
774  * attributes such as file type are determined by the file reference. See <link
775  * linkend="chimara-File-References">File References</link>.
776  * </para>
777  * </refsect2>
778  */
779  
780 /**
781  * SECTION:glk-stream-other
782  * @short_description: Miscellaneous functions for streams
783  * @include: libchimara/glk.h
784  *
785  * This section includes functions for streams that don't fit anywhere else.
786  */
787
788 /**
789  * SECTION:glk-fileref
790  * @short_description: A platform-independent way to refer to disk files
791  * @include: libchimara/glk.h
792  *
793  * You deal with disk files using file references. Each fileref is an opaque C
794  * structure pointer; see <link linkend="chimara-Opaque-Objects">Opaque 
795  * Objects</link>.
796  * 
797  * A file reference contains platform-specific information about the name and
798  * location of the file, and possibly its type, if the platform has a notion of
799  * file type. It also includes a flag indication whether the file is a text file
800  * or binary file. 
801  *
802  * <note><para>
803  *   Note that this is different from the standard C I/O library, in which you
804  *   specify text or binary mode when the file is opened.
805  * </para></note>
806  * 
807  * A fileref does not have to refer to a file which actually exists. You can
808  * create a fileref for a nonexistent file, and then open it in write mode to
809  * create a new file.
810  * 
811  * You always provide a usage argument when you create a fileref. The usage is a
812  * mask of constants (see below) to indicate the file type and the mode (text or
813  * binary.) These values are used when you create a new file, and also to filter
814  * file lists when the player is selecting a file to load. 
815  * 
816  * In general, you should use text mode if the player expects to read the file
817  * with a platform-native text editor; you should use binary mode if the file is
818  * to be read back by your program, or if the data must be stored exactly. Text
819  * mode is appropriate for %fileusage_Transcript; binary mode is appropriate for
820  * %fileusage_SavedGame and probably for %fileusage_InputRecord. %fileusage_Data
821  * files may be text or binary, depending on what you use them for. 
822  */
823  
824 /**
825  * SECTION:glk-fileref-types
826  * @short_description: Four different ways to create a file reference
827  * @include: libchimara/glk.h
828  *
829  * There are four different functions for creating a fileref, depending on how
830  * you wish to specify it. Remember that it is always possible that a fileref
831  * creation will fail and return %NULL.
832  */
833  
834 /**
835  * SECTION:glk-fileref-other
836  * @short_description: Miscellaneous functions for file references
837  * @include: libchimara/glk.h
838  *
839  * This section includes functions for file references that don't fit anywhere
840  * else.
841  */
842
843 /** 
844  * SECTION:blorb-program
845  * @short_description: How to use the Blorb layer in your program
846  * @include: libchimara/glk.h, libchimara/gi_blorb.h
847  *
848  * If you wish your program to load its resources from a Blorb file, you need to
849  * find and open that file in your startup code. (See <link 
850  * linkend="chimara-Startup-Options">Startup Options</link>.) Each platform will
851  * have appropriate functions available for finding startup data. Be sure to
852  * open the file in binary mode, not text mode. Once you have opened the file as
853  * a Glk stream, pass it to giblorb_set_resource_map().
854  *
855  * If you do not call giblorb_set_resource_map() in your startup code, or if it
856  * fails, the library is left to its own devices for finding resources. Some
857  * libraries may try to load resources from individual files &mdash; 
858  * <filename>PIC1</filename>, <filename>PIC2</filename>, 
859  * <filename>PIC3</filename>, and so on. (See the Blorb specification for more 
860  * on this approach.) Other libraries will not have any other loading mechanism
861  * at all; no resources will be available. 
862  */
863
864 /**
865  * SECTION:blorb-layer
866  * @short_description: The platform-independent functions in the Blorb layer
867  * @include: libchimara/glk.h, libchimara/gi_blorb.h
868  *
869  * These are the functions which are implemented in 
870  * <filename>gi_blorb.c</filename>. They will be compiled into the library, but
871  * they are the same on every platform. In general, only the library needs to
872  * call these functions. The Glk program should allow the library to do all the
873  * resource handling.
874  */ 
875  
876 /** 
877  * SECTION:blorb-errors
878  * @short_description: Error codes returned by the Blorb layer functions
879  * @include: libchimara/glk.h, libchimara/gi_blorb.h
880  *
881  * All Blorb layer functions, including giblorb_set_resource_map(), return the
882  * following error codes.
883  */
884
885 /**
886  * SECTION:glkext-startup
887  * @short_description: Parsing startup options
888  * @include: libchimara/glk.h, libchimara/glkstart.h
889  *
890  * This section describes an extension to Glk for parsing command-line startup
891  * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and
892  * GlkTerm. 
893  *
894  * When you compile a Glk program, you may define a function called 
895  * glkunix_startup_code(), and an array <code>glkunix_arguments[]</code>. These
896  * set up various Unix-specific options used by the Glk library. There is a
897  * sample <quote><filename>glkstart.c</filename></quote> file included in this 
898  * package; you should modify it to your needs.
899  * 
900  * |[ extern #glkunix_argumentlist_t glkunix_arguments[]; ]|
901  *  
902  * The <code>glkunix_arguments[]</code> array is a list of command-line 
903  * arguments that your program can accept. The library will sort these out of 
904  * the command line and pass them on to your code.
905  */
906
907 /**
908  * SECTION:glkext-unix
909  * @short_description: Unix-specific functions
910  * @include: libchimara/glk.h, libchimara/glkstart.h
911  *
912  * This section describes an extension to Glk for various Unix functions. It was
913  * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm.
914  *
915  * You can put other startup code in glkunix_startup_code(). This should
916  * generally be limited to finding and opening data files. There are a few Unix
917  * Glk library functions which are convenient for this purpose.
918  */
919  
920 /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/
921
922 /**
923  * glui32:
924  *
925  * A 32-bit unsigned integer type, used wherever possible in Glk.
926  */
927  
928 /**
929  * glsi32:
930  *
931  * A 32-bit signed integer type, rarely used.
932  */
933
934 /**
935  * GLK_MODULE_UNICODE:
936  *
937  * If this preprocessor symbol is defined, so are all the Unicode functions and
938  * constants (see %gestalt_Unicode). If not, not.
939  */
940
941 /**
942  * winid_t:
943  *
944  * Opaque structure representing a Glk window. It has no user-accessible 
945  * members.
946  */
947  
948 /**
949  * strid_t:
950  *
951  * Opaque structure representing an input or output stream. It has no
952  * user-accessible members.
953  */
954  
955 /**
956  * frefid_t:
957  * 
958  * Opaque structure representing a file reference. It has no user-accessible
959  * members.
960  */
961
962 /**
963  * gestalt_Version:
964  *
965  * For an example of the gestalt mechanism, consider the selector
966  * %gestalt_Version. If you do
967  * |[
968  * #glui32 res;
969  * res = #glk_gestalt(#gestalt_Version, 0);
970  * ]|
971  * <code>res</code> will be set to a 32-bit number which encodes the version of
972  * the Glk spec which the library implements. The upper 16 bits stores the major
973  * version number; the next 8 bits stores the minor version number; the low 8 
974  * bits stores an even more minor version number, if any.
975  *
976  * <note><para>
977  *   So the version number 78.2.11 would be encoded as 0x004E020B.
978  * </para></note>
979  *
980  * The current Glk specification version is 0.7.0, so this selector will return
981  * 0x00000700.
982  *
983  * |[
984  * #glui32 res;
985  * res = #glk_gestalt_ext(#gestalt_Version, 0, NULL, 0);
986  * ]|
987  * does exactly the same thing. Note that, in either case, the second argument 
988  * is not used; so you should always pass 0 to avoid future surprises.
989  */
990
991 /**
992  * gestalt_CharInput:
993  *
994  * If you set <code>ch</code> to a character code, or a special code (from
995  * 0xFFFFFFFF down), and call
996  * |[
997  * #glui32 res;
998  * res = #glk_gestalt(#gestalt_CharInput, ch);
999  * ]|
1000  * then <code>res</code> will be %TRUE (1) if that character can be typed by
1001  * the player in character input, and %FALSE (0) if not. See <link
1002  * linkend="chimara-Character-Input">Character Input</link>.
1003  */
1004
1005 /**
1006  * gestalt_LineInput:
1007  *
1008  * If you set <code>ch</code> to a character code, and call
1009  * |[
1010  * #glui32 res;
1011  * res = #glk_gestalt(#gestalt_LineInput, ch);
1012  * ]|
1013  * then <code>res</code> will be %TRUE (1) if that character can be typed by the
1014  * player in line input, and %FALSE (0) if not. Note that if <code>ch</code> is 
1015  * a nonprintable Latin-1 character (0 to 31, 127 to 159), then this is 
1016  * guaranteed to return %FALSE. See <link linkend="chimara-Line-Input">Line
1017  * Input</link>.
1018  */
1019
1020 /**
1021  * gestalt_CharOutput:
1022  *
1023  * If you set <code>ch</code> to a character code (Latin-1 or higher), and call
1024  * |[
1025  * #glui32 res, len;
1026  * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &amp;len, 1);
1027  * ]|
1028  * then <code>res</code> will be one of %gestalt_CharOutput_CannotPrint,
1029  * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see 
1030  * below.)
1031  * 
1032  * In all cases, <code>len</code> (the #glui32 value pointed at by the third
1033  * argument) will be the number of actual glyphs which will be used to represent
1034  * the character. In the case of %gestalt_CharOutput_ExactPrint, this will 
1035  * always be 1; for %gestalt_CharOutput_CannotPrint, it may be 0 (nothing 
1036  * printed) or higher; for %gestalt_CharOutput_ApproxPrint, it may be 1 or 
1037  * higher. This information may be useful when printing text in a fixed-width 
1038  * font.
1039  *
1040  * <note><para>
1041  *   As described in <link linkend="chimara-Other-API-Conventions">Other API
1042  *   Conventions</link>, you may skip this information by passing %NULL as the
1043  *   third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead.
1044  * </para></note>
1045  *
1046  * This selector will always return %gestalt_CharOutput_CannotPrint if 
1047  * <code>ch</code> is an unprintable eight-bit character (0 to 9, 11 to 31, 127 
1048  * to 159.)
1049  *
1050  * <note><para>
1051  *   Make sure you do not get confused by signed byte values. If you set a
1052  *   <quote><type>char</type></quote> variable <code>ch</code> to 0xFE, the 
1053  *   small-thorn character (&thorn;), and then call
1054  *   |[ res = #glk_gestalt(#gestalt_CharOutput, ch); ]|
1055  *   then (by the definition of C/C++) <code>ch</code> will be sign-extended to
1056  *   0xFFFFFFFE, which is not a legitimate character, even in Unicode. You 
1057  *   should write
1058  *   |[ res = #glk_gestalt(#gestalt_CharOutput, (unsigned char)ch); ]|
1059  *   instead.
1060  * </para></note>
1061  * <note><para>
1062  *   Unicode includes the concept of non-spacing or combining characters, which 
1063  *   do not represent glyphs; and double-width characters, whose glyphs take up
1064  *   two spaces in a fixed-width font. Future versions of this spec may 
1065  *   recognize these concepts by returning a <code>len</code> of 0 or 2 when
1066  *   %gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to 
1067  *   a policy of <quote>simple stuff first</quote>.
1068  * </para></note>
1069  */
1070  
1071 /**
1072  * gestalt_CharOutput_CannotPrint:
1073  *
1074  * When the %gestalt_CharOutput selector returns this for a character, the
1075  * character cannot be meaningfully printed. If you try, the player may see
1076  * nothing, or may see a placeholder.
1077  */
1078
1079 /**
1080  * gestalt_CharOutput_ApproxPrint:
1081  *
1082  * When the %gestalt_CharOutput selector returns this for a character, the 
1083  * library will print some approximation of the character. It will be more or 
1084  * less right, but it may not be precise, and it may not be distinguishable from
1085  * other, similar characters. (Examples: 
1086  * <quote><computeroutput>ae</computeroutput></quote> for the one-character
1087  * <quote>&aelig;</quote> ligature, 
1088  * <quote><computeroutput>e</computeroutput></quote> for 
1089  * <quote>&egrave;</quote>, <quote><computeroutput>|</computeroutput></quote> 
1090  * for a broken vertical bar (&brvbar;).)
1091  */
1092  
1093 /**
1094  * gestalt_CharOutput_ExactPrint:
1095  *
1096  * When the %gestalt_CharOutput selector returns this for a character, the
1097  * character will be printed exactly as defined.
1098  */
1099
1100 /**
1101  * gestalt_Unicode:
1102  *
1103  * The basic text functions will be available in every Glk library. The Unicode
1104  * functions may or may not be available. Before calling them, you should use
1105  * the following gestalt selector:
1106  * |[
1107  * glui32 res;
1108  * res = #glk_gestalt(#gestalt_Unicode, 0);
1109  * ]|
1110  * 
1111  * This returns 1 if the Unicode functions are available. If it returns 0, you
1112  * should not try to call them. They may print nothing, print gibberish, or
1113  * cause a run-time error. The Unicode functions include
1114  * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),  
1115  * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
1116  * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
1117  * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
1118  * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
1119  * glk_request_char_event_uni(), glk_request_line_event_uni(),
1120  * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
1121  * 
1122  * If you are writing a C program, there is an additional complication. A
1123  * library which does not support Unicode may not implement the Unicode
1124  * functions at all. Even if you put gestalt tests around your Unicode calls,
1125  * you may get link-time errors. If the 
1126  * <filename class="headerfile">glk.h</filename> file is so old that it does not
1127  * declare the Unicode functions and constants, you may even get compile-time
1128  * errors.
1129  * 
1130  * To avoid this, you can perform a preprocessor test for the existence of
1131  * #GLK_MODULE_UNICODE. 
1132  */
1133
1134 /**
1135  * gestalt_Timer:
1136  *
1137  * You can test whether the library supports timer events:
1138  * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]|
1139  * This returns 1 if timer events are supported, and 0 if they are not.
1140  */
1141  
1142 /**
1143  * evtype_None:
1144  *
1145  * No event. This is a placeholder, and glk_select() never returns it.
1146  */
1147
1148 /**
1149  * evtype_Timer:
1150  *
1151  * An event that repeats at fixed intervals. See <link 
1152  * linkend="chimara-Timer-Events">Timer Events</link>.
1153  */
1154  
1155 /**
1156  * evtype_CharInput:
1157  *
1158  * A keystroke event in a window. See <link 
1159  * linkend="chimara-Character-Input-Events">Character Input Events</link>.
1160  *
1161  * If a window has a pending request for character input, and the player hits a
1162  * key in that window, glk_select() will return an event whose type is
1163  * %evtype_CharInput. Once this happens, the request is complete; it is no 
1164  * longer pending. You must call glk_request_char_event() or
1165  * glk_request_char_event_uni() if you want another character from that window.
1166  * 
1167  * In the event structure, @win tells what window the event came from. @val1 
1168  * tells what character was entered; this will be a character code, or a special
1169  * keycode. (See <link linkend="chimara-Character-Input">Character 
1170  * Input</link>.) If you called glk_request_char_event(), @val1 will be in 
1171  * 0..255, or else a special keycode. In any case, @val2 will be 0.
1172  */
1173
1174 /**
1175  * evtype_LineInput:
1176  *
1177  * A full line of input completed in a window. See <link 
1178  * linkend="chimara-Line-Input-Events">Line Input Events</link>.
1179  *
1180  * If a window has a pending request for line input, and the player hits
1181  * <keycap>enter</keycap> in that window (or whatever action is appropriate to
1182  * enter his input), glk_select() will return an event whose type is
1183  * %evtype_LineInput. Once this happens, the request is complete; it is no 
1184  * longer pending. You must call glk_request_line_event() if you want another 
1185  * line of text from that window.
1186  * 
1187  * In the event structure, @win tells what window the event came from. @val1 
1188  * tells how many characters were entered. @val2 will be 0. The characters
1189  * themselves are stored in the buffer specified in the original
1190  * glk_request_line_event() or glk_request_line_event_uni() call. 
1191  *
1192  * <note><para>There is no null terminator stored in the buffer.</para></note>
1193  * 
1194  * It is illegal to print anything to a window which has line input pending. 
1195  *
1196  * <note><para>
1197  *   This is because the window may be displaying and editing the player's 
1198  *   input, and printing anything would make life unnecessarily complicated for
1199  *   the library.
1200  * </para></note>
1201  */
1202
1203 /**
1204  * evtype_MouseInput:
1205  *
1206  * A mouse click in a window. See <link 
1207  * linkend="chimara-Mouse-Input-Events">Mouse Input Events</link>.
1208  */
1209  
1210 /**
1211  * evtype_Arrange:
1212  *
1213  * An event signalling that the sizes of some windows have changed. 
1214  * 
1215  * Some platforms allow the player to resize the Glk window during play. This 
1216  * will naturally change the sizes of your windows. If this occurs, then
1217  * immediately after all the rearrangement, glk_select() will return an event
1218  * whose type is %evtype_Arrange. You can use this notification to redisplay the
1219  * contents of a graphics or text grid window whose size has changed.
1220  *
1221  * <note><para>
1222  *   The display of a text buffer window is entirely up to the library, so you
1223  *   don't need to worry about those.
1224  * </para></note>
1225  * 
1226  * In the event structure, @win will be %NULL if all windows are affected. If 
1227  * only some windows are affected, @win will refer to a window which contains 
1228  * all the affected windows. @val1 and @val2 will be 0.
1229  *
1230  * <note><para>
1231  *   You can always play it safe, ignore @win, and redraw every graphics and 
1232  *   text grid window.
1233  * </para></note>
1234  *
1235  * An arrangement event is guaranteed to occur whenever the player causes any
1236  * window to change size, as measured by its own metric. 
1237  *
1238  * <note><para>
1239  *   Size changes caused by you &mdash; for example, if you open, close, or 
1240  *   resize a window &mdash; do not trigger arrangement events. You must be 
1241  *   aware of the effects of your window management, and redraw the windows that
1242  *   you affect.
1243  * </para></note>
1244  * 
1245  * <note><para>
1246  *   It is possible that several different player actions can cause windows to
1247  *   change size. For example, if the player changes the screen resolution, an
1248  *   arrangement event might be triggered. This might also happen if the player
1249  *   changes his display font to a different size; the windows would then be
1250  *   different <quote>sizes</quote> in the metric of rows and columns, which is
1251  *   the important metric and the only one you have access to.
1252  * </para></note>
1253  * 
1254  * Arrangement events, like timer events, can be returned by glk_select_poll().
1255  * But this will not occur on all platforms. You must be ready to receive an
1256  * arrangement event when you call glk_select_poll(), but it is possible that it
1257  * will not arrive until the next time you call glk_select(). 
1258  *
1259  * <note><para>
1260  *   This is because on some platforms, window resizing is handled as part of
1261  *   player input; on others, it can be triggered by an external process such as 
1262  *   a window manager.
1263  * </para></note>
1264  */
1265
1266 /**
1267  * evtype_Redraw:
1268  *
1269  * An event signalling that graphics windows must be redrawn.
1270  *
1271  * On platforms that support graphics, it is possible that the contents of a
1272  * graphics window will be lost, and have to be redrawn from scratch. If this
1273  * occurs, then glk_select() will return an event whose type is %evtype_Redraw.
1274  *
1275  * In the event structure, @win will be %NULL if all windows are affected. If 
1276  * only some windows are affected, @win will refer to a window which contains 
1277  * all the affected windows. @val1 and @val2 will be 0.
1278  *
1279  * <note><para>
1280  *   You can always play it safe, ignore @win, and redraw every graphics window.
1281  * </para></note>
1282  *
1283  * Affected windows are already cleared to their background color when you 
1284  * receive the redraw event.
1285  * 
1286  * Redraw events can be returned by glk_select_poll(). But, like arrangement
1287  * events, this is platform-dependent. See %evtype_Arrange.
1288  *
1289  * For more about redraw events and how they affect graphics windows, see <link
1290  * linkend="chimara-Graphics-Windows">Graphics Windows</link>.
1291  */
1292
1293 /**
1294  * evtype_SoundNotify:
1295  *
1296  * On platforms that support sound, you can request to receive an 
1297  * %evtype_SoundNotify event when a sound finishes playing. See <link
1298  * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
1299  */
1300  
1301 /**
1302  * evtype_Hyperlink:
1303  * 
1304  * On platforms that support hyperlinks, you can request to receive an
1305  * %evtype_Hyperlink event when the player selects a link. See <link
1306  * linkend="chimara-Accepting-Hyperlink-Events">Accepting Hyperlink 
1307  * Events</link>.
1308  */
1309
1310 /**
1311  * event_t:
1312  * @type: the event type
1313  * @win: the window that spawned the event, or %NULL
1314  * @val1: information, the meaning of which depends on the type of event
1315  * @val2: more information, the meaning of which depends on the type of event
1316  *
1317  * The event structure is self-explanatory. @type is the event type. The window
1318  * that spawned the event, if relevant, is in @win. The remaining fields contain
1319  * more information specific to the event.
1320  *
1321  * The event types are described below. Note that %evtype_None is zero, and the
1322  * other values are positive. Negative event types (0x80000000 to 0xFFFFFFFF) 
1323  * are reserved for implementation-defined events. 
1324  */
1325
1326 /**
1327  * keycode_Unknown:
1328  *
1329  * Represents any key that has no Latin-1 or special code.
1330  */
1331
1332 /**
1333  * keycode_Left:
1334  *
1335  * Represents the <keycap function="left">left arrow</keycap> key.
1336  */
1337  
1338 /**
1339  * keycode_Right:
1340  *
1341  * Represents the <keycap function="right">right arrow</keycap> key.
1342  */
1343  
1344 /**
1345  * keycode_Up:
1346  *
1347  * Represents the <keycap function="up">up arrow</keycap> key.
1348  */
1349  
1350 /**
1351  * keycode_Down:
1352  *
1353  * Represents the <keycap function="down">down arrow</keycap> key.
1354  */
1355  
1356 /**
1357  * keycode_Return:
1358  *
1359  * Represents the <keycap function="enter">return</keycap> or <keycap 
1360  * function="enter">enter</keycap> keys.
1361  */
1362
1363 /**
1364  * keycode_Delete:
1365  *
1366  * Represents the <keycap function="delete">delete</keycap> or <keycap
1367  * function="backspace">backspace</keycap> keys.
1368  */
1369  
1370 /**
1371  * keycode_Escape:
1372  *
1373  * Represents the <keycap function="escape">escape</keycap> key.
1374  */
1375  
1376 /**
1377  * keycode_Tab:
1378  *
1379  * Represents the <keycap function="tab">tab</keycap> key.
1380  */
1381
1382 /**
1383  * keycode_PageUp:
1384  *
1385  * Represents the <keycap function="pageup">page up</keycap> key.
1386  */
1387
1388 /**
1389  * keycode_PageDown:
1390  *
1391  * Represents the <keycap function="pagedown">page down</keycap> key.
1392  */
1393
1394 /**
1395  * keycode_Home:
1396  *
1397  * Represents the <keycap function="home">home</keycap> key.
1398  */
1399  
1400 /**
1401  * keycode_End:
1402  *
1403  * Represents the <keycap function="end">end</keycap> key.
1404  */
1405
1406 /**
1407  * keycode_Func1:
1408  *
1409  * Represents the <keycap>F1</keycap> key.
1410  */
1411  
1412 /**
1413  * keycode_Func2:
1414  *
1415  * Represents the <keycap>F2</keycap> key.
1416  */
1417
1418 /**
1419  * keycode_Func3:
1420  *
1421  * Represents the <keycap>F3</keycap> key.
1422  */
1423
1424 /**
1425  * keycode_Func4:
1426  *
1427  * Represents the <keycap>F4</keycap> key.
1428  */
1429
1430 /**
1431  * keycode_Func5:
1432  *
1433  * Represents the <keycap>F5</keycap> key.
1434  */
1435  
1436 /**
1437  * keycode_Func6:
1438  *
1439  * Represents the <keycap>F6</keycap> key.
1440  */
1441
1442 /**
1443  * keycode_Func7:
1444  *
1445  * Represents the <keycap>F7</keycap> key.
1446  */
1447
1448 /**
1449  * keycode_Func8:
1450  *
1451  * Represents the <keycap>F8</keycap> key.
1452  */
1453
1454 /**
1455  * keycode_Func9:
1456  *
1457  * Represents the <keycap>F9</keycap> key.
1458  */
1459
1460 /**
1461  * keycode_Func10:
1462  *
1463  * Represents the <keycap>F10</keycap> key.
1464  */
1465
1466 /**
1467  * keycode_Func11:
1468  *
1469  * Represents the <keycap>F11</keycap> key.
1470  */
1471
1472 /**
1473  * keycode_Func12:
1474  *
1475  * Represents the <keycap>F12</keycap> key.
1476  */
1477
1478 /**
1479  * keycode_MAXVAL:
1480  *
1481  * This value is equal to the number of special keycodes. The last keycode is
1482  * always 
1483  * <inlineequation>
1484  *   <alt>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</alt>
1485  *   <mathphrase>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</mathphrase>
1486  * </inlineequation>
1487  * .
1488  */
1489
1490 /**
1491  * style_Normal: 
1492  *
1493  * The style of normal or body text. A new window or stream always starts with
1494  * %style_Normal as the current style.
1495  */
1496
1497 /**
1498  * style_Emphasized: 
1499  *
1500  * Text which is emphasized.
1501  */
1502
1503 /**
1504  * style_Preformatted: 
1505  *
1506  * Text which has a particular arrangement of characters.
1507  * <note><para>
1508  *  This style, unlike the others, does have a standard appearance; it will 
1509  *  always be a fixed-width font. This is a concession to practicality. Games 
1510  *  often want to display maps or diagrams using character graphics, and this is
1511  *  the style for that.
1512  * </para></note>
1513  */
1514  
1515 /**
1516  * style_Header: 
1517  * 
1518  * Text which introduces a large section. This is suitable for the title of an 
1519  * entire game, or a major division such as a chapter.
1520  */
1521
1522 /**
1523  * style_Subheader: 
1524  * 
1525  * Text which introduces a smaller section within a large section. 
1526  * <note><para>
1527  *  In a Colossal-Cave-style game, this is suitable for the name of a room (when
1528  *  the player looks around.)
1529  * </para></note>
1530  */
1531
1532 /**
1533  * style_Alert: 
1534  *
1535  * Text which warns of a dangerous condition, or one which the player should pay
1536  * attention to.
1537  */
1538
1539 /**
1540  * style_Note: 
1541  *
1542  * Text which notifies of an interesting condition.
1543  * <note><para>
1544  *  This is suitable for noting that the player's score has changed.
1545  * </para></note>
1546  */
1547
1548 /**
1549  * style_BlockQuote: 
1550  *
1551  * Text which forms a quotation or otherwise abstracted text.
1552  */
1553
1554 /**
1555  * style_Input: 
1556  *
1557  * Text which the player has entered. You should generally not use this style at
1558  * all; the library uses it for text which is typed during a line-input request.
1559  * One case when it is appropriate for you to use %style_Input is when you are 
1560  * simulating player input by reading commands from a text file.
1561  */
1562
1563 /**
1564  * style_User1: 
1565  * 
1566  * This style has no particular semantic meaning. You may define a meaning 
1567  * relevant to your own work, and use it as you see fit.
1568  */
1569
1570 /**
1571  * style_User2: 
1572  *
1573  * Another style available for your use. 
1574  */
1575  
1576 /**
1577  * style_NUMSTYLES:
1578  * 
1579  * The number of styles defined in this library.
1580  */
1581
1582 /**
1583  * stream_result_t:
1584  * @readcount: Number of characters read from the stream.
1585  * @writecount: Number of characters printed to the stream, including ones that
1586  * were thrown away.
1587  *
1588  * If you are interested in the character counts of a stream (see <link
1589  * linkend="chimara-Streams">Streams</link>), then you can pass a pointer to
1590  * #stream_result_t as an argument of glk_stream_close() or glk_window_close().
1591  * The structure will be filled with the stream's final character counts.
1592  */
1593
1594 /**
1595  * wintype_AllTypes:
1596  *
1597  * A constant representing all window types, which may be used as the @wintype
1598  * argument in glk_stylehint_set().
1599  */
1600
1601 /** 
1602  * wintype_Pair:
1603  * 
1604  * A pair window is completely filled by the two windows it contains. It
1605  * supports no input and no output, and it has no size.
1606  * 
1607  * You cannot directly create a pair window; one is automatically created
1608  * every time you split a window with glk_window_open(). Pair windows are
1609  * always created with a rock value of 0.
1610  * 
1611  * You can close a pair window with glk_window_close(); this also closes every
1612  * window contained within the pair window.
1613  * 
1614  * It is legal to split a pair window when you call glk_window_open().
1615  */
1616  
1617 /**
1618  * wintype_Blank:
1619  * 
1620  * A blank window is always blank. It supports no input and no output. (You
1621  * can call glk_window_get_stream() on it, as you can with any window, but
1622  * printing to the resulting stream has no effect.) A blank window has no
1623  * size; glk_window_get_size() will return (0,0), and it is illegal to set a
1624  * window split with a fixed size in the measurement system of a blank window.
1625  * 
1626  * <note><para>
1627  *   A blank window is not the same as there being no windows. When Glk starts
1628  *   up, there are no windows at all, not even a window of the blank type.
1629  * </para></note>
1630  */
1631  
1632 /**
1633  * wintype_TextBuffer: 
1634  *
1635  * A text buffer window contains a linear stream of text. It supports output;
1636  * when you print to it, the new text is added to the end. There is no way for
1637  * you to affect text which has already been printed. There are no guarantees
1638  * about how much text the window keeps; old text may be stored forever, so
1639  * that the user can scroll back to it, or it may be thrown away as soon as it
1640  * scrolls out of the window. 
1641  * 
1642  * <note><para>
1643  *   Therefore, there may or may not be a player-controllable scroll bar or
1644  *   other scrolling widget.
1645  * </para></note>
1646  * 
1647  * The display of the text in a text buffer is up to the library. Lines will
1648  * probably not be broken in the middles of words &mdash; but if they are, the
1649  * library is not doing anything illegal, only ugly. Text selection and copying
1650  * to a clipboard, if available, are handled however is best on the player's
1651  * machine. Paragraphs (as defined by newline characters in the output) may be
1652  * indented. 
1653  * 
1654  * <note><para>
1655  *   You should not, in general, fake this by printing spaces before each
1656  *   paragraph of prose text. Let the library and player preferences handle
1657  *   that. Special cases (like indented lists) are of course up to you.
1658  * </para></note>
1659  * 
1660  * When a text buffer is cleared (with glk_window_clear()), the library will do
1661  * something appropriate; the details may vary. It may clear the window, with
1662  * later text appearing at the top &mdash; or the bottom. It may simply print
1663  * enough blank lines to scroll the current text out of the window. It may
1664  * display a distinctive page-break symbol or divider.
1665  * 
1666  * The size of a text buffer window is necessarily imprecise. Calling
1667  * glk_window_get_size() will return the number of rows and columns that would
1668  * be available <emphasis>if</emphasis> the window was filled with 
1669  * <quote>0</quote> (zero) characters in the <quote>normal</quote> font.
1670  * However, the window may use a non-fixed-width font, so that number of
1671  * characters in a line could vary. The window might even support 
1672  * variable-height text (say, if the player is using large text for emphasis);
1673  * that would make the number of lines in the window vary as well.
1674  * 
1675  * Similarly, when you set a fixed-size split in the measurement system of a
1676  * text buffer, you are setting a window which can handle a fixed number of rows
1677  * (or columns) of <quote>0</quote> characters. The number of rows (or
1678  * characters) that will actually be displayed depends on font variances.
1679  * 
1680  * A text buffer window supports both character and line input, but not mouse
1681  * input.
1682  * 
1683  * In character input, there will be some visible signal that the window is
1684  * waiting for a keystroke. (Typically, a cursor at the end of the text.) When
1685  * the player hits a key in that window, an event is generated, but the key is
1686  * <emphasis>not</emphasis> printed in the window.
1687  * 
1688  * In line input, again, there will be some visible signal. It is most common
1689  * for the player to compose input in the window itself, at the end of the text.
1690  * (This is how IF story input usually looks.) But it's not strictly required.
1691  * An alternative approach is the way MUD clients usually work: there is a
1692  * dedicated one-line input window, outside of Glk's window space, and the user
1693  * composes input there.
1694  * 
1695  * <note><para>
1696  *   If this approach is used, there will still be some way to handle input from
1697  *   two windows at once. It is the library's responsibility to make this
1698  *   available to the player. You only need request line input and  wait for the
1699  *   result.
1700  * </para></note>
1701  * 
1702  * When the player finishes his line of input, the library will display the
1703  * input text at the end of the buffer text (if it wasn't there already.) It
1704  * will be followed by a newline, so that the next text you print will start a
1705  * new line (paragraph) after the input.
1706  * 
1707  * If you call glk_cancel_line_event(), the same thing happens; whatever text
1708  * the user was composing is visible at the end of the buffer text, followed by
1709  * a newline.
1710  */
1711  
1712 /**
1713  * wintype_TextGrid: 
1714  * 
1715  * A text grid contains a rectangular array of characters, in a fixed-width
1716  * font. Its size is the number of columns and rows of the array.
1717  * 
1718  * A text grid window supports output. It maintains knowledge of an output
1719  * cursor position. When the window is opened, it is filled with blanks (space
1720  * characters), and the output cursor starts in the top left corner &mdash;
1721  * character (0,0). If the window is cleared with glk_window_clear(), the window
1722  * is filled with blanks again, and the cursor returns to the top left corner.
1723  * 
1724  * When you print, the characters of the output are laid into the array in
1725  * order, left to right and top to bottom. When the cursor reaches the end of a
1726  * line, it goes to the beginning of the next line. The library makes no attempt
1727  * to wrap lines at word breaks.
1728  * 
1729  * <note><para>
1730  *   Note that printing fancy characters may cause the cursor to advance more
1731  *   than one position per character. (For example, the <quote>&aelig;</quote>
1732  *   ligature may print as two characters.) See <link 
1733  *   linkend="chimara-Output">Output</link>, for how to test this situation.
1734  * </para></note>
1735  * 
1736  * You can set the cursor position with glk_window_move_cursor().
1737  * 
1738  * When a text grid window is resized smaller, the bottom or right area is
1739  * thrown away, but the remaining area stays unchanged. When it is resized
1740  * larger, the new bottom or right area is filled with blanks.
1741  * 
1742  * <note><para>
1743  *   You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
1744  *   text grid windows when you see them change size.
1745  * </para></note>
1746  * 
1747  * Text grid window support character and line input, as well as mouse input (if
1748  * a mouse is available.)
1749  * 
1750  * Mouse input returns the position of the character that was touched, from
1751  * (0,0) to 
1752  * <inlineequation>
1753  *   <alt>(width-1,height-1)</alt>
1754  *   <mathphrase>(width - 1, height - 1)</mathphrase>
1755  * </inlineequation>
1756  * .
1757  * 
1758  * Character input is as described in the previous section.
1759  * 
1760  * Line input is slightly different; it is guaranteed to take place in the
1761  * window, at the output cursor position. The player can compose input only to
1762  * the right edge of the window; therefore, the maximum input length is
1763  * <inlineequation>
1764  *   <alt>(windowwidth - 1 - cursorposition)</alt>
1765  *   <mathphrase>(windowwidth - 1 - cursorposition)</mathphrase>
1766  * </inlineequation>
1767  * . If the maxlen argument of glk_request_line_event() is smaller than this,
1768  * the library will not allow the input cursor to go more than maxlen characters
1769  * past its start point. 
1770  * 
1771  * <note><para>
1772  *   This allows you to enter text in a fixed-width field, without the player
1773  *   being able to overwrite other parts of the window.
1774  * </para></note>
1775  * 
1776  * When the player finishes his line of input, it will remain visible in the
1777  * window, and the output cursor will be positioned at the beginning of the 
1778  * <emphasis>next</emphasis> row. Again, if you glk_cancel_line_event(), the
1779  * same thing happens.
1780  */
1781  
1782 /**
1783  * wintype_Graphics: 
1784  * 
1785  * A graphics window contains a rectangular array of pixels. Its size is the
1786  * number of columns and rows of the array.
1787  * 
1788  * Each graphics window has a background color, which is initially white. You
1789  * can change this; see <link 
1790  * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics 
1791  * Windows</link>.
1792  * 
1793  * When a text grid window is resized smaller, the bottom or right area is
1794  * thrown away, but the remaining area stays unchanged. When it is resized
1795  * larger, the new bottom or right area is filled with the background color.
1796  * 
1797  * <note><para>
1798  *   You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
1799  *   graphics windows when you see them change size.
1800  * </para></note>
1801  * 
1802  * In some libraries, you can receive a graphics-redraw event (%evtype_Redraw)
1803  * at any time. This signifies that the window in question has been cleared to
1804  * its background color, and must be redrawn. If you create any graphics
1805  * windows, you <emphasis>must</emphasis> handle these events.
1806  * 
1807  * <note><para>
1808  *   Redraw events can be triggered when a Glk window is uncovered or made
1809  *   visible by the platform's window manager. On the other hand, some Glk
1810  *   libraries handle these problem automatically &mdash; for example, with a
1811  *   backing store &mdash; and do not send you redraw events. On the third hand,
1812  *   the backing store may be discarded if memory is low, or for other reasons
1813  *   &mdash; perhaps the screen's color depth has changed. So redraw events are
1814  *   always a possibility, even in clever libraries. This is why you must be
1815  *   prepared to handle them.
1816  * 
1817  *   However, you will not receive a redraw event when you create a graphics
1818  *   window. It is assumed that you will do the initial drawing of your own
1819  *   accord. You also do not get redraw events when a graphics window is
1820  *   enlarged. If you ordered the enlargement, you already know about it; if the
1821  *   player is responsible, you receive a window-arrangement event, which covers
1822  *   the situation.
1823  * </para></note>
1824  * 
1825  * For a description of the drawing functions that apply to graphics windows,
1826  * see <link linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
1827  * Windows</link>.
1828  * 
1829  * Graphics windows support no text input or output.
1830  * 
1831  * Not all libraries support graphics windows. You can test whether Glk graphics
1832  * are available using the gestalt system. In a C program, you can also test
1833  * whether the graphics functions are defined at compile-time. See <link 
1834  * linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics
1835  * Capabilities</link>. 
1836  *
1837  * <note><para>
1838  *   As with all windows, you should also test for %NULL when you create a
1839  *   graphics window.
1840  * </para></note>
1841  */
1842  
1843 /**
1844  * winmethod_Left:
1845  *
1846  * When calling glk_window_open() with this @method, the new window will be 
1847  * to the left of the old one which was split.
1848  */
1849
1850 /**
1851  * winmethod_Right:
1852  *
1853  * When calling glk_window_open() with this @method, the new window will be 
1854  * to the right of the old one which was split.
1855  */
1856
1857 /**
1858  * winmethod_Above:
1859  *
1860  * When calling glk_window_open() with this @method, the new window will be 
1861  * above the old one which was split.
1862  */
1863  
1864 /**
1865  * winmethod_Below:
1866  *
1867  * When calling glk_window_open() with this @method, the new window will be 
1868  * below the old one which was split.
1869  */
1870
1871 /**
1872  * winmethod_DirMask:
1873  *
1874  * Bitwise AND this value with a window splitting method argument to find
1875  * whether the split is %winmethod_Left, %winmethod_Right, %winmethod_Above, or
1876  * %winmethod_Below.
1877  */
1878  
1879 /**
1880  * winmethod_Fixed:
1881  *
1882  * When calling glk_window_open() with this @method, the new window will be 
1883  * a fixed size. (See glk_window_open()).
1884  */
1885
1886 /**
1887  * winmethod_Proportional:
1888  *
1889  * When calling glk_window_open() with this @method, the new window will be 
1890  * a given proportion of the old window's size. (See glk_window_open()).
1891  */
1892  
1893 /**
1894  * winmethod_DivisionMask:
1895  *
1896  * Bitwise AND this value with a window splitting method argument to find
1897  * whether the new window has %winmethod_Fixed or %winmethod_Proportional.
1898  */
1899  
1900 /** 
1901  * fileusage_Data: 
1902  *
1903  * Any other kind of file (preferences, statistics, arbitrary data.) 
1904  */
1905
1906 /**
1907  * fileusage_SavedGame: 
1908  * 
1909  * A file which stores game state.
1910  */
1911
1912 /**
1913  * fileusage_Transcript: 
1914  * 
1915  * A file which contains a stream of text from the game (often an echo stream
1916  * from a window.)
1917  */
1918  
1919 /** 
1920  * fileusage_InputRecord: 
1921  * 
1922  * A file which records player input.
1923  */
1924
1925 /** 
1926  * fileusage_TextMode: 
1927  *
1928  * The file contents will be transformed to a platform-native text file as they
1929  * are written out. Newlines may be converted to linefeeds or 
1930  * linefeed-plus-carriage-return combinations; Latin-1 characters may be
1931  * converted to native character codes. When reading a file in text mode, native
1932  * line breaks will be converted back to newline (0x0A) characters, and native
1933  * character codes may be converted to Latin-1. 
1934  *
1935  * <note><para>
1936  *   Line breaks will always be converted; other conversions are more
1937  *   questionable. If you write out a file in text mode, and then read it back
1938  *   in text mode, high-bit characters (128 to 255) may be transformed or lost.
1939  * </para></note>
1940  * <note><title>Chimara</title>
1941  * <para>
1942  * Text mode files in Chimara are in UTF-8, which is GTK+'s native file
1943  * encoding.
1944  * </para></note>
1945  */
1946
1947 /**
1948  * fileusage_BinaryMode: 
1949  *
1950  * The file contents will be stored exactly as they are written, and read back
1951  * in the same way. The resulting file may not be viewable on platform-native
1952  * text file viewers.
1953  */
1954
1955 /**
1956  * fileusage_TypeMask:
1957  *
1958  * Bitwise AND this value with a file usage argument to find whether the file
1959  * type is %fileusage_SavedGame, %fileusage_Transcript, %fileusage_InputRecord,
1960  * or %fileusage_Data.
1961  */
1962
1963 /**
1964  * filemode_Write: 
1965  *
1966  * An output stream.
1967  *
1968  * <note><para>
1969  *   Corresponds to mode <code>"w"</code> in the stdio library, using fopen().
1970  * </para></note>
1971  */
1972
1973 /** 
1974  * filemode_Read: 
1975  *
1976  * An input stream.
1977  *
1978  * <note><para>
1979  *   Corresponds to mode <code>"r"</code> in the stdio library, using fopen().
1980  * </para></note>
1981  */
1982
1983 /**
1984  * filemode_ReadWrite: 
1985  *
1986  * Both an input and an output stream.
1987  *
1988  * <note><para>
1989  *   Corresponds to mode <code>"r+"</code> in the stdio library, using fopen().
1990  * </para></note>
1991  */
1992
1993 /**
1994  * filemode_WriteAppend: 
1995  *
1996  * An output stream, but the data will added to the end of whatever already
1997  * existed in the destination, instead of replacing it. 
1998  *
1999  * <note><para>
2000  *   Corresponds to mode <code>"a"</code> in the stdio library, using fopen().
2001  * </para></note>
2002  */
2003  
2004 /**
2005  * seekmode_Start:
2006  *
2007  * In glk_stream_set_position(), signifies that @pos is counted in characters
2008  * after the beginning of the file.
2009  */
2010  
2011 /**
2012  * seekmode_Current: 
2013  *
2014  * In glk_stream_set_position(), signifies that @pos is counted in characters
2015  * after the current position (moving backwards if @pos is negative.)
2016  */
2017
2018 /** 
2019  * seekmode_End: 
2020  *
2021  * In glk_stream_set_position(), signifies that @pos is counted in characters
2022  * after the end of the file. (@pos should always be zero or negative, so that
2023  * this will move backwards to a  position within the file.
2024  */
2025
2026 /**
2027  * stylehint_Indentation: 
2028  *
2029  * How much to indent lines of text in the given style. May be a negative 
2030  * number, to shift the text out (left) instead of in (right). The exact metric
2031  * isn't precisely specified; you can assume that +1 is the smallest indentation
2032  * possible which is clearly visible to the player.
2033  */
2034
2035 /**
2036  * stylehint_ParaIndentation: 
2037  *
2038  * How much to indent the first line of each paragraph. This is in addition to 
2039  * the indentation specified by %stylehint_Indentation. This too may be 
2040  * negative, and is measured in the same units as %stylehint_Indentation.
2041  */
2042
2043 /**
2044  * stylehint_Justification: 
2045  *
2046  * The value of this hint must be one of the constants 
2047  * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification), 
2048  * %stylehint_just_Centered, or %stylehint_just_RightFlush.
2049  */
2050
2051 /** 
2052  * stylehint_Size: 
2053  *
2054  * How much to increase or decrease the font size. This is relative; 0 means the
2055  * interpreter's default font size will be used, positive numbers increase it, 
2056  * and negative numbers decrease it. Again, +1 is the smallest size increase 
2057  * which is easily visible. 
2058  * <note><para>
2059  *  The amount of this increase may not be constant. +1 might increase an 
2060  *  8-point font to 9-point, but a 16-point font to 18-point.
2061  * </para></note>
2062  */
2063
2064 /**
2065  * stylehint_Weight: 
2066  *
2067  * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for 
2068  * normal weight, and -1 for light-weight fonts.
2069  */
2070
2071 /**
2072  * stylehint_Oblique: 
2073  *
2074  * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal
2075  * angle.
2076  */
2077  
2078 /** 
2079  * stylehint_Proportional: 
2080  * 
2081  * The value of this hint must be 1 for proportional-width fonts, or 0 for 
2082  * fixed-width.
2083  */
2084
2085 /**
2086  * stylehint_TextColor: 
2087  * 
2088  * The foreground color of the text. This is encoded in the 32-bit hint value: 
2089  * the top 8 bits must be zero, the next 8 bits are the red value, the next 8 
2090  * bits are the green value, and the bottom 8 bits are the blue value. Color 
2091  * values range from 0 to 255. 
2092  * <note><para>
2093  *   So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.
2094  * </para></note>
2095  */
2096  
2097 /** 
2098  * stylehint_BackColor: 
2099  *
2100  * The background color behind the text. This is encoded the same way as 
2101  * %stylehint_TextColor.
2102  */
2103  
2104 /** 
2105  * stylehint_ReverseColor: 
2106  *
2107  * The value of this hint must be 0 for normal printing (%stylehint_TextColor on 
2108  * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on 
2109  * %stylehint_TextColor). 
2110  * <note><para>
2111  *  Some libraries may support this hint but not the %stylehint_TextColor and 
2112  *  %stylehint_BackColor hints. Other libraries may take the opposite tack; 
2113  *  others may support both, or neither.
2114  * </para></note>
2115  */
2116
2117 /**
2118  * stylehint_NUMHINTS:
2119  *
2120  * The number of style hints defined in this library.
2121  */ 
2122  
2123 /**
2124  * stylehint_just_LeftFlush:
2125  *
2126  * A value for %stylehint_Justification representing left-justified text.
2127  */ 
2128  
2129 /**
2130  * stylehint_just_LeftRight:
2131  *
2132  * A value for %stylehint_Justification representing fully justified text.
2133  */ 
2134  
2135 /**
2136  * stylehint_just_Centered:
2137  *
2138  * A value for %stylehint_Justification representing centered text.
2139  */ 
2140  
2141 /**
2142  * stylehint_just_RightFlush:
2143  *
2144  * A value for %stylehint_Justification representing right-justified text.
2145  */
2146
2147 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/
2148  
2149 /**
2150  * giblorb_err_t: 
2151  *
2152  * An integer type that can hold the Blorb error codes.
2153  */ 
2154  
2155 /**
2156  * giblorb_err_None:
2157  *
2158  * No error.
2159  */
2160  
2161 /**
2162  * giblorb_err_CompileTime: 
2163  *
2164  * Something is compiled wrong in the Blorb layer.
2165  */
2166  
2167 /**
2168  * giblorb_err_Alloc: 
2169  *
2170  * Memory could not be allocated.
2171  * <note><title>Chimara</title>
2172  * <para>
2173  *  The Blorb layer in the Chimara library should not return this error code;
2174  *  instead, the program aborts if memory allocation fails, in keeping with
2175  *  GLib practices.
2176  * </para></note> 
2177  */
2178  
2179 /**
2180  * giblorb_err_Read: 
2181  *
2182  * Data could not be read from the file.
2183  */
2184
2185 /** 
2186  * giblorb_err_NotAMap:
2187  *
2188  * The map parameter is invalid.
2189  */
2190
2191 /** 
2192  * giblorb_err_Format:
2193  *
2194  * The Blorb file is corrupted or invalid.
2195  */
2196  
2197 /**
2198  * giblorb_err_NotFound:
2199  *
2200  * The requested data could not be found.
2201  */
2202
2203 /**
2204  * giblorb_method_DontLoad:
2205  *
2206  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2207  * giblorb_load_resource() to obtain information about a chunk without actually
2208  * loading it.
2209  */
2210
2211 /**
2212  * giblorb_method_Memory:
2213  *
2214  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2215  * giblorb_load_resource() to load a chunk into memory.
2216  */
2217
2218 /**
2219  * giblorb_method_DontLoad:
2220  *
2221  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
2222  * giblorb_load_resource() to get the position in the Blorb file at which the
2223  * chunk data starts.
2224  */
2225
2226 /**
2227  * giblorb_ID_Snd:
2228  *
2229  * Resource usage constant representing a sound file.
2230  */
2231
2232 /**
2233  * giblorb_ID_Exec:
2234  *
2235  * Resource usage constant representing an executable program.
2236  */
2237  
2238 /**
2239  * giblorb_ID_Pict:
2240  *
2241  * Resource usage constant representing an image file.
2242  */
2243
2244 /**
2245  * giblorb_ID_Copyright:
2246  *
2247  * Resource usage constant representing the copyright message (date and holder, 
2248  * without the actual copyright symbol). There should only be one such chunk per
2249  * file.
2250  */
2251
2252 /**
2253  * giblorb_ID_AUTH:
2254  *
2255  * Resource usage constant representing the name of the author or creator of the
2256  * file. This could be a login name on multi-user systems, for example. There
2257  * should only be one such chunk per file.
2258  */
2259  
2260 /**
2261  * giblorb_ID_ANNO:
2262  *
2263  * Resource usage constant representing any textual annotation that the user or 
2264  * writing program sees fit to include.
2265  */ 
2266  
2267 /**
2268  * giblorb_map_t:
2269  *
2270  * Holds the complete description of an open Blorb file. This type is opaque for
2271  * normal interpreter use.
2272  */
2273  
2274 /**
2275  * giblorb_result_t:
2276  *
2277  * Holds information about a chunk loaded from a Blorb file, and the method of
2278  * accessing the chunk data. See giblorb_load_chunk_by_type() and
2279  * giblorb_load_chunk_by_number(). 
2280  */
2281  
2282 /**
2283  * giblorb_create_map:
2284  * @file: An input stream pointing to a Blorb file.
2285  * @newmap: Return location for a Blorb resource map.
2286  *
2287  * Reads Blorb data out of a Glk stream. It does not load every resource at 
2288  * once; instead, it creates a map in memory which makes it easy to find 
2289  * resources. A pointer to the map is stored in @newmap. This is an opaque 
2290  * object; you pass it to the other Blorb-layer functions.
2291  *
2292  * Returns: a Blorb error code. 
2293  */
2294  
2295 /**
2296  * giblorb_destroy_map: 
2297  * @map: A Blorb resource map to deallocate.
2298  *
2299  * Deallocates @map and all associated memory. This does 
2300  * <emphasis>not</emphasis> close the original stream.
2301  *
2302  * Returns: a Blorb error code. 
2303  */
2304
2305 /**
2306  * giblorb_load_chunk_by_type:
2307  * @map: The Blorb resource map to load a chunk from.
2308  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
2309  * %giblorb_method_Memory, or %giblorb_method_FilePos.
2310  * @res: Return location for the result.
2311  * @chunktype: The type of chunk to load.
2312  * @count: The chunk number of type @chunktype to load.
2313  *
2314  * Loads a chunk of a given type. The @count parameter distinguishes between 
2315  * chunks of the same type. If @count is zero, the first chunk of that type is 
2316  * loaded, and so on.
2317  * 
2318  * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the 
2319  * form type, rather than FORM.
2320  * <note><para>
2321  *  This introduces a slight ambiguity &mdash; you cannot distiguish between a 
2322  *  FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is 
2323  *  almost certainly a mistake.
2324  * </para></note> 
2325  * 
2326  * The returned data is written into @res, according to @method.
2327  * 
2328  * The <structfield>chunknum</structfield> field is filled in with the number of
2329  * the chunk. (This value can then be passed to giblorb_load_chunk_by_number() 
2330  * or giblorb_unload_chunk().) The <structfield>length</structfield> field is 
2331  * filled in with the length of the chunk in bytes. The 
2332  * <structfield>chunktype</structfield> field is the chunk's type, which of 
2333  * course will be the type you asked for.
2334  * 
2335  * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You
2336  * can use this if you are only interested in whether a chunk exists, or in the
2337  * <structfield>chunknum</structfield> and <structfield>length</structfield> 
2338  * parameters.
2339  * 
2340  * If you specify %giblorb_method_FilePos, 
2341  * <structfield>data.startpos</structfield> is filled in with the file position
2342  * of the chunk data. You can use glk_stream_set_position() to read the data 
2343  * from the stream.
2344  * 
2345  * If you specify %giblorb_method_Memory, <structfield>data.ptr</structfield> is
2346  * filled with a pointer to allocated memory containing the chunk data. This 
2347  * memory is owned by the map, not you. If you load the chunk more than once 
2348  * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one
2349  * copy in memory. You should not deallocate this memory yourself; call 
2350  * giblorb_unload_chunk() instead.
2351  *
2352  * Returns: a Blorb error code.
2353  */
2354
2355 /** 
2356  * giblorb_load_chunk_by_number:
2357  * @map: The Blorb resource map to load a chunk from.
2358  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
2359  * %giblorb_method_Memory, or %giblorb_method_FilePos.
2360  * @res: Return location for the result.
2361  * @chunknum: The chunk number to load.
2362  *
2363  * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a
2364  * given chunk number. The type of the chunk can be found in the 
2365  * <structfield>chunktype</structfield> field of #giblorb_result_t. You can get
2366  * the chunk number from the <structfield>chunknum</structfield> field, after 
2367  * calling one of the other load functions.
2368  *
2369  * Returns: a Blorb error code. 
2370  */
2371
2372 /**
2373  * giblorb_unload_chunk:
2374  * @map: The Blorb resource map to unload a chunk from.
2375  * @chunknum: The chunk number to unload.
2376  *
2377  * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk
2378  * has never been loaded into memory, this has no effect. 
2379  *
2380  * Returns: a Blorb error code.
2381  */
2382
2383 /**
2384  * giblorb_load_resource:
2385  * @map: The Blorb resource map to load a resource from.
2386  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
2387  * %giblorb_method_Memory, or %giblorb_method_FilePos.
2388  * @res: Return location for the result.
2389  * @usage: The type of data resource to load.
2390  * @resnum: The resource number to load.
2391  *
2392  * Loads a resource, given its usage and resource number. Currently, the three
2393  * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and
2394  * %giblorb_ID_Exec (executable program). See the Blorb specification for more
2395  * information about the types of data that can be stored for these usages.
2396  * 
2397  * Note that a resource number is not the same as a chunk number. The resource
2398  * number is the sound or image number specified by a Glk program. Chunk number
2399  * is arbitrary, since chunks in a Blorb file can be in any order. To find the
2400  * chunk number of a given resource, call giblorb_load_resource() and look in
2401  * <structfield>res.chunknum</structfield>.
2402  *
2403  * Returns: a Blorb error code.
2404  */
2405
2406 /**
2407  * giblorb_count_resources:
2408  * @map: The Blorb resource map in which to count the resources.
2409  * @usage: The type of data resource to count.
2410  * @num: Return location for the number of chunks of @usage.
2411  * @min: Return location for the lowest resource number of @usage.
2412  * @max: Return location for the highest resource number of @usage.
2413  *
2414  * Counts the number of chunks with a given usage (image, sound, or executable.)
2415  * The total number of chunks of that usage is stored in @num. The lowest and 
2416  * highest resource number of that usage are stored in @min and @max. You can
2417  * leave any of the three pointers %NULL if you don't care about that
2418  * information. 
2419  *
2420  * Returns: a Blorb error code.
2421  */
2422
2423 /*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/
2424
2425 /**
2426  * glkunix_argumentlist_t:
2427  * 
2428  * In each entry, name is the option as it would appear on the command line
2429  * (including the leading dash, if any.) The desc is a description of the
2430  * argument; this is used when the library is printing a list of options. And
2431  * argtype is one of the following constants:
2432  * 
2433  * <variablelist>
2434  * <varlistentry>
2435  *  <term>%glkunix_arg_NoValue</term>
2436  *  <listitem><para>The argument appears by itself.</para></listitem>
2437  * </varlistentry>
2438  * <varlistentry>
2439  *  <term>%glkunix_arg_ValueFollows</term>
2440  *  <listitem><para>The argument must be followed by another argument (the 
2441  *  value).</para></listitem>
2442  * </varlistentry>
2443  * <varlistentry>
2444  *  <term>%glkunix_arg_ValueCanFollow</term> 
2445  *  <listitem><para>The argument may be followed by a value, optionally. (If the
2446  *  next argument starts with a dash, it is taken to be a new argument, not the 
2447  *  value of this one.)</para></listitem>
2448  * </varlistentry>
2449  * <varlistentry>
2450  *  <term>%glkunix_arg_NumberValue</term>
2451  *  <listitem><para>The argument must be followed by a number, which may be the 
2452  *  next argument or part of this one. (That is, either <quote><code>-width 
2453  *  20</code></quote> or <quote><code>-width20</code></quote> will be accepted.)
2454  *  </para></listitem>
2455  * </varlistentry>
2456  * <varlistentry> 
2457  *  <term>%glkunix_arg_End</term>
2458  *  <listitem><para>The <code>glkunix_arguments[]</code> array must be 
2459  *  terminated with an entry containing this value.</para></listitem>
2460  * </varlistentry>
2461  * </variablelist>
2462  * 
2463  * To accept arbitrary arguments which lack dashes, specify a name of 
2464  * <code>""</code> and an argtype of %glkunix_arg_ValueFollows.
2465  *
2466  * If you don't care about command-line arguments, you must still define an
2467  * empty arguments list, as follows:
2468  * |[
2469  * #glkunix_argumentlist_t glkunix_arguments[] = {
2470  *  { NULL, #glkunix_arg_End, NULL }
2471  * };
2472  * ]|
2473  * 
2474  * Here is a more complete sample list:
2475  * |[
2476  * #glkunix_argumentlist_t glkunix_arguments[] = {
2477  *  { "", #glkunix_arg_ValueFollows, "filename: The game file to load." },
2478  *  { "-hum", #glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
2479  *  { "-bom", #glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
2480  *   the NUM, if given)." },
2481  *  { "-goo", #glkunix_arg_NoValue, "-goo: Find goo." },
2482  *  { "-wob", #glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
2483  *  { NULL, #glkunix_arg_End, NULL }
2484  * };
2485  * ]|
2486  * This would match the arguments <quote><code>thingfile -goo -wob8 -bom -hum 
2487  * song</code></quote>.
2488  *
2489  * After the library parses the command line, it does various occult rituals of
2490  * initialization, and then calls glkunix_startup_code().
2491  *
2492  * |[ int glkunix_startup_code(#glkunix_startup_t *data); ]|
2493  *
2494  * This should return %TRUE if everything initializes properly. If it returns
2495  * %FALSE, the library will shut down without ever calling your glk_main() 
2496  * function.
2497  */
2498
2499 /**
2500  * glkunix_startup_t: 
2501  * 
2502  * The fields are a standard Unix <code>(argc, argv)</code> list, which contain
2503  * the arguments you requested from the command line. In deference to custom,
2504  * <code>argv[0]</code> is always the program name.
2505  */
2506
2507 /**
2508  * glkunix_arg_End:
2509  *
2510  * Terminates a list of #glkunix_argumentlist_t.
2511  */
2512  
2513 /**
2514  * glkunix_arg_ValueFollows:
2515  *
2516  * Indicates an argument which must be followed by a value, as the next 
2517  * argument.
2518  */
2519
2520 /** 
2521  * glkunix_arg_NoValue:
2522  *
2523  * Indicates an argument which occurs by itself, without a value.
2524  */
2525  
2526 /**
2527  * glkunix_arg_ValueCanFollow:
2528  *
2529  * Indicates an argument which may be followed by a value, or may occur by 
2530  * itself.
2531  */
2532  
2533 /**
2534  * glkunix_arg_NumberValue:
2535  *
2536  * Indicates an argument which must be followed by a numerical value, either as 
2537  * the next argument or tacked onto the end of this argument.
2538  */