<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
  <!ENTITY % gtkdocentities SYSTEM "../xml/gtkdocentities.ent">
  %gtkdocentities;
]>
<refentry id="AtkAction">
<refmeta>
<refentrytitle role="top_of_page" id="AtkAction.top_of_page">AtkAction</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>ATK Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>AtkAction</refname>
<refpurpose>The ATK interface provided by UI components
which the user can activate/interact with.</refpurpose>
</refnamediv>

<refsect1 id="AtkAction.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="atk-action-do-action">atk_action_do_action</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="atk-action-get-n-actions">atk_action_get_n_actions</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="atk-action-get-description">atk_action_get_description</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="atk-action-get-name">atk_action_get_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="atk-action-get-localized-name">atk_action_get_localized_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="atk-action-get-keybinding">atk_action_get_keybinding</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="atk-action-set-description">atk_action_set_description</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="AtkAction.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="AtkAction-struct">AtkAction</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="AtkActionIface">AtkActionIface</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="AtkAction.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GInterface">GInterface</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> AtkAction
</screen>
</refsect1>
<refsect1 id="AtkAction.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
AtkAction is implemented by
 <link linkend="AtkHyperlink">AtkHyperlink</link> and  <link linkend="AtkNoOpObject">AtkNoOpObject</link>.</para>

</refsect1>


<refsect1 id="AtkAction.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="AtkAction"><type>AtkAction</type></link> should be implemented by instances of <link linkend="AtkObject"><type>AtkObject</type></link> classes
with which the user can interact directly, i.e. buttons,
checkboxes, scrollbars, e.g. components which are not "passive"
providers of UI information.</para>
<para>Exceptions: when the user interaction is already covered by another
appropriate interface such as <link linkend="AtkEditableText"><type>AtkEditableText</type></link> (insert/delete text,
etc.) or <link linkend="AtkValue"><type>AtkValue</type></link> (set value) then these actions should not be
exposed by <link linkend="AtkAction"><type>AtkAction</type></link> as well.</para>
<para>Though most UI interactions on components should be invocable via
keyboard as well as mouse, there will generally be a close mapping
between "mouse actions" that are possible on a component and the
AtkActions.  Where mouse and keyboard actions are redundant in
effect, <link linkend="AtkAction"><type>AtkAction</type></link> should expose only one action rather than
exposing redundant actions if possible.  By convention we have been
using "mouse centric" terminology for <link linkend="AtkAction"><type>AtkAction</type></link> names.</para>

