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]> 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]> <[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]><[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 > [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
