<?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="AtkSelection">
<refmeta>
<refentrytitle role="top_of_page" id="AtkSelection.top_of_page">AtkSelection</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>ATK Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>AtkSelection</refname>
<refpurpose>The ATK interface implemented by container
objects whose <link linkend="AtkObject"><type>AtkObject</type></link> children can be selected.</refpurpose>
</refnamediv>

<refsect1 id="AtkSelection.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-selection-add-selection">atk_selection_add_selection</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-selection-clear-selection">atk_selection_clear_selection</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="AtkObject"><returnvalue>AtkObject</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="atk-selection-ref-selection">atk_selection_ref_selection</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-selection-get-selection-count">atk_selection_get_selection_count</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-selection-is-child-selected">atk_selection_is_child_selected</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-selection-remove-selection">atk_selection_remove_selection</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-selection-select-all-selection">atk_selection_select_all_selection</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="AtkSelection.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="signal_proto_type" colwidth="150px"/>
<colspec colname="signal_proto_name" colwidth="300px"/>
<colspec colname="signal_proto_flags" colwidth="200px"/>
<tbody>
<row><entry role="signal_type"><link linkend="void"><returnvalue>void</returnvalue></link></entry><entry role="signal_name"><link linkend="AtkSelection-selection-changed">selection-changed</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="AtkSelection.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="AtkSelection-struct">AtkSelection</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="AtkSelection.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> AtkSelection
</screen>
</refsect1>
<refsect1 id="AtkSelection.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
AtkSelection is implemented by
 <link linkend="AtkNoOpObject">AtkNoOpObject</link>.</para>

</refsect1>


<refsect1 id="AtkSelection.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="AtkSelection"><type>AtkSelection</type></link> should be implemented by UI components with children
which are exposed by <link linkend="atk-object-ref-child"><type>atk_object_ref_child</type></link> and
<link linkend="atk-object-get-n-children"><type>atk_object_get_n_children</type></link>, if the use of the parent UI component
ordinarily involves selection of one or more of the objects
corresponding to those <link linkend="AtkObject"><type>AtkObject</type></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="AtkSelection"><type>AtkSelection</type></link> is limited
to the selection/deselection of children.</para>

