Brought documentation up to date
authorfliep <fliep@ddfedd41-794f-dd11-ae45-00112f111e67>
Sun, 25 Apr 2010 14:38:32 +0000 (14:38 +0000)
committerfliep <fliep@ddfedd41-794f-dd11-ae45-00112f111e67>
Sun, 25 Apr 2010 14:38:32 +0000 (14:38 +0000)
docs/reference/chimara-docs.sgml
docs/reference/chimara-sections.txt
libchimara/chimara-glk.c
libchimara/chimara-if.c
libchimara/doc.c
libchimara/style.c

index 8f5c73fc316aa0409c9066f9e8f4734e85baa67a..eebc66cd09ccc9e3ec3eeb8a33a4ce53f4a2eea1 100644 (file)
@@ -84,7 +84,7 @@
          <xi:include href="xml/glk-stream-positions.xml"/>
          <xi:include href="xml/glk-styles.xml"/>
          <xi:include href="xml/glk-stylehints.xml"/>
-         <!--<xi:include href="xml/glk-style-measure.xml"/>-->
+         <xi:include href="xml/glk-style-measure.xml"/>
          <xi:include href="xml/glk-stream-types.xml"/>
          <xi:include href="xml/glk-stream-other.xml"/>
        </chapter>
       <title>Graphics</title>
       <xi:include href="xml/glk-image-resources.xml"/>
       <xi:include href="xml/glk-graphics-windows.xml"/>
-      <!--<xi:include href="xml/glk-graphics-text.xml"/>-->
+      <xi:include href="xml/glk-graphics-text.xml"/>
       <xi:include href="xml/glk-graphics-testing.xml"/>
     </chapter>
     
index 1170c7de58b9f654c30a58817341e6b19316ea53..fd9315ab2ccd95ed7a2416dd12b13fb28680a101 100644 (file)
@@ -10,14 +10,11 @@ chimara_glk_set_interactive
 chimara_glk_get_interactive
 chimara_glk_set_protect
 chimara_glk_get_protect
-chimara_glk_set_default_font_description
-chimara_glk_set_default_font_string
-chimara_glk_get_default_font_description
-chimara_glk_set_monospace_font_description
-chimara_glk_set_monospace_font_string
-chimara_glk_get_monospace_font_description
 chimara_glk_set_spacing
 chimara_glk_get_spacing
+chimara_glk_set_css_to_default
+chimara_glk_set_css_from_file
+chimara_glk_set_css_from_string
 chimara_glk_run
 chimara_glk_stop
 chimara_glk_wait
index dbd89c2cd5c21567f61e652030f10e83409cd7bc..63849189a1788347e3427795e4e5b140599a869c 100644 (file)
@@ -862,6 +862,9 @@ chimara_glk_get_protect(ChimaraGlk *glk)
  * @glk: a #ChimaraGlk widget
  *
  * Resets the styles for text buffer and text grid windows to their defaults.
+ * <para><warning>
+ *   This function is not implemented yet.
+ * </warning></para>
  */
 void
 chimara_glk_set_css_to_default(ChimaraGlk *glk)
