home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / idl / at-spi-1.0 / Accessibility_Selection.idl < prev    next >
Encoding:
Text File  |  2006-08-22  |  7.0 KB  |  160 lines

  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. };
  160.