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