From 0035771513d5c47d963858ef3f31da3ac28f7fc2 Mon Sep 17 00:00:00 2001
From: Philip Chimento <philip.chimento@gmail.com>
Date: Tue, 9 Feb 2010 21:56:35 +0000
Subject: [PATCH] Brought documentation up to date

git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@225 ddfedd41-794f-dd11-ae45-00112f111e67
---
 docs/reference/chimara-docs.sgml |   8 +-
 libchimara/doc.c                 | 284 +++++++++++++++++++++++++++----
 libchimara/graphics.c            | 133 ++++++++++++++-
 libchimara/mouse.c               |  12 ++
 4 files changed, 399 insertions(+), 38 deletions(-)

diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml
index 422118c..8f5c73f 100644
--- a/docs/reference/chimara-docs.sgml
+++ b/docs/reference/chimara-docs.sgml
@@ -69,7 +69,7 @@
       <xi:include href="xml/glk-events.xml"/>
       <xi:include href="xml/glk-character-input-events.xml"/>
       <xi:include href="xml/glk-line-input-events.xml"/>
-      <!--<xi:include href="xml/glk-mouse-events.xml"/>-->
+      <xi:include href="xml/glk-mouse-events.xml"/>
       <xi:include href="xml/glk-timer-events.xml"/>
       <xi:include href="xml/glk-other-events.sgml"/>
 	</chapter>
@@ -98,14 +98,14 @@
     </chapter>
     
     <!-- Chapter 7. Graphics -->
-<!--    <chapter>
+    <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>
--->    
+    
     <!-- Chapter 8. Sound -->
 <!--    <chapter>
       <title>Sound</title>
diff --git a/libchimara/doc.c b/libchimara/doc.c
index a3c3ead..0f00da9 100644
--- a/libchimara/doc.c
+++ b/libchimara/doc.c
@@ -482,6 +482,57 @@
  * 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 &mdash; 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
@@ -840,6 +891,92 @@
  * 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 &mdash; 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 &mdash; 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 &mdash; 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-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-creating-hyperlinks
  * @short_description: Printing text as a hyperlink
@@ -1028,6 +1165,35 @@
  * 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_HYPERLINKS:
  * 
@@ -1196,39 +1362,17 @@
  */
 
 /**
- * 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:
- * |[
- * 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. 
- */
-
+ * 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:
  *
@@ -1237,6 +1381,35 @@
  * 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_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.
+ * 
+ * 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:
+ * 
+ * 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_Hyperlinks:
  *
@@ -1264,6 +1437,53 @@
  * glk_request_hyperlink_event(), but they will have no effect, and you will
  * never get hyperlink events.
  */
+
+/**
+ * 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:
diff --git a/libchimara/graphics.c b/libchimara/graphics.c
index 2b2258d..12a42b2 100644
--- a/libchimara/graphics.c
+++ b/libchimara/graphics.c
@@ -169,6 +169,32 @@ image_cache_find(struct image_info* to_find)
 	return NULL; /* No match found */
 }
 
+/**
+ * glk_image_get_info:
+ * @image: An image resource number.
+ * @width: Pointer to a location at which to store the image's width.
+ * @height: Pointer to a location at which to store the image's height.
+ *
+ * This gets information about the image resource with the given identifier. It
+ * returns %TRUE if there is such an image, and %FALSE if not. You can also pass
+ * pointers to width and height variables; if the image exists, the variables
+ * will be filled in with the width and height of the image, in pixels. (You can
+ * pass %NULL for either width or height if you don't care about that 
+ * information.)
+ * 
+ * <note><para>
+ *   You should always use this function to measure the size of images when you 
+ *   are creating your display. Do this even if you created the images, and you
+ *   know how big they <quote>should</quote> be. This is because images may be 
+ *   scaled in translating from one platform to another, or even from one 
+ *   machine to another. A Glk library might display all images larger than 
+ *   their original size, because of screen resolution or player preference. 
+ *   Images will be scaled proportionally, but you still need to call 
+ *   glk_image_get_info() to determine their absolute size.
+ * </para></note>
+ * 
+ * Returns: %TRUE if @image is a valid identifier, %FALSE if not.
+ */
 glui32
 glk_image_get_info(glui32 image, glui32 *width, glui32 *height)
 {
@@ -190,6 +216,34 @@ glk_image_get_info(glui32 image, glui32 *width, glui32 *height)
 	return TRUE;
 }
 
+/**
+ * glk_image_draw:
+ * @win: A graphics or text buffer window.
+ * @image: An image resource number.
+ * @val1: The x coordinate at which to draw the image (if @win is a graphics 
+ * window); or, an <link linkend="chimara-imagealign-InlineUp">image 
+ * alignment</link> constant (if @win is a text window).
+ * @val2: The y coordinate at which to draw the image (if @win is a graphics
+ * window); this parameter is ignored if @win is a text buffer window.
+ *
+ * This draws the given image resource in the given window. The position of the
+ * image is given by @val1 and @val2, but their meaning varies depending on what
+ * kind of window you are drawing in. See <link 
+ * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics 
+ * Windows</link> and <link linkend="Graphics-in-Text-Buffer-Windows">Graphics 
+ * in Text Buffer Windows</link>.
+ * 
+ * This function returns a flag indicating whether the drawing operation 
+ * succeeded.
+ * <note><para>
+ *   A %FALSE result can occur for many reasons. The image data might be 
+ *   corrupted; the library may not have enough memory to operate; there may be 
+ *   no image with the given identifier; the window might not support image 
+ *   display; and so on.
+ * </para></note>
+ *
+ * Returns: %TRUE if the operation succeeded, %FALSE if not.
+ */
 glui32
 glk_image_draw(winid_t win, glui32 image, glsi32 val1, glsi32 val2)
 {
@@ -228,7 +282,29 @@ glk_image_draw(winid_t win, glui32 image, glsi32 val1, glsi32 val2)
 	return TRUE;
 }
 
