atk/atkselection.c

   1 /* ATK -  Accessibility Toolkit
   2  * Copyright 2001 Sun Microsystems Inc.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #include "atkselection.h"
  19
  20 /**
  21  * SECTION:atkselection
  22  * @Short_description: The ATK interface implemented by container
  23  *  objects whose #AtkObject children can be selected.
  24  * @Title:AtkSelection
  25  *
  26  * #AtkSelection should be implemented by UI components with children
  27  * which are exposed by #atk_object_ref_child and
  28  * #atk_object_get_n_children, if the use of the parent UI component
  29  * ordinarily involves selection of one or more of the objects
  30  * corresponding to those #AtkObject children - for example,
  31  * selectable lists.
  32  *
  33  * Note that other types of "selection" (for instance text selection)
  34  * are accomplished a other ATK interfaces - #AtkSelection is limited
  35  * to the selection/deselection of children.
  36  */
  37
  38
  39 enum {
  40   SELECTION_CHANGED,
  41   LAST_SIGNAL
  42 };
  43
  44 static void atk_selection_base_init (gpointer *g_class);
  45
  46 static guint atk_selection_signals[LAST_SIGNAL] = { 0 };
  47
  48 GType
  49 atk_selection_get_type (void)
  50 {
  51   static GType type = 0;
  52
  53   if (!type) {
  54     GTypeInfo tinfo =
  55     {
  56       sizeof (AtkSelectionIface),
  57       (GBaseInitFunc)atk_selection_base_init,
  58       (GBaseFinalizeFunc) NULL,
  59
  60     };
  61
  62     type = g_type_register_static (G_TYPE_INTERFACE, "AtkSelection", &tinfo, 0);
  63   }
  64
  65   return type;
  66 }
  67
  68 static void
  69 atk_selection_base_init (gpointer *g_class)
  70 {
  71   static gboolean initialized = FALSE;
  72
  73   if (! initialized)
  74     {
  75       /**
  76        * AtkSelection::selection-changed:
  77        * @atkselection: the object which received the signal.
  78        *
  79        * The "selection-changed" signal is emitted by an object which
  80        * implements AtkSelection interface when the selection changes.
  81        */
  82       atk_selection_signals[SELECTION_CHANGED] =
  83         g_signal_new ("selection_changed",
  84                       ATK_TYPE_SELECTION,
  85                       G_SIGNAL_RUN_LAST,
  86                       G_STRUCT_OFFSET (AtkSelectionIface, selection_changed),
  87                       (GSignalAccumulator) NULL, NULL,
  88                       g_cclosure_marshal_VOID__VOID,
  89                       G_TYPE_NONE, 0);
  90
  91
  92       initialized = TRUE;
  93     }
  94 }
  95
  96 /**
  97  * atk_selection_add_selection:
  98  * @selection: a #GObject instance that implements AtkSelectionIface
  99  * @i: a #gint specifying the child index.
 100  *
 101  * Adds the specified accessible child of the object to the
 102  * object's selection.
 103  *
 104  * Returns: TRUE if success, FALSE otherwise.
 105  **/
 106 gboolean
 107 atk_selection_add_selection (AtkSelection *obj,
 108                              gint         i)
 109 {
 110   AtkSelectionIface *iface;
 111
 112   g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 113
 114   iface = ATK_SELECTION_GET_IFACE (obj);
 115
 116   if (iface->add_selection)
 117     return (iface->add_selection) (obj, i);
 118   else
 119     return FALSE;
 120 }
 121
 122 /**
 123  * atk_selection_clear_selection:
 124  * @selection: a #GObject instance that implements AtkSelectionIface
 125  *
 126  * Clears the selection in the object so that no children in the object
 127  * are selected.
 128  *
 129  * Returns: TRUE if success, FALSE otherwise.
 130  **/
 131 gboolean
 132 atk_selection_clear_selection (AtkSelection *obj)
 133 {
 134   AtkSelectionIface *iface;
 135
 136   g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 137
 138   iface = ATK_SELECTION_GET_IFACE (obj);
 139
 140   if (iface->clear_selection)
 141     return (iface->clear_selection) (obj);
 142   else
 143     return FALSE;
 144 }
 145
 146 /**
 147  * atk_selection_ref_selection:
 148  * @selection: a #GObject instance that implements AtkSelectionIface
 149  * @i: a #gint specifying the index in the selection set.  (e.g. the
 150  * ith selection as opposed to the ith child).
 151  *
 152  * Gets a reference to the accessible object representing the specified
 153  * selected child of the object.
 154  * Note: callers should not rely on %NULL or on a zero value for
 155  * indication of whether AtkSelectionIface is implemented, they should
 156  * use type checking/interface checking macros or the
 157  * atk_get_accessible_value() convenience method.
 158  *
 159  * Returns: (transfer full): an #AtkObject representing the selected
 160  * accessible , or %NULL if @selection does not implement this interface.
 161  **/
 162 AtkObject*
 163 atk_selection_ref_selection (AtkSelection *obj,
 164                              gint         i)
 165 {
 166   AtkSelectionIface *iface;
 167
 168   g_return_val_if_fail (ATK_IS_SELECTION (obj), NULL);
 169
 170   iface = ATK_SELECTION_GET_IFACE (obj);
 171
 172   if (iface->ref_selection)
 173     return (iface->ref_selection) (obj, i);
 174   else
 175     return NULL;
 176 }
 177
 178 /**
 179  * atk_selection_get_selection_count:
 180  * @selection: a #GObject instance that implements AtkSelectionIface
 181  *
 182  * Gets the number of accessible children currently selected.
 183  * Note: callers should not rely on %NULL or on a zero value for
 184  * indication of whether AtkSelectionIface is implemented, they should
 185  * use type checking/interface checking macros or the
 186  * atk_get_accessible_value() convenience method.
 187  *
 188  * Returns: a gint representing the number of items selected, or 0
 189  * if @selection does not implement this interface.
 190  **/
 191 gint
 192 atk_selection_get_selection_count (AtkSelection *obj)
 193 {
 194   AtkSelectionIface *iface;
 195
 196   g_return_val_if_fail (ATK_IS_SELECTION (obj), 0);
 197
 198   iface = ATK_SELECTION_GET_IFACE (obj);
 199
 200   if (iface->get_selection_count)
 201     return (iface->get_selection_count) (obj);
 202   else
 203     return 0;
 204 }
 205
 206 /**
 207  * atk_selection_is_child_selected:
 208  * @selection: a #GObject instance that implements AtkSelectionIface
 209  * @i: a #gint specifying the child index.
 210  *
 211  * Determines if the current child of this object is selected
 212  * Note: callers should not rely on %NULL or on a zero value for
 213  * indication of whether AtkSelectionIface is implemented, they should
 214  * use type checking/interface checking macros or the
 215  * atk_get_accessible_value() convenience method.
 216  *
 217  * Returns: a gboolean representing the specified child is selected, or 0
 218  * if @selection does not implement this interface.
 219  **/
 220 gboolean
 221 atk_selection_is_child_selected (AtkSelection *obj,
 222                                  gint         i)
 223 {
 224   AtkSelectionIface *iface;
 225
 226   g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 227
 228   iface = ATK_SELECTION_GET_IFACE (obj);
 229
 230   if (iface->is_child_selected)
 231     return (iface->is_child_selected) (obj, i);
 232   else
 233     return FALSE;
 234 }
 235
 236 /**
 237  * atk_selection_remove_selection:
 238  * @selection: a #GObject instance that implements AtkSelectionIface
 239  * @i: a #gint specifying the index in the selection set.  (e.g. the
 240  * ith selection as opposed to the ith child).
 241  *
 242  * Removes the specified child of the object from the object's selection.
 243  *
 244  * Returns: TRUE if success, FALSE otherwise.
 245  **/
 246 gboolean
 247 atk_selection_remove_selection (AtkSelection *obj,
 248                                 gint         i)
 249 {
 250   AtkSelectionIface *iface;
 251
 252   g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 253
 254   iface = ATK_SELECTION_GET_IFACE (obj);
 255
 256   if (iface->remove_selection)
 257     return (iface->remove_selection) (obj, i);
 258   else
 259     return FALSE;
 260 }
 261
 262 /**
 263  * atk_selection_select_all_selection:
 264  * @selection: a #GObject instance that implements AtkSelectionIface
 265  *
 266  * Causes every child of the object to be selected if the object
 267  * supports multiple selections.
 268  *
 269  * Returns: TRUE if success, FALSE otherwise.
 270  **/
 271 gboolean
 272 atk_selection_select_all_selection (AtkSelection *obj)
 273 {
 274   AtkSelectionIface *iface;
 275
 276   g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 277
 278   iface = ATK_SELECTION_GET_IFACE (obj);
 279
 280   if (iface->select_all_selection)
 281     return (iface->select_all_selection) (obj);
 282   else
 283     return FALSE;
 284 }