Back on 17 Jan 07 on the IA2 list Bill Haneman said the following in
response to a comment from, "I've confirmed that the existing API docs
for Action (and AtkAction) are not really adequate. I'll log a bugzilla
bug and work on the doc changes."
Since then Bill has dropped out of sight so let's see if we can determine
what if any doc changes I need to make now and what if any changes need to
go into a version 2 of IAAction.
First of all, here is a comment from Willie Walker:
One main thing I'd like to see done with it is determining what strings
are supposed to be translated and which are to remain programmatic. The
big issue right now is the action name. I believe it was intended to be
human consumable, but it is done so inconsistently (gail doesn't do it,
evolution does).
For now, I'd prefer it remain a programmatic name and we introduce a new
human consumable name field if such a thing is desired. The reason for
this is that the action name can be very useful for inferring the type of
the component. For example "toggle" lets us know something of role table
is probably acting checkbox. It exposes a weakness in the API overall
(i.e., we should allow multiple roles for an object, there should be a
CHECKABLE state, etc.), but still, it's a nice thing to use.
In response to Willie: In IA2 there is both IAAction::name and
IAAction::localizedName, so the former is available for programmatic
purposes and the latter for the UI. I see the AT-SPI Action interface has
getDescription, getName, doAction, and getKeyBinding. It doesn't have
separate methods for the localized and unlocalized name and it doesn't
indicate if the name string is localized or not so I can see why there is
confusion. MSAA has get_defaultAction and its doc says the string is
localized and the following: The retrieved string describes the action
that is performed on an object, not what the object does as a result. For
example, a toolbar button that prints a document has a default action of
"Press" rather than "Prints the current document." Based on that I'd
guess more ATK implementations would localize the string. In any event
since IA2 has both localized and unlocalized strings perhaps it has
already solved the problem Bill was alluding to. Below is what I
currently have documented in my working copy of the spec. I think it's
adequate but let me know if you have suggestions.
Detailed Description
This interface gives access to actions that can be executed for accessible
objects.
Every accessible object that can be manipulated beyond its methods
exported over the accessibility API should support this interface to
expose all actions that it can perform. 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.
The first action should be equivalent to the MSAA default action. If there
is only one action, IAccessibleAction should also be implemented.
// Returns the number of accessible actions available in this object.
// If there are more than one, the first one is considered the "default"
action of the object.
HRESULT nActions ( [out,retval] long* nActions );
// Performs the specified Action on the object.
HRESULT doAction ( [in] long actionIndex );
// Returns a description of the specified action of the object.
HRESULT description ( [in] long actionIndex, [out, retval] BSTR
*description );
// Returns an array of BSTRs describing one or more key bindings, if there
are any, associated with the specified action.
// The returned strings are the human readable key sequences to be used
for each action, e.g. ctrl+shift+D.
// An AT such as an On Screen Keyboard might not expose these bindings but
provide alternative means of activation.
HRESULT keyBinding (
[in] long actionIndex,
[in] long nMaxBindings, // ignored (the parameter is included in the
IDL in error)
[out, size_is(,nMaxBindings), length_is(,*nBindings)] BSTR
**keyBindings,
[out, retval] long *nBindings // size of returned array (number of
bindings)
);
// Returns the non-localized name of specified action.
HRESULT name ( [in] long actionIndex, [out, retval] BSTR *name );
// Returns the localized name of specified action.
HRESULT localizedName ( [in] long actionIndex, [out, retval] BSTR
*localizedName );
Pete Brunet
IBM Accessibility Architecture and Development
11501 Burnet Road, MS 9022E004, Austin, TX 78758
Voice: (512) 838-4594, Cell: (512) 689-4155
Ionosphere: WS4G
----- Forwarded by Pete Brunet/Austin/IBM on 04/25/2008 02:01 PM -----
Willie Walker <[EMAIL PROTECTED]>
Sent by: [EMAIL PROTECTED]
04/23/2008 06:49 PM
To
Pete Brunet/Austin/[EMAIL PROTECTED]
cc
Subject
Re: Fw: docs for the action interface
Hi Pete:
No idea. :-( The Action API is relatively simple, though, and we
probably can hash it out if need be. One main thing I'd like to see
done with it is determining what strings are supposed to be translated
and which are to remain programmatic. The big issue right now is the
action name. I believe it was intended to be human consumable, but it
is done so inconsistently (gail doesn't do it, evolution does).
For now, I'd prefer it remain a programmatic name and we introduce a new
human consumable name field if such a thing is desired. The reason for
this is that the action name can be very useful for inferring the type
of the component. For example "toggle" lets us know something of role
table is probably acting checkbox. It exposes a weakness in the API
overall (i.e., we should allow multiple roles for an object, there
should be a CHECKABLE state, etc.), but still, it's a nice thing to use.
Will
Pete Brunet wrote:
>
> Hi Willie, Do you have an email address for Bill that he might respond
to?
>
> *Pete Brunet*
>
> IBM Accessibility Architecture and Development
> 11501 Burnet Road, MS 9022E004, Austin, TX 78758
> Voice: (512) 838-4594, Cell: (512) 689-4155
> Ionosphere: WS4G
>
> ----- Forwarded by Pete Brunet/Austin/IBM on 04/23/2008 03:05 PM -----
> *Pete Brunet/Austin/IBM*
>
> 03/19/2008 04:18 PM
>
>
> To
> Bill Haneman <[EMAIL PROTECTED]>
> cc
>
> Subject
> Fw: docs for the action interface
>
>
>
>
>
>
>
> Hi Bill, Will you be able to answer this question or direct me to
> someone who can?
>
> *Pete Brunet*
>
> IBM Accessibility Architecture and Development
> 11501 Burnet Road, MS 9022E004, Austin, TX 78758
> Voice: (512) 838-4594, Cell: (512) 689-4155
> Ionosphere: WS4G
>
> ----- Forwarded by Pete Brunet/Austin/IBM on 03/19/2008 04:17 PM -----
> *Pete Brunet/Austin/IBM*
>
> 02/07/2008 06:47 PM
>
>
> To
> Bill Haneman <[EMAIL PROTECTED]>
> cc
>
> Subject
> docs for the action interfaceLink
> <
Notes://D03NM116/8525604600452FB8/BD053B46B119C67A8525643000742B16/E7F04A21A87E1542872573D10061A1CC
>
>
>
>
>
>
>
>
> Hi Bill, I'm working on the IA2 IDL documentaiton.
>
> Back on 17 Jan 07 on the IA2 list you said this to Olaf, "I've confirmed
> that the existing API docs for Action (and AtkAction) are not really
> adequate. I'll log a bugzilla bug and work on the doc changes."
>
> Did you make those changes? Or did you document what needs to be done
> in the bug? Can you send me a link to the bug?
>
> Thanks,
> *Pete Brunet*
>
> IBM Accessibility Architecture and Development
> 11501 Burnet Road, MS 9022E004, Austin, TX 78758
> Voice: (512) 838-4594, Cell: (512) 689-4155
> Ionosphere: WS4G
_______________________________________________
Accessibility-ia2 mailing list
[email protected]
https://lists.linux-foundation.org/mailman/listinfo/accessibility-ia2