</refsect1>
<refsect1 id="AtkAction.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="atk-action-do-action" role="function">
<title>atk_action_do_action&#160;()</title>
<indexterm zone="atk-action-do-action"><primary>atk_action_do_action</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
atk_action_do_action (<parameter><link linkend="AtkAction"><type>AtkAction</type></link> *action</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>Perform the specified action on the object.</para>
<refsect3 id="atk-action-do-action.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>action</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkActionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>the action index corresponding to the action to be performed </para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-action-do-action.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para>
</refsect3></refsect2>
<refsect2 id="atk-action-get-n-actions" role="function">
<title>atk_action_get_n_actions&#160;()</title>
<indexterm zone="atk-action-get-n-actions"><primary>atk_action_get_n_actions</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
atk_action_get_n_actions (<parameter><link linkend="AtkAction"><type>AtkAction</type></link> *action</parameter>);</programlisting>
<para>Gets the number of accessible actions available on the object.
If there are more than one, the first one is considered the
"default" action of the object.</para>
<refsect3 id="atk-action-get-n-actions.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>action</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkActionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-action-get-n-actions.returns" role="returns">
<title>Returns</title>
<para> a the number of actions, or 0 if <parameter>action</parameter>
does not
implement this interface.</para>
</refsect3></refsect2>
<refsect2 id="atk-action-get-description" role="function">
<title>atk_action_get_description&#160;()</title>
<indexterm zone="atk-action-get-description"><primary>atk_action_get_description</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
atk_action_get_description (<parameter><link linkend="AtkAction"><type>AtkAction</type></link> *action</parameter>,
                            <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>Returns a description of the specified action of the object.</para>
<refsect3 id="atk-action-get-description.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>action</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkActionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>the action index corresponding to the action to be performed </para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-action-get-description.returns" role="returns">
<title>Returns</title>
<para>a description string, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>action</parameter>
does
not implement this interface. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="atk-action-get-name" role="function">
<title>atk_action_get_name&#160;()</title>
<indexterm zone="atk-action-get-name"><primary>atk_action_get_name</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
atk_action_get_name (<parameter><link linkend="AtkAction"><type>AtkAction</type></link> *action</parameter>,
                     <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>Returns a non-localized string naming the specified action of the 
object. This name is generally not descriptive of the end result 
of the action, but instead names the 'interaction type' which the 
object supports. By convention, the above strings should be used to 
represent the actions which correspond to the common point-and-click 
interaction techniques of the same name: i.e. 
"click", "press", "release", "drag", "drop", "popup", etc.
The "popup" action should be used to pop up a context menu for the 
object, if one exists.</para>
<para>For technical reasons, some toolkits cannot guarantee that the 
reported action is actually 'bound' to a nontrivial user event;
i.e. the result of some actions via <link linkend="atk-action-do-action"><function>atk_action_do_action()</function></link> may be
NIL.</para>
<refsect3 id="atk-action-get-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>action</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkActionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>the action index corresponding to the action to be performed </para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-action-get-name.returns" role="returns">
<title>Returns</title>
<para>a name string, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>action</parameter>
does not
implement this interface. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="atk-action-get-localized-name" role="function">
<title>atk_action_get_localized_name&#160;()</title>
<indexterm zone="atk-action-get-localized-name"><primary>atk_action_get_localized_name</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
atk_action_get_localized_name (<parameter><link linkend="AtkAction"><type>AtkAction</type></link> *action</parameter>,
                               <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>Returns the localized name of the specified action of the object.</para>
<refsect3 id="atk-action-get-localized-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>action</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkActionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>the action index corresponding to the action to be performed </para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-action-get-localized-name.returns" role="returns">
<title>Returns</title>
<para>a name string, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>action</parameter>
does not
implement this interface. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="atk-action-get-keybinding" role="function">
<title>atk_action_get_keybinding&#160;()</title>
<indexterm zone="atk-action-get-keybinding"><primary>atk_action_get_keybinding</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
atk_action_get_keybinding (<parameter><link linkend="AtkAction"><type>AtkAction</type></link> *action</parameter>,
                           <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>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".</para>
<itemizedlist>
<listitem><para>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.</para></listitem>
<listitem><para>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.</para></listitem>
<listitem>
<para>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.</para>
</listitem>
</itemizedlist>
<para>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.</para>
<refsect3 id="atk-action-get-keybinding.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>action</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkActionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>the action index corresponding to the action to be performed</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-action-get-keybinding.returns" role="returns">
<title>Returns</title>
<para>the keybinding which can be used to activate
this action, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if there is no keybinding for this action. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="atk-action-set-description" role="function">
<title>atk_action_set_description&#160;()</title>
<indexterm zone="atk-action-set-description"><primary>atk_action_set_description</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
atk_action_set_description (<parameter><link linkend="AtkAction"><type>AtkAction</type></link> *action</parameter>,
                            <parameter><link linkend="gint"><type>gint</type></link> i</parameter>,
                            <parameter>const <link linkend="gchar"><type>gchar</type></link> *desc</parameter>);</programlisting>
<para>Sets a description of the specified action of the object.</para>
<refsect3 id="atk-action-set-description.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>action</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkActionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>the action index corresponding to the action to be performed </para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>desc</para></entry>
<entry role="parameter_description"><para>the description to be assigned to this action</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-action-set-description.returns" role="returns">
<title>Returns</title>
<para> a gboolean representing if the description was successfully set;</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="AtkAction.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="AtkAction-struct" role="struct">
<title>AtkAction</title>
<indexterm zone="AtkAction-struct"><primary>AtkAction</primary></indexterm>
<programlisting language="C">typedef struct _AtkAction AtkAction;</programlisting>
</refsect2>
<refsect2 id="AtkActionIface" role="struct">
<title>struct AtkActionIface</title>
<indexterm zone="AtkActionIface"><primary>AtkActionIface</primary></indexterm>
<programlisting language="C">struct AtkActionIface {
  GTypeInterface parent;

  gboolean                (*do_action)         (AtkAction         *action,
                                                gint              i);
  gint                    (*get_n_actions)     (AtkAction         *action);
  const gchar*            (*get_description)   (AtkAction         *action,
                                                gint              i);
  const gchar*            (*get_name)          (AtkAction         *action,
                                                gint              i);
  const gchar*            (*get_keybinding)    (AtkAction         *action,
                                                gint              i);
  gboolean                (*set_description)   (AtkAction         *action,
                                                gint              i,
                                                const gchar       *desc);
  const gchar*            (*get_localized_name)(AtkAction         *action,
						gint              i);
};
</programlisting>
</refsect2>

</refsect1>

</refentry>
