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