idl/Accessibility_Selection.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include <Accessibility_Accessible.idl>
  24
  25 module Accessibility {
  26
  27   /**
  28    * An interface which indicates that an object exposes a 'selection' model,
  29    * allowing the selection of one or more of its children.  Read-only Selection
  30    * instances are possible, in which case the interface is used to programmatically
  31    * determine the selected-ness of its children.  A selected child has ::State::STATE_SELECTED,
  32    * and a child which may hypothetically be selected (though possibly not programmatically
  33    * selectable) has ::State::STATE_SELECTABLE.
  34    * @note Events emitted by implementors of Selection include:
  35    * \li \c "object:selection-changed" An instance of Selection has undergone a change in the
  36    *                                  'selected-ness' of its children, i.e. had a selection added,
  37    *                                  removed, and/or modified.  Usually accompanied by
  38    *                                  corresponding \c "object:state-changed:selected" events
  39    *                                  from the corresponding children, unless the children are
  40    *                                  previously un-queried via AT-SPI and the Selection instance
  41    *                                  has ::State::STATE_MANAGES_DESCENDANTS.
  42    **/
  43   interface Selection : Bonobo::Unknown {
  44     /**
  45      * The number of children of a Selection implementor which are
  46      *        currently selected.
  47      */
  48     readonly attribute long nSelectedChildren;
  49     /**
  50      * Get the i-th selected Accessible child of a Selection.
  51      * @note \c selectedChildIndex refers to the index in the list of
  52      * 'selected' children as opposed to the more general 'child index'
  53      * of an object;  as such it generally differs from that used in
  54      * Accessible::getChildAtIndex() or returned by
  55      * Accessible::getIndexInParent().
  56      * \c selectedChildIndex must lie between 0
  57      * and Selection::nSelectedChildren-1, inclusive.
  58      * @param selectedChildIndex: a long integer indicating which of the
  59      * selected children of an object is being requested.
  60      * @returns a pointer to a selected Accessible child object,
  61      *          specified by \c selectedChildIndex.
  62      */
  63     Accessible getSelectedChild (in long selectedChildIndex);
  64    /**
  65     * Add a child to the selected children list of a Selection.
  66     * @note For Selection implementors that only allow
  67     *       single selections, this call may result in the
  68     *       replacement of the (single) current
  69     *       selection.  The call may return \c False if
  70     *       the child is not selectable (i.e. does not have ::State::STATE_SELECTABLE),
  71     *       if the user does not have permission to change the selection,
  72     *       or if the Selection instance does not have ::State::STATE_SENSITIVE.
  73     *
  74     * @param childIndex: a long integer indicating which child of the
  75     *              Selection is to be selected.
  76     *
  77     * @returns \c True if the child was successfully selected,
  78     *          \c False otherwise.
  79     */
  80     boolean selectChild (in long childIndex);
  81    /**
  82     * Remove a child to the selected children list of a Selection.
  83     * @note \c childIndex is the index in the selected-children list,
  84     *       not the index in the parent container.  \c selectedChildIndex in this
  85     *       method, and \c childIndex in Selection::selectChild
  86     *       are asymmettric.
  87     *
  88     * @param selectedChildIndex: a long integer indicating which of the
  89     *         selected children of the Selection is to be deselected.  The index
  90     *         is a zero-offset index into the 'selected child list', not
  91     *         a zero-offset index into the list of all children of the Selection.
  92     *
  93     * @returns \c True if the child was successfully deselected,
  94     *          \c False otherwise.
  95     *
  96     * @see deselectChild
  97     **/
  98     boolean deselectSelectedChild (in long selectedChildIndex);
  99    /**
 100     * Determine whether a particular child of an Selection implementor
 101     *        is currently selected.  Note that \c childIndex is the zero-offset
 102     *        index into the standard Accessible container's list of children.
 103     *
 104     * @param childIndex: an index into the Selection's list of children.
 105     *
 106     * @returns \c True if the specified child is currently selected,
 107     *          \c False otherwise.
 108     **/
 109     boolean isChildSelected (in long childIndex);
 110     /**
 111      * Attempt to select all of the children of a Selection implementor.
 112      * Not all Selection implementors support this operation (for instance,
 113      * implementations which support only "single selection" do not support this operation).
 114      *
 115      * @returns \c True if successful, \c False otherwise.
 116      */
 117     boolean selectAll ();
 118     /**
 119      * Attempt to clear all selections (i.e. deselect all children) of a Selection.
 120      * Not all Selection implementations allow the removal of all selections.
 121      *
 122      * @note this operation may fail if the object must have at least one selected child,
 123      * if the user does not have permission to change the selection, or if the Selection
 124      * does not have ::State::STATE_SENSITIVE.
 125      *
 126      * @returns \c True if the selections were successfully cleared, \c False otherwise.
 127      */
 128     boolean clearSelection ();
 129     /**
 130      * Remove a child from the selected children list of a Selection,
 131      *       if the child is currently selected.
 132      *
 133      * @note unlike deselectSelectedChild, \c childIndex is the zero-offset
 134      *       index into the Accessible instance's list of children,
 135      *       not the index into the 'selected child list'.
 136      *
 137      * @param childIndex: a long integer (the zero offset index into the Accessible
 138      *              object's list of children) indicating which child of the
 139      *              Selection is to be selected.
 140      *
 141      * @returns \c True if the child was successfully selected,
 142      *          \c False otherwise.
 143      *
 144      * @see deselectSelectedChild
 145      *
 146      * @since AT-SPI 1.8.0
 147      */
 148     boolean deselectChild (in long childIndex);
 149
 150     /**
 151      * unImplemented:
 152      *
 153      * placeholders for future expansion.
 154      */
 155     void unImplemented ();
 156     void unImplemented2 ();
 157     void unImplemented3 ();
 158   };
 159 };