From 7ef4ef1fecab7ae0f724e59f7de1315a96822152 Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Sun, 25 Apr 2010 14:38:32 +0000 Subject: [PATCH] Brought documentation up to date git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@245 ddfedd41-794f-dd11-ae45-00112f111e67 --- docs/reference/chimara-docs.sgml | 4 +- docs/reference/chimara-sections.txt | 9 +-- libchimara/chimara-glk.c | 11 ++-- libchimara/chimara-if.c | 3 +- libchimara/doc.c | 60 +++++++++++++++++++ libchimara/style.c | 93 +++++++++++++++++++++++++---- 6 files changed, 154 insertions(+), 26 deletions(-) diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml index 8f5c73f..eebc66c 100644 --- a/docs/reference/chimara-docs.sgml +++ b/docs/reference/chimara-docs.sgml @@ -84,7 +84,7 @@ - + @@ -102,7 +102,7 @@ Graphics - + diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt index 1170c7d..fd9315a 100644 --- a/docs/reference/chimara-sections.txt +++ b/docs/reference/chimara-sections.txt @@ -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 diff --git a/libchimara/chimara-glk.c b/libchimara/chimara-glk.c index dbd89c2..6384918 100644 --- a/libchimara/chimara-glk.c +++ b/libchimara/chimara-glk.c @@ -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. + * + * This function is not implemented yet. + * */ 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) diff --git a/libchimara/chimara-if.c b/libchimara/chimara-if.c index be9fc20..7b91830 100644 --- a/libchimara/chimara-if.c +++ b/libchimara/chimara-if.c @@ -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, diff --git a/libchimara/doc.c b/libchimara/doc.c index 0f00da9..cb20d6e 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -760,6 +760,29 @@ * */ +/** + * 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. + * + * 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. + * + */ + /** * SECTION:glk-stream-types * @short_description: Window, memory, and file streams @@ -967,6 +990,21 @@ * 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 @@ -2490,6 +2528,28 @@ * 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 ------------------*/ /** diff --git a/libchimara/style.c b/libchimara/style.c index 80b66d6..a879b2c 100644 --- a/libchimara/style.c +++ b/libchimara/style.c @@ -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 - * style_ 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. + * style_ constants. However, any value is actually legal; if the + * interpreter does not recognize the style value, it will treat it as + * %style_Normal. * * 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. * * 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 stylehint_ 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. * * 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. + * Chimara + * Currently, all styles of one window are assumed to be mutually + * distinguishable. + * + * + * 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. + * + * As usual, it is legal for @result to be %NULL, although fairly pointless. + * + * + * The meaning of the value depends on the hint which was tested: + * + * + * %stylehint_Indentation, %stylehint_ParaIndentation + * The indentation and paragraph indentation. These are in a + * metric which is platform-dependent. + * Most likely either characters or pixels. + * + * + * + * %stylehint_Justification + * One of the constants %stylehint_just_LeftFlush, + * %stylehint_just_LeftRight, %stylehint_just_Centered, or + * %stylehint_just_RightFlush. + * + * + * %stylehint_Size + * The font size. Again, this is in a platform-dependent + * metric. + * Pixels, points, or simply 1 if the library does not support + * varying font sizes. + * + * + * + * %stylehint_Weight + * 1 for heavy-weight fonts (boldface), 0 for normal weight, + * and -1 for light-weight fonts. + * + * + * %stylehint_Oblique + * 1 for oblique fonts (italic), or 0 for normal angle. + * + * + * + * %stylehint_Proportional + * 1 for proportional-width fonts, or 0 for fixed-width. + * + * + * + * %stylehint_TextColor, %stylehint_BackColor + * These are values from 0x00000000 to 0x00FFFFFF, encoded as + * described in Suggesting the + * Appearance of Styles. + * + * + * %stylehint_ReverseColor + * 0 for normal printing, 1 if the foreground and background + * colors are reversed. + * + * + * * 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; } -- 2.30.2