diff options
author | Joanmarie Diggs <jdiggs@igalia.com> | 2012-01-22 20:47:23 +0100 |
---|---|---|
committer | Alejandro PiƱeiro <apinheiro@igalia.com> | 2012-01-23 14:36:29 +0100 |
commit | c347f165518cc4afef8c3f4f42a2722d99725c47 (patch) | |
tree | f6c271089ac6249f39f4309c205430f0dcb9814c | |
parent | 867d3f7debdd35738701156969f24544c4b6c5ce (diff) | |
download | atk-c347f165518cc4afef8c3f4f42a2722d99725c47.tar.gz |
Fix for bug 668441 - atk_action_get_keybinding() docs are confusing and need updating
-rwxr-xr-x | atk/atkaction.c | 39 |
1 files changed, 25 insertions, 14 deletions
diff --git a/atk/atkaction.c b/atk/atkaction.c index b37ebc9..fe27eb1 100755 --- a/atk/atkaction.c +++ b/atk/atkaction.c @@ -185,21 +185,32 @@ atk_action_get_localized_name (AtkAction *obj, /** * atk_action_get_keybinding: * @action: a #GObject instance that implements AtkActionIface - * @i: the action index corresponding to the action to be performed + * @i: the action index corresponding to the action to be performed + * + * Gets the keybinding which can be used to activate this action, if one + * exists. The string returned should contain localized, human-readable, + * key sequences as they would appear when displayed on screen. It must + * be in the format "mnemonic;sequence;shortcut". + * + * - The mnemonic key activates the object if it is presently enabled onscreen. + * This typically corresponds to the underlined letter within the widget. + * Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for + * a button. + * - The sequence is the full list of keys which invoke the action even if the + * relevant element is not currently shown on screen. For instance, for a menu + * item the sequence is the keybindings used to open the parent menus before + * invoking. The sequence string is colon-delimited. Example: "Alt+F:N" in a + * traditional "New..." menu item. + * - The shortcut, if it exists, will invoke the same action without showing + * the component or its enclosing menus or dialogs. Example: "Ctrl+N" in a + * traditional "New..." menu item. + * + * Example: For a traditional "New..." menu item, the expected return value + * would be: "N;Alt+F:N;Ctrl+N" for the English locale and "N;Alt+D:N;Strg+N" + * for the German locale. If, hypothetically, this menu item lacked a mnemonic, + * it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively. * - * Returns a keybinding associated with this action, if one exists. - * The returned string is in the format "<a>;<b>;<c>" - * (i.e. semicolon-delimited), where <a> is the keybinding which - * activates the object if it is presently enabled onscreen, - * <b> corresponds to the keybinding or sequence of keys - * which invokes the action even if the relevant element is not - * currently posted on screen (for instance, for a menu item it - * posts the parent menus before invoking). The last token in the - * above string, if non-empty, represents a keyboard shortcut which - * invokes the same action without posting the component or its - * enclosing menus or dialogs. - * - * Returns a string representing the available keybindings, or %NULL + * Returns the keybinding which can be used to activate this action, or %NULL * if there is no keybinding for this action. * **/ |