[pyatspi2: 1/2] Document that extents are only meaningful when accessible is both visible and showing

[Mike Gorse <mgorse src gnome org>]

commit f7cc9f907320ff1cd133c13140fd23137d40d9eb
Author: Samuel Thibault <samuel thibault ens-lyon org>
Date:   Mon Feb 11 17:46:44 2019 +0100

    Document that extents are only meaningful when accessible is both visible and showing

 pyatspi/component.py | 6 ++++++
 pyatspi/image.py     | 6 ++++++
 pyatspi/table.py     | 6 ++++++
 pyatspi/text.py      | 4 ++++
 4 files changed, 22 insertions(+)
---
diff --git a/pyatspi/component.py b/pyatspi/component.py
index 63ea849..4dd9552 100644
--- a/pyatspi/component.py
+++ b/pyatspi/component.py
@@ -145,6 +145,8 @@ class Component(interface):
                 """
                 Obtain the Component's bounding box, in pixels, relative to the
                 specified coordinate system. 
+                The returned values are meaningful only if the Component has
+                both STATE_VISIBLE and STATE_SHOWING.
                 @param coord_type
                 @return a BoundingBox which entirely contains the object's onscreen
                 visual representation.
@@ -172,6 +174,8 @@ class Component(interface):
                 """
                 Obtain the position of the current component in the coordinate
                 system specified by coord_type. 
+                The returned values are meaningful only if the Component has
+                both STATE_VISIBLE and STATE_SHOWING.
                 @param : coord_type
                 @param : x
                 an out parameter which will be back-filled with the returned
@@ -187,6 +191,8 @@ class Component(interface):
                 Obtain the size, in the coordinate system specified by coord_type,
                 of the rectangular area which fully contains the object's visual
                 representation, without accounting for viewport clipping. 
+                The returned values are meaningful only if the Component has
+                both STATE_VISIBLE and STATE_SHOWING.
                 @param : width
                 the object's horizontal extents in the specified coordinate system.
                 @param : height
diff --git a/pyatspi/image.py b/pyatspi/image.py
index 38d8a73..dd8d207 100644
--- a/pyatspi/image.py
+++ b/pyatspi/image.py
@@ -43,6 +43,8 @@ class Image:
                 as displayed on screen. The bounds returned do not account for
                 any viewport clipping or the fact that the image may be partially
                 or wholly obscured by other onscreen content. 
+                The returned values are meaningful only if the Image has
+                both STATE_VISIBLE and STATE_SHOWING.
                 @param : coordType
                 If 0, the returned bounding box position is returned relative
                 to the screen; if 1, the bounding box position is returned relative
@@ -54,6 +56,8 @@ class Image:
         def getImagePosition(self, coord_type):
                 """
                 Get the coordinates of the current image position on screen.
+                The returned values are meaningful only if the Image has
+                both STATE_VISIBLE and STATE_SHOWING.
                 @param : x
                 Back-filled with the x coordinate of the onscreen image (i.e.
                 the minimum x coordinate) 
@@ -73,6 +77,8 @@ class Image:
                 image. The extents returned do not account for any viewport clipping
                 or the fact that the image may be partially or wholly obscured
                 by other onscreen content. 
+                The returned values are meaningful only if the Image has
+                both STATE_VISIBLE and STATE_SHOWING.
                 @param : width
                 Back-filled with the x extents of the onscreen image (i.e. the
                 image width in pixels) 
diff --git a/pyatspi/table.py b/pyatspi/table.py
index f676aa1..4313aa8 100644
--- a/pyatspi/table.py
+++ b/pyatspi/table.py
@@ -98,6 +98,8 @@ class Table(interface):
                 Get 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.
                 @param : row
                 the specified table row, zero-indexed. 
                 @param : column
@@ -149,6 +151,8 @@ class Table(interface):
                 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.
                 @param : index
                 the index of the Table child whose row/column extents are requested.
                 @param : row
@@ -197,6 +201,8 @@ class Table(interface):
                 Get 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.
                 @param : row
                 the specified table row, zero-indexed. 
                 @param : column
diff --git a/pyatspi/text.py b/pyatspi/text.py
index 837e3c1..4cc2124 100644
--- a/pyatspi/text.py
+++ b/pyatspi/text.py
@@ -274,6 +274,8 @@ class Text(interface):
                 to multiple character offsets, for instance if the glyph is a
                 ligature, the bounding box reported will include the entire glyph
                 and therefore may apply to more than one character offset. 
+                The returned values are meaningful only if the Text has
+                both STATE_VISIBLE and STATE_SHOWING.
                 @param : offset
                 the character offset of the character or glyph being queried.
                 @param : coordType
@@ -349,6 +351,8 @@ class Text(interface):
                 range. Negative values may be returned for the bounding box parameters
                 in the event that all or part of the text range is offscreen
                 or not mapped to the screen. 
+                The returned values are meaningful only if the Text has
+                both STATE_VISIBLE and STATE_SHOWING.
                 @param : startOffset
                 the offset of the first character in the specified range. 
                 @param : endOffset