xml/Accessibility_Selection.xml

   1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   2
   3 <tp:title>AT-SPI - Assistive Technology Service Provider Interface </tp:title>
   4 <tp:copyright>Copyright 2008 Novell, Inc.</tp:copyright>
   5 <tp:copyright>Copyright 2001 Sun Microsystems, Inc.</tp:copyright>
   6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
   7   <p>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.</p>
  11
  12   <p>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.</p>
  16
  17   <p>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.</p>
  21 </tp:license>
  22 <interface name="org.freedesktop.accessibility.Selection">
  23   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  24     <p>An interface which indicates that an object exposes a 'selection' model,
  25       allowing the selection of one or more of its children.  Read-only Selection
  26       instances are possible, in which case the interface is used to programmatically
  27       determine the selected-ness of its children.  A selected child has ::State::STATE_SELECTED,
  28       and a child which may hypothetically be selected (though possibly not programmatically
  29       selectable) has ::State::STATE_SELECTABLE.
  30       @note Events emitted by implementors of Selection include:
  31       \li \c &quot;object:selection-changed&quot; An instance of Selection has undergone a change in the
  32       'selected-ness' of its children, i.e. had a selection added,
  33       removed, and/or modified.  Usually accompanied by
  34       corresponding \c &quot;object:state-changed:selected&quot; events
  35       from the corresponding children, unless the children are
  36       previously un-queried via AT-SPI and the Selection instance
  37       has ::State::STATE_MANAGES_DESCENDANTS.</p>
  38   </tp:docstring>
  39   <tp:property name="nSelectedChildren" type="i" access="read">
  40   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  41     <p>The number of children of a Selection implementor which are
  42       currently selected.</p>
  43   </tp:docstring>
  44   </tp:property>
  45   <method name="getSelectedChild">
  46     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  47       <p>Get the i-th selected Accessible child of a Selection.
  48         @note \c selectedChildIndex refers to the index in the list of
  49         'selected' children as opposed to the more general 'child index'
  50         of an object;  as such it generally differs from that used in
  51         Accessible::getChildAtIndex() or returned by
  52         Accessible::getIndexInParent().
  53         \c selectedChildIndex must lie between 0
  54         and Selection::nSelectedChildren-1, inclusive.</p>
  55     </tp:docstring>
  56     <arg direction="in" name="selectedChildIndex" type="i">
  57     <tp:docstring>
  58       a long integer indicating which of the selected children of an object is being requested.
  59     </tp:docstring>
  60     </arg>
  61     <arg direction="out" type="o" tp:type="Accessible">
  62     <tp:docstring>
  63       a pointer to a selected Accessible child object,specified by \c selectedChildIndex.
  64     </tp:docstring>
  65     </arg>
  66   </method>
  67   <method name="selectChild">
  68     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  69       <p>Add a child to the selected children list of a Selection.
  70         @note For Selection implementors that only allow
  71         single selections, this call may result in the
  72         replacement of the (single) current
  73         selection.  The call may return \c False if
  74         the child is not selectable (i.e. does not have ::State::STATE_SELECTABLE),
  75         if the user does not have permission to change the selection,
  76         or if the Selection instance does not have ::State::STATE_SENSITIVE.    </p>
  77     </tp:docstring>
  78     <arg direction="in" name="childIndex" type="i">
  79     <tp:docstring>
  80       a long integer indicating which child of theSelection is to be selected.
  81     </tp:docstring>
  82     </arg>
  83     <arg direction="out" type="b" tp:type="boolean">
  84     <tp:docstring>
  85       \c True if the child was successfully selected, \c False otherwise.
  86     </tp:docstring>
  87     </arg>
  88   </method>
  89   <method name="deselectSelectedChild">
  90     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  91       <p>Remove a child to the selected children list of a Selection.
  92         @note \c childIndex is the index in the selected-children list,
  93         not the index in the parent container.  \c selectedChildIndex in this
  94         method, and \c childIndex in Selection::selectChild
  95         are asymmettric.    </p>
  96     </tp:docstring>
  97     <arg direction="in" name="selectedChildIndex" type="i">
  98     <tp:docstring>
  99       a long integer indicating which of the selected children of the Selection is to be deselected.  The indexis a zero-offset index into the 'selected child list', nota zero-offset index into the list of all children of the Selection.
 100     </tp:docstring>
 101     </arg>
 102     <arg direction="out" type="b" tp:type="boolean">
 103     <tp:docstring>
 104       \c True if the child was successfully deselected, \c False otherwise.@see deselectChild
 105     </tp:docstring>
 106     </arg>
 107   </method>
 108   <method name="isChildSelected">
 109     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 110       <p>Determine whether a particular child of an Selection implementor
 111         is currently selected.  Note that \c childIndex is the zero-offset
 112         index into the standard Accessible container's list of children.    </p>
 113     </tp:docstring>
 114     <arg direction="in" name="childIndex" type="i">
 115     <tp:docstring>
 116       an index into the Selection's list of children.
 117     </tp:docstring>
 118     </arg>
 119     <arg direction="out" type="b" tp:type="boolean">
 120     <tp:docstring>
 121       \c True if the specified child is currently selected,\c False otherwise.
 122     </tp:docstring>
 123     </arg>
 124   </method>
 125   <method name="selectAll">
 126     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 127       <p>Attempt to select all of the children of a Selection implementor.
 128         Not all Selection implementors support this operation (for instance,
 129         implementations which support only &quot;single selection&quot; do not support this operation).    </p>
 130     </tp:docstring>
 131     <arg direction="out" type="b" tp:type="boolean">
 132     <tp:docstring>
 133       \c True if successful, \c False otherwise.
 134     </tp:docstring>
 135     </arg>
 136   </method>
 137   <method name="clearSelection">
 138     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 139       <p>Attempt to clear all selections (i.e. deselect all children) of a Selection.
 140         Not all Selection implementations allow the removal of all selections.    </p>
 141
 142       <p>@note this operation may fail if the object must have at least one selected child,
 143         if the user does not have permission to change the selection, or if the Selection
 144         does not have ::State::STATE_SENSITIVE.    </p>
 145     </tp:docstring>
 146     <arg direction="out" type="b" tp:type="boolean">
 147     <tp:docstring>
 148       \c True if the selections were successfully cleared, \c False otherwise.
 149     </tp:docstring>
 150     </arg>
 151   </method>
 152   <method name="deselectChild">
 153     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 154       <p>Remove a child from the selected children list of a Selection,
 155         if the child is currently selected.    </p>
 156
 157       <p>@note unlike deselectSelectedChild, \c childIndex is the zero-offset
 158         index into the Accessible instance's list of children,
 159         not the index into the 'selected child list'.    </p>
 160     </tp:docstring>
 161     <arg direction="in" name="childIndex" type="i">
 162     <tp:docstring>
 163       a long integer (the zero offset index into the Accessibleobject's list of children) indicating which child of theSelection is to be selected.
 164     </tp:docstring>
 165     </arg>
 166     <arg direction="out" type="b" tp:type="boolean">
 167     <tp:docstring>
 168       \c True if the child was successfully selected, \c False otherwise.@see deselectSelectedChild@since AT-SPI 1.8.0
 169     </tp:docstring>
 170     </arg>
 171   </method>
 172   <method name="unImplemented">
 173     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 174       <p>unImplemented:    </p>
 175
 176       <p>placeholders for future expansion.</p>
 177     </tp:docstring>
 178   </method>
 179   <method name="unImplemented2">
 180   </method>
 181   <method name="unImplemented3">
 182   </method>
 183 </interface>
 184 </node>