From c347f165518cc4afef8c3f4f42a2722d99725c47 Mon Sep 17 00:00:00 2001 From: Joanmarie Diggs Date: Sun, 22 Jan 2012 20:47:23 +0100 Subject: [PATCH] Fix for bug 668441 - atk_action_get_keybinding() docs are confusing and need updating --- atk/atkaction.c | 39 +++++++++++++++++++++++++-------------- 1 file 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 ";;" - * (i.e. semicolon-delimited), where is the keybinding which - * activates the object if it is presently enabled onscreen, - * 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. * **/ -- 2.7.4