Updates from 20080918.

api/AccessibleEventId.idl

@@ -36,12 +36,24 @@ enum IA2EventID {
   */
   IA2_EVENT_ACTION_CHANGED = 0x101,
 
-  /** The active descendant of a component has changed.  The active descendant 
-    is used in objects with transient children.
+  /** The active descendant of a component has changed.
+
+	Note: This event constant is misspelled and thus is deprecated and will be
+	removed in a later version. Please use the correctly spelled version which
+	follows.
   */
   IA2_EVENT_ACTIVE_DECENDENT_CHANGED,
 
-  /** Alternative constant with correct spelling.
+  /** The active descendant of a component has changed.  The active descendant 
+    is used in objects with transient children.  
+
+    Note: Due to the fact that MSAA's WinEvents don't allow the active child index
+	to be passed on the IA2_EVENT_ACTIVE_DESCENDANT_CHANGED event the manages
+	descendants	scheme can't be used.  Instead the active child object has to fire
+	MSAA's EVENT_OBJECT_FOCUS.  In a future release a new event mechanism may be
+	added to provide for event specific data to be passed with the event.  At that
+	time the IA2_EVENT_ACTIVE_DECENDENT_CHANGED event and
+	IA2_STATE_MANAGES_DESCENDANTS state would be useful.
   */
   IA2_EVENT_ACTIVE_DESCENDANT_CHANGED = IA2_EVENT_ACTIVE_DECENDENT_CHANGED,
 

api/AccessibleRelation.idl

@@ -64,9 +64,15 @@ const WCHAR *const IA2_RELATION_FLOWS_TO = L"flowsTo";
 /** This object is label for a target object. */
 const WCHAR *const IA2_RELATION_LABEL_FOR = L"labelFor";
 
-/** This object is labelled by a target object. */
+/** This object is labelled by a target object. Note that the double L spelling
+ which follows is preferred.  Please use it instead.  This single L version may
+ be removed in a later version.
+*/
 const WCHAR *const IA2_RELATION_LABELED_BY = L"labelledBy";
 
+/** This object is labelled by a target object. */
+const WCHAR *const IA2_RELATION_LABELLED_BY = L"labelledBy";
+
 /** This object is a member of a group of one or more objects. When 
  there is more than one object in the group each member may have one and the 
  same target, e.g. a grouping object.  It is also possible that each member has 

api/AccessibleStates.idl

@@ -43,7 +43,9 @@ enum IA2States {
   the item that will get focus if you tab to the container.
 
  This information is important for knowing what to report for trees and potentially 
-  other containers in a virtual buffer. 
+  other containers in a virtual buffer.
+
+ Also, see ::IA2_STATE_MANAGES_DESCENDANTS for more information.
 */
 IA2_STATE_ACTIVE =					0x1,
 
@@ -77,13 +79,13 @@ IA2_STATE_INVALID_ENTRY =			0x40,
 
 /** Indicates that this object manages its children.
 
- Used when children are transient.  In this case it is not necessary to add
-  listeners to the children.
-
- The state is added to improve performance in the case of large containers such 
-  as tables. When an object manages its children it is not necessary to iterate 
-  over all the children and add listeners.  The parent object will provide state 
-  notifications regarding the state of its children.
+ Note: Due to the fact that MSAA's WinEvents don't allow the active child index
+  to be passed on the IA2_EVENT_ACTIVE_DESCENDANT_CHANGED event, the manages
+  descendants	scheme can't be used.  Instead the active child object has to fire
+  MSAA's EVENT_OBJECT_FOCUS.  In a future release a new event mechanism may be
+  added to provide for event specific data to be passed with the event.  At that
+  time the IA2_EVENT_ACTIVE_DECENDENT_CHANGED event and
+  IA2_STATE_MANAGES_DESCENDANTS state would be useful.
 */
 IA2_STATE_MANAGES_DESCENDANTS =		0x80,
 
@@ -143,6 +145,8 @@ IA2_STATE_SUPPORTS_AUTOCOMPLETION =	0x8000,
  result it is likely that this state is not of use to an assistive technology, but it 
  is provided in case an assistive technology determines that knowledge of the transient 
  nature of the object is useful and also for harmony with the Linux accessibility API.
+
+ Also, see ::IA2_STATE_MANAGES_DESCENDANTS for more information.
  */
 IA2_STATE_TRANSIENT =				0x10000,
 

api/AccessibleText.idl

@@ -301,8 +301,8 @@ interface IAccessibleText : IUnknown
    For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete 
     word that is closest to and located before offset is returned.
 
-   If the index is valid, but no suitable word (or other boundary type) is found, an 
-    empty text segment is returned.
+   If the index is valid, but no suitable word (or other boundary type) is found, a
+    NULL pointer is returned.
 
    @param [in] offset
     Index of the character for which to return the text part before it.  The index 
@@ -340,10 +340,10 @@ interface IAccessibleText : IUnknown
     index value.
 
    For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete 
-    word that is closest to and located before offset is returned.
+    word that is closest to and located after offset is returned.
 
-   If the index is valid, but no suitable word (or other text type) is found, an 
-    empty text segment is returned.
+   If the index is valid, but no suitable word (or other text type) is found, a 
+    NULL pointer is returned.
 
    @param [in] offset
     Index of the character for which to return the text part before it.  The index 
@@ -377,11 +377,8 @@ interface IAccessibleText : IUnknown
 
    Returns the substring of the specified text type at the specified offset.
 
-   For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete 
-    word that is closest to and located before offset is returned.
-
-   If the index is valid, but no suitable word (or other text type) is found, an 
-    empty text segment is returned.
+   If the index is valid, but no suitable word (or other text type) is found, a 
+    NULL pointer is returned.
 
    @param [in] offset
     Index of the character for which to return the text part before it.  The index 
@@ -440,6 +437,7 @@ interface IAccessibleText : IUnknown
     insertion goes before the first character.  An index of IAccessibleText::nCharacters 
 	leads to insertion after the last character.
    @retval S_OK
+   @retval E_FAIL if the caret cannot be set
    @retval E_INVALIDARG if bad [in] passed
   */
   HRESULT setCaretOffset

api/AccessibleValue.idl

@@ -95,7 +95,7 @@ interface IAccessibleValue : IUnknown
 
    @param [out] minimumValue
     Returns the minimal value in an implementation dependent type. If this object 
-    has no upper bound then an empty object is returned.  See the section about 
+    has no lower bound then an empty object is returned.  See the section about 
 	@ref _variants "VARIANTs" for additional information.
    @retval S_OK
   */

changelog.txt

@@ -1,4 +1,4 @@
-2008-August-07 Pete Brunet <[email protected]>
+2008-September-18 Pete Brunet <[email protected]>
 
 	* General comments
 	Added a comment to the following methods that the max size [in] parameter is not used.
@@ -64,6 +64,7 @@
 
 	* api\AccessibleEvent.idl
 	Added constant  IA2_EVENT_ACTIVE_DESCENDANT_CHANGED = IA2_EVENT_ACTIVE_DECENDENT_CHANGED
+	Noted that the managed descendant scheme is not implementable with the current WinEvents mechanism.
 	Added comments:
 	  IA2_EVENT_TEXT_SELECTION_CHANGED:
 	    Later versions of Microsoft dev environments have equivalent EVENT_OBJECT_TEXTSELECTIONCHANGED.
@@ -79,6 +80,7 @@
 
 	*api\AccessibleRelation.idl
 	targets method: renamed out parameter from target to targets
+	added constant with double L spelling for labelled by
 
 	* api\AccessibleStates.idl
 	Added comments:
@@ -91,7 +93,10 @@
 	    Used when the parent has state IA2_STATE_MANAGES_DESCENDANTS.
 	  IA2_STATE_ARMED:
 	     The condition a widget is in between when the mouse button is pressed but not yet rlelased.
-	Changed states from being constants to an enum; this helps those creating a typelib
+	Removed nonsense comments from A2_STATE_MANAGES_DESCENDANTS.
+	Changed states from being constants to an enum; this helps those creating a typelib.
+	Noted that the managed descendant scheme is not implementable with the current WinEvents mechanism.
+	  This scheme uses IA2_STATE_MANAGES_DESCENDANTS, IA2_STATE_ACTIVE, and IA2_STATE_TRANSIENT.
 
 	* api\AccessibleTable.idl
 	Added comments:
@@ -111,8 +116,9 @@
 
 	* api\AccessibleText.idl
 	Fixed comments:
-	  textAtOffset: removed nonsense sentence
-	  textAfterOffset: changed a word, "decreased" to "increased"
+	  textAtOffset: removed nonsense sentences
+	  textAfterOffset: changed words, "decreased" to "increased", "before" to "after"
+	  textAt/After/BeforeOffset: NULL, not "", is returned if there is nothing valid to return
 	  attributes: improved description of start/endOffset
 	Added comments:
 	  For all methods that take a start and end offset, E_FAIL is returned when:
@@ -124,10 +130,12 @@
 	  caretOffset, setCaretOffset: reworded to use logical order rather than left to right order
 	  IA2_TEXT_BOUNDARY_CHAR: added discussion of multichar fields, e.g. date
 	  caretOffset returns -1 if the caret is active on some other object
-	Added name to IA2TextSegment struct to help with creating a typelib
+	Added name to IA2TextSegment struct to help with creating a typelib.
+	Added E_FAIL to setCaretOffset
 
 	*api\AccessibleValue.idl
 	Added reference to General Information section on VARIANTs.
+	minimumValue: changed text from "upper" to "lower" bound.
 
 	* api\IA2CommonTypes.idl
 	Enhanced commentary for IA2_SCROLL_* enums