<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-atkaction">

  <refnamediv>
    <refname>atk.Action</refname>
      <refpurpose>the ATK interface provided by UI components that the user
      can activate/interact with, </refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>atk.Action</classname></ooclass>
      <ooclass><classname>gobject.GInterface</classname></ooclass>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkaction--do-action">do_action</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkaction--get-n-actions">get_n_actions</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkaction--get-description">get_description</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkaction--get-name">get_name</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkaction--get-keybinding">get_keybinding</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkaction--set-description">set_description</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
        <methodparam><parameter role="keyword">desc</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkaction--get-localized-name">get_localized_name</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
</classsynopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para><link
    linkend="class-atkaction"><classname>atk.Action</classname></link>
    should be implemented by instances of <link
    linkend="class-atkobject"><classname>atk.Object</classname></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="class-atkeditabletext"><classname>atk.EditableText</classname></link>
    (insert/delete test, etc.) or <link
    linkend="class-atkvalue"><classname>atk.Value</classname></link> (set
    value) then these actions should not be exposed by <link
    linkend="class-atkaction"><classname>atk.Action</classname></link> as
    well.</para>

    <para>Also note that the <link
    linkend="class-atkaction"><classname>atk.Action</classname></link> API
    is limited in that parameters may not be passed to the object being
    activated; thus the action must be self-contained and specifiable via
    only a single "verb".  Concrete examples include "press", "release",
    "click" for buttons, "drag" (meaning initiate drag) and "drop" for drag
    sources and drop targets, etc.</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="class-atkaction"><classname>atk.Action</classname></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="class-atkaction"><classname>atk.Action</classname></link>
    names.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-atkaction--do-action">
      <title>atk.Action.do_action</title>

      <programlisting><methodsynopsis language="python">
        <methodname>do_action</methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>the action index corresponding to the action to
          be performed</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if success,
          <literal>False</literal> otherwise</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Perform the specified action on the object.</para>

    </refsect2>

    <refsect2 id="method-atkaction--get-n-actions">
      <title>atk.Action.get_n_actions</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_n_actions</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a the number of actions, or 0 if
          <parameter>action</parameter> does not implement this
          interface.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="method-atkaction--get-description">
      <title>atk.Action.get_description</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_description</methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>the action index corresponding to the action to be performed</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a description string, or
          <literal>None</literal> if <parameter>action</parameter> does not
          implement this interface.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Returns a description of the specified action of the
      object.</para>

    </refsect2>

    <refsect2 id="method-atkaction--get-name">
      <title>atk.Action.get_name</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_name</methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>the action index corresponding to the action to
          be performed</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a name string, or <literal>None</literal> if
          <parameter>action</parameter> does not implement this
          interface.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Returns the name of the specified action of the object.</para>

    </refsect2>

    <refsect2 id="method-atkaction--get-keybinding">
      <title>atk.Action.get_keybinding</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_keybinding</methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>the action index corresponding to the action to
          be performed</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a string representing the keybinding, or
          <literal>None</literal> if there is no keybinding for this
          action.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Returns a keybinding associated with this action, if one
      exists.</para>

    </refsect2>

    <refsect2 id="method-atkaction--set-description">
      <title>atk.Action.set_description</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_description</methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
        <methodparam><parameter role="keyword">desc</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>the action index corresponding to the action to
          be performed</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">desc</parameter>&nbsp;:</term>
          <listitem><simpara>the description to be assigned to this
          action</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the description was
          successfully set;</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Sets a description of the specified action of the object.</para>

    </refsect2>

    <refsect2 id="method-atkaction--get-localized-name">
      <title>atk.Action.get_localized_name</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_localized_name</methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>the action index corresponding to the action to
          be performed</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a name string, or <literal>None</literal> if
          <parameter>action</parameter> does not implement this
          interface.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Returns the localized name of the specified action of the
      object.</para>

    </refsect2>

  </refsect1>

</refentry>
