<?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-atkselection">

  <refnamediv>
    <refname>atk.Selection</refname>
      <refpurpose>the ATK interface implemented by container objects whose
      <link
      linkend="class-atkobject"><classname>atk.Object</classname></link>
      children can be selected.  </refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>atk.Selection</classname></ooclass>
      <ooclass><classname>gobject.GInterface</classname></ooclass>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkselection--add-selection">add_selection</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkselection--clear-selection">clear_selection</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkselection--ref-selection">ref_selection</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkselection--get-selection-count">get_selection_count</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkselection--is-child-selected">is_child_selected</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkselection--remove-selection">remove_selection</link></methodname>
        <methodparam><parameter role="keyword">i</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-atkselection--select-all-selection">select_all_selection</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
</classsynopsis>

  </refsect1>

  <refsect1 id="signal-prototypes-atkselection">
    <title>atk.Selection Signal Prototypes</title>


      <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-atkselection--selection-changed">selection-changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>atkselection</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para><link
    linkend="class-atkselection"><classname>atk.Selection</classname></link>
    should be implemented by UI components with children which are exposed
    by the <link
    linkend="method-atkobject--ref-accessible-child"><methodname>ref_accessible_child</methodname>()</link>
    and <link
    linkend="method-atkobject--get-n-accessible-children"><methodname>get_n_accessible_children</methodname>()</link>
    methods, if the use of the parent UI component ordinarily involves
    selection of one or more of the objects corresponding to those <link
    linkend="class-atkobject"><classname>atk.Object</classname></link>
    children - for example, selectable lists.</para>

    <para>Note that other types of "selection" (for instance text selection)
    are accomplished a other ATK interfaces - <link
    linkend="class-atkselection"><classname>atk.Selection</classname></link>
    is limited to the selection/deselection of children.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-atkselection--add-selection">
      <title>atk.Selection.add_selection</title>

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

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>an index specifying the child
          index.</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>Adds the specified accessible child of the object to the
      object's selection.</para>

    </refsect2>

    <refsect2 id="method-atkselection--clear-selection">
      <title>atk.Selection.clear_selection</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if success,
          <literal>False</literal> otherwise.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Clears the selection in the object so that no children in the
      object are selected.</para>

    </refsect2>

    <refsect2 id="method-atkselection--ref-selection">
      <title>atk.Selection.ref_selection</title>

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

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>an index specifying the index in the selection
          set. (e.g. the ith selection as opposed to the ith
          child).</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>an <link
          linkend="class-atkobject"><classname>atk.Object</classname></link>
          representing the selected accessible , or <literal>None</literal>
          if the selection does not implement this
          interface.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Gets a reference to the accessible object representing the
      specified selected child of the object.  Note: callers should not rely
      on <literal>None</literal> or on a zero value for indication of
      whether the <link
      linkend="class-atkselection"><classname>atk.Selection</classname></link>
      interface is implemented.</para>

    </refsect2>

    <refsect2 id="method-atkselection--get-selection-count">
      <title>atk.Selection.get_selection_count</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>an integer representing the number of items
          selected, or 0 if the selection does not implement this
          interface.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Gets the number of accessible children currently selected.
      Note: callers should not rely on <literal>None</literal> or on a zero
      value for indication of whether the <link
      linkend="class-atkselection"><classname>atk.Selection</classname></link>
      interface is implemented.</para>

    </refsect2>

    <refsect2 id="method-atkselection--is-child-selected">
      <title>atk.Selection.is_child_selected</title>

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

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>an index specifying the child
          index.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the specified child
          is selected, or 0 if the selection does not implement this
          interface.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Determines if the current child of this object is selected Note:
      callers should not rely on <literal>None</literal> or on a zero value
      for indication of whether the <link
      linkend="class-atkselection"><classname>atk.Selection</classname></link>
      interface is implemented.</para>

    </refsect2>

    <refsect2 id="method-atkselection--remove-selection">
      <title>atk.Selection.remove_selection</title>

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

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">i</parameter>&nbsp;:</term>
          <listitem><simpara>an index specifying the index in the selection
          set.  (e.g. the ith selection as opposed to the ith
          child).</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>Removes the specified child of the object from the object's
      selection.</para>

    </refsect2>

    <refsect2 id="method-atkselection--select-all-selection">
      <title>atk.Selection.select_all_selection</title>

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

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if success,
          <literal>False</literal> otherwise.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>Causes every child of the object to be selected if the object
      supports multiple selections.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-atkselection--selection-changed">
      <title>The "selection-changed" atk.Selection Signal</title>

      <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>atkselection</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>atkselection</parameter>&nbsp;:</term>
          <listitem><simpara>the object which received the signal.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
          with the <link
          linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
          method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if any)</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The "selection-changed" signal is emitted by an object which
      implements <link
      linkend="class-atkselection"><classname>atk.Selection</classname></link>
      interface when the selection changes.</para>

    </refsect2>

</refsect1>

</refentry>
