Update libatspi documentation to indicate that extents are only meaningful

when an object has both STATE_VISIBLE and STATE_SHOWING.

Corresponds to merge request GNOME/at-spi2-core!8

5 files changed, 28 insertions, 0 deletions

diff --git a/atspi/atspi-component.c b/atspi/atspi-component.c
index ed225821..d6873efc 100644
--- a/atspi/atspi-component.c
+++ b/atspi/atspi-component.c
@@ -129,6 +129,8 @@ atspi_component_get_accessible_at_point (AtspiComponent *obj,
  *         (e.g. ATSPI_COORD_TYPE_WINDOW, ATSPI_COORD_TYPE_SCREEN).
  *
  * Gets the bounding box of the specified #AtspiComponent.
+ * The returned values are meaningful only if the Component has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: An #AtspiRect giving the accessible's extents.
  **/
@@ -164,6 +166,8 @@ atspi_component_get_extents (AtspiComponent *obj,
  *         (e.g. ATSPI_COORD_TYPE_WINDOW, ATSPI_COORD_TYPE_SCREEN).
  *
  * Gets the minimum x and y coordinates of the specified #AtspiComponent.
+ * The returned values are meaningful only if the Component has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * returns: An #AtspiPoint giving the @obj's position.
  **/
@@ -192,6 +196,8 @@ atspi_component_get_position (AtspiComponent *obj,
  * @obj: a pointer to the #AtspiComponent to query.
  *
  * Gets the size of the specified #AtspiComponent.
+ * The returned values are meaningful only if the Component has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * returns: An #AtspiPoint giving the @obj's size.
  **/
diff --git a/atspi/atspi-image.c b/atspi/atspi-image.c
index 4f173269..2ede1076 100644
--- a/atspi/atspi-image.c
+++ b/atspi/atspi-image.c
@@ -49,6 +49,8 @@ atspi_image_get_image_description (AtspiImage *obj, GError **error)
  * @obj: a pointer to the #AtspiImage to query.
  *
  * Gets the size of the image displayed in a specified #AtspiImage object.
+ * The returned values are meaningful only if the Image has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: a pointer to an #AtspiPoint where x corresponds to
  * the image's width and y corresponds to the image's height.
@@ -78,6 +80,8 @@ atspi_image_get_image_size (AtspiImage *obj, GError **error)
  *
  * Gets the minimum x and y coordinates of the image displayed in a
  *         specified #AtspiImage implementor.
+ * The returned values are meaningful only if the Image has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: a pointer to an #AtspiPoint where x and y correspond to the
  * minimum coordinates of the displayed image. 
@@ -112,6 +116,8 @@ atspi_image_get_image_position (AtspiImage *obj,
  *
  * Gets the bounding box of the image displayed in a
  *         specified #AtspiImage implementor.
+ * The returned values are meaningful only if the Image has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: a pointer to an #AtspiRect corresponding to the image's bounding box. The minimum x and y coordinates, 
  * width, and height are specified.
diff --git a/atspi/atspi-table-cell.c b/atspi/atspi-table-cell.c
index 13203bf6..3a475655 100644
--- a/atspi/atspi-table-cell.c
+++ b/atspi/atspi-table-cell.c
@@ -58,6 +58,8 @@ get_object_array_and_unref (DBusMessage *reply)
  * @obj: a GObject instance that implements AtspiTableCellIface
  *
  * Returns the number of columns occupied by this cell accessible.
+ * The returned values are meaningful only if the table cell has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: a gint representing the number of columns occupied by this cell,
  * or 0 if the cell does not implement this method.
@@ -101,6 +103,8 @@ atspi_table_cell_get_column_header_cells (AtspiTableCell *obj, GError **error)
  * @obj: a GObject instance that implements AtspiTableCellIface
  *
  * Returns the number of rows occupied by this cell accessible.
+ * The returned values are meaningful only if the table cell has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: a gint representing the number of rows occupied by this cell,
  * or 0 if the cell does not implement this method.
@@ -206,6 +210,8 @@ atspi_table_cell_get_position (AtspiTableCell *obj,
  * @column_span: (out): the number of columns occupied by this cell.
  *
  * Gets the row and column indexes and extents of this cell accessible.
+ * The returned values are meaningful only if the table cell has both
+ * STATE_VISIBLE and STATE_SHOWING.
  */
 void
 atspi_table_cell_get_row_column_span (AtspiTableCell *obj,
diff --git a/atspi/atspi-table.c b/atspi/atspi-table.c
index b17e2f1c..54db9603 100644
--- a/atspi/atspi-table.c
+++ b/atspi/atspi-table.c
@@ -285,6 +285,8 @@ atspi_table_get_column_description (AtspiTable *obj,
  * Gets the number of rows spanned by the table cell at the specific row
  * and column. (some tables can have cells which span multiple rows
  * and/or columns).
+ * The returned values are meaningful only if the Table has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: a #gint indicating the number of rows spanned by the specified cell.
  **/
@@ -313,6 +315,8 @@ atspi_table_get_row_extent_at (AtspiTable *obj,
  * Gets the number of columns spanned by the table cell at the specific
  * row and column (some tables can have cells which span multiple
  * rows and/or columns).
+ * The returned values are meaningful only if the Table has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: a #gint indicating the number of columns spanned by the specified cell.
  **/
@@ -646,6 +650,8 @@ atspi_table_remove_column_selection (AtspiTable *obj,
  * extents, and whether the cell is currently selected.  If
  * the child at index is not a cell (for instance, if it is 
  * a summary, caption, etc.), #FALSE is returned.
+ * The returned values are meaningful only if the Table has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Example:
  * If the #AtspiTable child at index '6' extends across columns 5 and 6 of
diff --git a/atspi/atspi-text.c b/atspi/atspi-text.c
index 009d07bf..a360f56c 100644
--- a/atspi/atspi-text.c
+++ b/atspi/atspi-text.c
@@ -618,6 +618,8 @@ atspi_text_get_character_at_offset (AtspiText *obj,
  *
  * Gets a bounding box containing the glyph representing
  *        the character at a particular text offset.
+ * The returned values are meaningful only if the Text has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: An #AtspiRect specifying the position and size of the character.
  *
@@ -690,6 +692,8 @@ atspi_text_get_offset_at_point (AtspiText *obj,
  *        for the returned values.
  *
  * Gets the bounding box for text within a range in an  #AtspiText object.
+ * The returned values are meaningful only if the Text has both
+ * STATE_VISIBLE and STATE_SHOWING.
  *
  * Returns: An #AtspiRect giving the position and size of the specified range
  *          of text.