[at-spi2-core] Add error-message, error-for, details, and details-for relation types

[Joanmarie Diggs <joanied src gnome org>]

commit 504e6d0ddaf1f3e5fd1c751acc822d51dfccfbb4
Author: Joanmarie Diggs <jdiggs igalia com>
Date:   Tue May 23 18:50:48 2017 +0200

    Add error-message, error-for, details, and details-for relation types
    
    Also update documentation of description-for and described-by relation
    types to help clarify which relation type is most suitable for each of
    the accessible descriptions.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=782999

 atspi/atspi-constants.h                |   47 +++++++++++++++++++++++++++-----
 doc/libatspi/tmpl/atspi-constants.sgml |    4 +++
 2 files changed, 44 insertions(+), 7 deletions(-)
---
diff --git a/atspi/atspi-constants.h b/atspi/atspi-constants.h
index b1c9eb5..1af391d 100644
--- a/atspi/atspi-constants.h
+++ b/atspi/atspi-constants.h
@@ -811,12 +811,41 @@ typedef enum {
  * @ATSPI_ROLE_FRAME object may still be the active window.
  * @ATSPI_RELATION_PARENT_WINDOW_OF: This is the reciprocal relation to
  * @ATSPI_RELATION_POPUP_FOR.
- * @ATSPI_RELATION_DESCRIPTION_FOR: Indicates that an object provides
- * descriptive information about another object; more verbose than
- * @ATSPI_RELATION_LABEL_FOR.
- * @ATSPI_RELATION_DESCRIBED_BY: Indicates that another object provides
- * descriptive information about this object; more verbose than
- * @ATSPI_RELATION_LABELLED_BY.
+ * @ATSPI_RELATION_DESCRIBED_BY: Reciprocal of %ATSPI_RELATION_DESCRIPTION_FOR.
+ * Indicates that one or more target objects provide descriptive information
+ * about this object. This relation type is most appropriate for information
+ * that is not essential as its presentation may be user-configurable and/or
+ * limited to an on-demand mechanism such as an assistive technology command.
+ * For brief, essential information such as can be found in a widget's on-screen
+ * label, use %ATSPI_RELATION_LABELLED_BY. For an on-screen error message, use
+ * %ATSPI_RELATION_ERROR_MESSAGE. For lengthy extended descriptive information
+ * contained in an on-screen object, consider using %ATSPI_RELATION_DETAILS as
+ * assistive technologies may provide a means for the user to navigate to
+ * objects containing detailed descriptions so that their content can be more
+ * closely reviewed.
+ * @ATSPI_RELATION_DESCRIPTION_FOR: Reciprocal of %ATSPI_RELATION_DESCRIBED_BY.
+ * Indicates that this object provides descriptive information about the target
+ * object(s). See also %ATSPI_RELATION_DETAILS_FOR and %ATSPI_RELATION_ERROR_FOR.
+ * @ATSPI_RELATION_DETAILS: Reciprocal of %ATSPI_RELATION_DETAILS_FOR. Indicates
+ * that this object has a detailed or extended description, the contents of
+ * which can be found in the target object(s). This relation type is most
+ * appropriate for information that is sufficiently lengthy as to make
+ * navigation to the container of that information desirable. For less verbose
+ * information suitable for announcement only, see %ATSPI_RELATION_DESCRIBED_BY.
+ * If the detailed information describes an error condition,
+ * %ATSPI_RELATION_ERROR_FOR should be used instead. @Since: 2.26.
+ * @ATSPI_RELATION_DETAILS_FOR: Reciprocal of %ATSPI_RELATION_DETAILS. Indicates
+ * that this object provides a detailed or extended description about the target
+ * object(s). See also %ATSPI_RELATION_DESCRIPTION_FOR and
+ * %ATSPI_RELATION_ERROR_FOR. @Since: 2.26.
+ * @ATSPI_RELATION_ERROR_MESSAGE: Reciprocal of %ATSPI_RELATION_ERROR_FOR.
+ * Indicates that this object has one or more errors, the nature of which is
+ * described in the contents of the target object(s). Objects that have this
+ * relation type should also contain %ATSPI_STATE_INVALID_ENTRY in their
+ * #AtspiStateSet. @Since: 2.26.
+ * @ATSPI_RELATION_ERROR_FOR: Reciprocal of %ATSPI_RELATION_ERROR_MESSAGE.
+ * Indicates that this object contains an error message describing an invalid
+ * condition in the target object(s). @Since: 2.26.
  * @ATSPI_RELATION_LAST_DEFINED: Do not use as a parameter value, used to
  * determine the size of the enumeration. 
  *
@@ -860,6 +889,10 @@ typedef enum {
     ATSPI_RELATION_PARENT_WINDOW_OF,
     ATSPI_RELATION_DESCRIPTION_FOR,
     ATSPI_RELATION_DESCRIBED_BY,
+    ATSPI_RELATION_DETAILS,
+    ATSPI_RELATION_DETAILS_FOR,
+    ATSPI_RELATION_ERROR_MESSAGE,
+    ATSPI_RELATION_ERROR_FOR,
     ATSPI_RELATION_LAST_DEFINED,
 } AtspiRelationType;
 
@@ -868,7 +901,7 @@ typedef enum {
  *
  * One higher than the highest valid value of #AtspiRelationType.
  **/
-#define ATSPI_RELATIONTYPE_COUNT (19+1)
+#define ATSPI_RELATIONTYPE_COUNT (23+1)
 
 /**
  * AtspiRole:
diff --git a/doc/libatspi/tmpl/atspi-constants.sgml b/doc/libatspi/tmpl/atspi-constants.sgml
index c16f685..8763873 100644
--- a/doc/libatspi/tmpl/atspi-constants.sgml
+++ b/doc/libatspi/tmpl/atspi-constants.sgml
@@ -323,6 +323,10 @@ Constant definitions needed by multiple interfaces.
 @ATSPI_RELATION_PARENT_WINDOW_OF: 
 @ATSPI_RELATION_DESCRIPTION_FOR: 
 @ATSPI_RELATION_DESCRIBED_BY: 
+@ATSPI_RELATION_DETAILS:
+@ATSPI_RELATION_DETAILS_FOR:
+@ATSPI_RELATION_ERROR_MESSAGE:
+@ATSPI_RELATION_ERROR_FOR:
 @ATSPI_RELATION_LAST_DEFINED: 
 
 <!-- ##### MACRO ATSPI_RELATIONTYPE_COUNT ##### -->