Updates from 20080807.

api/Accessible2.idl

@@ -98,7 +98,8 @@
  @ref _changingInterfaces\n
  @ref _applicationInfo\n
  @ref _childIDs\n
- @ref _variants
+ @ref _variants\n
+ @ref _iaaction-iahyperlink
 
  @section _errors Error Handling
   HRESULT values are defined by the Microsoft Win32 API.  For more information, refer to 
@@ -110,7 +111,8 @@
   but there was nothing valid to return, e.g. in IAccessilbe2::attributes when
   there are no attributes.  When S_FALSE is returned [out] pointer types should 
   be NULL and [out] longs should generally be 0, but sometimes -1 is used such
-  as IAccessible2::indexInParent and IAccessibleHypertext::hyperlinkIndex.
+  as IAccessible2::indexInParent, IAccessibleText::caretOffset, and
+  IAccessibleHypertext::hyperlinkIndex.
 
   Note that for BSTR [out] variables common COM practice is that the server does 
   the SysAllocString and the client does the SysFreeString.  Also note that when
@@ -269,6 +271,14 @@
   specified, i.e. VT_I4, VT_IDISPATCH, etc.  The methods that return VARIANTs are 
   IAccessibleHyperlink::anchor, IAccessibleHyperlink::anchorTarget, IAccessibleValue::currentValue,
   IAccessibleValue::maximumValue, IAccessibleValue::minimumValue.
+
+ @section _iaaction-iahyperlink IAccessibleHyperlink as subclass of IAccessibleAction
+  In this version of the IDL, IAccessibleHyperlink is a subclass of IAccessibleAction.  
+  However, there is no practical need for that inheritance and in some cases, such as
+  an image map of smart tags, it doesn't make sense because such an image map doesn't 
+  have actionable objects; it's the secondary smart tags that are actionable.  As a 
+  result, implementations should not rely on the inheritance as it may be removed in 
+  a later version of the IDL.
 **/
 
 import "objidl.idl";

api/AccessibleAction.idl

@@ -37,9 +37,10 @@ import "oleacc.idl";
   support the IAccessibleAction interface in order to provide Assistive Technology
   access to all the actions that can be performed by the object.  Each action can 
   be performed or queried for a name, description or associated key bindings.  
-  Actions are needed more for ATs that assist the mobility impaired.  By providing 
-  actions directly, the AT can present them to the user without the user having
-  to perform the extra steps to navigate a context menu.
+  Actions are needed more for ATs that assist the mobility impaired, such as
+  on-screen keyboards and voice command software.  By providing actions directly,
+  the AT can present them to the user without the user having to perform the extra
+  steps to navigate a context menu.
 
  The first action should be equivalent to the MSAA default action.  If there is 
   only one action, %IAccessibleAction should also be implemented.

api/AccessibleHyperlink.idl

@@ -48,13 +48,24 @@ import "AccessibleAction.idl";
  This interface provides access to a single object which can have multiple actions.
   An example is an image map which is an image with multiple links each of which is
   associated with a separate non-overlapping area of the image.  This interface could
-  also be applied to other kinds of objects with multiple actions.
+  also be applied to other kinds of objects with multiple actions such as "smart tags"
+  which are objects, typically strings, which have multiple actions such as
+  "Activate URI", "Bookmark URI", etc.
+
+ An interesting use case is an image map where each area is associated with multiple
+  actions, e.g. an image map of smart tags.  In this case you would have to implement
+  two levels of accessible hyperlinks.  The first level hyperlinks would only implement
+  anchor and anchorTarget.  The anchors would all reference the image object.  The
+  anchorTargets would reference the second level accessible hyperlink objects.  None
+  of the IAccessibleAction methods would be implemented on the first level hyperlink
+  objects.  The second level hyperlink objects would implement the IAccessibleAction
+  methods.  Their anchors would also reference the image object and their anchorTargets
+  would reference URLs or the objects that would be activated.
+
+ This use case demonstrates that in some cases there is no need for IAccessibleHyperlink
+  to derive from IAccessibleAction.  As a result it may be removed in a later version of
+  the IDL and it is suggested that implementations should not rely on the inheritance.
 
- An interesting use case to consider is an image map where each area of the image
-  is associated with multiple actions such as "Activate URI", "Bookmark URI", etc.
-  The typical UI implementation for this is to provide a means to activate a menu
-  listing multiple actions.  In this case the action associated with an area is to
-  activate a menu rather than activating a link as in the typical image map case.
 */
 [object, uuid(01C20F2B-3DD2-400f-949F-AD00BDAB1D41)]
 interface IAccessibleHyperlink : IAccessibleAction

api/AccessibleStates.idl

@@ -149,4 +149,4 @@ IA2_STATE_TRANSIENT =				0x10000,
 /** Indicates the orientation of this object is vertical. */
 IA2_STATE_VERTICAL =				0x20000
 
-}
+};

api/AccessibleText.idl

@@ -55,7 +55,13 @@ typedef struct IA2TextSegment {
 */
 
 enum IA2TextBoundaryType {
-  IA2_TEXT_BOUNDARY_CHAR,		///< A single character is returned 
+  IA2_TEXT_BOUNDARY_CHAR,		/**< Typically, a single character is returned.  In some cases more than
+								 one character is returned, for example, when a document contains field
+								 data such as a field containing a date, time, or footnote reference.
+								 In this case the caret can move over several characters in one movement
+								 of the caret.  Note that after the caret moves, the caret offset changes
+								 by the number of characters in the field, e.g. by 8 characters in the 
+								 following date: 03/26/07. */
   IA2_TEXT_BOUNDARY_WORD,		///< Range is from start of one word to the start of another word.
   IA2_TEXT_BOUNDARY_SENTENCE,	///< Range is from start of one sentence to the start of another sentence.
   IA2_TEXT_BOUNDARY_PARAGRAPH,	///< Range is from start of one paragraph to the start of another paragraph.
@@ -143,6 +149,8 @@ interface IAccessibleText : IUnknown
    @param [out] offset
     The returned offset is relative to the text represented by this object.
    @retval S_OK
+   @retval S_FALSE if the caret is not currently active on this object, i.e. the
+    caret is located on some other object.  The returned offset value will be -1.
   */
   [propget] HRESULT caretOffset
     (