Hi Alex, I see what you are saying about those three methods. For
example, if there is a selection then there has to be something to
return so S_FALSE would never happen. So I will change item 3 to merge
3 and 5 and then delete 5 as follows:
3) IAccessibleText::selection, IAccessibleHyperlink::anchor and
IAccessibleHyperlink::anchorTarget
Remove:
S_FALSE if there is nothing to return,
[out] values are 0s
Because:
There will always be something to return if a valid
index is provided
>I think it's worth to point default values of [out] arguments
Are there some that I should specify?
Pete
===
Alexander Surkov wrote:
> Hi, Pete.
>
> I think it's worth to point default values of [out] arguments. Default
> values shouldn't depend on whether the method returns S_FALSE or
> failure code.
>
> Thank you.
> Alex.
>
>
> On Fri, Apr 16, 2010 at 6:59 AM, Pete Brunet <[email protected]
> <mailto:[email protected]>> wrote:
>
> 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]> <mailto:[email protected]>
>> To: [email protected]
>> <mailto:[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]
>> <mailto:[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]>
>> <mailto:[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]
>> <mailto:[email protected]>
>> >>
>> https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
>> >>
>> >>
>> > _______________________________________________
>> > Accessibility-ia2 mailing list
>> > [email protected]
>> <mailto:[email protected]>
>> >
>> https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
>>
>> --
>> Michael Curran
>> email/msn/jabber: [email protected] <mailto:[email protected]>
>> Skype/Twitter: md_curran
>> _______________________________________________
>> Accessibility-ia2 mailing list
>> [email protected]
>> <mailto:[email protected]>
>> https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
>>
>>
>>
>> ------------------------------------------------------------------------
>> _______________________________________________ Accessibility-ia2
>> mailing list [email protected]
>> <mailto:[email protected]>
>> https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
>>
>
> _______________________________________________
> Accessibility-ia2 mailing list
> [email protected]
> <mailto:[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
