Thanks Mick, I didn't realize your Python library gave you an indicator
for E_* results.
Please review this revised change:
1) In all cases where E_INVALIDARG is specified, remove any mention of
the [out] parameters.
2) IAccessibleText::offsetAtPoint
Add:
S_FALSE if nothing to return, [out] value is -1
Because:
The [in] values could all be valid, but x and y could
specify a valid screen position but not one associated with a caret offset.
3) IAccessibleText::selection
Change:
S_FALSE if there is nothing to return,
[out] values are 0s
To:
S_FALSE if there is nothing to return,
[out] values are -1s
Because:
0,0 is a valid value for the selection (i.e. the caret
is before the first character).
4) IAccessible2::groupPosition
Change:
S_FALSE if no values are valid
To:
S_FALSE if no values are valid, [out] values are 0s
Because:
Although it can be determined from reading the parameter
specs, this should probably be stated with the return value as well, for
consistency and completeness.
5) IAccessibleHyperlink::anchor and IAccessibleHyperlink::anchorTarget
Change:
S_FALSE if there is nothing to return,
[out] value is NULL
To:
S_FALSE if there is nothing to return,
[out] value is a VARIANT with vt = VT_EMPTY
Because:
The AT's will expect to see an "empty variant", not
NULL. http://msdn.microsoft.com/en-us/library/dd373687(VS.85).aspx
<http://msdn.microsoft.com/en-us/library/dd373687%28VS.85%29.aspx>
6) IAccessibleValue::currentValue
Change:
S_FALSE if there is nothing to return, [out]
value is NULL
To:
S_FALSE if there is nothing to return, [out]
value is a VARIANT with vt = VT_EMPTY
Because:
The AT's will expect to see an "empty variant", not NULL.
7) IAccessibleValue::maximumValue and IAccessibleValue::minimumValue
Add:
S_FALSE if there is nothing to return, [out]
value is a VARIANT with vt = VT_EMPTY
Because:
This should be consistent with
IAccessibleValue::currentValue.
Also modify the general note about variants slightly to mention
VT_EMPTY:
http://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/_generalinfo.html#_variants
8) IAccessibleText::oldText and newText
Change:
S_FALSE if there is nothing to return, [out] value
is NULL
To:
S_FALSE if there is nothing to return, the values of
IA2TextSegment struct are set as follows: text = NULL, start = 0, end = 0.
Because:
Setting the [out] pointer to NULL does not make sense in
pass-by-reference world.
Pete
===
Carolyn MacLeod wrote:
>
> My bad - I somehow got the impression from Pete that NVDA couldn't
> see any HRESULTS.
> But if you can distinguish E_* HRESULTS because Python throws an
> exception, then that's great.
>
> So the IA2 spec shouldn't spec return values for any E_* HRESULTS.
> We just need to make sure that you can tell the difference between
> S_OK and S_FALSE.
>
> Simpler spec... Less code... yay! ;)
>
> Pete, do you want me to open a doc bug for all of this?
>
> Carolyn
>
>
> From: Michael Curran <[email protected]>
> To: [email protected]
> Date: 14/04/2010 11:38 AM
> Subject: Re: [Accessibility-ia2] IA2 spec changes for cases where
> HRESULT is not S_OK
> Sent by: [email protected]
>
>
> ------------------------------------------------------------------------
>
>
>
> Hi,
>
> I understand why the out params need to be something identifiable for
> S_FALSE, as we deal with this problem directly in Python with NVDA.
>
> However, I'm lost as to why out params mean anything for any of the E_*
> error values.
>
> In Python's case, it will always raise an exception for any E_* value.
> In VB I would have thought it would do the same?
>
> Can someone please point out any languages that hide the hResult by
> returning out params, and don't differenciate between S_OK and S_FALSE,
> yet don't cause some kind of exception or major error for E_* values?
>
> If there is in deed languages that don't raise exceptions, then these
> changes are completely fine.
> If there are not, then when returning E_INVALIDARG it may not be
> necessary to mention what should happen to the out params.
>
> Certainly I agree with the changes to out params for better handling
> S_FALSE.
>
> Thanks
> Mick
>
>
>
>
> On 14/04/2010 5:24 PM, Alexander Surkov wrote:
> > Hi. Looks fine with me however I have a question.
> >
> >> 3) IAccessibleText::selection
> >> Change:
> >> To:
> >> S_FALSE if there is nothing to return,
> [out] values
> >> are -1s
> >> E_INVALIDARG if bad [in] passed, [out]
> values are
> >
> >> 5) IAccessibleHyperlink::anchor and IAccessibleHyperlink::anchorTarget
> >> Change:
> >> S_FALSE if there is nothing to return,
> [out] value
> >> is NULL
> >> E_INVALIDARG if bad [in] passed, [out]
> value is NULL
> >> To:
> >> S_FALSE if there is nothing to return,
> [out] value
> >> is a VARIANT with vt = VT_EMPTY
> >> E_INVALIDARG if bad [in] passed, [out]
> value is a
> >> VARIANT with vt = VT_EMPTY
> >
> > I confused by the difference between "nothing to return" and "bad [in]
> > passed". It sounds like "bad [in]" means "nothing to return" and vise
> > versa.
> >
> > Thank you.
> > Alex.
> >
> >
> > On Wed, Apr 14, 2010 at 5:54 AM, Pete Brunet<[email protected]> wrote:
> >> Please review the following...
> >>
> >> Thanks to Carolyn who is implementing IA2 in Eclipse I believe the
> following
> >> changes need to be made in next update to the spec.
> >>
> >> 1) IAccessibleHypertext::hyperlinkIndex
> >> Change:
> >> E_INVALIDARG if bad [in] passed, [out] value is NULL
> >> To:
> >> E_INVALIDARG if bad [in] passed, [out] value is -1
> >> Because:
> >> Setting the pointer to NULL does not make sense in
> >> pass-by-reference world.
> >>
> >> 2) IAccessibleText::offsetAtPoint
> >> Change:
> >> E_INVALIDARG if bad [in] passed, [out] value is 0
> >> To:
> >> E_INVALIDARG if bad [in] passed, [out] value is -1
> >> Because:
> >> 0 is a valid value for the offset, and AT that
> cannot get
> >> the HRESULT will not be able to distinguish between S_OK and
> E_INVALIDARG.
> >> Add:
> >> S_FALSE if nothing to return, [out] value is -1
> >> Because:
> >> The [in] values could all be valid, but x and y could
> >> specify a valid screen position but not one associated with a caret
> offset.
> >>
> >> 3) IAccessibleText::selection
> >> Change:
> >> S_FALSE if there is nothing to return,
> [out] values
> >> are 0s
> >> E_INVALIDARG if bad [in] passed, [out]
> values are 0s
> >> To:
> >> S_FALSE if there is nothing to return,
> [out] values
> >> are -1s
> >> E_INVALIDARG if bad [in] passed, [out]
> values are
> >> -1s
> >> Because:
> >> 0,0 is a valid value for the selection (i.e. the
> caret is
> >> before the first character), and AT that cannot get the HRESULT
> will not be
> >> able to distinguish between S_OK and S_FALSE/E_INVALIDARG.
> >>
> >> 4) IAccessible2::groupPosition
> >> Change:
> >> S_FALSE if no values are valid
> >> To:
> >> S_FALSE if no values are valid, [out]
> values are 0s
> >> Because:
> >> Although it can be determined from reading the
> parameter
> >> specs, this should probably be stated with the return value as
> well, for
> >> consistency and completeness.
> >>
> >> 5) IAccessibleHyperlink::anchor and IAccessibleHyperlink::anchorTarget
> >> Change:
> >> S_FALSE if there is nothing to return,
> [out] value
> >> is NULL
> >> E_INVALIDARG if bad [in] passed, [out]
> value is NULL
> >> To:
> >> S_FALSE if there is nothing to return,
> [out] value
> >> is a VARIANT with vt = VT_EMPTY
> >> E_INVALIDARG if bad [in] passed, [out]
> value is a
> >> VARIANT with vt = VT_EMPTY
> >> Because:
> >> The AT's will expect to see an "empty variant",
> not NULL.
> >> http://msdn.microsoft.com/en-us/library/dd373687(VS.85).aspx
> <http://msdn.microsoft.com/en-us/library/dd373687%28VS.85%29.aspx>
> >>
> >> 6) IAccessibleValue::currentValue
> >> Change:
> >> S_FALSE if there is nothing to return,
> [out] value
> >> is NULL
> >> To:
> >> S_FALSE if there is nothing to return,
> [out] value
> >> is a VARIANT with vt = VT_EMPTY
> >> Because:
> >> The AT's will expect to see an "empty variant",
> not NULL.
> >>
> >> 7) IAccessibleValue::maximumValue and IAccessibleValue::minimumValue
> >> Add:
> >> S_FALSE if there is nothing to return,
> [out] value
> >> is a VARIANT with vt = VT_EMPTY
> >> Because:
> >> This should be consistent with
> >> IAccessibleValue::currentValue.
> >>
> >> Also modify the general note about variants slightly to mention
> VT_EMPTY:
> >>
> http://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/_generalinfo.html#_variants
> >>
> >> 8) IAccessibleText::oldText and newText
> >> Change:
> >> S_FALSE if there is nothing to return, [out]
> value is
> >> NULL
> >> To:
> >> S_FALSE if there is nothing to return, the
> values of
> >> IA2TextSegment struct are set as follows: text = NULL, start = 0,
> end = 0.
> >> Because:
> >> Setting the [out] pointer to NULL does not make
> sense in
> >> pass-by-reference world.
> >>
> >> _______________________________________________
> >> Accessibility-ia2 mailing list
> >> [email protected]
> >> https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
> >>
> >>
> > _______________________________________________
> > Accessibility-ia2 mailing list
> > [email protected]
> > https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
>
> --
> Michael Curran
> email/msn/jabber: [email protected]
> Skype/Twitter: md_curran
> _______________________________________________
> Accessibility-ia2 mailing list
> [email protected]
> https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
>
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> Accessibility-ia2 mailing list
> [email protected]
> https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
>
_______________________________________________
Accessibility-ia2 mailing list
[email protected]
https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
