EXTRA_HFILES =
# Header files to ignore when scanning. Use base file name, no paths
-IGNORE_HFILES = chimara-glk-private.h \
- abort.h charset.h event.h input.h stream.h window.h
+IGNORE_HFILES = chimara-glk-private.h chimara-marshallers.h \
+ abort.h charset.h event.h fileref.h graphics.h hyperlink.h init.h input.h \
+ magic.h mouse.h pager.h resource.h stream.h strio.h style.h timer.h window.h
# Images to copy into HTML directory.
HTML_IMAGES = \
giblorb_ID_Copyright
giblorb_ID_AUTH
giblorb_ID_ANNO
+<SUBSECTION Private>
+giblorb_make_id
</SECTION>
<SECTION>
glkunix_arg_ValueCanFollow
glkunix_arg_NumberValue
glkunix_arg_End
+<SUBSECTION Private>
+glkunix_startup_code
+NULL
</SECTION>
<SECTION>
glkunix_stream_open_pathname
glkunix_set_base_file
</SECTION>
+
+<SECTION>
+<FILE>glkext-garglk</FILE>
+<TITLE>Gargoyle Extensions</TITLE>
+garglk_set_reverse_video
+</SECTION>
\ No newline at end of file
</para></note>
<note><para>
This is also why you must put calls to glk_select() in loops. If you tried to read a character by simply writing
-<informalexample><programlisting>
-#glk_request_char_event(win);
-#glk_select(&ev);
-</programlisting></informalexample>
+|[
+glk_request_char_event(win);
+glk_select(&ev);
+]|
you might not get a CharInput event back. You could get some not-yet-defined event which happened to occur before the player hit a key. Or, for that matter, a window arrangement event.
</para></note>
<note><para>
It is not generally necessary to put a call to glk_select_poll() in a loop. You usually call glk_select_poll() to update the display or test if an event is available, not to wait for a particular event. However, if you are using sound notification events, and several sounds are playing, it might be important to make sure you knew about all sounds completed at any particular time. You would do this with
-<informalexample><programlisting>
-#glk_select_poll(&ev);
-while (ev.type != #evtype_None) {
+|[
+glk_select_poll(&ev);
+while (ev.type != evtype_None) {
/* handle event */
- #glk_select_poll(&ev);
+ glk_select_poll(&ev);
}
-</programlisting></informalexample>
+]|
</para>
<para>
Once glk_select_poll() returns #evtype_None, you should not call it again immediately. Do some work first. If you want to wait for an event, use glk_select(), not a loop of glk_select_poll().
You can repeat this as often as you want. Every time you split a window, one new window is created. Therefore, the call that does this is called glk_window_open().
</para>
<note><para>
-It might have been less confusing to call it <quote>glk_split_window()</quote> — or it might have been more confusing. I picked one.
+It might have been less confusing to call it <quote>glk_split_window()</quote> — or it might have been more confusing. I picked one.
</para></note>
<para>
It is important to remember that the order of splitting matters. If you split twice, you don't have a trio of windows; you have a pair with another pair on one side. Mathematically, the window structure is a binary tree.
*
* Sets whether the widget is interactive. A Glk widget is normally
* interactive, but in non-interactive mode, keyboard and mouse input are
- * ignored and the Glk program is controlled by chimara_glk_feed_text().
+ * ignored and the Glk program is controlled by
+ * chimara_glk_feed_char_input() and chimara_glk_feed_line_input().
* <quote>More</quote> prompts when a lot of text is printed to a text
* buffer are also disabled. This is typically used when you wish to control
* an interpreter program by feeding it a predefined list of commands.
* chimara_glk_set_css_from_file:
* @glk: a #ChimaraGlk widget
* @filename: path to a CSS file, or %NULL
- * @error: location to store a <link linkend="glib-GError">GError</link>, or
- * %NULL
+ * @error: location to store a <link
+ * linkend="glib-Error-Reporting">GError</link>, or %NULL
*
* Sets the styles for text buffer and text grid windows according to the CSS
* file @filename. Note that the styles are set cumulatively on top of whatever
/**
* chimara_glk_set_css_from_string:
* @glk: a #ChimaraGlk widget
- * @filename: a string containing CSS code
+ * @css: a string containing CSS code
*
* Sets the styles for text buffer and text grid windows according to the CSS
* code @css. Note that the styles are set cumulatively on top of whatever the
* class="header">glk.h</filename>
* @argc: Number of command line arguments in @argv
* @argv: Array of command line arguments to pass to the plugin
- * @error: location to store a <link linkend="glib-GError">GError</link>, or
- * %NULL
+ * @error: location to store a <link
+ * linkend="glib-Error-Reporting">GError</link>, or %NULL
*
* Opens a Glk program compiled as a plugin. Sorts out its command line
* arguments from #glkunix_arguments, calls its startup function
/**
* ChimaraError:
+ * @CHIMARA_LOAD_MODULE_ERROR: There was an error opening the plugin containing
+ * the Glk program. The error message from <link
+ * linkend="g-module-error">g_module_error()</link> is appended to the <link
+ * linkend="GError">GError</link> message.
+ * @CHIMARA_NO_GLK_MAIN: The plugin containing the Glk program did not export a
+ * glk_main() function.
+ * @CHIMARA_PLUGIN_NOT_FOUND: An appropriate interpreter plugin for the
+ * autodetected game file type could not be found.
+ * @CHIMARA_PLUGIN_ALREADY_RUNNING: A plugin was opened while there was already
+ * another plugin running in the widget.
*
* Error codes returned by #ChimaraGlk widgets and subclasses.
- * <variablelist>
- * <varlistentry>
- * <term>CHIMARA_LOAD_MODULE_ERROR</term>
- * <listitem><para>There was an error opening the plugin containing the Glk
- * program. The error message from <link
- * linkend="g-module-error">g_module_error()</link> is appended to the <link
- * linkend="GError">GError</link> message.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>CHIMARA_NO_GLK_MAIN</term>
- * <listitem><para>The plugin containing the Glk program did not export a
- * glk_main() function.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>CHIMARA_PLUGIN_NOT_FOUND</term>
- * <listitem><para>An appropriate interpreter plugin for the autodetected
- * game file type could not be found.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>CHIMARA_PLUGIN_ALREADY_RUNNING</term>
- * <listitem><para>A plugin was opened while there was already another plugin
- * running in the widget.</para></listitem>
- * </varlistentry>
- * </variablelist>
*/
typedef enum _ChimaraError {
CHIMARA_LOAD_MODULE_ERROR,
void chimara_glk_stop(ChimaraGlk *glk);
void chimara_glk_wait(ChimaraGlk *glk);
gboolean chimara_glk_get_running(ChimaraGlk *glk);
-void chimara_glk_feed_char_input(ChimaraGlk *glk, guint32 keycode);
+void chimara_glk_feed_char_input(ChimaraGlk *glk, guint32 keyval);
void chimara_glk_feed_line_input(ChimaraGlk *glk, const gchar *text);
G_END_DECLS
/**
* ChimaraIFFormat:
- *
+ * @CHIMARA_IF_FORMAT_Z5: Z-code version 5
+ * @CHIMARA_IF_FORMAT_Z6: Z-code version 6
+ * @CHIMARA_IF_FORMAT_Z8: Z-code version 8
+ * @CHIMARA_IF_FORMAT_Z_BLORB: Blorbed Z-code
+ * @CHIMARA_IF_FORMAT_GLULX: Glulx
+ * @CHIMARA_IF_FORMAT_GLULX_BLORB: Blorbed Glulx
+ *
* Constants representing all game formats supported by the Chimara system.
*/
typedef enum _ChimaraIFFormat {
+ /*< private >*/
CHIMARA_IF_FORMAT_NONE = -1,
+ /*< public >*/
CHIMARA_IF_FORMAT_Z5,
CHIMARA_IF_FORMAT_Z6,
CHIMARA_IF_FORMAT_Z8,
CHIMARA_IF_FORMAT_Z_BLORB,
CHIMARA_IF_FORMAT_GLULX,
CHIMARA_IF_FORMAT_GLULX_BLORB,
+ /*< private >*/
CHIMARA_IF_NUM_FORMATS
} ChimaraIFFormat;
/**
* ChimaraIFInterpreter:
+ * @CHIMARA_IF_INTERPRETER_FROTZ: Frotz
+ * @CHIMARA_IF_INTERPRETER_NITFOL: Nitfol
+ * @CHIMARA_IF_INTERPRETER_GLULXE: Glulxe
+ * @CHIMARA_IF_INTERPRETER_GIT: Git
*
* Constants representing the available interpreter plugins.
*/
typedef enum _ChimaraIFInterpreter {
+ /*< private >*/
CHIMARA_IF_INTERPRETER_NONE = -1,
+ /*< public >*/
CHIMARA_IF_INTERPRETER_FROTZ,
CHIMARA_IF_INTERPRETER_NITFOL,
CHIMARA_IF_INTERPRETER_GLULXE,
CHIMARA_IF_INTERPRETER_GIT,
+ /*< private >*/
CHIMARA_IF_NUM_INTERPRETERS
} ChimaraIFInterpreter;
/**
* ChimaraIFZmachineVersion:
+ * @CHIMARA_IF_ZMACHINE_DEFAULT: Use the interpreter's default interpreter
+ * number.
+ * @CHIMARA_IF_ZMACHINE_DECSYSTEM_20: DEC System 20
+ * @CHIMARA_IF_ZMACHINE_APPLE_IIE: Apple IIe
+ * @CHIMARA_IF_ZMACHINE_MACINTOSH: Apple Macintosh
+ * @CHIMARA_IF_ZMACHINE_AMIGA: Commodore Amiga
+ * @CHIMARA_IF_ZMACHINE_ATARI_ST: Atari ST
+ * @CHIMARA_IF_ZMACHINE_IBM_PC: IBM PC
+ * @CHIMARA_IF_ZMACHINE_COMMODORE_128: Commodore 128
+ * @CHIMARA_IF_ZMACHINE_COMMODORE_64: Commodore 64
+ * @CHIMARA_IF_ZMACHINE_APPLE_IIC: Apple IIc
+ * @CHIMARA_IF_ZMACHINE_APPLE_IIGS: Apple IIgs
+ * @CHIMARA_IF_ZMACHINE_TANDY_COLOR: Tandy Color Computer
*
- * Allowed values for the #ChimaraIF:interpreter-number property.
+ * Allowed values for the #ChimaraIF:interpreter-number property. All trademarks
+ * are the property of their respective owners.
*/
typedef enum _ChimaraIFZmachineVersion {
CHIMARA_IF_ZMACHINE_DEFAULT = 0,
CHIMARA_IF_ZMACHINE_APPLE_IIC,
CHIMARA_IF_ZMACHINE_APPLE_IIGS,
CHIMARA_IF_ZMACHINE_TANDY_COLOR,
+ /*< private >*/
CHIMARA_IF_ZMACHINE_MAXVAL = CHIMARA_IF_ZMACHINE_TANDY_COLOR
} ChimaraIFZmachineVersion;
* actually executing VM code.) You pass in two function pointers, matching the
* following prototypes:
* |[
- * #gidispatch_rock_t my_vm_reg_object(void *obj, #glui32 objclass);
- * void my_vm_unreg_object(void *obj, #glui32 objclass, #gidispatch_rock_t objrock);
+ * gidispatch_rock_t my_vm_reg_object(void *obj, glui32 objclass);
+ * void my_vm_unreg_object(void *obj, glui32 objclass, gidispatch_rock_t objrock);
* ]|
*
- * Whenever the Glk library creates an object, it will call my_vm_reg_object().
- * It will pass the object pointer and the class number (from 0 to
- * <inlineequation><mathphrase>N - 1</mathphrase><alt>N -
- * 1</alt></inlineequation>, where N is the value returned by
- * gidispatch_count_classes().)
+ * Whenever the Glk library creates an object, it will call
+ * <function>my_vm_reg_object()</function>. It will pass the object
+ * pointer and the class number (from 0 to <inlineequation><mathphrase>N -
+ * 1</mathphrase><alt>N - 1</alt></inlineequation>, where N is the value
+ * returned by gidispatch_count_classes().)
*
* You can return any value in the #gidispatch_rock_t object; the library will
* stash this away inside the object.
* </para></note>
*
* Whenever the Glk library destroys an object, it will call
- * my_vm_unreg_object(). It passes you the object pointer, class number, and the
- * object rock.
+ * <function>my_vm_unreg_object()</function>. It passes you the object
+ * pointer, class number, and the object rock.
*
* One significant detail: It is possible that some Glk objects will already
* exist when your glk_main() function is called.
* </para></note>
*
* So when you call gidispatch_set_object_registry(), it may immediately call
- * your my_vm_reg_object() callback, notifying you of the existing objects. You
- * must be prepared for this possibility.
+ * your <function>my_vm_reg_object()</function> callback, notifying
+ * you of the existing objects. You must be prepared for this possibility.
*
* <note><para>
* If you are keeping hash tables, for example, create them before you call
*
* Again, you pass in two function pointers:
* |[
- * #gidispatch_rock_t my_vm_reg_array(void *array, #glui32 len, char *typecode);
- * void my_vm_unreg_array(void *array, #glui32 len, char *typecode, #gidispatch_rock_t objrock);
+ * gidispatch_rock_t my_vm_reg_array(void *array, glui32 len, char *typecode);
+ * void my_vm_unreg_array(void *array, glui32 len, char *typecode, gidispatch_rock_t objrock);
* ]|
*
- * Whenever a Glk function retains an array, it will call my_vm_reg_array().
- * This occurs only if you pass an array to an argument with the
- * <code>"#!"</code> prefix.
+ * Whenever a Glk function retains an array, it will call
+ * <function>my_vm_reg_array()</function>. This occurs only if you
+ * pass an array to an argument with the <code>"#!"</code> prefix.
*
* <note><para>
- * But not in every such case. Wait for the my_vm_reg_array() call to confirm
- * it.
+ * But not in every such case. Wait for the
+ * <function>my_vm_reg_array()</function> call to confirm it.
* </para></note>
*
* The library passes the array and its length, exactly as you put them in the
* stash this away with the array.
*
* When a Glk function releases a retained array, it will call
- * my_vm_unreg_array(). It passes back the same @array, @len, and @typecode
- * parameters, as well as the #gidispatch_rock_t you returned from
- * my_vm_reg_array().
+ * <function>my_vm_unreg_array()</function>. It passes back the same
+ * @array, @len, and @typecode parameters, as well as the #gidispatch_rock_t you
+ * returned from <function>my_vm_reg_array()</function>.
*
* With these callbacks, you can maintain a collection of retained arrays. You
* can use this to copy data from C arrays to your own data structures, or keep
* 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>
* 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
* 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_Timer:
*
* You can test whether the library supports timer events:
- * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]|
+ * |[ res = glk_gestalt(gestalt_Timer, 0); ]|
* This returns 1 if timer events are supported, and 0 if they are not.
*/
* Before calling Glk graphics functions, you should use the following gestalt
* selector:
* |[
- * glui32 res;
- * res = glk_gestalt(gestalt_Graphics, 0);
+ * glui32 res;
+ * 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(),
*
* 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
* the following gestalt selector:
* |[
* glui32 res;
- * res = #glk_gestalt(#gestalt_Unicode, 0);
+ * res = glk_gestalt(gestalt_Unicode, 0);
* ]|
*
* This returns 1 if the Unicode functions are available. If it returns 0, you
* 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>.
*/
/**
* 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>
+ * <alt>(0x100000000 - <code><keysym>keycode_MAXVAL</keysym></code>)</alt>
+ * <mathphrase>(0x100000000 - <code><keysym>keycode_MAXVAL</keysym></code>)</mathphrase>
* </inlineequation>
* .
*/
* 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_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,
* <note><title>Chimara</title>
* <para>
* Chimara uses a <link
- * linkend="gtk-GtkFileChooserDialog">GtkFileChooserDialog</link>. The default
+ * linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>. The default
* starting location for the dialog may be set with glkunix_set_base_file().
* </para></note>
*
extern GPrivate *glk_data_key;
-void
+static void
apply_reverse_color(GtkTextTag *tag, gpointer data)
{
g_object_set_data( G_OBJECT(tag), "reverse_color", data );
* loop, this is critical. In a C program, you can often eyeball it.
* </para>
* <para>But the next version of <filename>model.c</filename> will have a
- * glk_tick() in the ornate printing loop of <function>verb_yada()</function>.
- * Just to make the point.
+ * glk_tick() in the ornate printing loop of
+ * <function>verb_yada()</function>. Just to make the point.
* </para>
* </note>
*/
/**
* glkunix_stream_open_pathname:
* @pathname: A path to a file, in the system filename encoding.
- * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
+ * @textmode: Bitfield with one or more of the <code>fileusage_</code> constants.
* @rock: The new stream's rock value.
*
* Opens an arbitrary file, in read-only mode. Note that this function is
* Returns: A new stream, or %NULL if the file operation failed.
*/
strid_t
-glkunix_stream_open_pathname(char *pathname, glui32 usage, glui32 rock)
+glkunix_stream_open_pathname(char *pathname, glui32 textmode, glui32 rock)
{
ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
* <note><para>
* This function may only be used with graphics windows. To set background
* colors in a text window, use text styles with color hints; see <link
- * linkend="Styles">Styles</link>.
+ * linkend="chimara-Styles">Styles</link>.
* </para></note>
*/
void
* equivalent to
* |[
* for (ptr = s; *ptr; ptr++)
- * #glk_put_char(*ptr);
+ * glk_put_char(*ptr);
* ]|
* However, it may be more efficient.
*/
* to:
* |[
* for (i = 0; i < len; i++)
- * #glk_put_char(buf[i]);
+ * glk_put_char(buf[i]);
* ]|
* However, it may be more efficient.
*/
*
* So to create a text buffer window which takes the top 40% of the original
* window's space, you would execute
- * |[ newwin = #glk_window_open(win, #winmethod_Above | #winmethod_Proportional, 40, #wintype_TextBuffer, 0); ]|
+ * |[ newwin = glk_window_open(win, winmethod_Above | winmethod_Proportional, 40, wintype_TextBuffer, 0); ]|
*
* To create a text grid which is always five lines high, at the bottom of the
* original window, you would do
- * |[ newwin = #glk_window_open(win, #winmethod_Below | #winmethod_Fixed, 5, #wintype_TextGrid, 0); ]|
+ * |[ newwin = glk_window_open(win, winmethod_Below | winmethod_Fixed, 5, wintype_TextGrid, 0); ]|
*
* Note that the meaning of the @size argument depends on the @method argument.
* If the method is %winmethod_Fixed, it also depends on the @wintype argument.
* <quote>O</quote>. C gets two rows; A gets the rest. All done.
*
* Then the user maliciously starts squeezing the window down, in stages:
- * <informaltable frame="none"><tgroup cols="5"><tbody><row valign="top">
+ * <informaltable xml:id="chimara-Figure-Squeezing-Window" frame="none">
+ * <tgroup cols="5"><tbody><row valign="top">
* <entry><mediaobject><imageobject><imagedata fileref="fig5-7a.png"/>
* </imageobject></mediaobject></entry>
* <entry><mediaobject><imageobject><imagedata fileref="fig7b.png"/>
* <term>Graphics</term>
* <listitem><para>
* Clears the entire window to its current background color. See <link
- * linkend="chimara-Graphics-Windows">Graphics Windows</link>.
+ * linkend="chimara-The-Types-of-Windows#wintype-Graphics">Graphics
+ * Windows</link>.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* @win: A window, or %NULL.
*
* Sets the current stream to @win's window stream. It is exactly equivalent to
- * |[ #glk_stream_set_current(#glk_window_get_stream(@win)) ]|
+ * |[ glk_stream_set_current(glk_window_get_stream(win)) ]|
* See <link linkend="chimara-Streams">Streams</link>.
*
* <note><title>Chimara</title>
* Consider the example above, where D has collapsed to zero height. Say D was a
* text buffer window. You could make a more useful layout by doing
* |[
- * #winid_t o2;
- * o2 = #glk_window_get_parent(d);
- * glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Fixed, 3, d);
+ * winid_t o2;
+ * o2 = glk_window_get_parent(d);
+ * glk_window_set_arrangement(o2, winmethod_Above | winmethod_Fixed, 3, d);
* ]|
* That would set D (the upper child of O2) to be O2's key window, and give it a
* fixed size of 3 rows.
*
* If you later wanted to expand D, you could do
- * |[ glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Fixed, 5, NULL); ]|
+ * |[ glk_window_set_arrangement(o2, winmethod_Above | winmethod_Fixed, 5, NULL); ]|
* That expands D to five rows. Note that, since O2's key window is already set
* to D, it is not necessary to provide the @keywin argument; you can pass %NULL
* to mean <quote>leave the key window unchanged.</quote>
* example, you could change O2's key window to be A, but not B. The key window
* also cannot be a pair window itself.
*
- * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Fixed, 3, NULL); ]|
+ * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Fixed, 3, NULL); ]|
* This changes the constraint to be on the <emphasis>lower</emphasis> child of
* O2, which is A. The key window is still D; so A would then be three rows high
* as measured in D's font, and D would get the rest of O2's space. That may not
* be what you want. To set A to be three rows high as measured in A's font, you
* would do
- * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Fixed, 3, a); ]|
+ * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Fixed, 3, a); ]|
*
* Or you could change O2 to a proportional split:
- * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Proportional, 30, NULL); ]|
+ * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Proportional, 30, NULL); ]|
* or
- * |[ glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Proportional, 70, NULL); ]|
+ * |[ glk_window_set_arrangement(o2, winmethod_Above | winmethod_Proportional, 70, NULL); ]|
* These do exactly the same thing, since 30% above is the same as
* 70% below. You don't need to specify a key window with a proportional
* split, so the @keywin argument is %NULL. (You could actually specify either A
projects / rodin / chimara.git / commitdiff