@@ -920,10 +923,10 @@ chimara_glk_set_css_from_file(ChimaraGlk *glk, const gchar *filename, GError **e
  * @glk: a #ChimaraGlk widget
  * @filename: a string containing CSS code
  *
- * Sets the styles for text buffer and text grid windows according to @css. Note
- * that the styles are set cumulatively on top of whatever the styles are at the
- * time this function is called; to reset the styles to their defaults, use 
- * chimara_glk_set_css_to_default().
+ * 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 
+ * styles are at the time this function is called; to reset the styles to their
+ * defaults, use chimara_glk_set_css_to_default().
  */
 void 
 chimara_glk_set_css_from_string(ChimaraGlk *glk, const gchar *css)
index be9fc206f0c519ec8cd06bbce56e894a02ff63cc..7b91830acdce059d12ab64193a28355cbf6c75df 100644 (file)
@@ -279,8 +279,7 @@ chimara_if_class_init(ChimaraIFClass *klass)
         *
         * Emitted once for each input-response cycle of an interactive fiction
         * game. Note that games with nontraditional input systems (i.e. not all
-        * taking place in the same text buffer window) may throw this signal for a
-        * loop.
+        * taking place in the same text buffer window) may confuse this signal.
         */
        chimara_if_signals[COMMAND] = g_signal_new("command",
                G_OBJECT_CLASS_TYPE(klass), 0,
index 0f00da92a5a3f06e74225087835a60458f9aa3b8..cb20d6e8f15ca3f83e8a479b8324c5d0e4ad49cc 100644 (file)
  * </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
  * 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.
+ */
+
 /**
  * SECTION:glk-graphics-testing
  * @short_description: Checking whether the library supports graphics
  * 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.
+ */
 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
 
 /**
index 80b66d6f2517f2e1129b73f37bf573764416bdc0..a879b2c8e2b8f635f198e323aa7724e809a77e44 100644 (file)
@@ -22,9 +22,9 @@ GtkTextTag* gtk_text_tag_copy(GtkTextTag *tag);
  * @styl: The style to apply
  *
  * Changes the style of the current output stream. @styl should be one of the
- * <code>style_</code> constants listed above. However, any value is actually
- * legal; if the interpreter does not recognize the style value, it will treat
- * it as %style_Normal.
+ * <code>style_</code> constants. However, any value is actually legal; if the 
+ * interpreter does not recognize the style value, it will treat it as 
+ * %style_Normal.
  * <note><para>
  *  This policy allows for the future definition of styles without breaking old
  *  Glk libraries.
@@ -780,7 +780,7 @@ query_tag(GtkTextTag *tag, glui32 wintype, glui32 hint)
  * @val: The style hint. The meaning of this depends on @hint.
  *
  * Sets a hint about the appearance of one style for a particular type of 
- * window. You can also set wintype to %wintype_AllTypes, which sets a hint for 
+ * window. You can also set @wintype to %wintype_AllTypes, which sets a hint for 
  * all types of window.
  * <note><para>
  *  There is no equivalent constant to set a hint for all styles of a single 
@@ -810,9 +810,9 @@ glk_stylehint_set(glui32 wintype, glui32 styl, glui32 hint, glsi32 val)
  * @styl: The style to set a hint for.
  * @hint: The type of style hint, one of the <code>stylehint_</code> constants.
  *
- * Resets a hint about the appearance of one style for a particular type of 
- * window to it's default value. You can also set wintype to %wintype_AllTypes, which resets a hint for 
- * all types of window.
+ * Clears a hint about the appearance of one style for a particular type of 
+ * window to its default value. You can also set @wintype to %wintype_AllTypes, 
+ * which clears a hint for all types of window.
  * <note><para>
  *  There is no equivalent constant to reset a hint for all styles of a single 
  *  window type.
@@ -843,12 +843,20 @@ glk_stylehint_clear(glui32 wintype, glui32 styl, glui32 hint)
  * @styl1: The first style to be distinguished from the second style.
  * @styl2: The second style to be distinguished from the first style.
  * 
- * Returns: TRUE if the two styles are visually distinguishable in the given window.
- * If they are not, it returns FALSE.
+ * Decides whether two styles are visually distinguishable in the given window.
+ * The exact meaning of this is left for the library to determine.
+ * <note><title>Chimara</title><para>
+ *   Currently, all styles of one window are assumed to be mutually
+ *   distinguishable.
+ * </para></note>
+ * 
+ * Returns: %TRUE (1) if the two styles are visually distinguishable. If they 
+ * are not, it returns %FALSE (0).
  */
 glui32
 glk_style_distinguish(winid_t win, glui32 styl1, glui32 styl2)
 {
+       /* FIXME */
        return styl1 != styl2;
 }
 
@@ -859,7 +867,66 @@ glk_style_distinguish(winid_t win, glui32 styl1, glui32 styl2)
  * @hint: The stylehint to measure.
  * @result: Address to write the result to.
  * 
- * This function can be used to query the current value of a particular style hint.
+ * Tries to test an attribute of one style in the given window @win. The library
+ * may not be able to determine the attribute; if not, this returns %FALSE (0).
+ * If it can, it returns %TRUE (1) and stores the value in the location pointed
+ * at by @result. 
+ * <note><para>
+ *   As usual, it is legal for @result to be %NULL, although fairly pointless.
+ * </para></note>
+ *
+ * The meaning of the value depends on the hint which was tested:
+ * <variablelist>
+ * <varlistentry>
+ *   <term>%stylehint_Indentation, %stylehint_ParaIndentation</term>
+ *   <listitem><para>The indentation and paragraph indentation. These are in a
+ *   metric which is platform-dependent.</para>
+ *   <note><para>Most likely either characters or pixels.</para></note>
+ *   </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>%stylehint_Justification</term>
+ *   <listitem><para>One of the constants %stylehint_just_LeftFlush,
+ *   %stylehint_just_LeftRight, %stylehint_just_Centered, or
+ *   %stylehint_just_RightFlush.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>%stylehint_Size</term>
+ *   <listitem><para>The font size. Again, this is in a platform-dependent
+ *   metric.</para>
+ *   <note><para>Pixels, points, or simply 1 if the library does not support
+ *   varying font sizes.</para></note>
+ *   </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>%stylehint_Weight</term>
+ *   <listitem><para>1 for heavy-weight fonts (boldface), 0 for normal weight,
+ *   and -1 for light-weight fonts.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>%stylehint_Oblique</term>
+ *   <listitem><para>1 for oblique fonts (italic), or 0 for normal angle.</para>
+ *   </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>%stylehint_Proportional</term>
+ *   <listitem><para>1 for proportional-width fonts, or 0 for fixed-width.
+ *   </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>%stylehint_TextColor, %stylehint_BackColor</term>
+ *   <listitem><para>These are values from 0x00000000 to 0x00FFFFFF, encoded as
+ *   described in <link 
+ *   linkend="chimara-Suggesting-the-Appearance-of-Styles">Suggesting the
+ *   Appearance of Styles</link>.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>%stylehint_ReverseColor</term>
+ *   <listitem><para>0 for normal printing, 1 if the foreground and background
+ *   colors are reversed.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ * 
  * Returns: TRUE upon successul retrieval, otherwise FALSE.
  */
 glui32
@@ -871,11 +938,13 @@ glk_style_measure(winid_t win, glui32 styl, glui32 hint, glui32 *result)
        switch(win->type) {
        case wintype_TextBuffer:
                tag = g_hash_table_lookup( glk_data->current_styles->text_buffer, get_tag_name(styl) );
-               *result = query_tag(tag, win->type, hint);
+               if(result)
+                       *result = query_tag(tag, win->type, hint);
                break;
        case wintype_TextGrid:
                tag = g_hash_table_lookup( glk_data->current_styles->text_grid, get_tag_name(styl) );
-               *result = query_tag(tag, win->type, hint);
+               if(result)
+                       *result = query_tag(tag, win->type, hint);
        default:
                return FALSE;
        }