* This is how you deal with opaque objects from a C program. If you are using
* Glk through a virtual machine, matters will probably be different. Opaque
* objects may be represented as integers, or as VM objects of some sort.
- * </para></note>
+ * </para></note></para>
* <refsect2 id="chimara-Rocks"><!-- Indeed it does. -->
* <title>Rocks</title>
* <para>
* For each class of opaque objects, there is an iterate function, which you can
* use to obtain a list of all existing objects of that class. It takes the form
* |[
- * <replaceable>CLASS</replaceable>id_t glk_<replaceable>CLASS</replaceable>_iterate(<replaceable>CLASS</replaceable>id_t <parameter>obj</parameter>, #glui32 *<parameter>rockptr</parameter>);
+ * CLASSid_t glk_CLASS_iterate(CLASSid_t obj, glui32 *rockptr);
* ]|
* ...where <code><replaceable>CLASS</replaceable></code> represents one of the
* opaque object classes.
* <para>
* You usually use this as follows:
* |[
- * obj = glk_<replaceable>CLASS</replaceable>_iterate(NULL, NULL);
+ * obj = glk_CLASS_iterate(NULL, NULL);
* while (obj) {
* /* ...do something with obj... *<!-- -->/
- * obj = glk_<replaceable>CLASS</replaceable>_iterate(obj, NULL);
+ * obj = glk_CLASS_iterate(obj, NULL);
* }
* ]|
* </para>
* and Unicode input; see %gestalt_Unicode.
*/
+/**
+ * SECTION:glk-mouse-events
+ * @short_description: Events representing a mouse click
+ * @include: libchimara/glk.h
+ *
+ * On some platforms, Glk can recognize when the mouse (or other pointer) is
+ * used to select a spot in a window. You can request mouse input only in text
+ * grid windows and graphics windows.
+ *
+ * A window can have mouse input and character/line input pending at the same
+ * time.
+ *
+ * If the player clicks in a window which has a mouse input event pending,
+ * glk_select() will return an event whose type is %evtype_MouseInput. Again,
+ * once this happens, the request is complete, and you must request another if
+ * you want further mouse input.
+ *
+ * In the event structure, @win tells what window the event came from.
+ *
+ * In a text grid window, the @val1 and @val2 fields are the x and y coordinates
+ * of the character that was clicked on.
+ * <note><para>So @val1 is the column, and @val2 is the row.</para></note>
+ * The top leftmost character is considered to be (0,0).
+ *
+ * In a graphics window, they are the x and y coordinates of the pixel that was
+ * clicked on. Again, the top left corner of the window is (0,0).
+ *
+ * <note><para>
+ * Most mouse-based idioms define standard functions for mouse hits in text
+ * windows — typically selecting or copying text. It is up to the
+ * library to separate this from Glk mouse input. The library may choose to
+ * select text when it is clicked normally, and cause Glk mouse events when
+ * text is control-clicked. Or the other way around. Or it may be the
+ * difference between clicking and double-clicking. Or the library may
+ * reserve a particular mouse button, on a multi-button mouse. It may even
+ * specify a keyboard key to be the "mouse button", referring to wherever the
+ * mouse cursor is when the key is hit. Or some even more esoteric positioning
+ * system. You need only know that the user can do it, or not.
+ * </para></note>
+ * <note><para>
+ * However, since different platforms will handle this issue differently, you
+ * should be careful how you instruct the player in your program. Do not tell
+ * the player to <quote>double-click</quote>, <quote>right-click</quote>, or
+ * <quote>control-click</quote> in a window. The preferred term is <quote>to
+ * touch the window</quote>, or a spot in the window.
+ * </para></note>
+ * <note><para>
+ * Goofy, but preferred.
+ * </para></note>
+ */
+
/**
* SECTION:glk-timer-events
* @short_description: Events sent at fixed intervals
* </para></note>
*/
+/**
+ * SECTION:glk-style-measure
+ * @short_description: Finding out how the library displays your style hints
+ * @include: libchimara/glk.h
+ *
+ * You can suggest the appearance of a window's style before the window is
+ * created; after the window is created, you can test the style's actual
+ * appearance. These functions do not test the style hints; they test the
+ * attribute of the style as it appears to the player.
+ *
+ * Note that although you cannot change the appearance of a window's styles
+ * after the window is created, the library can. A platform may support dynamic
+ * preferences, which allow the player to change text formatting while your
+ * program is running.
+ * <note><para>
+ * Changes that affect window size (such as font size changes) will be
+ * signalled by an %evtype_Arrange event. However, more subtle changes (such
+ * as text color differences) are not signalled. If you test the appearance of
+ * styles at the beginning of your program, you must keep in mind the
+ * possibility that the player will change them later.
+ * </para></note>
+ */
+
/**
* SECTION:glk-stream-types
* @short_description: Window, memory, and file streams
* else.
*/
+/**
+ * SECTION:glk-image-resources
+ * @short_description: Graphics in Glk
+ * @include: libchimara/glk.h
+ *
+ * In accordance with this modern age, Glk provides for a modicum of graphical
+ * flair. It does not attempt to be a complete graphical toolkit. Those already
+ * exist. Glk strikes the usual uncomfortable balance between power,
+ * portability, and ease of implementation: commands for arranging pre-supplied
+ * images on the screen and intermixed with text.
+ *
+ * Graphics is an optional capability in Glk; not all libraries support
+ * graphics. This should not be a surprise.
+ *
+ * Most of the graphics commands in Glk deal with image resources. Your program
+ * does not have to worry about how images are stored. Everything is a resource,
+ * and a resource is referred to by an integer identifier. You may, for example,
+ * call a function to display image number 17. The format, loading, and
+ * displaying of that image is entirely up to the Glk library for the platform
+ * in question.
+ *
+ * Of course, it is also desirable to have a platform-independent way to store
+ * sounds and images. Blorb is the official resource-storage format of Glk. A
+ * Glk library does not have to understand Blorb, but it is more likely to
+ * understand Blorb than any other format.
+ *
+ * <note><para>
+ * Glk does not specify the exact format of images, but Blorb does. Images in
+ * a Blorb archive must be PNG or JPEG files. More formats may be added if
+ * real-world experience shows it to be desirable. However, that is in the
+ * domain of the Blorb specification. The Glk spec, and Glk programming, will
+ * not change.
+ * </para></note>
+ *
+ * At present, images can only be drawn in graphics windows and text buffer
+ * windows. In fact, a library may not implement both of these possibilities.
+ * You should test each with the %gestalt_DrawImage selector if you plan to use
+ * it. See <link linkend="chimara-Testing-for-Graphics-Capabilities">Testing for
+ * Graphics Capabilities</link>.
+ */
+
+/**
+ * SECTION:glk-graphics-windows
+ * @short_description: Drawing graphics in graphics windows
+ * @include: libchimara/glk.h
+ *
+ * A graphics window is a rectangular canvas of pixels, upon which you can draw
+ * images. The contents are entirely under your control. You can draw as many
+ * images as you like, at any positions — overlapping if you like. If the
+ * window is resized, you are responsible for redrawing everything. See <link
+ * linkend="wintype-Graphics">Graphics Windows</link>.
+ *
+ * <note><para>
+ * Note that graphics windows do not support a full set of object-drawing
+ * commands, nor can you draw text in them. That may be available in a future
+ * Glk extension. For now, it seems reasonable to limit the task to a single
+ * primitive, the drawing of a raster image. And then there's the ability to
+ * fill a rectangle with a solid color — a small extension, and
+ * hopefully no additional work for the library, since it can already clear
+ * with arbitrary background colors. In fact, if glk_window_fill_rect() did
+ * not exist, an author could invent it — by briefly setting the
+ * background color, erasing a rectangle, and restoring.
+ * </para></note>
+ *
+ * If you call glk_image_draw() or glk_image_draw_scaled() in a graphics window,
+ * @val1 and @val2 are interpreted as X and Y coordinates. The image will be
+ * drawn with its upper left corner at this position.
+ *
+ * It is legitimate for part of the image to fall outside the window; the excess
+ * is not drawn. Note that these are signed arguments, so you can draw an image
+ * which falls outside the left or top edge of the window, as well as the right
+ * or bottom.
+ *
+ * There are a few other commands which apply to graphics windows.
+ */
+
+/**
+ * SECTION:glk-graphics-text
+ * @short_description: Drawing graphics inside or beside text
+ * @include: libchimara/glk.h
+ *
+ * A text buffer is a linear text stream. You can draw images in-line with this
+ * text. If you are familiar with HTML, you already understand this model. You
+ * draw images with flags indicating alignment. The library takes care of
+ * scrolling, resizing, and reformatting text buffer windows.
+ *
+ * If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer
+ * window, @val1 gives the image alignment. The @val2 argument is currently
+ * unused, and should always be zero.
+ *
+ * The two <quote>margin</quote> alignments require some care. To allow proper
+ * positioning, images using %imagealign_MarginLeft and %imagealign_MarginRight
+ * must be placed at the beginning of a line. That is, you may only call
+ * glk_image_draw() (with these two alignments) in a window, if you have just
+ * printed a newline to the window's stream, or if the window is entirely empty.
+ * If you margin-align an image in a line where text has already appeared, no
+ * image will appear at all.
+ *
+ * Inline-aligned images count as <quote>text</quote> for the purpose of this
+ * rule.
+ *
+ * You may have images in both margins at the same time.
+ *
+ * It is also legal to have more than one image in the same margin (left or
+ * right.) However, this is not recommended. It is difficult to predict how text
+ * will wrap in that situation, and libraries may err on the side of
+ * conservatism.
+ */
+
+/**
+ * SECTION:glk-graphics-testing
+ * @short_description: Checking whether the library supports graphics
+ * @include: libchimara/glk.h
+ *
+ * Before calling Glk graphics functions, you should use the gestalt selector
+ * %gestalt_Graphics. To test for additional capabilities, you can also use the
+ * %gestalt_DrawImage and %gestalt_GraphicsTransparency selectors.
+ */
+
+/**
+ * SECTION:glk-sound-channels
+ * @short_description: Creating new sound channels and closing them
+ * @include: libchimara/glk.h
+ */
+
+/**
+ * SECTION:glk-playing-sounds
+ * @short_description: Producing noise
+ * @include: libchimara/glk.h
+ */
+
+/**
+ * SECTION:glk-sound-other
+ * @short_description: Miscellaneous functions for sound channels
+ * @include: libchimara/glk.h
+ */
+
+/**
+ * SECTION:glk-sound-testing
+ * @short_description: Checking whether the library supports sound
+ * @include: libchimara/glk.h
+ *
+ * Before calling Glk sound functions, you should use the %gestalt_Sound
+ * selector. To test for additional capabilities, you can use the
+ * %gestalt_SoundMusic, %gestalt_SoundVolume, and %gestalt_SoundNotify
+ * selectors.
+ */
+
/**
* SECTION:glk-creating-hyperlinks
* @short_description: Printing text as a hyperlink
* GlkTerm.
*
* When you compile a Glk program, you may define a function called
- * glkunix_startup_code(), and an array <code>glkunix_arguments[]</code>. These
- * set up various Unix-specific options used by the Glk library. There is a
- * sample <quote><filename>glkstart.c</filename></quote> file included in this
- * package; you should modify it to your needs.
+ * <function>glkunix_startup_code()</function>, and an array
+ * <code>glkunix_arguments[]</code>. These set up various Unix-specific options
+ * used by the Glk library. There is a sample
+ * <quote><filename>glkstart.c</filename></quote> file included in this package;
+ * you should modify it to your needs.
*
- * |[ extern #glkunix_argumentlist_t glkunix_arguments[]; ]|
+ * |[ extern glkunix_argumentlist_t glkunix_arguments[]; ]|
*
* The <code>glkunix_arguments[]</code> array is a list of command-line
* arguments that your program can accept. The library will sort these out of
* constants (see %gestalt_Unicode). If not, not.
*/
+/**
+ * GLK_MODULE_IMAGE:
+ *
+ * If you are writing a C program, there is an additional complication. A
+ * library which does not support graphics may not implement the graphics
+ * functions at all. Even if you put gestalt tests around your graphics calls,
+ * you may get link-time errors. If the <filename
+ * class="headerfile">glk.h</filename> file is so old that it does not declare
+ * the graphics functions and constants, you may even get compile-time errors.
+ *
+ * To avoid this, you can perform a preprocessor test for the existence of
+ * %GLK_MODULE_IMAGE. If this is defined, so are all the functions and constants
+ * described in this section. If not, not.
+ *
+ * <note><para>
+ * To be extremely specific, there are two ways this can happen. If the
+ * <filename class="headerfile">glk.h</filename> file that comes with the
+ * library is too old to have the graphics declarations in it, it will of
+ * course lack %GLK_MODULE_IMAGE as well. If the <filename
+ * class="headerfile">glk.h</filename> file is recent, but the library is old,
+ * the definition of %GLK_MODULE_IMAGE should be removed from <filename
+ * class="headerfile">glk.h</filename>, to avoid link errors. This is not a
+ * great solution. A better one is for the library to implement the graphics
+ * functions as stubs that do nothing (or cause run-time errors). Since no
+ * program will call the stubs without testing %gestalt_Graphics, this is
+ * sufficient.
+ * </para></note>
+ */
+
+/**
+ * GLK_MODULE_SOUND:
+ *
+ * If you are writing a C program, there is an additional complication. A
+ * library which does not support sound may not implement the sound functions at
+ * all. Even if you put gestalt tests around your sound calls, you may get
+ * link-time errors. If the <filename class="headerfile">glk.h</filename> file
+ * is so old that it does not declare the sound functions and constants, you may
+ * even get compile-time errors.
+ *
+ * To avoid this, you can perform a preprocessor test for the existence of
+ * %GLK_MODULE_SOUND. If this is defined, so are all the functions and constants
+ * described in this section. If not, not.
+ */
+
/**
* GLK_MODULE_HYPERLINKS:
*
* members.
*/
+/**
+ * schanid_t:
+ *
+ * Opaque structure representing a sound channel. It has no user-accessible
+ * members.
+ */
+
/**
* gestalt_Version:
*
* For an example of the gestalt mechanism, consider the selector
* %gestalt_Version. If you do
* |[
- * #glui32 res;
- * res = #glk_gestalt(#gestalt_Version, 0);
+ * glui32 res;
+ * res = glk_gestalt(gestalt_Version, 0);
* ]|
* <code>res</code> will be set to a 32-bit number which encodes the version of
* the Glk spec which the library implements. The upper 16 bits stores the major
* 0x00000700.
*
* |[
- * #glui32 res;
- * res = #glk_gestalt_ext(#gestalt_Version, 0, NULL, 0);
+ * glui32 res;
+ * res = glk_gestalt_ext(gestalt_Version, 0, NULL, 0);
* ]|
* does exactly the same thing. Note that, in either case, the second argument
* is not used; so you should always pass 0 to avoid future surprises.
* If you set <code>ch</code> to a character code, or a special code (from
* 0xFFFFFFFF down), and call
* |[
- * #glui32 res;
- * res = #glk_gestalt(#gestalt_CharInput, ch);
+ * glui32 res;
+ * res = glk_gestalt(gestalt_CharInput, ch);
* ]|
* then <code>res</code> will be %TRUE (1) if that character can be typed by
* the player in character input, and %FALSE (0) if not. See <link
*
* If you set <code>ch</code> to a character code, and call
* |[
- * #glui32 res;
- * res = #glk_gestalt(#gestalt_LineInput, ch);
+ * glui32 res;
+ * res = glk_gestalt(gestalt_LineInput, ch);
* ]|
* then <code>res</code> will be %TRUE (1) if that character can be typed by the
* player in line input, and %FALSE (0) if not. Note that if <code>ch</code> is
*
* If you set <code>ch</code> to a character code (Latin-1 or higher), and call
* |[
- * #glui32 res, len;
- * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &len, 1);
+ * glui32 res, len;
+ * res = glk_gestalt_ext(gestalt_CharOutput, ch, &len, 1);
* ]|
* then <code>res</code> will be one of %gestalt_CharOutput_CannotPrint,
* %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see
* Make sure you do not get confused by signed byte values. If you set a
* <quote><type>char</type></quote> variable <code>ch</code> to 0xFE, the
* small-thorn character (þ), and then call
- * |[ res = #glk_gestalt(#gestalt_CharOutput, ch); ]|
+ * |[ res = glk_gestalt(gestalt_CharOutput, ch); ]|
* then (by the definition of C/C++) <code>ch</code> will be sign-extended to
* 0xFFFFFFFE, which is not a legitimate character, even in Unicode. You
* should write
- * |[ res = #glk_gestalt(#gestalt_CharOutput, (unsigned char)ch); ]|
+ * |[ res = glk_gestalt(gestalt_CharOutput, (unsigned char)ch); ]|
* instead.
* </para></note>
* <note><para>
*/
/**
- * gestalt_Unicode:
+ * gestalt_MouseInput:
*
- * The basic text functions will be available in every Glk library. The Unicode
- * functions may or may not be available. Before calling them, you should use
- * the following gestalt selector:
+ * You can test whether mouse input is supported with the %gestalt_MouseInput
+ * selector.
+ * |[ res = glk_gestalt(gestalt_MouseInput, windowtype); ]|
+ * This will return %TRUE (1) if windows of the given type support mouse input.
+ * If this returns %FALSE (0), it is still legal to call
+ * glk_request_mouse_event(), but it will have no effect, and you will never get
+ * mouse events.
+ */
+
+/**
+ * gestalt_Timer:
+ *
+ * You can test whether the library supports timer events:
+ * |[ res = glk_gestalt(gestalt_Timer, 0); ]|
+ * This returns 1 if timer events are supported, and 0 if they are not.
+ */
+
+/**
+ * gestalt_Graphics:
+ *
+ * Before calling Glk graphics functions, you should use the following gestalt
+ * selector:
* |[
* glui32 res;
- * res = #glk_gestalt(#gestalt_Unicode, 0);
+ * res = glk_gestalt(gestalt_Graphics, 0);
* ]|
+ * This returns 1 if the overall suite of graphics functions is available. This
+ * includes glk_image_draw(), glk_image_draw_scaled(), glk_image_get_info(),
+ * glk_window_erase_rect(), glk_window_fill_rect(),
+ * glk_window_set_background_color(), and glk_window_flow_break(). It also
+ * includes the capability to create graphics windows.
*
- * This returns 1 if the Unicode functions are available. If it returns 0, you
- * should not try to call them. They may print nothing, print gibberish, or
- * cause a run-time error. The Unicode functions include
- * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),
- * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
- * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
- * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
- * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
- * glk_request_char_event_uni(), glk_request_line_event_uni(),
- * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
- *
- * If you are writing a C program, there is an additional complication. A
- * library which does not support Unicode may not implement the Unicode
- * functions at all. Even if you put gestalt tests around your Unicode calls,
- * you may get link-time errors. If the
- * <filename class="headerfile">glk.h</filename> file is so old that it does not
- * declare the Unicode functions and constants, you may even get compile-time
- * errors.
+ * If this selector returns 0, you should not try to call these functions. They
+ * may have no effect, or they may cause a run-time error. If you try to create
+ * a graphics window, you will get %NULL.
+ */
+
+/**
+ * gestalt_DrawImage:
*
- * To avoid this, you can perform a preprocessor test for the existence of
- * #GLK_MODULE_UNICODE.
+ * This selector returns 1 if images can be drawn in windows of the given type.
+ * If it returns 0, glk_image_draw() will fail and return %FALSE. You should
+ * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries
+ * may implement both, neither, or only one.
*/
/**
- * gestalt_Timer:
+ * gestalt_Sound:
*
- * You can test whether the library supports timer events:
- * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]|
- * This returns 1 if timer events are supported, and 0 if they are not.
+ * You can test whether the library supports sound:
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_Sound, 0);
+ * ]|
+ * This returns 1 if the overall suite of sound functions is available. This
+ * includes glk_schannel_create(), glk_schannel_destroy(),
+ * glk_schannel_iterate(), glk_schannel_get_rock(), glk_schannel_play(),
+ * glk_schannel_play_ext(), glk_schannel_stop(), glk_schannel_set_volume(), and
+ * glk_sound_load_hint().
+ *
+ * If this selector returns 0, you should not try to call these functions. They
+ * may have no effect, or they may cause a run-time error.
+ */
+
+/**
+ * gestalt_SoundVolume:
+ *
+ * You can test whether the library supports setting the volume of sound
+ * channels:
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_SoundVolume, 0);
+ * ]|
+ * This selector returns 1 if the glk_schannel_set_volume() function works. If
+ * it returns zero, glk_schannel_set_volume() has no effect.
+ */
+
+/**
+ * gestalt_SoundNotify:
+ *
+ * You can test whether the library supports sound notification events:
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_SoundNotify, 0);
+ * ]|
+ * This selector returns 1 if the library supports sound notification events. If
+ * it returns zero, you will never get such events.
*/
/**
*
* You can test whether the library supports hyperlinks:
* |[
- * #glui32 res;
- * res = #glk_gestalt(#gestalt_Hyperlinks, 0);
+ * glui32 res;
+ * res = glk_gestalt(gestalt_Hyperlinks, 0);
* ]|
* This returns 1 if the overall suite of hyperlinks functions is available.
* This includes glk_set_hyperlink(), glk_set_hyperlink_stream(),
*
* You can test whether hyperlinks are supported with the
* %gestalt_HyperlinkInput selector:
- * |[ res = #glk_gestalt(#gestalt_HyperlinkInput, windowtype); ]|
+ * |[ res = glk_gestalt(gestalt_HyperlinkInput, windowtype); ]|
* This will return %TRUE (1) if windows of the given type support hyperlinks.
* If this returns %FALSE (0), it is still legal to call glk_set_hyperlink() and
* glk_request_hyperlink_event(), but they will have no effect, and you will
* never get hyperlink events.
*/
+
+/**
+ * gestalt_SoundMusic:
+ *
+ * You can test whether music resources are supported:
+ * |[ res = glk_gestalt(gestalt_SoundMusic, 0); ]|
+ * This returns 1 if the library is capable of playing music sound resources. If
+ * it returns 0, only sampled sounds can be played.
+ * <note><para>
+ * <quote>Music sound resources</quote> means MOD songs — the only music
+ * format that Blorb currently supports. The presence of this selector is, of
+ * course, an ugly hack. It is a concession to the current state of the Glk
+ * libraries, some of which can handle AIFF but not MOD sounds.
+ * </para></note>
+ */
+
+/**
+ * gestalt_GraphicsTransparency:
+ *
+ * This returns 1 if images with alpha channels can actually be drawn with the
+ * appropriate degree of transparency. If it returns 0, the alpha channel is
+ * ignored; fully transparent areas will be drawn in an implementation-defined
+ * color.
+ * <note><para>
+ * The JPEG format does not support transparency or alpha channels; the PNG
+ * format does.
+ * </para></note>
+ */
+
+/**
+ * gestalt_Unicode:
+ *
+ * The basic text functions will be available in every Glk library. The Unicode
+ * functions may or may not be available. Before calling them, you should use
+ * the following gestalt selector:
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_Unicode, 0);
+ * ]|
+ *
+ * This returns 1 if the Unicode functions are available. If it returns 0, you
+ * should not try to call them. They may print nothing, print gibberish, or
+ * cause a run-time error. The Unicode functions include
+ * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),
+ * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
+ * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
+ * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
+ * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
+ * glk_request_char_event_uni(), glk_request_line_event_uni(),
+ * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
+ *
+ * If you are writing a C program, there is an additional complication. A
+ * library which does not support Unicode may not implement the Unicode
+ * functions at all. Even if you put gestalt tests around your Unicode calls,
+ * you may get link-time errors. If the
+ * <filename class="headerfile">glk.h</filename> file is so old that it does not
+ * declare the Unicode functions and constants, you may even get compile-time
+ * errors.
+ *
+ * To avoid this, you can perform a preprocessor test for the existence of
+ * #GLK_MODULE_UNICODE.
+ */
/**
* evtype_None:
* events, this is platform-dependent. See %evtype_Arrange.
*
* For more about redraw events and how they affect graphics windows, see <link
- * linkend="chimara-Graphics-Windows">Graphics Windows</link>.
+ * linkend="wintype-Graphics">Graphics Windows</link>.
*/
/**
* Represents the <keycap>F12</keycap> key.
*/
-/**
- * keycode_MAXVAL:
- *
- * This value is equal to the number of special keycodes. The last keycode is
- * always
- * <inlineequation>
- * <alt>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</alt>
- * <mathphrase>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</mathphrase>
- * </inlineequation>
- * .
- */
-
/**
* style_Normal:
*
*
* Another style available for your use.
*/
-
-/**
- * style_NUMSTYLES:
- *
- * The number of styles defined in this library.
- */
/**
* stream_result_t:
* When calling glk_window_open() with this @method, the new window will be
* below the old one which was split.
*/
-
-/**
- * winmethod_DirMask:
- *
- * Bitwise AND this value with a window splitting method argument to find
- * whether the split is %winmethod_Left, %winmethod_Right, %winmethod_Above, or
- * %winmethod_Below.
- */
/**
* winmethod_Fixed:
* a given proportion of the old window's size. (See glk_window_open()).
*/
-/**
- * winmethod_DivisionMask:
- *
- * Bitwise AND this value with a window splitting method argument to find
- * whether the new window has %winmethod_Fixed or %winmethod_Proportional.
- */
-
/**
* fileusage_Data:
*
* others may support both, or neither.
* </para></note>
*/
-
-/**
- * stylehint_NUMHINTS:
- *
- * The number of style hints defined in this library.
- */
/**
* stylehint_just_LeftFlush:
* A value for %stylehint_Justification representing right-justified text.
*/
+/**
+ * imagealign_InlineUp:
+ *
+ * The image appears at the current point in the text, sticking up. That is, the
+ * bottom edge of the image is aligned with the baseline of the line of text.
+ */
+
+/**
+ * imagealign_InlineDown:
+ *
+ * The image appears at the current point, and the top edge is aligned with the
+ * top of the line of text.
+ */
+
+/**
+ * imagealign_InlineCenter:
+ *
+ * The image appears at the current point, and it is centered between the top
+ * and baseline of the line of text. If the image is taller than the line of
+ * text, it will stick up and down equally.
+ */
+
+/**
+ * imagealign_MarginLeft:
+ *
+ * The image appears in the left margin. Subsequent text will be displayed to
+ * the right of the image, and will flow around it — that is, it will be
+ * left-indented for as many lines as it takes to pass the image.
+ *
+ * <warning><para>Margin images are not implemented yet.</para></warning>
+ */
+
+/**
+ * imagealign_MarginRight:
+ *
+ * The image appears in the right margin, and subsequent text will flow around
+ * it on the left.
+ *
+ * <warning><para>Margin images are not implemented yet.</para></warning>
+ */
+
/*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
/**
* For example, consider a hypothetical function, with selector
* <code>0xABCD</code>:
* |[
- * void glk_glomp(#glui32 num, #winid_t win, #glui32 *numref, #strid_t *strref);
+ * void glk_glomp(glui32 num, winid_t win, glui32 *numref, strid_t *strref);
* ]|
* ...and the calls:
* |[
- * #glui32 value;
- * #winid_t mainwin;
- * #strid_t gamefile;
+ * glui32 value;
+ * winid_t mainwin;
+ * strid_t gamefile;
* glk_glomp(5, mainwin, &value, &gamefile);
* ]|
*
* To perform this through gidispatch_call(), you would do the following:
* |[
- * #gluniversal_t arglist[6];
+ * gluniversal_t arglist[6];
* arglist[0].uint = 5;
* arglist[1].opaqueref = mainwin;
* arglist[2].ptrflag = TRUE;
* arglist[3].uint = value;
* arglist[4].ptrflag = TRUE;
* arglist[5].opaqueref = gamefile;
- * #gidispatch_call(0xABCD, 6, arglist);
+ * gidispatch_call(0xABCD, 6, arglist);
* value = arglist[3].uint;
* gamefile = arglist[5].opaqueref;
* ]|
*
* Note that you copy the value of the reference arguments into and out of
- * @arglist. Of course, it may be that glk_glomp() only uses these as pass-out
+ * @arglist. Of course, it may be that
+ * <function>glk_glomp()</function> only uses these as pass-out
* references or pass-in references; if so, you could skip copying in or out.
*
* For further examples:
* |[
* glk_glomp(7, mainwin, NULL, NULL);
* ...or...
- * #gluniversal_t arglist[4];
+ * gluniversal_t arglist[4];
* arglist[0].uint = 7;
* arglist[1].opaqueref = mainwin;
* arglist[2].ptrflag = FALSE;
* arglist[3].ptrflag = FALSE;
- * #gidispatch_call(0xABCD, 4, arglist);
+ * gidispatch_call(0xABCD, 4, arglist);
* ]|
*
* |[
* glk_glomp(13, NULL, NULL, &gamefile);
* ...or...
- * #gluniversal_t arglist[5];
+ * gluniversal_t arglist[5];
* arglist[0].uint = 13;
* arglist[1].opaqueref = NULL;
* arglist[2].ptrflag = FALSE;
* arglist[3].ptrflag = TRUE;
* arglist[4].opaqueref = gamefile;
- * #gidispatch_call(0xABCD, 5, arglist);
+ * gidispatch_call(0xABCD, 5, arglist);
* gamefile = arglist[4].opaqueref;
* ]|
*
* |[
* glk_glomp(17, NULL, &value, NULL);
* ...or...
- * #gluniversal_t arglist[5];
+ * gluniversal_t arglist[5];
* arglist[0].uint = 17;
* arglist[1].opaqueref = NULL;
* arglist[2].ptrflag = TRUE;
* arglist[3].uint = value;
* arglist[4].ptrflag = FALSE;
- * #gidispatch_call(0xABCD, 5, arglist);
+ * gidispatch_call(0xABCD, 5, arglist);
* value = arglist[3].uint;
* ]|
*
*
* For example, the function glk_select() can be invoked as follows:
* |[
- * #event_t ev;
- * #gluniversal_t arglist[5];
+ * event_t ev;
+ * gluniversal_t arglist[5];
* arglist[0].ptrflag = TRUE;
- * #gidispatch_call(0x00C0, 5, arglist);
+ * gidispatch_call(0x00C0, 5, arglist);
* ev.type = arglist[1].uint;
* ev.win = arglist[2].opaqueref;
* ev.val1 = arglist[3].uint;
*
* For example, the function glk_put_buffer() can be invoked as follows:
* |[
- * #char buf[64];
- * #glui32 len = 64;
- * #glk_put_buffer(buf, len);
+ * char buf[64];
+ * glui32 len = 64;
+ * glk_put_buffer(buf, len);
* ...or...
- * #gluniversal_t arglist[3];
+ * gluniversal_t arglist[3];
* arglist[0].ptrflag = TRUE;
* arglist[1].array = buf;
* arglist[2].uint = len;
- * #gidispatch_call(0x0084, 3, arglist);
+ * gidispatch_call(0x0084, 3, arglist);
* ]|
*
* Since you are passing a C char array to gidispatch_call(), the contents will
*
* For example, the function glk_window_get_rock() can be invoked as follows:
* |[
- * #glui32 rock;
- * #winid_t win;
- * rock = #glk_window_get_rock(win);
+ * glui32 rock;
+ * winid_t win;
+ * rock = glk_window_get_rock(win);
* ...or...
- * #gluniversal_t arglist[3];
+ * gluniversal_t arglist[3];
* arglist[0].opaqueref = win;
* arglist[1].ptrflag = TRUE;
- * #gidispatch_call(0x0021, 3, arglist);
+ * gidispatch_call(0x0021, 3, arglist);
* rock = arglist[2].uint;
* ]|
* </para></refsect3><para>
* @uch: Stores an #unsigned #char.
* @sch: Stores a #signed #char.
* @ch: Stores a #char with the default signedness.
- * @charstr: Stores a %NULL-terminated string.
+ * @charstr: Stores a null-terminated string.
+ * @unicharstr: Stores a zero-terminated string of #glui32 values representing
+ * Unicode characters.
* @array: Stores a pointer to an array, and should be followed by another
* #gluniversal_t with the array length stored in the @uint member.
* @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL,
* This returns a string which encodes the proper argument list for the given
* function. If there is no such function in the library, this returns %NULL.
*
- * The prototype string for the glk_glomp() function described above would be:
- * <code>"4IuQa&Iu&Qb:"</code>. The <code>"4"</code> is the number of
- * arguments (including the return value, if there is one, which in this case
- * there isn't.) <code>"Iu"</code> denotes an unsigned integer;
- * <code>"Qa"</code> is an opaque object of class 0 (window).
+ * The prototype string for the <function>glk_glomp()</function>
+ * function described above would be: <code>"4IuQa&Iu&Qb:"</code>. The
+ * <code>"4"</code> is the number of arguments (including the return value, if
+ * there is one, which in this case there isn't.) <code>"Iu"</code> denotes an
+ * unsigned integer; <code>"Qa"</code> is an opaque object of class 0 (window).
* <code>"&Iu"</code> is a <emphasis>reference</emphasis> to an unsigned
* integer, and <code>"&Qb"</code> is a reference to a stream. The colon at
* the end terminates the argument list; the return value would follow it, if
*
* Note that the initial number (<code>"4"</code> in this case) is the number of
* logical arguments, not the number of #gluniversal_t objects which will be
- * passed to gidispatch_call(). The glk_glomp() call uses anywhere from four to
- * six #gluniversal_t objects, as demonstrated above.
+ * passed to gidispatch_call(). The <function>glk_glomp()</function>
+ * call uses anywhere from four to six #gluniversal_t objects, as demonstrated
+ * above.
*
* The basic type codes:
* <variablelist>
*/
/**
- * giblorb_method_DontLoad:
+ * giblorb_method_FilePos:
*
* Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
* giblorb_load_resource() to get the position in the Blorb file at which the
/**
* giblorb_result_t:
+ * @chunknum: The chunk number (for use in giblorb_unload_chunk(), etc.)
+ * @data: A union containing a pointer to the data @ptr (if you used
+ * %giblorb_method_Memory) and the position in the file @startpos (if you used
+ * %giblorb_method_FilePos)
+ * @length: The length of the data
+ * @chunktype: The type of the chunk.
*
* Holds information about a chunk loaded from a Blorb file, and the method of
* accessing the chunk data. See giblorb_load_chunk_by_type() and
/**
* glkunix_argumentlist_t:
- *
- * In each entry, name is the option as it would appear on the command line
- * (including the leading dash, if any.) The desc is a description of the
- * argument; this is used when the library is printing a list of options. And
- * argtype is one of the following constants:
+ * @name: the option as it would appear on the command line (including the
+ * leading dash, if any.)
+ * @desc: a description of the argument; this is used when the library is
+ * printing a list of options.
+ * @argtype: one of the <code>glkunix_arg_</code> constants.
*
* <variablelist>
* <varlistentry>
* If you don't care about command-line arguments, you must still define an
* empty arguments list, as follows:
* |[
- * #glkunix_argumentlist_t glkunix_arguments[] = {
- * { NULL, #glkunix_arg_End, NULL }
+ * glkunix_argumentlist_t glkunix_arguments[] = {
+ * { NULL, glkunix_arg_End, NULL }
* };
* ]|
*
* Here is a more complete sample list:
* |[
- * #glkunix_argumentlist_t glkunix_arguments[] = {
- * { "", #glkunix_arg_ValueFollows, "filename: The game file to load." },
- * { "-hum", #glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
- * { "-bom", #glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
- * the NUM, if given)." },
- * { "-goo", #glkunix_arg_NoValue, "-goo: Find goo." },
- * { "-wob", #glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
- * { NULL, #glkunix_arg_End, NULL }
+ * glkunix_argumentlist_t glkunix_arguments[] = {
+ * { "", glkunix_arg_ValueFollows, "filename: The game file to load." },
+ * { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
+ * { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
+ * the NUM, if given)." },
+ * { "-goo", glkunix_arg_NoValue, "-goo: Find goo." },
+ * { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
+ * { NULL, glkunix_arg_End, NULL }
* };
* ]|
* This would match the arguments <quote><code>thingfile -goo -wob8 -bom -hum
* After the library parses the command line, it does various occult rituals of
* initialization, and then calls glkunix_startup_code().
*
- * |[ int glkunix_startup_code(#glkunix_startup_t *data); ]|
+ * |[ int glkunix_startup_code(glkunix_startup_t *data); ]|
*
* This should return %TRUE if everything initializes properly. If it returns
* %FALSE, the library will shut down without ever calling your glk_main()
/**
* glkunix_startup_t:
+ * @argc: The number of arguments in @argv.
+ * @argv: Strings representing command line arguments.
*
* The fields are a standard Unix <code>(argc, argv)</code> list, which contain
* the arguments you requested from the command line. In deference to custom,
projects / rodin / chimara.git / blobdiff