/* * AT-SPI - Assistive Technology Service Provider Interface * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap) * * Copyright 2001 Sun Microsystems, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ #include module Accessibility { /** * An interface which indicates that an object exposes a 'selection' model, * allowing the selection of one or more of its children. Read-only Selection * instances are possible, in which case the interface is used to programmatically * determine the selected-ness of its children. A selected child has ::State::STATE_SELECTED, * and a child which may hypothetically be selected (though possibly not programmatically * selectable) has ::State::STATE_SELECTABLE. * @note Events emitted by implementors of Selection include: * \li \c "object:selection-changed" An instance of Selection has undergone a change in the * 'selected-ness' of its children, i.e. had a selection added, * removed, and/or modified. Usually accompanied by * corresponding \c "object:state-changed:selected" events * from the corresponding children, unless the children are * previously un-queried via AT-SPI and the Selection instance * has ::State::STATE_MANAGES_DESCENDANTS. **/ interface Selection : Bonobo::Unknown { /** * The number of children of a Selection implementor which are * currently selected. */ readonly attribute long nSelectedChildren; /** * Get the i-th selected Accessible child of a Selection. * @note \c selectedChildIndex refers to the index in the list of * 'selected' children as opposed to the more general 'child index' * of an object; as such it generally differs from that used in * Accessible::getChildAtIndex() or returned by * Accessible::getIndexInParent(). * \c selectedChildIndex must lie between 0 * and Selection::nSelectedChildren-1, inclusive. * @param selectedChildIndex: a long integer indicating which of the * selected children of an object is being requested. * @returns a pointer to a selected Accessible child object, * specified by \c selectedChildIndex. */ Accessible getSelectedChild (in long selectedChildIndex); /** * Add a child to the selected children list of a Selection. * @note For Selection implementors that only allow * single selections, this call may result in the * replacement of the (single) current * selection. The call may return \c False if * the child is not selectable (i.e. does not have ::State::STATE_SELECTABLE), * if the user does not have permission to change the selection, * or if the Selection instance does not have ::State::STATE_SENSITIVE. * * @param childIndex: a long integer indicating which child of the * Selection is to be selected. * * @returns \c True if the child was successfully selected, * \c False otherwise. */ boolean selectChild (in long childIndex); /** * Remove a child to the selected children list of a Selection. * @note \c childIndex is the index in the selected-children list, * not the index in the parent container. \c selectedChildIndex in this * method, and \c childIndex in Selection::selectChild * are asymmettric. * * @param selectedChildIndex: a long integer indicating which of the * selected children of the Selection is to be deselected. The index * is a zero-offset index into the 'selected child list', not * a zero-offset index into the list of all children of the Selection. * * @returns \c True if the child was successfully deselected, * \c False otherwise. * * @see deselectChild **/ boolean deselectSelectedChild (in long selectedChildIndex); /** * Determine whether a particular child of an Selection implementor * is currently selected. Note that \c childIndex is the zero-offset * index into the standard Accessible container's list of children. * * @param childIndex: an index into the Selection's list of children. * * @returns \c True if the specified child is currently selected, * \c False otherwise. **/ boolean isChildSelected (in long childIndex); /** * Attempt to select all of the children of a Selection implementor. * Not all Selection implementors support this operation (for instance, * implementations which support only "single selection" do not support this operation). * * @returns \c True if successful, \c False otherwise. */ boolean selectAll (); /** * Attempt to clear all selections (i.e. deselect all children) of a Selection. * Not all Selection implementations allow the removal of all selections. * * @note this operation may fail if the object must have at least one selected child, * if the user does not have permission to change the selection, or if the Selection * does not have ::State::STATE_SENSITIVE. * * @returns \c True if the selections were successfully cleared, \c False otherwise. */ boolean clearSelection (); /** * Remove a child from the selected children list of a Selection, * if the child is currently selected. * * @note unlike deselectSelectedChild, \c childIndex is the zero-offset * index into the Accessible instance's list of children, * not the index into the 'selected child list'. * * @param childIndex: a long integer (the zero offset index into the Accessible * object's list of children) indicating which child of the * Selection is to be selected. * * @returns \c True if the child was successfully selected, * \c False otherwise. * * @see deselectSelectedChild * * @since AT-SPI 1.8.0 */ boolean deselectChild (in long childIndex); /** * unImplemented: * * placeholders for future expansion. */ void unImplemented (); void unImplemented2 (); void unImplemented3 (); }; };