[at-spi2-core: 1/2] Document that extents are only meaningful when accessible is both visible and showing

[Mike Gorse <mgorse src gnome org>]

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

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

 idl/component.didl |  3 +++
 idl/image.didl     | 15 ++++++++++++---
 idl/table.didl     |  4 ++++
 idl/text.didl      |  2 ++
 4 files changed, 21 insertions(+), 3 deletions(-)
---
diff --git a/idl/component.didl b/idl/component.didl
index 31cfbf0..76b2fa3 100644
--- a/idl/component.didl
+++ b/idl/component.didl
@@ -102,6 +102,7 @@ interface org.freestandards.atspi.Component {
 
        /*
          Obtain the components 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.
        */
        method GetExtents {
                CoordType cood_type;
@@ -111,6 +112,7 @@ interface org.freestandards.atspi.Component {
 
        /*
          Obtain the position of the current component in the specified coordinate system.
+          The returned values are meaningful only if the Component has both STATE_VISIBLE and STATE_SHOWING.
        */
        method GetPosition {
                CoordType coord_type;
@@ -122,6 +124,7 @@ interface org.freestandards.atspi.Component {
        /*
          Obtain the size in the specified coordinate system.
           Fully contains teh 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.
         */
        method GetSize reply {
                int32 width;
diff --git a/idl/image.didl b/idl/image.didl
index 9dee626..7222da3 100644
--- a/idl/image.didl
+++ b/idl/image.didl
@@ -10,14 +10,20 @@ interface org.freestandards.atspi.Image {
        /* A string corresponding to the local used by the image description. */
        read property string ImageLocale;
 
-       /* Obtain a bounding box which entirely contains the image contents. */
+       /*
+         Obtain a bounding box which entirely contains the image contents.
+         The returned values are meaningful only if the Image has both STATE_VISIBLE and STATE_SHOWING.
+        */
        method GetImageExtents {
                CoordType coord_type;
        } reply {
                BoundingBox;
        }
 
-       /* Get the coordinates of the image on the screen */
+       /*
+         Get the coordinates of the image on the screen
+         The returned values are meaningful only if the Image has both STATE_VISIBLE and STATE_SHOWING.
+        */
        method GetImagePosition {
                CoordType coord_type;
        } reply {
@@ -25,7 +31,10 @@ interface org.freestandards.atspi.Image {
                int32 y;
        }
 
-       /* Get the size of the current on-screen view of the image. */
+       /*
+         Get the size of the current on-screen view of the image.
+         The returned values are meaningful only if the Image has both STATE_VISIBLE and STATE_SHOWING.
+        */
        method GetImageSize reply {
                int32 width;
                int32 height;
diff --git a/idl/table.didl b/idl/table.didl
index ae1b8f0..5ecd491 100644
--- a/idl/table.didl
+++ b/idl/table.didl
@@ -76,6 +76,8 @@ namespace org.freestandards.atspi {
 
                /*
                  Get the number of rows spanned by the table cell at the specific row and column.
+                 The returned values are meaningful only if the Table has both STATE_VISIBLE and 
STATE_SHOWING.
+                */
                method GetRowExtentAt {
                        int32 row;
                        int32 column;
@@ -85,6 +87,7 @@ namespace org.freestandards.atspi {
 
                /*
                  Get the number of columns spanned by the table cell at the specific row and column.
+                 The returned values are meaningful only if the Table has both STATE_VISIBLE and 
STATE_SHOWING.
                 */
                method GetColumnExtentAt {
                        int32 row;
@@ -171,6 +174,7 @@ namespace org.freestandards.atspi {
                /*
                  Given a child index determine the row and column indicies and extents
                  and whether the cell is currently selected.
+                 The returned values are meaningful only if the Table has both STATE_VISIBLE and 
STATE_SHOWING.
                 */
                method GetRowColumnExtentsAtIndex {
                        int32 index;
diff --git a/idl/text.didl b/idl/text.didl
index d5ae66c..e59ea80 100644
--- a/idl/text.didl
+++ b/idl/text.didl
@@ -129,6 +129,7 @@ namespace org.freestandards.atspi {
                /*
                  Obtain a bounding box of the character glyph at a particular character offset,
                  in the given coordinate system.
+                 The returned values are meaningful only if the Text has both STATE_VISIBLE and 
STATE_SHOWING.
                 */
                method GetCharacterExtents {
                        int32     offset;
@@ -192,6 +193,7 @@ namespace org.freestandards.atspi {
                  Obtain the bounding box which entirely contains the given text range.
                  Negative values may be obtained in the event that part of the text range is
                  off-screen.
+                 The returned values are meaningful only if the Text has both STATE_VISIBLE and 
STATE_SHOWING.
                 */
                method GetRangeExtents {
                        int32 start_offset;