2 * doc.c - Contains the short and long descriptions of all the documentation
3 * sections in the Glk spec, as well as the GtkDoc comments for symbols
4 * defined only in glk.h.
9 * @short_description: How to terminate a Glk program cleanly
11 * A Glk program usually ends when the end of the glk_main() function is
12 * reached. You can also terminate it earlier.
16 * SECTION:glk-interrupt
17 * @short_description: Specifying an interrupt handler for cleaning up critical
20 * Most platforms have some provision for interrupting a program —
21 * <keycombo action="simul"><keycap function="command">command</keycap>
22 * <keycap>period</keycap></keycombo> on the Macintosh, <keycombo
23 * action="simul"><keycap function="control">control</keycap><keycap>C</keycap>
24 * </keycombo> in Unix, possibly a window manager item, or other possibilities.
25 * This can happen at any time, including while execution is nested inside one
26 * of your own functions, or inside a Glk library function.
28 * If you need to clean up critical resources, you can specify an interrupt
34 * @short_description: Yielding time to the operating system
36 * Many platforms have some annoying thing that has to be done every so often,
37 * or the gnurrs come from the voodvork out and eat your computer.
39 * Well, not really. But you should call glk_tick() every so often, just in
40 * case. It may be necessary to yield time to other applications in a
41 * cooperative-multitasking OS, or to check for player interrupts in an infinite
47 * @short_description: Basic types used in Glk
49 * For simplicity, all the arguments used in Glk calls are of a very few types.
52 * <term>32-bit unsigned integer</term>
53 * <listitem><para>Unsigned integers are used wherever possible, which is
54 * nearly everywhere. This type is called #glui32.</para></listitem>
57 * <term>32-bit signed integer</term>
58 * <listitem><para>This type is called #glsi32. Rarely used.</para>
62 * <term>References to library objects</term>
63 * <listitem><para>These are pointers to opaque C structures; each library
64 * will use different structures, so you can not and should not try to
65 * manipulate their contents. See <link
66 * linkend="chimara-Opaque-Objects">Opaque Objects</link>.</para></listitem>
69 * <term>Pointer to one of the above types</term>
70 * <listitem><para>Pointer to a structure which consists entirely of the
71 * above types.</para></listitem>
74 * <term><type>unsigned char</type></term>
75 * <listitem><para>This is used only for Latin-1 text characters; see
76 * <link linkend="chimara-Character-Encoding">Character Encoding</link>.
80 * <term>Pointer to <type>char</type></term>
81 * <listitem><para>Sometimes this means a null-terminated string; sometimes
82 * an unterminated buffer, with length as a separate #glui32 argument. The
83 * documentation says which.</para></listitem>
86 * <term>Pointer to <type>void</type></term>
87 * <listitem><para>When nothing else will do.</para></listitem>
93 * SECTION:glk-opaque-objects
94 * @short_description: Complex objects in Glk
96 * Glk keeps track of a few classes of special objects. These are opaque to your
97 * program; you always refer to them using pointers to opaque C structures.
99 * Currently, these classes are:
102 * <term>Windows</term>
103 * <listitem><para>Screen panels, used to input or output information.
107 * <term>Streams</term>
108 * <listitem><para>Data streams, to which you can input or output text.
110 * <note><para>There are file streams and window streams, since you can
111 * output data to windows or files.</para></note>
115 * <term>File references</term>
116 * <listitem><para>Pointers to files in permanent storage.</para>
117 * <note><para>In Unix a file reference is a pathname; on the Mac, an
118 * <type>FSSpec</type>. Actually there's a little more information included,
119 * such as file type and whether it is a text or binary file.</para></note>
123 * <term>Sound channels</term>
124 * <listitem><para>Audio output channels.</para>
125 * <note><para>Not all Glk libraries support sound.</para></note>
131 * Note that there may be more object classes in future versions of the Glk API.
134 * When you create one of these objects, it is always possible that the creation
135 * will fail (due to lack of memory, or some other OS error.) When this happens,
136 * the allocation function will return %NULL instead of a valid pointer. You
137 * should always test for this possibility.
139 * %NULL is never the identifier of any object (window, stream, file reference,
140 * or sound channel). The value %NULL is often used to indicate <quote>no
141 * object</quote> or <quote>nothing</quote>, but it is not a valid reference. If
142 * a Glk function takes an object reference as an argument, it is illegal to
143 * pass in %NULL unless the function definition says otherwise.
145 * The <filename class="headerfile">glk.h</filename> file defines types
146 * #winid_t, #strid_t, #frefid_t, #schanid_t to store references. These are
147 * pointers to struct #glk_window_struct, #glk_stream_struct,
148 * #glk_fileref_struct, and #glk_schannel_struct respectively. It is, of course,
149 * illegal to pass one kind of pointer to a function which expects another.
152 * This is how you deal with opaque objects from a C program. If you are using
153 * Glk through a virtual machine, matters will probably be different. Opaque
154 * objects may be represented as integers, or as VM objects of some sort.
155 * </para></note></para>
157 * <refsect2 id="chimara-Rocks"><!-- Indeed it does. -->
158 * <title>Rocks</title>
160 * Every one of these objects (window, stream, file reference, or sound channel)
161 * has a <quote>rock</quote> value. This is simply a 32-bit integer value which
162 * you provide, for your own purposes, when you create the object.
164 * <note><para>The library — so to speak — stuffs this value under a
165 * rock for safe-keeping, and gives it back to you when you ask for it.
167 * <note><para>If you don't know what to use the rocks for, provide 0 and forget
168 * about it.</para></note>
170 * <refsect2 id="chimara-Iterating-Through-Opaque-Objects">
171 * <title>Iteration Through Opaque Objects</title>
173 * For each class of opaque objects, there is an iterate function, which you can
174 * use to obtain a list of all existing objects of that class. It takes the form
176 * CLASSid_t glk_CLASS_iterate(CLASSid_t obj, glui32 *rockptr);
178 * ...where <code><replaceable>CLASS</replaceable></code> represents one of the
179 * opaque object classes.
182 * So, at the current time, these are the functions glk_window_iterate(),
183 * glk_stream_iterate(), glk_fileref_iterate(), and glk_schannel_iterate().
184 * There may be more classes in future versions of the spec; they all behave
188 * Calling <code>glk_<replaceable>CLASS</replaceable>_iterate(%NULL, r)</code>
189 * returns the first object; calling
190 * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> returns
191 * the next object, until there aren't any more, at which time it returns %NULL.
194 * The @rockptr argument is a pointer to a location; whenever
195 * <code>glk_<replaceable>CLASS</replaceable>_iterate()</code> returns an
196 * object, the object's rock is stored in the location <code>(*@rockptr)</code>.
197 * If you don't want the rocks to be returned, you may set @rockptr to %NULL.
200 * You usually use this as follows:
202 * obj = glk_CLASS_iterate(NULL, NULL);
204 * /* ...do something with obj... *<!-- -->/
205 * obj = glk_CLASS_iterate(obj, NULL);
210 * If you create or destroy objects inside this loop, obviously, the results are
211 * unpredictable. However it is always legal to call
212 * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> as long as
213 * @obj is a valid object id, or %NULL.
216 * The order in which objects are returned is entirely arbitrary. The library
217 * may even rearrange the order every time you create or destroy an object of
218 * the given class. As long as you do not create or destroy any object, the rule
219 * is that <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> has
220 * a fixed result, and iterating through the results as above will list every
221 * object exactly once.
227 * SECTION:glk-gestalt
228 * @short_description: Testing Glk's capabilities
230 * The <quote>gestalt</quote> mechanism (cheerfully stolen from the Mac OS) is a
231 * system by which the Glk API can be upgraded without making your life
232 * impossible. New capabilities (graphics, sound, or so on) can be added without
233 * changing the basic specification. The system also allows for
234 * <quote>optional</quote> capabilities — those which not all Glk library
235 * implementations will support — and allows you to check for their
236 * presence without trying to infer them from a version number.
238 * The basic idea is that you can request information about the capabilities of
239 * the API, by calling the gestalt functions.
243 * SECTION:glk-character-input
244 * @short_description: Waiting for a single keystroke
246 * You can request that the player hit a single key. See <link
247 * linkend="chimara-Character-Input-Events">Character Input Events</link>.
249 * If you use the basic text API, the character code which is returned can be
250 * any value from 0 to 255. The printable character codes have already been
251 * described. The remaining codes are typically control codes: <keycombo
252 * action="simul"><keycap function="control">control</keycap>
253 * <keycap>A</keycap></keycombo> to <keycombo action="simul"><keycap
254 * function="control">control</keycap><keycap>Z</keycap></keycombo> and a few
257 * There are also a number of special codes, representing special keyboard
258 * keys, which can be returned from a char-input event. These are represented
259 * as 32-bit integers, starting with 4294967295 (0xFFFFFFFF) and working down.
260 * The special key codes are defined in the <filename
261 * class="headerfile">glk.h</filename> file. They include one code for <keycap
262 * function="enter">return</keycap> or <keycap function="enter">enter</keycap>,
263 * one for <keycap function="delete">delete</keycap> or <keycap
264 * function="backspace">backspace</keycap>, twelve function keys, and one code
265 * for any key which has no Latin-1 or special code. The full list of key codes
268 * Various implementations of Glk will vary widely in which characters the
269 * player can enter. The most obvious limitation is that some characters are
270 * mapped to others. For example, most keyboards return a <keycombo
271 * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
272 * </keycombo> code when the <keycap function="tab">tab</keycap> key is
273 * pressed. The Glk library, if it can recognize this at all, will generate a
274 * <keysym>%keycode_Tab</keysym> event (value 0xFFFFFFF7) when this occurs.
275 * Therefore, for these keyboards, no keyboard key will generate a <keycombo
276 * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
277 * </keycombo> event (value 9.) The Glk library will probably map many of the
278 * control codes to the other special keycodes.
281 * On the other hand, the library may be very clever and discriminate between
282 * <keycap>tab</keycap> and <keycombo action="simul"><keycap
283 * function="control">control</keycap><keycap>I</keycap></keycombo>. This is
284 * legal. The idea is, however, that if your program asks the player to
285 * <quote><computeroutput>press the <keycap function="tab">tab</keycap>
286 * key</computeroutput></quote>, you should check for a
287 * <keysym>%keycode_Tab</keysym> event as opposed to a <keycombo
288 * action="simul"><keycap function="control">control</keycap>
289 * <keycap>I</keycap></keycombo> event.
292 * Some characters may not be enterable simply because they do not exist.
295 * Not all keyboards have a <keycap function="home">home</keycap> or <keycap
296 * function="end">end</keycap> key. A pen-based platform may not recognize
297 * any control characters at all.
300 * Some characters may not be enterable because they are reserved for the
301 * purposes of the interface. For example, the Mac Glk library reserves the
302 * <keycap function="tab">tab</keycap> key for switching between different Glk
303 * windows. Therefore, on the Mac, the library will never generate a
304 * <keysym>%keycode_Tab</keysym> event or a <keycombo action="simul">
305 * <keycap function="control">control</keycap><keycap>I</keycap></keycombo>
309 * Note that the linefeed or <keycombo action="simul"><keycap
310 * function="control">control</keycap><keycap>J</keycap></keycombo>
311 * character, which is the only printable control character, is probably not
312 * typable. This is because, in most libraries, it will be converted to
313 * <keysym>%keycode_Return</keysym>. Again, you should check for
314 * <keysym>%keycode_Return</keysym> if your program asks the player to
315 * <quote><computeroutput>press the <keycap function="enter">return</keycap>
316 * key</computeroutput></quote>.
320 * The <keycap function="delete">delete</keycap> and <keycap
321 * function="backspace">backspace</keycap> keys are merged into a single
322 * keycode because they have such an astonishing history of being confused in
323 * the first place... this spec formally waives any desire to define the
324 * difference. Of course, a library is free to distinguish <keycap
325 * function="delete">delete</keycap> and <keycap
326 * function="backspace">backspace</keycap> during line input. This is when it
327 * matters most; conflating the two during character input should not be a
331 * You can test for this by using the %gestalt_CharInput selector.
334 * Glk porters take note: it is not a goal to be able to generate every
335 * single possible key event. If the library says that it can generate a
336 * particular keycode, then game programmers will assume that it is
337 * available, and ask players to use it. If a <keysym>%keycode_Home</keysym>
338 * event can only be generated by typing <keycombo action="seq"><keycap
339 * function="escape">escape</keycap><keycombo action="simul"><keycap
340 * function="control">control</keycap><keycap>A</keycap></keycombo>
341 * </keycombo>, and the player does not know this, the player will be lost
342 * when the game says <quote><computeroutput>Press the <keycap
343 * function="home">home</keycap> key to see the next
344 * hint.</computeroutput></quote> It is better for the library to say that it
345 * cannot generate a <keysym>%keycode_Home</keysym> event; that way the game
346 * can detect the situation and ask the user to type <keycap>H</keycap>
350 * Of course, it is better not to rely on obscure keys in any case. The arrow
351 * keys and <keycap function="enter">return</keycap> are nearly certain to be
352 * available; the others are of gradually decreasing reliability, and you
353 * (the game programmer) should not depend on them. You must be certain to
354 * check for the ones you want to use, including the arrow keys and <keycap
355 * function="enter">return</keycap>, and be prepared to use different keys in
356 * your interface if %gestalt_CharInput says they are not available.
362 * @short_description: Changing the case of strings
364 * Glk has functions to manipulate the case of both Latin-1 and Unicode strings.
365 * One Latin-1 lowercase character corresponds to one uppercase character, and
366 * vice versa, so the Latin-1 functions act on single characters. The Unicode
367 * functions act on whole strings, since the length of the string may change.
371 * SECTION:glk-normalize
372 * @short_description: Combining characters
374 * Comparing Unicode strings is difficult, because there can be several ways to
375 * represent a piece of text as a Unicode string. For example, the one-character
376 * string <quote>è</quote> (an accented <quote>e</quote>) will be
377 * displayed the same as the two-character string containing <quote>e</quote>
378 * followed by Unicode character 0x0300 (COMBINING GRAVE ACCENT). These strings
379 * should be considered equal.
381 * Therefore, a Glk program that accepts line input should convert its text to a
382 * normalized form before parsing it. These functions offer those conversions.
383 * The algorithms are defined by the Unicode spec (chapter 3.7) and <ulink
384 * url="http://www.unicode.org/reports/tr15/">Unicode Standard Annex
389 * SECTION:glk-window-opening
390 * @short_description: Creating new windows and closing them
392 * You can open a new window using glk_window_open() and close it again using
393 * glk_window_close().
397 * SECTION:glk-window-constraints
398 * @short_description: Manipulating the size of a window
400 * There are library functions to change and to measure the size of a window.
404 * SECTION:glk-window-types
405 * @short_description: Blank, pair, text grid, text buffer, and graphics windows
407 * A technical description of all the window types, and exactly how they behave.
411 * SECTION:glk-echo-streams
412 * @short_description: Creating a copy of a window's output
414 * Every window has an associated window stream; you print to the window by
415 * printing to this stream. However, it is possible to attach a second stream to
416 * a window. Any text printed to the window is also echoed to this second
417 * stream, which is called the window's <quote>echo stream.</quote>
419 * Effectively, any call to glk_put_char() (or the other output commands) which
420 * is directed to the window's window stream, is replicated to the window's echo
421 * stream. This also goes for the style commands such as glk_set_style().
423 * Note that the echoing is one-way. You can still print text directly to the
424 * echo stream, and it will go wherever the stream is bound, but it does not
425 * back up and appear in the window.
427 * An echo stream can be of any type, even another window's window stream.
430 * This would be somewhat silly, since it would mean that any text printed to
431 * the window would be duplicated in another window. More commonly, you would
432 * set a window's echo stream to be a file stream, in order to create a
433 * transcript file from that window.
436 * A window can only have one echo stream. But a single stream can be the echo
437 * stream of any number of windows, sequentially or simultaneously.
439 * If a window is closed, its echo stream remains open; it is not automatically
443 * Do not confuse the window's window stream with its echo stream. The window
444 * stream is <quote>owned</quote> by the window, and dies with it. The echo
445 * stream is merely temporarily associated with the window.
448 * If a stream is closed, and it is the echo stream of one or more windows,
449 * those windows are reset to not echo anymore. (So then calling
450 * glk_window_get_echo_stream() on them will return %NULL.)
454 * SECTION:glk-window-other
455 * @short_description: Miscellaneous functions for windows
457 * This section contains functions for windows that don't fit anywhere else.
462 * @short_description: Waiting for events
464 * As described in <link linkend="chimara-Your-Programs-Main-Function">Your
465 * Program's Main Function</link>, all player input is handed to your program by
466 * the glk_select() call, in the form of events. You should write at least one
467 * event loop to retrieve these events.
471 * SECTION:glk-character-input-events
472 * @short_description: Events representing a single keystroke
474 * You can request character input from text buffer and text grid windows. See
475 * %evtype_CharInput. There are separate functions for requesting Latin-1 input
476 * and Unicode input; see %gestalt_Unicode.
480 * SECTION:glk-line-input-events
481 * @short_description: Events representing a line of user input
483 * You can request line input from text buffer and text grid windows. See
484 * %evtype_LineInput. There are separate functions for requesting Latin-1 input
485 * and Unicode input; see %gestalt_Unicode.
489 * SECTION:glk-mouse-events
490 * @short_description: Events representing a mouse click
492 * On some platforms, Glk can recognize when the mouse (or other pointer) is
493 * used to select a spot in a window. You can request mouse input only in text
494 * grid windows and graphics windows.
496 * A window can have mouse input and character/line input pending at the same
499 * If the player clicks in a window which has a mouse input event pending,
500 * glk_select() will return an event whose type is %evtype_MouseInput. Again,
501 * once this happens, the request is complete, and you must request another if
502 * you want further mouse input.
504 * In the event structure, @win tells what window the event came from.
506 * In a text grid window, the @val1 and @val2 fields are the x and y coordinates
507 * of the character that was clicked on.
508 * <note><para>So @val1 is the column, and @val2 is the row.</para></note>
509 * The top leftmost character is considered to be (0,0).
511 * In a graphics window, they are the x and y coordinates of the pixel that was
512 * clicked on. Again, the top left corner of the window is (0,0).
515 * Most mouse-based idioms define standard functions for mouse hits in text
516 * windows — typically selecting or copying text. It is up to the
517 * library to separate this from Glk mouse input. The library may choose to
518 * select text when it is clicked normally, and cause Glk mouse events when
519 * text is control-clicked. Or the other way around. Or it may be the
520 * difference between clicking and double-clicking. Or the library may
521 * reserve a particular mouse button, on a multi-button mouse. It may even
522 * specify a keyboard key to be the "mouse button", referring to wherever the
523 * mouse cursor is when the key is hit. Or some even more esoteric positioning
524 * system. You need only know that the user can do it, or not.
527 * However, since different platforms will handle this issue differently, you
528 * should be careful how you instruct the player in your program. Do not tell
529 * the player to <quote>double-click</quote>, <quote>right-click</quote>, or
530 * <quote>control-click</quote> in a window. The preferred term is <quote>to
531 * touch the window</quote>, or a spot in the window.
534 * Goofy, but preferred.
539 * SECTION:glk-timer-events
540 * @short_description: Events sent at fixed intervals
542 * You can request that an event be sent at fixed intervals, regardless of what
543 * the player does. Unlike input events, timer events can be tested for with
544 * glk_select_poll() as well as glk_select().
546 * It is possible that the library does not support timer events. You can check
547 * this with the %gestalt_Timer selector.
551 * SECTION:glk-streams
552 * @short_description: Input and output abstractions
554 * All character output in Glk is done through streams. Every window has an
555 * output stream associated with it. You can also write to files on disk; every
556 * open file is represented by an output stream as well.
558 * There are also input streams; these are used for reading from files on disk.
559 * It is possible for a stream to be both an input and an output stream.
562 * Player input is done through line and character input events, not streams.
563 * This is a small inelegance in theory. In practice, player input is slow and
564 * things can interrupt it, whereas file input is immediate. If a network
565 * extension to Glk were proposed, it would probably use events and not
566 * streams, since network communication is not immediate.
569 * It is also possible to create a stream that reads or writes to a buffer in
572 * Finally, there may be platform-specific types of streams, which are created
573 * before your program starts running.
576 * For example, a program running under Unix may have access to standard input
577 * as a stream, even though there is no Glk call to explicitly open standard
578 * input. On the Mac, data in a Mac resource may be available through a
579 * resource-reading stream.
582 * You do not need to worry about the origin of such streams; just read or write
583 * them as usual. For information about how platform-specific streams come to
584 * be, see <link linkend="chimara-Startup-Options">Startup Options</link>.
586 * A stream is opened with a particular file mode, see the
587 * <code>filemode_</code> constants below.
590 * In the stdio library, using fopen(), %filemode_Write would be mode
591 * <code>"w"</code>; %filemode_Read would be mode <code>"r"</code>;
592 * %filemode_ReadWrite would be mode <code>"r+"</code>. Confusingly,
593 * %filemode_WriteAppend cannot be mode <code>"a"</code>, because the stdio
594 * spec says that when you open a file with mode <code>"a"</code>, then
595 * fseek() doesn't work. So we have to use mode <code>"r+"</code> for
596 * appending. Then we run into the <emphasis>other</emphasis> stdio problem,
597 * which is that <code>"r+"</code> never creates a new file. So
598 * %filemode_WriteAppend has to <emphasis>first</emphasis> open the file with
599 * <code>"a"</code>, close it, reopen with <code>"r+"</code>, and then
600 * fseek() to the end of the file. For %filemode_ReadWrite, the process is
601 * the same, except without the fseek() — we begin at the beginning of
605 * We must also obey an obscure geas of ANSI C <code>"r+"</code> files: you
606 * can't switch from reading to writing without doing an fseek() in between.
607 * Switching from writing to reading has the same restriction, except that an
608 * fflush() also works.
611 * For information on opening streams, see the discussion of each specific type
612 * of stream in <link linkend="chimara-The-Types-of-Streams">The Types of
613 * Streams</link>. Remember that it is always possible that opening a stream
614 * will fail, in which case the creation function will return %NULL.
616 * Each stream remembers two character counts, the number of characters printed
617 * to and read from that stream. The write-count is exactly one per
618 * glk_put_char() call; it is figured before any platform-dependent character
622 * For example, if a newline character is converted to
623 * linefeed-plus-carriage-return, the stream's count still only goes up by
624 * one; similarly if an accented character is displayed as two characters.
627 * The read-count is exactly one per glk_get_char_stream() call, as long as the
628 * call returns an actual character (as opposed to an end-of-file token.)
630 * Glk has a notion of the <quote>current (output) stream</quote>. If you print
631 * text without specifying a stream, it goes to the current output stream. The
632 * current output stream may be %NULL, meaning that there isn't one. It is
633 * illegal to print text to stream %NULL, or to print to the current stream when
636 * If the stream which is the current stream is closed, the current stream
642 * @short_description: Printing to streams
644 * You can print Latin-1 and Unicode characters, null-terminated strings, or
645 * buffers to any stream. The characters will be converted into the appropriate
646 * format for that stream.
651 * @short_description: Reading from streams
653 * You can read Latin-1 or Unicode characters, buffers, or whole lines from any
654 * stream. The characters will be converted into the form in which you request
659 * SECTION:glk-closing-streams
660 * @short_description: Closing streams and retrieving their character counts
662 * When you close a Glk stream, you have the opportunity to examine the
663 * character counts — the number of characters written to or read from the
668 * SECTION:glk-stream-positions
669 * @short_description: Moving the read/write mark
671 * You can set the position of the read/write mark in a stream.
674 * Which makes one wonder why they're called <quote>streams</quote> in the
675 * first place. Oh well.
681 * @short_description: Changing the appearance of printed text
683 * You can send style-changing commands to an output stream. After a style
684 * change, new text which is printed to that stream will be given the new style,
685 * whatever that means for the stream in question. For a window stream, the text
686 * will appear in that style. For a memory stream, style changes have no effect.
687 * For a file stream, if the machine supports styled text files, the styles may
688 * be written to the file; more likely the style changes will have no effect.
690 * Styles are exclusive. A character is shown with exactly one style, not a
691 * subset of the possible styles.
694 * Note that every stream and window has its own idea of the <quote>current
695 * style.</quote> Sending a style command to one window or stream does not
699 * Except for a window's echo stream; see <link
700 * linkend="chimara-Echo-Streams">Echo Streams</link>.
703 * The styles are intended to distinguish meaning and use, not formatting. There
704 * is no standard definition of what each style will look like. That is left up
705 * to the Glk library, which will choose an appearance appropriate for the
706 * platform's interface and the player's preferences.
708 * There are currently eleven styles defined. More may be defined in the future.
710 * Styles may be distinguished on screen by font, size, color, indentation,
711 * justification, and other attributes. Note that some attributes (notably
712 * justification and indentation) apply to entire paragraphs. If possible and
713 * relevant, you should apply a style to an entire paragraph — call
714 * glk_set_style() immediately after printing the newline at the beginning of
715 * the text, and do the same at the end.
718 * For example, %style_Header may well be centered text. If you print
719 * <quote>Welcome to Victim (a short interactive mystery)</quote>, and only the
720 * word <quote>Victim</quote> is in the %style_Header, the center-justification
721 * attribute will be lost. Similarly, a block quote is usually indented on both
722 * sides, but indentation is only meaningful when applied to an entire line or
723 * paragraph, so block quotes should take up an entire paragraph. Contrariwise,
724 * %style_Emphasized need not be used on an entire paragraph. It is often used
725 * for single emphasized words in normal text, so you can expect that it will
726 * appear properly that way; it will be displayed in italics or underlining,
727 * not center-justified or indented.
731 * Yes, this is all a matter of mutual agreement between game authors and game
732 * players. It's not fixed by this specification. That's natural language for
738 * SECTION:glk-stylehints
739 * @short_description: Setting style hints
741 * There are no guarantees of how styles will look, but you can make
744 * Initially, no hints are set for any window type or style. Note that having no
745 * hint set is not the same as setting a hint with value 0.
747 * These functions do <emphasis>not</emphasis> affect
748 * <emphasis>existing</emphasis> windows. They affect the windows which you
749 * create subsequently. If you want to set hints for all your game windows, call
750 * glk_stylehint_set() before you start creating windows. If you want different
751 * hints for different windows, change the hints before creating each window.
754 * This policy makes life easier for the interpreter. It knows everything about
755 * a particular window's appearance when the window is created, and it doesn't
756 * have to change it while the window exists.
759 * Hints are hints. The interpreter may ignore them, or give the player a choice
760 * about whether to accept them. Also, it is never necessary to set hints. You
761 * don't have to suggest that %style_Preformatted be fixed-width, or
762 * %style_Emphasized be boldface or italic; they will have appropriate defaults.
763 * Hints are for situations when you want to <emphasis>change</emphasis> the
764 * appearance of a style from what it would ordinarily be. The most common case
765 * when this is appropriate is for the styles %style_User1 and %style_User2.
767 * There are currently ten style hints defined. More may be defined in the
770 * Again, when passing a style hint to a Glk function, any value is actually
771 * legal. If the interpreter does not recognize the stylehint value, it will
774 * This policy allows for the future definition of style hints without breaking
780 * SECTION:glk-style-measure
781 * @short_description: Finding out how the library displays your style hints
783 * You can suggest the appearance of a window's style before the window is
784 * created; after the window is created, you can test the style's actual
785 * appearance. These functions do not test the style hints; they test the
786 * attribute of the style as it appears to the player.
788 * Note that although you cannot change the appearance of a window's styles
789 * after the window is created, the library can. A platform may support dynamic
790 * preferences, which allow the player to change text formatting while your
791 * program is running.
793 * Changes that affect window size (such as font size changes) will be
794 * signalled by an %evtype_Arrange event. However, more subtle changes (such
795 * as text color differences) are not signalled. If you test the appearance of
796 * styles at the beginning of your program, you must keep in mind the
797 * possibility that the player will change them later.
802 * SECTION:glk-stream-types
803 * @short_description: Window, memory, file, and resource streams
805 * <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
807 * Every window has an output stream associated with it. This is created
808 * automatically, with %filemode_Write, when you open the window. You get it
809 * with glk_window_get_stream(). Window streams always have rock value 0.
811 * A window stream cannot be closed with glk_stream_close(). It is closed
812 * automatically when you close its window with glk_window_close().
814 * Only printable characters (including newline) may be printed to a window
815 * stream. See <link linkend="chimara-Character-Encoding">Character
819 * <refsect2 id="chimara-Memory-Streams"><title>Memory Streams</title>
821 * You can open a stream which reads from or writes to a space in memory. See
822 * glk_stream_open_memory() and glk_stream_open_memory_uni(). When opening a
823 * memory stream, you specify a buffer to which the stream's output will be
824 * written, and its length @buflen.
826 * When outputting, if more than @buflen characters are written to the stream,
827 * all of them beyond the buffer length will be thrown away, so as not to
828 * overwrite the buffer. (The character count of the stream will still be
829 * maintained correctly. That is, it will count the number of characters written
830 * into the stream, not the number that fit into the buffer.)
832 * If the buffer is %NULL, or for that matter if @buflen is zero, then
833 * <emphasis>everything</emphasis> written to the stream is thrown away. This
834 * may be useful if you are interested in the character count.
836 * When inputting, if more than @buflen characters are read from the stream, the
837 * stream will start returning -1 (signalling end-of-file.) If the buffer is
838 * %NULL, the stream will always return end-of-file.
840 * The data is written to the buffer exactly as it was passed to the printing
841 * functions (glk_put_char(), etc.); input functions will read the data exactly
842 * as it exists in memory. No platform-dependent cookery will be done on it.
845 * You can write a disk file in text mode, but a memory stream is effectively
846 * always in binary mode.
849 * Whether reading or writing, the contents of the buffer are undefined until
850 * the stream is closed. The library may store the data there as it is written,
851 * or deposit it all in a lump when the stream is closed. It is illegal to
852 * change the contents of the buffer while the stream is open.
855 * <refsect2 id="chimara-File-Streams"><title>File Streams</title>
857 * You can open a stream which reads from or writes to a disk file. See
858 * glk_stream_open_file() and glk_stream_open_file_uni().
860 * The file may be written in text or binary mode; this is determined by the
861 * file reference you open the stream with. Similarly, platform-dependent
862 * attributes such as file type are determined by the file reference. See <link
863 * linkend="chimara-File-References">File References</link>.
866 * <refsect2 id="chimara-Resource-Streams"><title>Resource Streams</title>
868 * You can open a stream which reads from (but not writes to) a resource file.
871 * Typically this is embedded in a Blorb file, as Blorb is the official
872 * resource-storage format of Glk. A Blorb file can contain images and sounds,
873 * but it can also contain raw data files, which are accessed by
874 * glk_stream_open_resource() and glk_stream_open_resource_uni(). A data file
875 * is identified by number, not by a filename. The Blorb usage field will be
876 * <code>'Data'</code>. The chunk type will be %giblorb_ID_TEXT for text
877 * resources, %giblorb_ID_BINA for binary resources.
881 * If the running program is not associated with a Blorb file, the library may
882 * look for data files as actual files instead. These would be named
883 * <filename>DATA1</filename>, <filename>DATA2</filename>, etc, with a suffix
884 * distinguishing text and binary files. See <quote>Other Resource
885 * Arrangements</quote> in the Blorb spec: <ulink
886 * url="http://eblong.com/zarf/blorb/"></ulink>
893 * SECTION:glk-stream-other
894 * @short_description: Miscellaneous functions for streams
896 * This section includes functions for streams that don't fit anywhere else.
900 * SECTION:glk-fileref
901 * @short_description: A platform-independent way to refer to disk files
903 * You deal with disk files using file references. Each fileref is an opaque C
904 * structure pointer; see <link linkend="chimara-Opaque-Objects">Opaque
907 * A file reference contains platform-specific information about the name and
908 * location of the file, and possibly its type, if the platform has a notion of
909 * file type. It also includes a flag indication whether the file is a text file
913 * Note that this is different from the standard C I/O library, in which you
914 * specify text or binary mode when the file is opened.
917 * A fileref does not have to refer to a file which actually exists. You can
918 * create a fileref for a nonexistent file, and then open it in write mode to
921 * You always provide a usage argument when you create a fileref. The usage
922 * indicates the file type and the mode (text or binary.) It must be the
923 * logical-or of a file-type constant and a mode constant. These values are used
924 * when you create a new file, and also to filter file lists when the player is
925 * selecting a file to load.
927 * In general, you should use text mode if the player expects to read the file
928 * with a platform-native text editor; you should use binary mode if the file is
929 * to be read back by your program, or if the data must be stored exactly. Text
930 * mode is appropriate for %fileusage_Transcript; binary mode is appropriate for
931 * %fileusage_SavedGame and probably for %fileusage_InputRecord. %fileusage_Data
932 * files may be text or binary, depending on what you use them for.
936 * SECTION:glk-fileref-types
937 * @short_description: Four different ways to create a file reference
939 * There are four different functions for creating a fileref, depending on how
940 * you wish to specify it. Remember that it is always possible that a fileref
941 * creation will fail and return %NULL.
945 * SECTION:glk-fileref-other
946 * @short_description: Miscellaneous functions for file references
948 * This section includes functions for file references that don't fit anywhere
953 * SECTION:glk-image-resources
954 * @short_description: Graphics in Glk
956 * In accordance with this modern age, Glk provides for a modicum of graphical
957 * flair. It does not attempt to be a complete graphical toolkit. Those already
958 * exist. Glk strikes the usual uncomfortable balance between power,
959 * portability, and ease of implementation: commands for arranging pre-supplied
960 * images on the screen and intermixed with text.
962 * Graphics is an optional capability in Glk; not all libraries support
963 * graphics. This should not be a surprise.
965 * Most of the graphics commands in Glk deal with image resources. Your program
966 * does not have to worry about how images are stored. Everything is a resource,
967 * and a resource is referred to by an integer identifier. You may, for example,
968 * call a function to display image number 17. The format, loading, and
969 * displaying of that image is entirely up to the Glk library for the platform
972 * Of course, it is also desirable to have a platform-independent way to store
973 * sounds and images. Blorb is the official resource-storage format of Glk. A
974 * Glk library does not have to understand Blorb, but it is more likely to
975 * understand Blorb than any other format.
978 * Glk does not specify the exact format of images, but Blorb does. Images in
979 * a Blorb archive must be PNG or JPEG files. More formats may be added if
980 * real-world experience shows it to be desirable. However, that is in the
981 * domain of the Blorb specification. The Glk spec, and Glk programming, will
985 * At present, images can only be drawn in graphics windows and text buffer
986 * windows. In fact, a library may not implement both of these possibilities.
987 * You should test each with the %gestalt_DrawImage selector if you plan to use
988 * it. See <link linkend="chimara-Testing-for-Graphics-Capabilities">Testing for
989 * Graphics Capabilities</link>.
993 * SECTION:glk-graphics-windows
994 * @short_description: Drawing graphics in graphics windows
996 * A graphics window is a rectangular canvas of pixels, upon which you can draw
997 * images. The contents are entirely under your control. You can draw as many
998 * images as you like, at any positions — overlapping if you like. If the
999 * window is resized, you are responsible for redrawing everything. See <link
1000 * linkend="wintype-Graphics">Graphics Windows</link>.
1003 * Note that graphics windows do not support a full set of object-drawing
1004 * commands, nor can you draw text in them. That may be available in a future
1005 * Glk extension. For now, it seems reasonable to limit the task to a single
1006 * primitive, the drawing of a raster image. And then there's the ability to
1007 * fill a rectangle with a solid color — a small extension, and
1008 * hopefully no additional work for the library, since it can already clear
1009 * with arbitrary background colors. In fact, if glk_window_fill_rect() did
1010 * not exist, an author could invent it — by briefly setting the
1011 * background color, erasing a rectangle, and restoring.
1014 * If you call glk_image_draw() or glk_image_draw_scaled() in a graphics window,
1015 * @val1 and @val2 are interpreted as X and Y coordinates. The image will be
1016 * drawn with its upper left corner at this position.
1018 * It is legitimate for part of the image to fall outside the window; the excess
1019 * is not drawn. Note that these are signed arguments, so you can draw an image
1020 * which falls outside the left or top edge of the window, as well as the right
1023 * There are a few other commands which apply to graphics windows.
1027 * SECTION:glk-graphics-text
1028 * @short_description: Drawing graphics inside or beside text
1030 * A text buffer is a linear text stream. You can draw images in-line with this
1031 * text. If you are familiar with HTML, you already understand this model. You
1032 * draw images with flags indicating alignment. The library takes care of
1033 * scrolling, resizing, and reformatting text buffer windows.
1035 * If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer
1036 * window, @val1 gives the image alignment. The @val2 argument is currently
1037 * unused, and should always be zero.
1039 * The two <quote>margin</quote> alignments require some care. To allow proper
1040 * positioning, images using %imagealign_MarginLeft and %imagealign_MarginRight
1041 * must be placed at the beginning of a line. That is, you may only call
1042 * glk_image_draw() (with these two alignments) in a window, if you have just
1043 * printed a newline to the window's stream, or if the window is entirely empty.
1044 * If you margin-align an image in a line where text has already appeared, no
1045 * image will appear at all.
1047 * Inline-aligned images count as <quote>text</quote> for the purpose of this
1050 * You may have images in both margins at the same time.
1052 * It is also legal to have more than one image in the same margin (left or
1053 * right.) However, this is not recommended. It is difficult to predict how text
1054 * will wrap in that situation, and libraries may err on the side of
1059 * SECTION:glk-graphics-testing
1060 * @short_description: Checking whether the library supports graphics
1062 * Before calling Glk graphics functions, you should use the gestalt selector
1063 * %gestalt_Graphics. To test for additional capabilities, you can also use the
1064 * %gestalt_DrawImage and %gestalt_GraphicsTransparency selectors.
1068 * SECTION:glk-sound-channels
1069 * @short_description: Creating new sound channels and closing them
1071 * Sounds in Glk are played through sound channels. Sound channels are another
1072 * type of opaque object, like windows, streams, and file references.
1076 * SECTION:glk-playing-sounds
1077 * @short_description: Producing noise
1079 * These functions play the actual sounds through the sound channels.
1083 * SECTION:glk-sound-other
1084 * @short_description: Miscellaneous functions for sound channels
1086 * This section includes functions for sound channels that don't fit anywhere
1091 * SECTION:glk-sound-testing
1092 * @short_description: Checking whether the library supports sound
1094 * Before calling Glk sound functions, you should use the %gestalt_Sound2
1097 * Earlier versions of the Glk spec defined separate selectors for various
1098 * optional capabilities. This has proven to be an unnecessarily confusing
1099 * strategy, and is no longer used. The %gestalt_Sound, %gestalt_SoundMusic,
1100 * %gestalt_SoundVolume, and %gestalt_SoundNotify selectors still exist, but you
1101 * should not need to test them; the %gestalt_Sound2 selector covers all of
1106 * SECTION:glk-creating-hyperlinks
1107 * @short_description: Printing text as a hyperlink
1109 * Some games may wish to mark up text in their windows with hyperlinks, which
1110 * can be selected by the player — most likely by mouse click. Glk allows
1111 * this in a manner similar to the way text styles are set.
1113 * Hyperlinks are an optional capability in Glk.
1117 * SECTION:glk-accepting-hyperlinks
1118 * @short_description: Generating and catching hyperlink navigation events
1120 * When you request a hyperlink event in a window, you will receive a hyperlink
1121 * event when the player clicks on a hyperlink.
1125 * SECTION:glk-hyperlinks-testing
1126 * @short_description: Checking whether the library supports hyperlinks
1128 * Before calling Glk hyperlink functions, you should use the gestalt selectors
1129 * %gestalt_Hyperlinks and %gestalt_HyperlinkInput.
1134 * @short_description: Getting the current time from the system clock
1136 * You can get the current time, either as a Unix timestamp (seconds since 1970)
1137 * or as a broken-out structure of time elements (year, month, day, hour,
1140 * The system clock is not guaranteed to line up with timer events (see <link
1141 * linkend="chimara-Timer-Events">Timer Events</link>). Timer events may be
1142 * delivered late according to the system clock.
1146 * SECTION:glk-clock-conversions
1147 * @short_description: Converting from timestamps to date structures and back
1149 * This section describes functions for converting timestamps to more
1150 * human-readable date structures and back.
1154 * SECTION:glk-clock-testing
1155 * @short_description: Checking whether the library supports the clock functions
1157 * Before calling Glk date and time functions, you should use the
1158 * %gestalt_DateTime selector.
1162 * SECTION:dispatch-interrogating
1163 * @short_description: Finding out what functions the Glk library exports
1165 * These are the ancilliary functions that let you enumerate.
1169 * SECTION:dispatch-dispatching
1170 * @short_description: Dispatching the call to the Glk library
1172 * The function gidispatch_call() invokes a function from the Glk library.
1176 * SECTION:dispatch-prototypes
1177 * @short_description: Querying Glk function prototypes
1179 * There are many possible ways to set up a #gluniversal_t array, and it's
1180 * illegal to call gidispatch_call() with an array which doesn't match the
1181 * function. Furthermore, some references are passed in, some passed out, and
1182 * some both. How do you know how to handle the argument list?
1184 * One possibility is to recognize each function selector, and set up the
1185 * arguments appropriately. However, this entails writing special code for each
1186 * Glk function; which is exactly what we don't want to do.
1188 * Instead, you can call gidispatch_prototype().
1192 * SECTION:dispatch-library-functions
1193 * @short_description: Platform-dependent dispatch layer functions
1195 * Ideally, the three layers — program, dispatch layer, Glk library
1196 * — would be completely modular; each would refer only to the layers
1197 * beneath it. Sadly, there are a few places where the library must notify the
1198 * program that something has happened. Worse, these situations are only
1199 * relevant to programs which use the dispatch layer, and then only some of
1202 * Since C is uncomfortable with the concept of calling functions which may not
1203 * exist, Glk handles this with call-back function pointers. The program can
1204 * pass callbacks in to the library; if it does, the library will call them, and
1205 * if not, the library doesn't try.
1207 * These callbacks are optional, in the sense that the program may or may not
1208 * set them. However, any library which wants to interoperate with the dispatch
1209 * layer must <emphasis>allow</emphasis> the program to set them; it is the
1210 * program's choice. The library does this by implementing
1211 * <code>set_registry functions</code> — the functions to which the
1212 * program passes its callbacks.
1215 * Even though these callbacks and the functions to set them are declared in
1216 * <filename class="headerfile">gi_dispa.h</filename>, they are not defined in
1217 * <filename>gi_dispa.c</filename>. The dispatch layer merely coordinates
1218 * them. The program defines the callback functions; the library calls them.
1223 * SECTION:blorb-program
1224 * @short_description: How to use the Blorb layer in your program
1226 * If you wish your program to load its resources from a Blorb file, you need to
1227 * find and open that file in your startup code. (See <link
1228 * linkend="chimara-Startup-Options">Startup Options</link>.) Each platform will
1229 * have appropriate functions available for finding startup data. Be sure to
1230 * open the file in binary mode, not text mode. Once you have opened the file as
1231 * a Glk stream, pass it to giblorb_set_resource_map().
1233 * If you do not call giblorb_set_resource_map() in your startup code, or if it
1234 * fails, the library is left to its own devices for finding resources. Some
1235 * libraries may try to load resources from individual files —
1236 * <filename>PIC1</filename>, <filename>PIC2</filename>,
1237 * <filename>PIC3</filename>, and so on. (See the Blorb specification for more
1238 * on this approach.) Other libraries will not have any other loading mechanism
1239 * at all; no resources will be available.
1243 * SECTION:blorb-layer
1244 * @short_description: The platform-independent functions in the Blorb layer
1246 * These are the functions which are implemented in
1247 * <filename>gi_blorb.c</filename>. They will be compiled into the library, but
1248 * they are the same on every platform. In general, only the library needs to
1249 * call these functions. The Glk program should allow the library to do all the
1250 * resource handling.
1254 * SECTION:blorb-errors
1255 * @short_description: Error codes returned by the Blorb layer functions
1257 * All Blorb layer functions, including giblorb_set_resource_map(), return the
1258 * following error codes.
1262 * SECTION:glkext-startup
1263 * @short_description: Parsing startup options
1265 * This section describes an extension to Glk for parsing command-line startup
1266 * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and
1269 * When you compile a Glk program, you may define a function called
1270 * <function>glkunix_startup_code()</function>, and an array
1271 * <code>glkunix_arguments[]</code>. These set up various Unix-specific options
1272 * used by the Glk library. There is a sample
1273 * <quote><filename>glkstart.c</filename></quote> file included in this package;
1274 * you should modify it to your needs.
1276 * |[ extern glkunix_argumentlist_t glkunix_arguments[]; ]|
1278 * The <code>glkunix_arguments[]</code> array is a list of command-line
1279 * arguments that your program can accept. The library will sort these out of
1280 * the command line and pass them on to your code.
1284 * SECTION:glkext-unix
1285 * @short_description: Unix-specific functions
1287 * This section describes an extension to Glk for various Unix functions. It was
1288 * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm.
1290 * You can put other startup code in glkunix_startup_code(). This should
1291 * generally be limited to finding and opening data files. There are a few Unix
1292 * Glk library functions which are convenient for this purpose.
1296 * SECTION:glkext-garglk
1297 * @short_description: Gargoyle extensions to Glk
1299 * This section describes various extensions to Glk that were written for the
1300 * popular interpreter <ulink
1301 * url="http://www.ccxvii.net/gargoyle/">Gargoyle</ulink> by Tor Andersson (now
1302 * maintained by Ben Cressey).
1304 * These functions mostly serve to close the gap between Glk's input/output
1305 * capabilities and what some interpreters expect. For example,
1306 * garglk_set_zcolors() displays the colors defined in the Z-machine standard,
1307 * and garglk_set_story_name() can be used to give the host program a hint
1308 * about what to display in the title bar of its window.
1311 /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/
1316 * A 32-bit unsigned integer type, used wherever possible in Glk.
1322 * A 32-bit signed integer type, rarely used.
1326 * GLK_MODULE_UNICODE:
1328 * If this preprocessor symbol is defined, so are the core Unicode functions and
1329 * constants (see %gestalt_Unicode). If not, not.
1335 * If you are writing a C program, there is an additional complication. A
1336 * library which does not support graphics may not implement the graphics
1337 * functions at all. Even if you put gestalt tests around your graphics calls,
1338 * you may get link-time errors. If the <filename
1339 * class="headerfile">glk.h</filename> file is so old that it does not declare
1340 * the graphics functions and constants, you may even get compile-time errors.
1342 * To avoid this, you can perform a preprocessor test for the existence of
1343 * %GLK_MODULE_IMAGE. If this is defined, so are all the functions and constants
1344 * described in this section. If not, not.
1347 * To be extremely specific, there are two ways this can happen. If the
1348 * <filename class="headerfile">glk.h</filename> file that comes with the
1349 * library is too old to have the graphics declarations in it, it will of
1350 * course lack %GLK_MODULE_IMAGE as well. If the <filename
1351 * class="headerfile">glk.h</filename> file is recent, but the library is old,
1352 * the definition of %GLK_MODULE_IMAGE should be removed from <filename
1353 * class="headerfile">glk.h</filename>, to avoid link errors. This is not a
1354 * great solution. A better one is for the library to implement the graphics
1355 * functions as stubs that do nothing (or cause run-time errors). Since no
1356 * program will call the stubs without testing %gestalt_Graphics, this is
1362 * GLK_MODULE_SOUND2:
1364 * If you are writing a C program, there is an additional complication. A
1365 * library which does not support sound may not implement the sound functions at
1366 * all. Even if you put gestalt tests around your sound calls, you may get
1367 * link-time errors. If the <filename class="headerfile">glk.h</filename> file
1368 * is so old that it does not declare the sound functions and constants, you may
1369 * even get compile-time errors.
1371 * To avoid this, you can perform a preprocessor test for the existence of
1372 * %GLK_MODULE_SOUND2. If this is defined, so are all the functions and constants
1373 * described in this section. If not, not.
1379 * You can perform a preprocessor test for the existence of %GLK_MODULE_SOUND.
1380 * If this is defined, so are all the functions and constants described in this
1381 * section. If not, not.
1385 * GLK_MODULE_HYPERLINKS:
1387 * If you are writing a C program, you can perform a preprocessor test for the
1388 * existence of %GLK_MODULE_HYPERLINKS. If this is defined, so are all the
1389 * functions and constants described in this section. If not, not.
1393 * GLK_MODULE_UNICODE_NORM:
1395 * If this preprocessor symbol is defined, so are the Unicode normalization
1396 * functions (see %gestalt_UnicodeNorm). If not, not.
1400 * GLK_MODULE_DATETIME:
1402 * If you are writing a C program, you can perform a preprocessor test for the
1403 * existence of %GLK_MODULE_DATETIME. If this is defined, so are all the
1404 * functions and data types described in this section.
1408 * GLK_MODULE_LINE_ECHO:
1410 * If this preprocessor symbol is defined, so is glk_set_echo_line_event(). If
1415 * GLK_MODULE_LINE_TERMINATORS:
1417 * If this preprocessor symbol is defined, so is
1418 * glk_set_terminators_line_event(). If not, not.
1424 * Opaque structure representing a Glk window. It has no user-accessible
1431 * Opaque structure representing an input or output stream. It has no
1432 * user-accessible members.
1438 * Opaque structure representing a file reference. It has no user-accessible
1445 * Opaque structure representing a sound channel. It has no user-accessible
1452 * For an example of the gestalt mechanism, consider the selector
1453 * %gestalt_Version. If you do
1456 * res = glk_gestalt(gestalt_Version, 0);
1458 * <code>res</code> will be set to a 32-bit number which encodes the version of
1459 * the Glk spec which the library implements. The upper 16 bits stores the major
1460 * version number; the next 8 bits stores the minor version number; the low 8
1461 * bits stores an even more minor version number, if any.
1464 * So the version number 78.2.11 would be encoded as 0x004E020B.
1467 * The current Glk specification version is 0.7.4, so this selector will return
1472 * res = glk_gestalt_ext(gestalt_Version, 0, NULL, 0);
1474 * does exactly the same thing. Note that, in either case, the second argument
1475 * is not used; so you should always pass 0 to avoid future surprises.
1479 * gestalt_CharInput:
1481 * If you set <code>ch</code> to a character code, or a special code (from
1482 * 0xFFFFFFFF down), and call
1485 * res = glk_gestalt(gestalt_CharInput, ch);
1487 * then <code>res</code> will be %TRUE (1) if that character can be typed by
1488 * the player in character input, and %FALSE (0) if not. See <link
1489 * linkend="chimara-Character-Input">Character Input</link>.
1493 * gestalt_LineInput:
1495 * If you set <code>ch</code> to a character code, and call
1498 * res = glk_gestalt(gestalt_LineInput, ch);
1500 * then <code>res</code> will be %TRUE (1) if that character can be typed by the
1501 * player in line input, and %FALSE (0) if not. Note that if <code>ch</code> is
1502 * a nonprintable Latin-1 character (0 to 31, 127 to 159), then this is
1503 * guaranteed to return %FALSE. See <link linkend="chimara-Line-Input">Line
1508 * gestalt_CharOutput:
1510 * If you set <code>ch</code> to a character code (Latin-1 or higher), and call
1513 * res = glk_gestalt_ext(gestalt_CharOutput, ch, &len, 1);
1515 * then <code>res</code> will be one of %gestalt_CharOutput_CannotPrint,
1516 * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see
1519 * In all cases, <code>len</code> (the #glui32 value pointed at by the third
1520 * argument) will be the number of actual glyphs which will be used to represent
1521 * the character. In the case of %gestalt_CharOutput_ExactPrint, this will
1522 * always be 1; for %gestalt_CharOutput_CannotPrint, it may be 0 (nothing
1523 * printed) or higher; for %gestalt_CharOutput_ApproxPrint, it may be 1 or
1524 * higher. This information may be useful when printing text in a fixed-width
1528 * As described in <link linkend="chimara-Other-API-Conventions">Other API
1529 * Conventions</link>, you may skip this information by passing %NULL as the
1530 * third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead.
1533 * This selector will always return %gestalt_CharOutput_CannotPrint if
1534 * <code>ch</code> is an unprintable eight-bit character (0 to 9, 11 to 31, 127
1538 * Make sure you do not get confused by signed byte values. If you set a
1539 * <quote><type>signed char</type></quote> variable <code>ch</code> to 0xFE,
1540 * the small-thorn character (þ), it will wind up as -2. (The same is
1541 * true of a <quote><type>char</type></quote> variable, if your compiler
1542 * treats <quote><type>char</type></quote> as signed!) If you then call
1543 * |[ res = glk_gestalt(gestalt_CharOutput, ch); ]|
1544 * then (by the definition of C/C++) <code>ch</code> will be sign-extended to
1545 * 0xFFFFFFFE, which is not a legitimate character, even in Unicode. You
1547 * |[ res = glk_gestalt(gestalt_CharOutput, (unsigned char)ch); ]|
1551 * Unicode includes the concept of non-spacing or combining characters, which
1552 * do not represent glyphs; and double-width characters, whose glyphs take up
1553 * two spaces in a fixed-width font. Future versions of this spec may
1554 * recognize these concepts by returning a <code>len</code> of 0 or 2 when
1555 * %gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to
1556 * a policy of <quote>simple stuff first</quote>.
1561 * gestalt_CharOutput_CannotPrint:
1563 * When the %gestalt_CharOutput selector returns this for a character, the
1564 * character cannot be meaningfully printed. If you try, the player may see
1565 * nothing, or may see a placeholder.
1569 * gestalt_CharOutput_ApproxPrint:
1571 * When the %gestalt_CharOutput selector returns this for a character, the
1572 * library will print some approximation of the character. It will be more or
1573 * less right, but it may not be precise, and it may not be distinguishable from
1574 * other, similar characters. (Examples:
1575 * <quote><computeroutput>ae</computeroutput></quote> for the one-character
1576 * <quote>æ</quote> ligature,
1577 * <quote><computeroutput>e</computeroutput></quote> for
1578 * <quote>è</quote>, <quote><computeroutput>|</computeroutput></quote>
1579 * for a broken vertical bar (¦).)
1583 * gestalt_CharOutput_ExactPrint:
1585 * When the %gestalt_CharOutput selector returns this for a character, the
1586 * character will be printed exactly as defined.
1590 * gestalt_MouseInput:
1592 * You can test whether mouse input is supported with the %gestalt_MouseInput
1594 * |[ res = glk_gestalt(gestalt_MouseInput, windowtype); ]|
1595 * This will return %TRUE (1) if windows of the given type support mouse input.
1596 * If this returns %FALSE (0), it is still legal to call
1597 * glk_request_mouse_event(), but it will have no effect, and you will never get
1604 * You can test whether the library supports timer events:
1605 * |[ res = glk_gestalt(gestalt_Timer, 0); ]|
1606 * This returns %TRUE (1) if timer events are supported, and %FALSE (0) if they
1613 * Before calling Glk graphics functions, you should use the following gestalt
1617 * res = glk_gestalt(gestalt_Graphics, 0);
1619 * This returns 1 if the overall suite of graphics functions is available. This
1620 * includes glk_image_draw(), glk_image_draw_scaled(), glk_image_get_info(),
1621 * glk_window_erase_rect(), glk_window_fill_rect(),
1622 * glk_window_set_background_color(), and glk_window_flow_break(). It also
1623 * includes the capability to create graphics windows.
1625 * If this selector returns 0, you should not try to call these functions. They
1626 * may have no effect, or they may cause a run-time error. If you try to create
1627 * a graphics window, you will get %NULL.
1631 * gestalt_DrawImage:
1633 * This selector returns 1 if images can be drawn in windows of the given type.
1634 * If it returns 0, glk_image_draw() will fail and return %FALSE (0). You should
1635 * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries
1636 * may implement both, neither, or only one.
1642 * You can test whether the library supports sound:
1645 * res = glk_gestalt(gestalt_Sound2, 0);
1647 * This returns 1 if the overall suite of sound functions is available. This
1648 * includes all the functions defined in <link
1649 * linkend="chimara-glk-spec-sound">this chapter</link>. It also includes the
1650 * capabilities described below under %gestalt_SoundMusic, %gestalt_SoundVolume,
1651 * and %gestalt_SoundNotify.
1659 * res = glk_gestalt(gestalt_Sound, 0);
1661 * This returns 1 if the overall suite of sound functions is available. This
1662 * includes glk_schannel_create(), glk_schannel_destroy(),
1663 * glk_schannel_iterate(), glk_schannel_get_rock(), glk_schannel_play(),
1664 * glk_schannel_play_ext(), glk_schannel_stop(), glk_schannel_set_volume(), and
1665 * glk_sound_load_hint().
1667 * If this selector returns 0, you should not try to call these functions. They
1668 * may have no effect, or they may cause a run-time error.
1670 * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
1674 * gestalt_SoundVolume:
1676 * You can test whether the library supports setting the volume of sound
1678 * |[ res = glk_gestalt(gestalt_SoundVolume, 0); ]|
1679 * This selector returns 1 if the glk_schannel_set_volume() function works. If
1680 * it returns zero, glk_schannel_set_volume() has no effect.
1682 * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
1686 * gestalt_SoundNotify:
1688 * You can test whether the library supports sound notification events:
1689 * |[ res = glk_gestalt(gestalt_SoundNotify, 0); ]|
1690 * This selector returns 1 if the library supports sound notification events. If
1691 * it returns zero, you will never get such events.
1693 * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
1697 * gestalt_Hyperlinks:
1699 * You can test whether the library supports hyperlinks:
1702 * res = glk_gestalt(gestalt_Hyperlinks, 0);
1704 * This returns 1 if the overall suite of hyperlinks functions is available.
1705 * This includes glk_set_hyperlink(), glk_set_hyperlink_stream(),
1706 * glk_request_hyperlink_event(), glk_cancel_hyperlink_event().
1708 * If this selector returns 0, you should not try to call these functions. They
1709 * may have no effect, or they may cause a run-time error.
1713 * gestalt_HyperlinkInput:
1715 * You can test whether hyperlinks are supported with the
1716 * %gestalt_HyperlinkInput selector:
1717 * |[ res = glk_gestalt(gestalt_HyperlinkInput, windowtype); ]|
1718 * This will return %TRUE (1) if windows of the given type support hyperlinks.
1719 * If this returns %FALSE (0), it is still legal to call glk_set_hyperlink() and
1720 * glk_request_hyperlink_event(), but they will have no effect, and you will
1721 * never get hyperlink events.
1725 * gestalt_SoundMusic:
1727 * You can test whether music resources are supported:
1728 * |[ res = glk_gestalt(gestalt_SoundMusic, 0); ]|
1729 * This returns 1 if the library is capable of playing music sound resources. If
1730 * it returns 0, only sampled sounds can be played.
1732 * <quote>Music sound resources</quote> means MOD songs — the only music
1733 * format that Blorb currently supports. The presence of this selector is, of
1734 * course, an ugly hack. It is a concession to the current state of the Glk
1735 * libraries, some of which can handle AIFF but not MOD sounds.
1738 * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
1742 * gestalt_GraphicsTransparency:
1744 * This returns 1 if images with alpha channels can actually be drawn with the
1745 * appropriate degree of transparency. If it returns 0, the alpha channel is
1746 * ignored; fully transparent areas will be drawn in an implementation-defined
1749 * The JPEG format does not support transparency or alpha channels; the PNG
1757 * The basic text functions will be available in every Glk library. The Unicode
1758 * functions may or may not be available. Before calling them, you should use
1759 * the %gestalt_Unicode and %gestalt_UnicodeNorm gestalt selectors.
1763 * res = glk_gestalt(gestalt_Unicode, 0);
1765 * This returns 1 if the core Unicode functions are available. If it returns 0,
1766 * you should not try to call them. They may print nothing, print gibberish, or
1767 * cause a run-time error. The Unicode functions include
1768 * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),
1769 * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
1770 * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
1771 * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
1772 * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
1773 * glk_request_char_event_uni(), glk_request_line_event_uni(),
1774 * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
1776 * If you are writing a C program, there is an additional complication. A
1777 * library which does not support Unicode may not implement the Unicode
1778 * functions at all. Even if you put gestalt tests around your Unicode calls,
1779 * you may get link-time errors. If the
1780 * <filename class="headerfile">glk.h</filename> file is so old that it does not
1781 * declare the Unicode functions and constants, you may even get compile-time
1784 * To avoid this, you can perform a preprocessor test for the existence of
1785 * %GLK_MODULE_UNICODE.
1789 * gestalt_UnicodeNorm:
1793 * res = glk_gestalt(gestalt_UnicodeNorm, 0);
1795 * This code returns 1 if the Unicode normalization functions are available. If
1796 * it returns 0, you should not try to call them. The Unicode normalization
1797 * functions include glk_buffer_canon_decompose_uni() and
1798 * glk_buffer_canon_normalize_uni().
1800 * The equivalent preprocessor test for these functions is
1801 * %GLK_MODULE_UNICODE_NORM.
1805 * gestalt_LineInputEcho:
1808 * res = glk_gestalt(gestalt_LineInputEcho, 0);
1811 * This returns 1 if glk_set_echo_line_event() is supported, and 0 if it is not.
1813 * Remember that if it is not supported, the behavior is always the default,
1814 * which is line echoing <emphasis>enabled</emphasis>.
1819 * gestalt_LineTerminators:
1822 * res = glk_gestalt(gestalt_LineTerminators, 0);
1825 * This returns 1 if glk_set_terminators_line_event() is supported, and 0 if it
1830 * gestalt_LineTerminatorKey:
1833 * res = glk_gestalt(gestalt_LineTerminatorKey, ch);
1836 * This returns 1 if the keycode @ch can be passed to
1837 * glk_set_terminators_line_event(). If it returns 0, that keycode will be
1838 * ignored as a line terminator. Printable characters and %keycode_Return will
1846 * res = glk_gestalt(gestalt_DateTime, 0);
1849 * This returns 1 if the overall suite of system clock functions, as described
1850 * in <link linkend="chimara-The-System-Clock">this chapter</link>, is
1853 * If this selector returns 0, you should not try to call these functions. They
1854 * may have no effect, or they may cause a run-time error.
1857 * Glk timer events are covered by a different selector. See %gestalt_Timer.
1862 * gestalt_ResourceStream:
1865 * res = glk_gestalt(gestalt_ResourceStream, 0);
1868 * This returns 1 if the glk_stream_open_resource() and
1869 * glk_stream_open_resource_uni() functions are available. If it returns 0, you
1870 * should not call them.
1876 * No event. This is a placeholder, and glk_select() never returns it.
1882 * An event that repeats at fixed intervals. See <link
1883 * linkend="chimara-Timer-Events">Timer Events</link>.
1889 * A keystroke event in a window. See <link
1890 * linkend="chimara-Character-Input-Events">Character Input Events</link>.
1892 * If a window has a pending request for character input, and the player hits a
1893 * key in that window, glk_select() will return an event whose type is
1894 * %evtype_CharInput. Once this happens, the request is complete; it is no
1895 * longer pending. You must call glk_request_char_event() or
1896 * glk_request_char_event_uni() if you want another character from that window.
1898 * In the event structure, @win tells what window the event came from. @val1
1899 * tells what character was entered; this will be a character code, or a special
1900 * keycode. (See <link linkend="chimara-Character-Input">Character
1901 * Input</link>.) If you called glk_request_char_event(), @val1 will be in
1902 * 0..255, or else a special keycode. In any case, @val2 will be 0.
1908 * A full line of input completed in a window. See <link
1909 * linkend="chimara-Line-Input-Events">Line Input Events</link>.
1911 * If a window has a pending request for line input, the player can generally
1912 * hit the <keycap>enter</keycap> key (in that window) to complete line input.
1913 * The details will depend on the platform's native user interface.
1915 * When line input is completed, glk_select() will return an event whose type is
1916 * %evtype_LineInput. Once this happens, the request is complete; it is no
1917 * longer pending. You must call glk_request_line_event() if you want another
1918 * line of text from that window.
1920 * In the event structure, @win tells what window the event came from. @val1
1921 * tells how many characters were entered. @val2 will be 0 unless input was
1922 * ended by a special terminator key, in which case @val2 will be the keycode
1923 * (one of the values passed to glk_set_terminators_line_event()).
1925 * The characters themselves are stored in the buffer specified in the original
1926 * glk_request_line_event() or glk_request_line_event_uni() call.
1929 * There is no null terminator or newline stored in the buffer.
1932 * It is illegal to print anything to a window which has line input pending.
1935 * This is because the window may be displaying and editing the player's
1936 * input, and printing anything would make life unnecessarily complicated for
1942 * evtype_MouseInput:
1944 * A mouse click in a window. See <link
1945 * linkend="chimara-Mouse-Input-Events">Mouse Input Events</link>.
1951 * An event signalling that the sizes of some windows have changed.
1953 * Some platforms allow the player to resize the Glk window during play. This
1954 * will naturally change the sizes of your windows. If this occurs, then
1955 * immediately after all the rearrangement, glk_select() will return an event
1956 * whose type is %evtype_Arrange. You can use this notification to redisplay the
1957 * contents of a graphics or text grid window whose size has changed.
1960 * The display of a text buffer window is entirely up to the library, so you
1961 * don't need to worry about those.
1964 * In the event structure, @win will be %NULL if all windows are affected. If
1965 * only some windows are affected, @win will refer to a window which contains
1966 * all the affected windows. @val1 and @val2 will be 0.
1969 * You can always play it safe, ignore @win, and redraw every graphics and
1973 * An arrangement event is guaranteed to occur whenever the player causes any
1974 * window to change size, as measured by its own metric.
1977 * Size changes caused by you — for example, if you open, close, or
1978 * resize a window — do not trigger arrangement events. You must be
1979 * aware of the effects of your window management, and redraw the windows that
1984 * It is possible that several different player actions can cause windows to
1985 * change size. For example, if the player changes the screen resolution, an
1986 * arrangement event might be triggered. This might also happen if the player
1987 * changes his display font to a different size; the windows would then be
1988 * different <quote>sizes</quote> in the metric of rows and columns, which is
1989 * the important metric and the only one you have access to.
1992 * Arrangement events, like timer events, can be returned by glk_select_poll().
1993 * But this will not occur on all platforms. You must be ready to receive an
1994 * arrangement event when you call glk_select_poll(), but it is possible that it
1995 * will not arrive until the next time you call glk_select().
1998 * This is because on some platforms, window resizing is handled as part of
1999 * player input; on others, it can be triggered by an external process such as
2007 * An event signalling that graphics windows must be redrawn.
2009 * On platforms that support graphics, it is possible that the contents of a
2010 * graphics window will be lost, and have to be redrawn from scratch. If this
2011 * occurs, then glk_select() will return an event whose type is %evtype_Redraw.
2013 * In the event structure, @win will be %NULL if all windows are affected. If
2014 * only some windows are affected, @win will refer to a window which contains
2015 * all the affected windows. @val1 and @val2 will be 0.
2018 * You can always play it safe, ignore @win, and redraw every graphics window.
2021 * Affected windows are already cleared to their background color when you
2022 * receive the redraw event.
2024 * Redraw events can be returned by glk_select_poll(). But, like arrangement
2025 * events, this is platform-dependent. See %evtype_Arrange.
2027 * For more about redraw events and how they affect graphics windows, see <link
2028 * linkend="wintype-Graphics">Graphics Windows</link>.
2032 * evtype_SoundNotify:
2034 * The completion of a sound being played in a sound channel.
2036 * On platforms that support sound, you can request to receive an
2037 * %evtype_SoundNotify event when a sound finishes playing. See <link
2038 * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
2044 * The selection of a hyperlink in a window.
2046 * On platforms that support hyperlinks, you can request to receive an
2047 * %evtype_Hyperlink event when the player selects a link. See <link
2048 * linkend="chimara-Accepting-Hyperlink-Events">Accepting Hyperlink
2053 * evtype_VolumeNotify:
2055 * The completion of a gradual volume change in a sound channel.
2057 * On platforms that support sound, you can request to receive an
2058 * %evtype_VolumeNotify event when a gradual volume change completes. See <link
2059 * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
2064 * @type: the event type
2065 * @win: the window that spawned the event, or %NULL
2066 * @val1: information, the meaning of which depends on the type of event
2067 * @val2: more information, the meaning of which depends on the type of event
2069 * The event structure is self-explanatory. @type is the event type. The window
2070 * that spawned the event, if relevant, is in @win. The remaining fields contain
2071 * more information specific to the event.
2073 * The event types are described below. Note that %evtype_None is zero, and the
2074 * other values are positive. Negative event types (0x80000000 to 0xFFFFFFFF)
2075 * are reserved for implementation-defined events.
2081 * Represents any key that has no Latin-1 or special code.
2087 * Represents the <keycap function="left">left arrow</keycap> key.
2093 * Represents the <keycap function="right">right arrow</keycap> key.
2099 * Represents the <keycap function="up">up arrow</keycap> key.
2105 * Represents the <keycap function="down">down arrow</keycap> key.
2111 * Represents the <keycap function="enter">return</keycap> or <keycap
2112 * function="enter">enter</keycap> keys.
2118 * Represents the <keycap function="delete">delete</keycap> or <keycap
2119 * function="backspace">backspace</keycap> keys.
2125 * Represents the <keycap function="escape">escape</keycap> key.
2131 * Represents the <keycap function="tab">tab</keycap> key.
2137 * Represents the <keycap function="pageup">page up</keycap> key.
2143 * Represents the <keycap function="pagedown">page down</keycap> key.
2149 * Represents the <keycap function="home">home</keycap> key.
2155 * Represents the <keycap function="end">end</keycap> key.
2161 * Represents the <keycap>F1</keycap> key.
2167 * Represents the <keycap>F2</keycap> key.
2173 * Represents the <keycap>F3</keycap> key.
2179 * Represents the <keycap>F4</keycap> key.
2185 * Represents the <keycap>F5</keycap> key.
2191 * Represents the <keycap>F6</keycap> key.
2197 * Represents the <keycap>F7</keycap> key.
2203 * Represents the <keycap>F8</keycap> key.
2209 * Represents the <keycap>F9</keycap> key.
2215 * Represents the <keycap>F10</keycap> key.
2221 * Represents the <keycap>F11</keycap> key.
2227 * Represents the <keycap>F12</keycap> key.
2233 * The style of normal or body text. A new window or stream always starts with
2234 * %style_Normal as the current style.
2240 * Text which is emphasized.
2244 * style_Preformatted:
2246 * Text which has a particular arrangement of characters.
2248 * This style, unlike the others, does have a standard appearance; it will
2249 * always be a fixed-width font. This is a concession to practicality. Games
2250 * often want to display maps or diagrams using character graphics, and this is
2251 * the style for that.
2258 * Text which introduces a large section. This is suitable for the title of an
2259 * entire game, or a major division such as a chapter.
2265 * Text which introduces a smaller section within a large section.
2267 * In a Colossal-Cave-style game, this is suitable for the name of a room (when
2268 * the player looks around.)
2275 * Text which warns of a dangerous condition, or one which the player should pay
2282 * Text which notifies of an interesting condition.
2284 * This is suitable for noting that the player's score has changed.
2291 * Text which forms a quotation or otherwise abstracted text.
2297 * Text which the player has entered. You should generally not use this style at
2298 * all; the library uses it for text which is typed during a line-input request.
2299 * One case when it is appropriate for you to use %style_Input is when you are
2300 * simulating player input by reading commands from a text file.
2306 * This style has no particular semantic meaning. You may define a meaning
2307 * relevant to your own work, and use it as you see fit.
2313 * Another style available for your use.
2318 * @readcount: Number of characters read from the stream.
2319 * @writecount: Number of characters printed to the stream, including ones that
2322 * If you are interested in the character counts of a stream (see <link
2323 * linkend="chimara-Streams">Streams</link>), then you can pass a pointer to
2324 * #stream_result_t as an argument of glk_stream_close() or glk_window_close().
2325 * The structure will be filled with the stream's final character counts.
2331 * A constant representing all window types, which may be used as the @wintype
2332 * argument in glk_stylehint_set().
2338 * A pair window is completely filled by the two windows it contains. It
2339 * supports no input and no output, and it has no size.
2341 * You cannot directly create a pair window; one is automatically created
2342 * every time you split a window with glk_window_open(). Pair windows are
2343 * always created with a rock value of 0.
2345 * You can close a pair window with glk_window_close(); this also closes every
2346 * window contained within the pair window.
2348 * It is legal to split a pair window when you call glk_window_open().
2354 * A blank window is always blank. It supports no input and no output. (You
2355 * can call glk_window_get_stream() on it, as you can with any window, but
2356 * printing to the resulting stream has no effect.) A blank window has no
2357 * size; glk_window_get_size() will return (0,0), and it is illegal to set a
2358 * window split with a fixed size in the measurement system of a blank window.
2361 * A blank window is not the same as there being no windows. When Glk starts
2362 * up, there are no windows at all, not even a window of the blank type.
2367 * wintype_TextBuffer:
2369 * A text buffer window contains a linear stream of text. It supports output;
2370 * when you print to it, the new text is added to the end. There is no way for
2371 * you to affect text which has already been printed. There are no guarantees
2372 * about how much text the window keeps; old text may be stored forever, so
2373 * that the user can scroll back to it, or it may be thrown away as soon as it
2374 * scrolls out of the window.
2377 * Therefore, there may or may not be a player-controllable scroll bar or
2378 * other scrolling widget.
2381 * The display of the text in a text buffer is up to the library. Lines will
2382 * probably not be broken in the middles of words — but if they are, the
2383 * library is not doing anything illegal, only ugly. Text selection and copying
2384 * to a clipboard, if available, are handled however is best on the player's
2385 * machine. Paragraphs (as defined by newline characters in the output) may be
2389 * You should not, in general, fake this by printing spaces before each
2390 * paragraph of prose text. Let the library and player preferences handle
2391 * that. Special cases (like indented lists) are of course up to you.
2394 * When a text buffer is cleared (with glk_window_clear()), the library will do
2395 * something appropriate; the details may vary. It may clear the window, with
2396 * later text appearing at the top — or the bottom. It may simply print
2397 * enough blank lines to scroll the current text out of the window. It may
2398 * display a distinctive page-break symbol or divider.
2400 * The size of a text buffer window is necessarily imprecise. Calling
2401 * glk_window_get_size() will return the number of rows and columns that would
2402 * be available <emphasis>if</emphasis> the window was filled with
2403 * <quote>0</quote> (zero) characters in the <quote>normal</quote> font.
2404 * However, the window may use a non-fixed-width font, so that number of
2405 * characters in a line could vary. The window might even support
2406 * variable-height text (say, if the player is using large text for emphasis);
2407 * that would make the number of lines in the window vary as well.
2409 * Similarly, when you set a fixed-size split in the measurement system of a
2410 * text buffer, you are setting a window which can handle a fixed number of rows
2411 * (or columns) of <quote>0</quote> characters. The number of rows (or
2412 * characters) that will actually be displayed depends on font variances.
2414 * A text buffer window supports both character and line input, but not mouse
2417 * In character input, there will be some visible signal that the window is
2418 * waiting for a keystroke. (Typically, a cursor at the end of the text.) When
2419 * the player hits a key in that window, an event is generated, but the key is
2420 * <emphasis>not</emphasis> printed in the window.
2422 * In line input, again, there will be some visible signal. It is most common
2423 * for the player to compose input in the window itself, at the end of the text.
2424 * (This is how IF story input usually looks.) But it's not strictly required.
2425 * An alternative approach is the way MUD clients usually work: there is a
2426 * dedicated one-line input window, outside of Glk's window space, and the user
2427 * composes input there.
2430 * If this approach is used, there will still be some way to handle input from
2431 * two windows at once. It is the library's responsibility to make this
2432 * available to the player. You only need request line input and wait for the
2436 * By default, when the player finishes his line of input, the library will
2437 * display the input text at the end of the buffer text (if it wasn't there
2438 * already.) It will be followed by a newline, so that the next text you print
2439 * will start a new line (paragraph) after the input.
2441 * If you call glk_cancel_line_event(), the same thing happens; whatever text
2442 * the user was composing is visible at the end of the buffer text, followed by
2445 * However, this default behavior can be changed with the
2446 * glk_set_echo_line_event() call. If the default echoing is disabled, the
2447 * library will <emphasis>not</emphasis> display the input text (plus newline)
2448 * after input is either completed or cancelled. The buffer will end with
2449 * whatever prompt you displayed before requesting input. If you want the
2450 * traditional input behavior, it is then your responsibility to print the text,
2451 * using the Input text style, followed by a newline (in the original style).
2457 * A text grid contains a rectangular array of characters, in a fixed-width
2458 * font. Its size is the number of columns and rows of the array.
2460 * A text grid window supports output. It maintains knowledge of an output
2461 * cursor position. When the window is opened, it is filled with blanks (space
2462 * characters), and the output cursor starts in the top left corner —
2463 * character (0,0). If the window is cleared with glk_window_clear(), the window
2464 * is filled with blanks again, and the cursor returns to the top left corner.
2466 * When you print, the characters of the output are laid into the array in
2467 * order, left to right and top to bottom. When the cursor reaches the end of a
2468 * line, or if a newline (0x0A) is printed, the cursor goes to the beginning of
2469 * the next line. The library makes <emphasis>no</emphasis> attempt to wrap
2470 * lines at word breaks. If the cursor reaches the end of the last line, further
2471 * printing has no effect on the window until the cursor is moved.
2474 * Note that printing fancy characters may cause the cursor to advance more
2475 * than one position per character. (For example, the <quote>æ</quote>
2476 * ligature may print as two characters.) See <link
2477 * linkend="chimara-Output">Output</link>, for how to test this situation.
2480 * You can set the cursor position with glk_window_move_cursor().
2482 * When a text grid window is resized smaller, the bottom or right area is
2483 * thrown away, but the remaining area stays unchanged. When it is resized
2484 * larger, the new bottom or right area is filled with blanks.
2487 * You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
2488 * text grid windows when you see them change size.
2491 * Text grid window support character and line input, as well as mouse input (if
2492 * a mouse is available.)
2494 * Mouse input returns the position of the character that was touched, from
2497 * <alt>(width-1,height-1)</alt>
2498 * <mathphrase>(width - 1, height - 1)</mathphrase>
2502 * Character input is as described in the previous section.
2504 * Line input is slightly different; it is guaranteed to take place in the
2505 * window, at the output cursor position. The player can compose input only to
2506 * the right edge of the window; therefore, the maximum input length is
2508 * <alt>(windowwidth - 1 - cursorposition)</alt>
2509 * <mathphrase>(windowwidth - 1 - cursorposition)</mathphrase>
2511 * . If the maxlen argument of glk_request_line_event() is smaller than this,
2512 * the library will not allow the input cursor to go more than maxlen characters
2513 * past its start point.
2516 * This allows you to enter text in a fixed-width field, without the player
2517 * being able to overwrite other parts of the window.
2520 * When the player finishes his line of input, it will remain visible in the
2521 * window, and the output cursor will be positioned at the beginning of the
2522 * <emphasis>next</emphasis> row. Again, if you glk_cancel_line_event(), the
2523 * same thing happens. The glk_set_echo_line_event() call has no effect in grid
2530 * A graphics window contains a rectangular array of pixels. Its size is the
2531 * number of columns and rows of the array.
2533 * Each graphics window has a background color, which is initially white. You
2534 * can change this; see <link
2535 * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
2538 * When a graphics window is resized smaller, the bottom or right area is
2539 * thrown away, but the remaining area stays unchanged. When it is resized
2540 * larger, the new bottom or right area is filled with the background color.
2543 * You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
2544 * graphics windows when you see them change size.
2547 * In some libraries, you can receive a graphics-redraw event (%evtype_Redraw)
2548 * at any time. This signifies that the window in question has been cleared to
2549 * its background color, and must be redrawn. If you create any graphics
2550 * windows, you <emphasis>must</emphasis> handle these events.
2553 * Redraw events can be triggered when a Glk window is uncovered or made
2554 * visible by the platform's window manager. On the other hand, some Glk
2555 * libraries handle these problem automatically — for example, with a
2556 * backing store — and do not send you redraw events. On the third hand,
2557 * the backing store may be discarded if memory is low, or for other reasons
2558 * — perhaps the screen's color depth has changed. So redraw events are
2559 * always a possibility, even in clever libraries. This is why you must be
2560 * prepared to handle them.
2562 * However, you will not receive a redraw event when you create a graphics
2563 * window. It is assumed that you will do the initial drawing of your own
2564 * accord. You also do not get redraw events when a graphics window is
2565 * enlarged. If you ordered the enlargement, you already know about it; if the
2566 * player is responsible, you receive a window-arrangement event, which covers
2570 * For a description of the drawing functions that apply to graphics windows,
2571 * see <link linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
2574 * Graphics windows support no text input or output.
2576 * Not all libraries support graphics windows. You can test whether Glk graphics
2577 * are available using the gestalt system. In a C program, you can also test
2578 * whether the graphics functions are defined at compile-time. See <link
2579 * linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics
2580 * Capabilities</link>.
2583 * As with all windows, you should also test for %NULL when you create a
2591 * When calling glk_window_open() with this @method, the new window will be
2592 * to the left of the old one which was split.
2598 * When calling glk_window_open() with this @method, the new window will be
2599 * to the right of the old one which was split.
2605 * When calling glk_window_open() with this @method, the new window will be
2606 * above the old one which was split.
2612 * When calling glk_window_open() with this @method, the new window will be
2613 * below the old one which was split.
2619 * When calling glk_window_open() with this @method, the new window will be
2620 * a fixed size. (See glk_window_open()).
2624 * winmethod_Proportional:
2626 * When calling glk_window_open() with this @method, the new window will be
2627 * a given proportion of the old window's size. (See glk_window_open()).
2633 * When calling glk_window_open() with this @method, it specifies that there
2634 * should be a visible window border between the new window and its sibling.
2635 * (This is a hint to the library.)
2637 * <note><title>Chimara</title><para>
2638 * There will only be a visible border if the #ChimaraGlk:spacing property
2639 * is nonzero. Setting #ChimaraGlk:spacing to zero disables all borders on Glk
2645 * winmethod_NoBorder:
2647 * When calling glk_window_open() with this @method, it specifies that there
2648 * should not be a visible window border between the new window and its sibling.
2649 * (This is a hint to the library; you might specify NoBorder between two
2650 * graphics windows that should form a single image.)
2656 * Any other kind of file (preferences, statistics, arbitrary data.)
2660 * fileusage_SavedGame:
2662 * A file which stores game state.
2666 * fileusage_Transcript:
2668 * A file which contains a stream of text from the game (often an echo stream
2673 * fileusage_InputRecord:
2675 * A file which records player input.
2679 * fileusage_TextMode:
2681 * The file contents will be transformed to a platform-native text file as they
2682 * are written out. Newlines may be converted to linefeeds or
2683 * linefeed-plus-carriage-return combinations; Latin-1 characters may be
2684 * converted to native character codes. When reading a file in text mode, native
2685 * line breaks will be converted back to newline (0x0A) characters, and native
2686 * character codes may be converted to Latin-1 or UTF-8.
2689 * Line breaks will always be converted; other conversions are more
2690 * questionable. If you write out a file in text mode, and then read it back
2691 * in text mode, high-bit characters (128 to 255) may be transformed or lost.
2693 * <note><title>Chimara</title>
2695 * Text mode files in Chimara are in UTF-8, which is GTK+'s native file
2701 * fileusage_BinaryMode:
2703 * The file contents will be stored exactly as they are written, and read back
2704 * in the same way. The resulting file may not be viewable on platform-native
2705 * text file viewers.
2709 * fileusage_TypeMask:
2711 * Bitwise AND this value with a file usage argument to find whether the file
2712 * type is %fileusage_SavedGame, %fileusage_Transcript, %fileusage_InputRecord,
2713 * or %fileusage_Data.
2722 * Corresponds to mode <code>"w"</code> in the stdio library, using fopen().
2732 * Corresponds to mode <code>"r"</code> in the stdio library, using fopen().
2737 * filemode_ReadWrite:
2739 * Both an input and an output stream.
2742 * Corresponds to mode <code>"r+"</code> in the stdio library, using fopen().
2747 * filemode_WriteAppend:
2749 * An output stream, but the data will added to the end of whatever already
2750 * existed in the destination, instead of replacing it.
2753 * Confusingly, %filemode_WriteAppend cannot be mode <code>"a"</code>, because
2754 * the stdio spec says that when you open a file with mode <code>"a"</code>,
2755 * then fseek() doesn't work. So we have to use mode <code>"r+"</code> for
2756 * appending. Then we run into the <emphasis>other</emphasis> stdio problem,
2757 * which is that <code>"r+"</code> never creates a new file. So
2758 * %filemode_WriteAppend has to <emphasis>first</emphasis> open the file with
2759 * <code>"a"</code>, close it, reopen with <code>"r+"</code>, and then fseek()
2760 * to the end of the file. For %filemode_ReadWrite, the process is the same,
2761 * except without the fseek() — we begin at the beginning of the file.
2768 * In glk_stream_set_position(), signifies that @pos is counted in characters
2769 * after the beginning of the file.
2775 * In glk_stream_set_position(), signifies that @pos is counted in characters
2776 * after the current position (moving backwards if @pos is negative.)
2782 * In glk_stream_set_position(), signifies that @pos is counted in characters
2783 * after the end of the file. (@pos should always be zero or negative, so that
2784 * this will move backwards to a position within the file.
2788 * stylehint_Indentation:
2790 * How much to indent lines of text in the given style. May be a negative
2791 * number, to shift the text out (left) instead of in (right). The exact metric
2792 * isn't precisely specified; you can assume that +1 is the smallest indentation
2793 * possible which is clearly visible to the player.
2797 * stylehint_ParaIndentation:
2799 * How much to indent the first line of each paragraph. This is in addition to
2800 * the indentation specified by %stylehint_Indentation. This too may be
2801 * negative, and is measured in the same units as %stylehint_Indentation.
2805 * stylehint_Justification:
2807 * The value of this hint must be one of the constants
2808 * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification),
2809 * %stylehint_just_Centered, or %stylehint_just_RightFlush.
2815 * How much to increase or decrease the font size. This is relative; 0 means the
2816 * interpreter's default font size will be used, positive numbers increase it,
2817 * and negative numbers decrease it. Again, +1 is the smallest size increase
2818 * which is easily visible.
2820 * The amount of this increase may not be constant. +1 might increase an
2821 * 8-point font to 9-point, but a 16-point font to 18-point.
2828 * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for
2829 * normal weight, and -1 for light-weight fonts.
2833 * stylehint_Oblique:
2835 * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal
2840 * stylehint_Proportional:
2842 * The value of this hint must be 1 for proportional-width fonts, or 0 for
2847 * stylehint_TextColor:
2849 * The foreground color of the text. This is encoded in the 32-bit hint value:
2850 * the top 8 bits must be zero, the next 8 bits are the red value, the next 8
2851 * bits are the green value, and the bottom 8 bits are the blue value. Color
2852 * values range from 0 to 255.
2854 * So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.
2859 * stylehint_BackColor:
2861 * The background color behind the text. This is encoded the same way as
2862 * %stylehint_TextColor.
2866 * stylehint_ReverseColor:
2868 * The value of this hint must be 0 for normal printing (%stylehint_TextColor on
2869 * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on
2870 * %stylehint_TextColor).
2872 * Some libraries may support this hint but not the %stylehint_TextColor and
2873 * %stylehint_BackColor hints. Other libraries may take the opposite tack;
2874 * others may support both, or neither.
2879 * stylehint_just_LeftFlush:
2881 * A value for %stylehint_Justification representing left-justified text.
2885 * stylehint_just_LeftRight:
2887 * A value for %stylehint_Justification representing fully justified text.
2891 * stylehint_just_Centered:
2893 * A value for %stylehint_Justification representing centered text.
2897 * stylehint_just_RightFlush:
2899 * A value for %stylehint_Justification representing right-justified text.
2903 * imagealign_InlineUp:
2905 * The image appears at the current point in the text, sticking up. That is, the
2906 * bottom edge of the image is aligned with the baseline of the line of text.
2910 * imagealign_InlineDown:
2912 * The image appears at the current point, and the top edge is aligned with the
2913 * top of the line of text.
2917 * imagealign_InlineCenter:
2919 * The image appears at the current point, and it is centered between the top
2920 * and baseline of the line of text. If the image is taller than the line of
2921 * text, it will stick up and down equally.
2925 * imagealign_MarginLeft:
2927 * The image appears in the left margin. Subsequent text will be displayed to
2928 * the right of the image, and will flow around it — that is, it will be
2929 * left-indented for as many lines as it takes to pass the image.
2931 * <warning><para>Margin images are not implemented yet.</para></warning>
2935 * imagealign_MarginRight:
2937 * The image appears in the right margin, and subsequent text will flow around
2940 * <warning><para>Margin images are not implemented yet.</para></warning>
2945 * @year: The full (four-digit) year
2946 * @month: The month number, ranging from 1-12, 1 is January
2947 * @day: The day of the month, ranging from 1-31
2948 * @weekday: The day of the week, ranging from 0-6, 0 is Sunday
2949 * @hour: The hour of the day, ranging from 0-23
2950 * @minute: The minute of the hour, ranging from 0-59
2951 * @second: The second of the minute, ranging from 0-59; may be 60 during a leap
2953 * @microsec: The fraction of the second in microseconds, ranging from 0-999999
2955 * This structure represents a human-readable date in a specific timezone.
2960 * @high_sec: The most significant 32 bits of the timestamp in seconds.
2961 * @low_sec: The least significant 32 bits of the timestamp in seconds.
2962 * @microsec: The fraction of the timestamp, in microseconds, ranging from
2965 * This structure represents the Unix timestamp, i.e. the number of seconds
2966 * since January 1, 1970.
2969 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
2972 * gidispatch_count_classes:
2974 * Returns the number of opaque object classes used by the library. You will
2975 * need to know this if you want to keep track of opaque objects as they are
2976 * created; see <link linkend="gidispatch-set-object-registry">Opaque Object
2979 * As of Glk API 0.7.0, there are four classes: windows, streams, filerefs, and
2980 * sound channels (numbered 0, 1, 2, and 3 respectively.)
2982 * Returns: Number of opaque object classes used by the library.
2986 * gidispatch_get_class:
2987 * @index: Unique integer index of the class.
2989 * Returns a structure describing an opaque class that the library exports.
2990 * @index can range from 0 to <inlineequation><mathphrase>N -
2991 * 1</mathphrase><alt>N - 1</alt></inlineequation>, where N is the value
2992 * returned by gidispatch_count_classes().
2994 * Returns: A #gidispatch_intconst_t structure describing the class.
2998 * gidispatch_count_intconst:
3000 * Returns the number of integer constants exported by the library.
3002 * Returns: Number of integer constants exported by the library.
3006 * gidispatch_get_intconst:
3007 * @index: Unique integer index of the integer constant.
3009 * Returns a structure describing an integer constant which the library exports.
3010 * These are, roughly, all the constants defined in the <filename
3011 * class="headerfile">glk.h</filename> file. @index can range from 0 to
3012 * <inlineequation><mathphrase>N - 1</mathphrase><alt>N -
3013 * 1</alt></inlineequation>, where N is the value returned by
3014 * gidispatch_count_intconst().
3016 * Returns: A #gidispatch_intconst_t structure describing the integer constant.
3020 * gidispatch_intconst_t:
3021 * @name: Symbolic name of the integer constant.
3022 * @val: Value of the integer constant.
3024 * This structure simply contains a string and a value. The string is a
3025 * symbolic name of the value, and can be re-exported to anyone interested in
3026 * using Glk constants.
3029 * In the current <filename>gi_dispa.c</filename> library, these structures
3030 * are static and immutable, and will never be deallocated. However, it is
3031 * safer to assume that the structure may be reused in future
3032 * gidispatch_get_intconst() calls.
3037 * gidispatch_count_functions:
3039 * Returns the number of functions exported by the library.
3041 * Returns: Number of functions exported by the library.
3045 * gidispatch_get_function:
3046 * @index: Unique integer index of the function.
3048 * Returns a structure describing a Glk function. @index can range from 0 to
3049 * <inlineequation><mathphrase>N - 1</mathphrase><alt>N -
3050 * 1</alt></inlineequation>, where N is the value returned by
3051 * gidispatch_count_functions().
3054 * Again, it is safest to assume that the structure is only valid until the
3055 * next gidispatch_get_function() or gidispatch_get_function_by_id() call.
3058 * Returns: A #gidispatch_function_t structure describing the function.
3062 * gidispatch_function_t:
3063 * @id: Dispatch selector of the function.
3064 * @fnptr: Pointer to the function.
3065 * @name: Name of the function, without the <code>glk_</code> prefix.
3067 * The @id field is a selector — a numeric constant used to refer to the
3068 * function in question. @name is the function name, as it is given in the
3069 * <filename class="headerfile">glk.h</filename> file, but without the
3070 * <quote><code>glk_</code></quote> prefix. And @fnptr is the address of the
3074 * This is included because it might be useful, but it is not recommended. To
3075 * call an arbitrary Glk function, you should use gidispatch_call().
3078 * See <link linkend="chimara-Table-of-Selectors">Table of Selectors</link> for
3079 * the selector definitions. See <link
3080 * linkend="chimara-Dispatching">Dispatching</link> for more about calling Glk
3081 * functions by selector.
3085 * gidispatch_get_function_by_id:
3088 * Returns a structure describing the Glk function with selector @id. If there
3089 * is no such function in the library, this returns %NULL.
3092 * Again, it is safest to assume that the structure is only valid until the
3093 * next gidispatch_get_function() or gidispatch_get_function_by_id() call.
3096 * Returns: a #gidispatch_function_t structure, or %NULL.
3101 * @funcnum: Selector of the function to call.
3102 * @numargs: Length of @arglist.
3103 * @arglist: List of arguments to pass to the function.
3105 * @funcnum is the function number to invoke; see <link
3106 * linkend="chimara-Table-of-Selectors">Table of Selectors</link>. @arglist is
3107 * the list of arguments, and @numargs is the length of the list.
3109 * The arguments are all stored as #gluniversal_t objects.
3110 * </para><refsect3 id="chimara-Basic-Dispatch-Types"><title>Basic Dispatch
3111 * Types</title><para>
3112 * Numeric arguments are passed in the obvious way — one argument per
3113 * #gluniversal_t, with the @uint or @sint field set to the numeric value.
3114 * Characters and strings are also passed in this way — #char<!---->s in
3115 * the @uch, @sch, or @ch fields (depending on whether the #char is signed) and
3116 * strings in the @charstr field. Opaque objects (windows, streams, etc) are
3117 * passed in the @opaqueref field (which is <code>void*</code>, in order to
3118 * handle all opaque pointer types.)
3120 * However, pointers (other than C strings), arrays, and structures complicate
3121 * life. So do return values.
3122 * </para></refsect3>
3123 * <refsect3 id="chimara-References"><title>References</title><para>
3124 * A reference to a numeric type or object reference — that is,
3125 * <code>#glui32*</code>, <code>#winid_t*</code>, and so on — takes
3126 * <emphasis>one or two</emphasis> #gluniversal_t objects. The first is a flag
3127 * indicating whether the reference argument is %NULL or not. The @ptrflag field
3128 * of this #gluniversal_t should be %FALSE (0) if the reference is %NULL, and
3129 * %TRUE (1) otherwise. If %FALSE, that is the end of the argument; you should
3130 * not use a #gluniversal_t to explicitly store the %NULL reference. If the flag
3131 * is %TRUE, you must then put a #gluniversal_t storing the base type of the
3134 * For example, consider a hypothetical function, with selector
3135 * <code>0xABCD</code>:
3137 * void glk_glomp(glui32 num, winid_t win, glui32 *numref, strid_t *strref);
3144 * glk_glomp(5, mainwin, &value, &gamefile);
3147 * To perform this through gidispatch_call(), you would do the following:
3149 * gluniversal_t arglist[6];
3150 * arglist[0].uint = 5;
3151 * arglist[1].opaqueref = mainwin;
3152 * arglist[2].ptrflag = TRUE;
3153 * arglist[3].uint = value;
3154 * arglist[4].ptrflag = TRUE;
3155 * arglist[5].opaqueref = gamefile;
3156 * gidispatch_call(0xABCD, 6, arglist);
3157 * value = arglist[3].uint;
3158 * gamefile = arglist[5].opaqueref;
3161 * Note that you copy the value of the reference arguments into and out of
3162 * @arglist. Of course, it may be that
3163 * <function>glk_glomp()</function> only uses these as pass-out
3164 * references or pass-in references; if so, you could skip copying in or out.
3166 * For further examples:
3168 * glk_glomp(7, mainwin, NULL, NULL);
3170 * gluniversal_t arglist[4];
3171 * arglist[0].uint = 7;
3172 * arglist[1].opaqueref = mainwin;
3173 * arglist[2].ptrflag = FALSE;
3174 * arglist[3].ptrflag = FALSE;
3175 * gidispatch_call(0xABCD, 4, arglist);
3179 * glk_glomp(13, NULL, NULL, &gamefile);
3181 * gluniversal_t arglist[5];
3182 * arglist[0].uint = 13;
3183 * arglist[1].opaqueref = NULL;
3184 * arglist[2].ptrflag = FALSE;
3185 * arglist[3].ptrflag = TRUE;
3186 * arglist[4].opaqueref = gamefile;
3187 * gidispatch_call(0xABCD, 5, arglist);
3188 * gamefile = arglist[4].opaqueref;
3192 * glk_glomp(17, NULL, &value, NULL);
3194 * gluniversal_t arglist[5];
3195 * arglist[0].uint = 17;
3196 * arglist[1].opaqueref = NULL;
3197 * arglist[2].ptrflag = TRUE;
3198 * arglist[3].uint = value;
3199 * arglist[4].ptrflag = FALSE;
3200 * gidispatch_call(0xABCD, 5, arglist);
3201 * value = arglist[3].uint;
3204 * As you see, the length of @arglist depends on how many of the reference
3205 * arguments are %NULL.
3206 * </para></refsect3>
3207 * <refsect3 id="chimara-Structures"><title>Structures</title><para>
3208 * A structure pointer is represented by a single @ptrflag, possibly followed by
3209 * a sequence of #gluniversal_t objects (one for each field of the structure.)
3210 * Again, if the structure pointer is non-%NULL, the @ptrflag should be %TRUE
3211 * and be followed by values; if not, the @ptrflag should be %NULL and stands
3214 * For example, the function glk_select() can be invoked as follows:
3217 * gluniversal_t arglist[5];
3218 * arglist[0].ptrflag = TRUE;
3219 * gidispatch_call(0x00C0, 5, arglist);
3220 * ev.type = arglist[1].uint;
3221 * ev.win = arglist[2].opaqueref;
3222 * ev.val1 = arglist[3].uint;
3223 * ev.val2 = arglist[4].uint;
3226 * Since the structure passed to glk_select() is a pass-out reference (the entry
3227 * values are ignored), you don't need to fill in <code>arglist[1..4]</code>
3228 * before calling gidispatch_call().
3231 * Theoretically, you would invoke <code>#glk_select(%NULL)</code> by setting'
3232 * <code>arglist[0].ptrflag</code> to %FALSE, and using a one-element @arglist
3233 * instead of five-element. But it's illegal to pass %NULL to glk_select(). So
3234 * you cannot actually do this.
3235 * </para></note></para></refsect3>
3236 * <refsect3 id="chimara-Arrays"><title>Arrays</title><para>
3237 * In the Glk API, an array argument is always followed by a numeric argument
3238 * giving the array's length. These two C arguments are a single logical
3239 * argument, which is represented by <emphasis>one or three</emphasis>
3240 * #gluniversal_t objects. The first is a @ptrflag, indicating whether the
3241 * argument is %NULL or not. The second is a pointer, stored in the @array
3242 * field. The third is the array length, stored in the @uint field. And again,
3243 * if the @ptrflag is %NULL, the following two are omitted.
3245 * For example, the function glk_put_buffer() can be invoked as follows:
3249 * glk_put_buffer(buf, len);
3251 * gluniversal_t arglist[3];
3252 * arglist[0].ptrflag = TRUE;
3253 * arglist[1].array = buf;
3254 * arglist[2].uint = len;
3255 * gidispatch_call(0x0084, 3, arglist);
3258 * Since you are passing a C char array to gidispatch_call(), the contents will
3259 * be read directly from that. There is no need to copy data into @arglist, as
3260 * you would for a basic type.
3262 * If you are implementing a VM whose native representation of char arrays is
3263 * more complex, you will have to do more work. You should allocate a C char
3264 * array, copy your characters into it, make the call, and then free the array.
3267 * glk_put_buffer() does not modify the array passed to it, so there is no
3268 * need to copy the characters out.
3269 * </para></note></para></refsect3>
3270 * <refsect3 id="chimara-Return-Values"><title>Return Values</title><para>
3271 * The return value of a function is not treated specially. It is simply
3272 * considered to be a pass-out reference argument which may not be %NULL. It
3273 * comes after all the other arguments of the function.
3275 * For example, the function glk_window_get_rock() can be invoked as follows:
3279 * rock = glk_window_get_rock(win);
3281 * gluniversal_t arglist[3];
3282 * arglist[0].opaqueref = win;
3283 * arglist[1].ptrflag = TRUE;
3284 * gidispatch_call(0x0021, 3, arglist);
3285 * rock = arglist[2].uint;
3287 * </para></refsect3><para>
3292 * @uint: Stores a #glui32.
3293 * @sint: Stores a #glsi32.
3294 * @opaqueref: Stores a #winid_t, #strid_t, #frefid_t, or #schanid_t.
3295 * @uch: Stores an #unsigned #char.
3296 * @sch: Stores a #signed #char.
3297 * @ch: Stores a #char with the default signedness.
3298 * @charstr: Stores a null-terminated string.
3299 * @unicharstr: Stores a zero-terminated string of #glui32 values representing
3300 * Unicode characters.
3301 * @array: Stores a pointer to an array, and should be followed by another
3302 * #gluniversal_t with the array length stored in the @uint member.
3303 * @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL,
3304 * in which case it represents the entire argument. If %TRUE, should be followed
3305 * by another #gluniversal_t with the pointer in its @opaqueref or @array field.
3307 * This is a union, encompassing all the types that can be passed to Glk
3312 * gidispatch_prototype:
3313 * @funcnum: A selector for the function to be queried.
3315 * This returns a string which encodes the proper argument list for the given
3316 * function. If there is no such function in the library, this returns %NULL.
3318 * The prototype string for the <function>glk_glomp()</function>
3319 * function described above would be: <code>"4IuQa&Iu&Qb:"</code>. The
3320 * <code>"4"</code> is the number of arguments (including the return value, if
3321 * there is one, which in this case there isn't.) <code>"Iu"</code> denotes an
3322 * unsigned integer; <code>"Qa"</code> is an opaque object of class 0 (window).
3323 * <code>"&Iu"</code> is a <emphasis>reference</emphasis> to an unsigned
3324 * integer, and <code>"&Qb"</code> is a reference to a stream. The colon at
3325 * the end terminates the argument list; the return value would follow it, if
3328 * Note that the initial number (<code>"4"</code> in this case) is the number of
3329 * logical arguments, not the number of #gluniversal_t objects which will be
3330 * passed to gidispatch_call(). The <function>glk_glomp()</function>
3331 * call uses anywhere from four to six #gluniversal_t objects, as demonstrated
3334 * The basic type codes:
3337 * <term><code>Iu, Is</code></term>
3338 * <listitem><para>Unsigned and signed 32-bit integer.</para></listitem>
3341 * <term><code>Cn, Cu, Cs</code></term>
3342 * <listitem><para>Character, #unsigned #char, and #signed #char.</para>
3343 * <note><para>Of course <code>Cn</code> will be the same as either
3344 * <code>Cu</code> or <code>Cs</code>, depending on the platform. For this
3345 * reason, Glk avoids using it, but it is included here for completeness.
3350 * <term><code>S</code></term>
3351 * <listitem><para>A C-style string (null-terminated array of #char). In Glk,
3352 * strings are always treated as read-only and used immediately; the library
3353 * does not retain a reference to a string between Glk calls. A Glk call that
3354 * wants to use writable char arrays will use an array type
3355 * (<code>"#C"</code>), not string (<code>"S"</code>).</para></listitem>
3358 * <term><code>U</code></term>
3359 * <listitem><para>A zero-terminated array of 32-bit integers. This is
3360 * primarily intended as a Unicode equivalent of <code>"S"</code>. Like
3361 * <code>"S"</code> strings, <code>"U"</code> strings are read-only and used
3362 * immediately. A Glk call that wants to use writable Unicode arrays will use
3363 * an array type (<code>"#Iu"</code>) instead of <code>"U"</code>.</para>
3367 * <term><code>F</code></term>
3368 * <listitem><para>A floating-point value. Glk does not currently use
3369 * floating-point values, but we might as well define a code for them.</para>
3373 * <term><code>Qa, Qb, Qc...</code></term>
3374 * <listitem><para>A reference to an opaque object. The second letter
3375 * determines which class is involved. (The number of classes can be gleaned
3376 * from gidispatch_count_classes(); see <link
3377 * linkend="chimara-Interrogating-the-Interface">Interrogating the
3378 * Interface</link>).</para>
3380 * If Glk expands to have more than 26 classes, we'll think of something.
3381 * </para></note></listitem>
3384 * Any type code can be prefixed with one or more of the following characters:
3387 * <term><code>&</code></term>
3388 * <listitem><para>A reference to the type; or, if you like, a variable passed
3389 * by reference. The reference is passed both in and out, so you must copy the
3390 * value in before calling gidispatch_call() and copy it out afterward.</para>
3394 * <term><code><</code></term>
3395 * <listitem><para>A reference which is pass-out only. The initial value is
3396 * ignored, so you only need copy out the value after the call.</para>
3400 * <term><code>></code></term>
3401 * <listitem><para>A reference which is pass-in only.</para>
3403 * This is not generally used for simple types, but is useful for structures
3405 * </para></note></listitem>
3408 * <term><code>+</code></term>
3409 * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
3410 * <code>">"</code>, indicates that a valid reference is mandatory; %NULL
3411 * cannot be passed.</para>
3413 * Note that even though the @ptrflag #gluniversal_t for a <code>"+"</code>
3414 * reference is always %TRUE, it cannot be omitted.
3415 * </para></note></listitem>
3418 * <term><code>:</code></term>
3419 * <listitem><para>The colon separates the arguments from the return value, or
3420 * terminates the string if there is no return value. Since return values are
3421 * always non-%NULL pass-out references, you may treat <code>":"</code> as
3422 * equivalent to <code>"<+"</code>. The colon is never combined with any
3423 * other prefix character.</para></listitem>
3426 * <term><code>[...]</code></term>
3427 * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
3428 * <code>">"</code>, indicates a structure reference. Between the brackets
3429 * is a complete argument list encoding string, including the number of
3432 * For example, the prototype string for glk_select() is
3433 * <code>"1<+[4IuQaIuIu]:"</code> — one argument, which is a
3434 * pass-out non-%NULL reference to a structure, which contains four
3437 * <para>Currently, structures in Glk contain only basic types.</para>
3441 * <term><code>#</code></term>
3442 * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
3443 * <code>">"</code>, indicates an array reference. As described above, this
3444 * encompasses up to three #gluniversal_t objects — @ptrflag, pointer,
3445 * and integer length.</para>
3447 * Depending on the design of your program, you may wish to pass a pointer
3448 * directly to your program's memory, or allocate an array and copy the
3449 * contents in and out. See <link linkend="chimara-Arrays">Arrays</link>.
3450 * </para></note></listitem>
3453 * <term><code>!</code></term>
3454 * <listitem><para>Combined with <code>"#"</code>, indicates that the
3455 * array is retained by the library. The library will keep a reference to the
3456 * array; the contents are undefined until further notice. You should not use
3457 * or copy the contents of the array out after the call, even for
3458 * <code>"&#!"</code> or <code>"<#!"</code> arrays. Instead, do
3459 * it when the library releases the array.</para>
3461 * For example, glk_stream_open_memory() retains the array that you pass it,
3462 * and releases it when the stream is closed. The library can notify you
3463 * automatically when arrays are retained and released; see <link
3464 * linkend="gidispatch-set-retained-registry">Retained Array
3466 * </para></note></listitem>
3470 * The order of these characters and prefixes is not completely arbitrary. Here
3471 * is a formal grammar for the prototype strings.
3473 * <note><para>Thanks to Neil Cerutti for working this out.</para></note>
3476 * <production id="prototype">
3477 * <lhs>prototype</lhs>
3478 * <rhs>ArgCount [ <nonterminal def="#arg_list">arg_list</nonterminal> ]
3479 * ':' [ <nonterminal def="#arg">arg</nonterminal> ] EOL</rhs>
3481 * <production id="arg_list">
3482 * <lhs>arg_list</lhs>
3483 * <rhs><nonterminal def="#arg">arg</nonterminal> { <nonterminal
3484 * def="#arg">arg</nonterminal> }</rhs>
3486 * <production id="arg">
3488 * <rhs>TypeName | <nonterminal def="#ref_type">ref_type</nonterminal>
3491 * <production id="ref_type">
3492 * <lhs>ref_type</lhs>
3493 * <rhs>RefType [ '+' ] <nonterminal
3494 * def="#target_type">target_type</nonterminal></rhs>
3496 * <production id="target_type">
3497 * <lhs>target_type</lhs>
3498 * <rhs>TypeName | <nonterminal def="#array">array</nonterminal> |
3499 * <nonterminal def="#struct">struct</nonterminal></rhs>
3501 * <production id="array">
3503 * <rhs>'#' [ '!' ] TypeName</rhs>
3505 * <production id="struct">
3507 * <rhs>'[' ArgCount [ <nonterminal def="#arg_list">arg_list</nonterminal>
3511 * <constraintdef id="TypeName">
3512 * <para>TypeName is <code>I[us]<!---->|C[nus]<!---->|S|U|F|Q[a-z]</code>
3515 * <constraintdef id="ArgCount">
3516 * <para>ArgCount is <code>\d+</code></para>
3518 * <constraintdef id="RefType">
3519 * <para>RefType is <code>&|<|></code></para>
3521 * <constraintdef id="EOL">
3522 * <para>EOL is end of input</para>
3525 * Returns: A string which encodes the prototype of the specified Glk function.
3529 * gidisp_Class_Window:
3531 * Represents a #winid_t opaque object.
3535 * gidisp_Class_Stream:
3537 * Represents a #strid_t opaque object.
3541 * gidisp_Class_Fileref:
3543 * Represents a #frefid_t opaque object.
3547 * gidisp_Class_Schannel:
3549 * Represents a #schanid_t opaque object.
3553 * gidispatch_rock_t:
3554 * @num: Space for storing an integer.
3555 * @ptr: Space for storing a pointer.
3557 * You can store any value you want in this object; return it from your object
3558 * registry and retained array registry callbacks, and the library will stash it
3559 * away. You can retrieve it with gidispatch_get_objrock().
3562 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/
3567 * An integer type that can hold the Blorb error codes.
3577 * giblorb_err_CompileTime:
3579 * Something is compiled wrong in the Blorb layer.
3583 * giblorb_err_Alloc:
3585 * Memory could not be allocated.
3586 * <note><title>Chimara</title>
3588 * The Blorb layer in the Chimara library should not return this error code;
3589 * instead, the program aborts if memory allocation fails, in keeping with
3597 * Data could not be read from the file.
3601 * giblorb_err_NotAMap:
3603 * The map parameter is invalid.
3607 * giblorb_err_Format:
3609 * The Blorb file is corrupted or invalid.
3613 * giblorb_err_NotFound:
3615 * The requested data could not be found.
3619 * giblorb_method_DontLoad:
3621 * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3622 * giblorb_load_resource() to obtain information about a chunk without actually
3627 * giblorb_method_Memory:
3629 * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3630 * giblorb_load_resource() to load a chunk into memory.
3634 * giblorb_method_FilePos:
3636 * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3637 * giblorb_load_resource() to get the position in the Blorb file at which the
3638 * chunk data starts.
3644 * Resource usage constant representing a sound file.
3650 * Resource usage constant representing an executable program.
3656 * Resource usage constant representing an image file.
3662 * Resource usage constant representing a data file.
3666 * giblorb_ID_Copyright:
3668 * Resource usage constant representing the copyright message (date and holder,
3669 * without the actual copyright symbol). There should only be one such chunk per
3676 * Resource usage constant representing the name of the author or creator of the
3677 * file. This could be a login name on multi-user systems, for example. There
3678 * should only be one such chunk per file.
3684 * Resource usage constant representing any textual annotation that the user or
3685 * writing program sees fit to include.
3691 * Resource usage constant representing a text data file.
3697 * Resource usage constant representing a binary data file.
3703 * Holds the complete description of an open Blorb file. This type is opaque for
3704 * normal interpreter use.
3709 * @chunknum: The chunk number (for use in giblorb_unload_chunk(), etc.)
3710 * @length: The length of the data
3711 * @chunktype: The type of the chunk.
3713 * Holds information about a chunk loaded from a Blorb file, and the method of
3714 * accessing the chunk data. @data is a union of @ptr, a pointer to the data (if
3715 * you used %giblorb_method_Memory) and @startpos, the position in the file (if
3716 * you used %giblorb_method_FilePos). See giblorb_load_chunk_by_type() and
3717 * giblorb_load_chunk_by_number().
3721 * giblorb_create_map:
3722 * @file: An input stream pointing to a Blorb file.
3723 * @newmap: Return location for a Blorb resource map.
3725 * Reads Blorb data out of a Glk stream. It does not load every resource at
3726 * once; instead, it creates a map in memory which makes it easy to find
3727 * resources. A pointer to the map is stored in @newmap. This is an opaque
3728 * object; you pass it to the other Blorb-layer functions.
3730 * Returns: a Blorb error code.
3734 * giblorb_destroy_map:
3735 * @map: A Blorb resource map to deallocate.
3737 * Deallocates @map and all associated memory. This does
3738 * <emphasis>not</emphasis> close the original stream.
3740 * Returns: a Blorb error code.
3744 * giblorb_load_chunk_by_type:
3745 * @map: The Blorb resource map to load a chunk from.
3746 * @method: The loading method to use, one of %giblorb_method_DontLoad,
3747 * %giblorb_method_Memory, or %giblorb_method_FilePos.
3748 * @res: Return location for the result.
3749 * @chunktype: The type of chunk to load.
3750 * @count: The chunk number of type @chunktype to load.
3752 * Loads a chunk of a given type. The @count parameter distinguishes between
3753 * chunks of the same type. If @count is zero, the first chunk of that type is
3754 * loaded, and so on.
3756 * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the
3757 * form type, rather than FORM.
3759 * This introduces a slight ambiguity — you cannot distiguish between a
3760 * FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is
3761 * almost certainly a mistake.
3764 * The returned data is written into @res, according to @method.
3766 * The <structfield>chunknum</structfield> field is filled in with the number of
3767 * the chunk. (This value can then be passed to giblorb_load_chunk_by_number()
3768 * or giblorb_unload_chunk().) The <structfield>length</structfield> field is
3769 * filled in with the length of the chunk in bytes. The
3770 * <structfield>chunktype</structfield> field is the chunk's type, which of
3771 * course will be the type you asked for.
3773 * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You
3774 * can use this if you are only interested in whether a chunk exists, or in the
3775 * <structfield>chunknum</structfield> and <structfield>length</structfield>
3778 * If you specify %giblorb_method_FilePos,
3779 * <structfield>data.startpos</structfield> is filled in with the file position
3780 * of the chunk data. You can use glk_stream_set_position() to read the data
3783 * If you specify %giblorb_method_Memory, <structfield>data.ptr</structfield> is
3784 * filled with a pointer to allocated memory containing the chunk data. This
3785 * memory is owned by the map, not you. If you load the chunk more than once
3786 * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one
3787 * copy in memory. You should not deallocate this memory yourself; call
3788 * giblorb_unload_chunk() instead.
3790 * Returns: a Blorb error code.
3794 * giblorb_load_chunk_by_number:
3795 * @map: The Blorb resource map to load a chunk from.
3796 * @method: The loading method to use, one of %giblorb_method_DontLoad,
3797 * %giblorb_method_Memory, or %giblorb_method_FilePos.
3798 * @res: Return location for the result.
3799 * @chunknum: The chunk number to load.
3801 * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a
3802 * given chunk number. The type of the chunk can be found in the
3803 * <structfield>chunktype</structfield> field of #giblorb_result_t. You can get
3804 * the chunk number from the <structfield>chunknum</structfield> field, after
3805 * calling one of the other load functions.
3807 * Returns: a Blorb error code.
3811 * giblorb_unload_chunk:
3812 * @map: The Blorb resource map to unload a chunk from.
3813 * @chunknum: The chunk number to unload.
3815 * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk
3816 * has never been loaded into memory, this has no effect.
3818 * Returns: a Blorb error code.
3822 * giblorb_load_resource:
3823 * @map: The Blorb resource map to load a resource from.
3824 * @method: The loading method to use, one of %giblorb_method_DontLoad,
3825 * %giblorb_method_Memory, or %giblorb_method_FilePos.
3826 * @res: Return location for the result.
3827 * @usage: The type of data resource to load.
3828 * @resnum: The resource number to load.
3830 * Loads a resource, given its usage and resource number. Currently, the three
3831 * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and
3832 * %giblorb_ID_Exec (executable program). See the Blorb specification for more
3833 * information about the types of data that can be stored for these usages.
3835 * Note that a resource number is not the same as a chunk number. The resource
3836 * number is the sound or image number specified by a Glk program. Chunk number
3837 * is arbitrary, since chunks in a Blorb file can be in any order. To find the
3838 * chunk number of a given resource, call giblorb_load_resource() and look in
3839 * <structfield>res.chunknum</structfield>.
3841 * Returns: a Blorb error code.
3845 * giblorb_count_resources:
3846 * @map: The Blorb resource map in which to count the resources.
3847 * @usage: The type of data resource to count.
3848 * @num: Return location for the number of chunks of @usage.
3849 * @min: Return location for the lowest resource number of @usage.
3850 * @max: Return location for the highest resource number of @usage.
3852 * Counts the number of chunks with a given usage (image, sound, or executable.)
3853 * The total number of chunks of that usage is stored in @num. The lowest and
3854 * highest resource number of that usage are stored in @min and @max. You can
3855 * leave any of the three pointers %NULL if you don't care about that
3858 * Returns: a Blorb error code.
3861 /*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/
3864 * glkunix_argumentlist_t:
3865 * @name: the option as it would appear on the command line (including the
3866 * leading dash, if any.)
3867 * @desc: a description of the argument; this is used when the library is
3868 * printing a list of options.
3869 * @argtype: one of the <code>glkunix_arg_</code> constants.
3873 * <term>%glkunix_arg_NoValue</term>
3874 * <listitem><para>The argument appears by itself.</para></listitem>
3877 * <term>%glkunix_arg_ValueFollows</term>
3878 * <listitem><para>The argument must be followed by another argument (the
3879 * value).</para></listitem>
3882 * <term>%glkunix_arg_ValueCanFollow</term>
3883 * <listitem><para>The argument may be followed by a value, optionally. (If the
3884 * next argument starts with a dash, it is taken to be a new argument, not the
3885 * value of this one.)</para></listitem>
3888 * <term>%glkunix_arg_NumberValue</term>
3889 * <listitem><para>The argument must be followed by a number, which may be the
3890 * next argument or part of this one. (That is, either <quote><code>-width
3891 * 20</code></quote> or <quote><code>-width20</code></quote> will be accepted.)
3892 * </para></listitem>
3895 * <term>%glkunix_arg_End</term>
3896 * <listitem><para>The <code>glkunix_arguments[]</code> array must be
3897 * terminated with an entry containing this value.</para></listitem>
3901 * To accept arbitrary arguments which lack dashes, specify a name of
3902 * <code>""</code> and an argtype of %glkunix_arg_ValueFollows.
3904 * If you don't care about command-line arguments, you must still define an
3905 * empty arguments list, as follows:
3907 * glkunix_argumentlist_t glkunix_arguments[] = {
3908 * { NULL, glkunix_arg_End, NULL }
3912 * Here is a more complete sample list:
3914 * glkunix_argumentlist_t glkunix_arguments[] = {
3915 * { "", glkunix_arg_ValueFollows, "filename: The game file to load." },
3916 * { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
3917 * { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
3918 * the NUM, if given)." },
3919 * { "-goo", glkunix_arg_NoValue, "-goo: Find goo." },
3920 * { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
3921 * { NULL, glkunix_arg_End, NULL }
3924 * This would match the arguments <quote><code>thingfile -goo -wob8 -bom -hum
3925 * song</code></quote>.
3927 * After the library parses the command line, it does various occult rituals of
3928 * initialization, and then calls glkunix_startup_code().
3930 * |[ int glkunix_startup_code(glkunix_startup_t *data); ]|
3932 * This should return %TRUE if everything initializes properly. If it returns
3933 * %FALSE, the library will shut down without ever calling your glk_main()
3938 * glkunix_startup_t:
3939 * @argc: The number of arguments in @argv.
3940 * @argv: Strings representing command line arguments.
3942 * The fields are a standard Unix <code>(argc, argv)</code> list, which contain
3943 * the arguments you requested from the command line. In deference to custom,
3944 * <code>argv[0]</code> is always the program name.
3950 * Terminates a list of #glkunix_argumentlist_t.
3954 * glkunix_arg_ValueFollows:
3956 * Indicates an argument which must be followed by a value, as the next
3961 * glkunix_arg_NoValue:
3963 * Indicates an argument which occurs by itself, without a value.
3967 * glkunix_arg_ValueCanFollow:
3969 * Indicates an argument which may be followed by a value, or may occur by
3974 * glkunix_arg_NumberValue:
3976 * Indicates an argument which must be followed by a numerical value, either as
3977 * the next argument or tacked onto the end of this argument.
projects / projects / chimara / chimara.git / blob