</refsect1>
<refsect1 id="AtkSelection.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="atk-selection-add-selection" role="function">
<title>atk_selection_add_selection&#160;()</title>
<indexterm zone="atk-selection-add-selection"><primary>atk_selection_add_selection</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
atk_selection_add_selection (<parameter><link linkend="AtkSelection"><type>AtkSelection</type></link> *selection</parameter>,
                             <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>Adds the specified accessible child of the object to the
object's selection.</para>
<refsect3 id="atk-selection-add-selection.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>selection</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkSelectionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>a <link linkend="gint"><type>gint</type></link> specifying the child index.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-selection-add-selection.returns" role="returns">
<title>Returns</title>
<para> TRUE if success, FALSE otherwise.</para>
</refsect3></refsect2>
<refsect2 id="atk-selection-clear-selection" role="function">
<title>atk_selection_clear_selection&#160;()</title>
<indexterm zone="atk-selection-clear-selection"><primary>atk_selection_clear_selection</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
atk_selection_clear_selection (<parameter><link linkend="AtkSelection"><type>AtkSelection</type></link> *selection</parameter>);</programlisting>
<para>Clears the selection in the object so that no children in the object
are selected.</para>
<refsect3 id="atk-selection-clear-selection.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>selection</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkSelectionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-selection-clear-selection.returns" role="returns">
<title>Returns</title>
<para> TRUE if success, FALSE otherwise.</para>
</refsect3></refsect2>
<refsect2 id="atk-selection-ref-selection" role="function">
<title>atk_selection_ref_selection&#160;()</title>
<indexterm zone="atk-selection-ref-selection"><primary>atk_selection_ref_selection</primary></indexterm>
<programlisting language="C"><link linkend="AtkObject"><returnvalue>AtkObject</returnvalue></link>&#160;*
atk_selection_ref_selection (<parameter><link linkend="AtkSelection"><type>AtkSelection</type></link> *selection</parameter>,
                             <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>Gets a reference to the accessible object representing the specified 
selected child of the object.
Note: callers should not rely on <link linkend="NULL:CAPS"><literal>NULL</literal></link> or on a zero value for
indication of whether AtkSelectionIface is implemented, they should
use type checking/interface checking macros or the
<link linkend="atk-get-accessible-value"><function>atk_get_accessible_value()</function></link> convenience method.</para>
<refsect3 id="atk-selection-ref-selection.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>selection</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkSelectionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>a <link linkend="gint"><type>gint</type></link> specifying the index in the selection set.  (e.g. the
ith selection as opposed to the ith child).</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-selection-ref-selection.returns" role="returns">
<title>Returns</title>
<para>an <link linkend="AtkObject"><type>AtkObject</type></link> representing the
selected accessible, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>selection</parameter>
does not implement this
interface. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="atk-selection-get-selection-count" role="function">
<title>atk_selection_get_selection_count&#160;()</title>
<indexterm zone="atk-selection-get-selection-count"><primary>atk_selection_get_selection_count</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
atk_selection_get_selection_count (<parameter><link linkend="AtkSelection"><type>AtkSelection</type></link> *selection</parameter>);</programlisting>
<para>Gets the number of accessible children currently selected.
Note: callers should not rely on <link linkend="NULL:CAPS"><literal>NULL</literal></link> or on a zero value for
indication of whether AtkSelectionIface is implemented, they should
use type checking/interface checking macros or the
<link linkend="atk-get-accessible-value"><function>atk_get_accessible_value()</function></link> convenience method.</para>
<refsect3 id="atk-selection-get-selection-count.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>selection</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkSelectionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-selection-get-selection-count.returns" role="returns">
<title>Returns</title>
<para> a gint representing the number of items selected, or 0
if <parameter>selection</parameter>
does not implement this interface.</para>
</refsect3></refsect2>
<refsect2 id="atk-selection-is-child-selected" role="function">
<title>atk_selection_is_child_selected&#160;()</title>
<indexterm zone="atk-selection-is-child-selected"><primary>atk_selection_is_child_selected</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
atk_selection_is_child_selected (<parameter><link linkend="AtkSelection"><type>AtkSelection</type></link> *selection</parameter>,
                                 <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>Determines if the current child of this object is selected
Note: callers should not rely on <link linkend="NULL:CAPS"><literal>NULL</literal></link> or on a zero value for
indication of whether AtkSelectionIface is implemented, they should
use type checking/interface checking macros or the
<link linkend="atk-get-accessible-value"><function>atk_get_accessible_value()</function></link> convenience method.</para>
<refsect3 id="atk-selection-is-child-selected.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>selection</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkSelectionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>a <link linkend="gint"><type>gint</type></link> specifying the child index.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-selection-is-child-selected.returns" role="returns">
<title>Returns</title>
<para> a gboolean representing the specified child is selected, or 0
if <parameter>selection</parameter>
does not implement this interface.</para>
</refsect3></refsect2>
<refsect2 id="atk-selection-remove-selection" role="function">
<title>atk_selection_remove_selection&#160;()</title>
<indexterm zone="atk-selection-remove-selection"><primary>atk_selection_remove_selection</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
atk_selection_remove_selection (<parameter><link linkend="AtkSelection"><type>AtkSelection</type></link> *selection</parameter>,
                                <parameter><link linkend="gint"><type>gint</type></link> i</parameter>);</programlisting>
<para>Removes the specified child of the object from the object's selection.</para>
<refsect3 id="atk-selection-remove-selection.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>selection</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkSelectionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>a <link linkend="gint"><type>gint</type></link> specifying the index in the selection set.  (e.g. the
ith selection as opposed to the ith child).</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-selection-remove-selection.returns" role="returns">
<title>Returns</title>
<para> TRUE if success, FALSE otherwise.</para>
</refsect3></refsect2>
<refsect2 id="atk-selection-select-all-selection" role="function">
<title>atk_selection_select_all_selection&#160;()</title>
<indexterm zone="atk-selection-select-all-selection"><primary>atk_selection_select_all_selection</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
atk_selection_select_all_selection (<parameter><link linkend="AtkSelection"><type>AtkSelection</type></link> *selection</parameter>);</programlisting>
<para>Causes every child of the object to be selected if the object
supports multiple selections.</para>
<refsect3 id="atk-selection-select-all-selection.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>selection</para></entry>
<entry role="parameter_description"><para>a <link linkend="GObject"><type>GObject</type></link> instance that implements AtkSelectionIface</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="atk-selection-select-all-selection.returns" role="returns">
<title>Returns</title>
<para> TRUE if success, FALSE otherwise.</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="AtkSelection.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="AtkSelection-struct" role="struct">
<title>AtkSelection</title>
<indexterm zone="AtkSelection-struct"><primary>AtkSelection</primary></indexterm>
<programlisting language="C">typedef struct _AtkSelection AtkSelection;</programlisting>
</refsect2>

</refsect1>
<refsect1 id="AtkSelection.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="AtkSelection-selection-changed" role="signal"><title>The <literal>“selection-changed”</literal> signal</title>
<indexterm zone="AtkSelection-selection-changed"><primary>AtkSelection::selection-changed</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
user_function (<link linkend="AtkSelection"><type>AtkSelection</type></link> *atkselection,
               <link linkend="gpointer"><type>gpointer</type></link>      user_data)</programlisting>
<para>The "selection-changed" signal is emitted by an object which
implements AtkSelection interface when the selection changes.</para>
<refsect3 id="AtkSelection-selection-changed.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>atkselection</para></entry>
<entry role="parameter_description"><para>the object which received the signal.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></para>
</refsect2>
</refsect1>

</refentry>