-
+/**
+ * glk_image_draw_scaled:
+ * @win: A graphics or text buffer window.
+ * @image: An image resource number.
+ * @val1: The x coordinate at which to draw the image (if @win is a graphics 
+ * window); or, an <link linkend="chimara-imagealign-InlineUp">image 
+ * alignment</link> constant (if @win is a text window).
+ * @val2: The y coordinate at which to draw the image (if @win is a graphics
+ * window); this parameter is ignored if @win is a text buffer window.
+ * @width: The width of the image.
+ * @height: The height of the image.
+ *
+ * This is similar to glk_image_draw(), but it scales the image to the given 
+ * @width and @height, instead of using the image's standard size. (You can 
+ * measure the standard size with glk_image_get_info().)
+ * 
+ * If @width or @height is zero, nothing is drawn. Since those arguments are 
+ * unsigned integers, they cannot be negative. If you pass in a negative number,
+ * it will be interpreted as a very large positive number, which is almost 
+ * certain to end badly. 
+ *
+ * Returns: %TRUE if the operation succeeded, %FALSE otherwise.
+ */
 glui32
 glk_image_draw_scaled(winid_t win, glui32 image, glsi32 val1, glsi32 val2, glui32 width, glui32 height)
 {
@@ -286,11 +362,51 @@ glk_image_draw_scaled(winid_t win, glui32 image, glsi32 val1, glsi32 val2, glui3
 	return TRUE;
 }
 
+/**
+ * glk_window_set_background_color:
+ * @win: A graphics window.
+ * @color: a 32-bit RGB color value.
+ *
+ * This sets the window's background color. It does not change what is currently
+ * displayed; it only affects subsequent clears and resizes. The initial 
+ * background color of each window is white.
+ * 
+ * Colors are encoded in a 32-bit value: the top 8 bits must be zero, the next 8
+ * bits are the red value, the next 8 bits are the green value, and the bottom 8
+ * bits are the blue value. Color values range from 0 to 255.
+ * <note><para>
+ *   So <code>0x00000000</code> is black, <code>0x00FFFFFF</code> is white, and 
+ *   <code>0x00FF0000</code> is bright red.
+ * </para></note>
+ * 
+ * <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>.
+ * </para></note>
+ */
 void
-glk_window_set_background_color(winid_t win, glui32 color) {
+glk_window_set_background_color(winid_t win, glui32 color) 
+{
+	VALID_WINDOW(win, return);
+	g_return_if_fail(win->type == wintype_Graphics);
+	
 	win->background_color = color;
 }
 
+/**
+ * glk_window_fill_rect:
+ * @win: A graphics window.
+ * @color: A 32-bit RGB color value, see glk_window_set_background_color().
+ * @left: The x coordinate of the top left corner of the rectangle.
+ * @top: The y coordinate of the top left corner of the rectangle.
+ * @width: The width of the rectangle.
+ * @height: The height of the rectangle.
+ *
+ * This fills the given rectangle with the given color. It is legitimate for
+ * part of the rectangle to fall outside the window. If width or height is zero,
+ * nothing is drawn. 
+ */
 void
 glk_window_fill_rect(winid_t win, glui32 color, glsi32 left, glsi32 top, glui32 width, glui32 height)
 {
@@ -308,6 +424,19 @@ glk_window_fill_rect(winid_t win, glui32 color, glsi32 left, glsi32 top, glui32
 	gdk_threads_leave();
 }
 
+/**
+ * glk_window_erase_rect:
+ * @win: A graphics window.
+ * @left: The x coordinate of the top left corner of the rectangle.
+ * @top: The y coordinate of the top left corner of the rectangle.
+ * @width: The width of the rectangle.
+ * @height: The height of the rectangle.
+ *
+ * This fills the given rectangle with the window's background color.
+ * 
+ * You can also fill an entire graphics window with its background color by 
+ * calling glk_window_clear().
+ */
 void
 glk_window_erase_rect(winid_t win, glsi32 left, glsi32 top, glui32 width, glui32 height)
 {
diff --git a/libchimara/mouse.c b/libchimara/mouse.c
index 3fd464f..1f54b5c 100644
--- a/libchimara/mouse.c
+++ b/libchimara/mouse.c
@@ -1,6 +1,12 @@
 #include "mouse.h"
 #include "magic.h"
 
+/**
+ * glk_request_mouse_event:
+ * @win: Window on which to request a mouse input event.
+ *
+ * Requests mouse input on the window @win.
+ */
 void
 glk_request_mouse_event(winid_t win)
 {
@@ -11,6 +17,12 @@ glk_request_mouse_event(winid_t win)
 	g_signal_handler_unblock(win->widget, win->button_press_event_handler);
 }
 
+/**
+ * glk_cancel_mouse_event:
+ * @win: Window with a mouse input event pending.
+ *
+ * Cancels the pending mouse input request on @win.
+ */
 void 
 glk_cancel_mouse_event(winid_t win)
 {
-- 
2.30.2