atk/atkhyperlink.c

   1 /* ATK -  Accessibility Toolkit
   2  * Copyright 2001, 2002, 2003 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 #include "atkhyperlink.h"
  22 #include <glib/gi18n-lib.h>
  23
  24 /**
  25  * SECTION:atkhyperlink
  26  * @Short_description: An ATK object which encapsulates a link or set
  27  *  of links in a hypertext document.
  28  * @Title:AtkHyperlink
  29  *
  30  * An ATK object which encapsulates a link or set of links (for
  31  * instance in the case of client-side image maps) in a hypertext
  32  * document.  It may implement the AtkAction interface.  AtkHyperlink
  33  * may also be used to refer to inline embedded content, since it
  34  * allows specification of a start and end offset within the host
  35  * AtkHypertext object.
  36  */
  37
  38 enum
  39 {
  40   LINK_ACTIVATED,
  41
  42   LAST_SIGNAL
  43 };
  44
  45 enum
  46 {
  47   PROP_0,  /* gobject convention */
  48
  49   PROP_SELECTED_LINK,
  50   PROP_NUMBER_ANCHORS,
  51   PROP_END_INDEX,
  52   PROP_START_INDEX,
  53   PROP_LAST
  54 };
  55
  56 static void atk_hyperlink_class_init (AtkHyperlinkClass *klass);
  57 static void atk_hyperlink_init       (AtkHyperlink      *link,
  58                                       AtkHyperlinkClass *klass);
  59
  60 static void atk_hyperlink_real_get_property (GObject            *object,
  61                                              guint              prop_id,
  62                                              GValue             *value,
  63                                              GParamSpec         *pspec);
  64
  65 static void atk_hyperlink_action_iface_init (AtkActionIface *iface);
  66
  67 static guint atk_hyperlink_signals[LAST_SIGNAL] = { 0, };
  68
  69 static gpointer  parent_class = NULL;
  70
  71 GType
  72 atk_hyperlink_get_type (void)
  73 {
  74   static GType type = 0;
  75
  76   if (!type)
  77     {
  78       static const GTypeInfo typeInfo =
  79       {
  80         sizeof (AtkHyperlinkClass),
  81         (GBaseInitFunc) NULL,
  82         (GBaseFinalizeFunc) NULL,
  83         (GClassInitFunc) atk_hyperlink_class_init,
  84         (GClassFinalizeFunc) NULL,
  85         NULL,
  86         sizeof (AtkHyperlink),
  87         0,
  88         (GInstanceInitFunc) atk_hyperlink_init,
  89       } ;
  90
  91       static const GInterfaceInfo action_info =
  92       {
  93         (GInterfaceInitFunc) atk_hyperlink_action_iface_init,
  94         (GInterfaceFinalizeFunc) NULL,
  95         NULL
  96       };
  97
  98       type = g_type_register_static (G_TYPE_OBJECT, "AtkHyperlink", &typeInfo, 0) ;
  99       g_type_add_interface_static (type, ATK_TYPE_ACTION, &action_info);
 100     }
 101   return type;
 102 }
 103
 104 static void
 105 atk_hyperlink_class_init (AtkHyperlinkClass *klass)
 106 {
 107   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 108
 109   parent_class = g_type_class_peek_parent (klass);
 110
 111   gobject_class->get_property = atk_hyperlink_real_get_property;
 112
 113   klass->link_activated = NULL;
 114
 115   /**
 116    * AtkHyperlink:selected-link:
 117    *
 118    * Selected link
 119    *
 120    * Deprecated: Since 1.8. This property is deprecated since ATK
 121    * version 1.8. Please use ATK_STATE_FOCUSABLE for all links, and
 122    * ATK_STATE_FOCUSED for focused links.
 123    *
 124    */
 125   g_object_class_install_property (gobject_class,
 126                                    PROP_SELECTED_LINK,
 127                                    g_param_spec_boolean ("selected-link",
 128                                                          _("Selected Link"),
 129                                                          _("Specifies whether the AtkHyperlink object is selected"),
 130                                                          FALSE,
 131                                                          G_PARAM_READABLE));
 132   g_object_class_install_property (gobject_class,
 133                                    PROP_NUMBER_ANCHORS,
 134                                    g_param_spec_int ("number-of-anchors",
 135                                                      _("Number of Anchors"),
 136                                                      _("The number of anchors associated with the AtkHyperlink object"),
 137                                                      0,
 138                                                      G_MAXINT,
 139                                                      0,
 140                                                      G_PARAM_READABLE));
 141   g_object_class_install_property (gobject_class,
 142                                    PROP_END_INDEX,
 143                                    g_param_spec_int ("end-index",
 144                                                      _("End index"),
 145                                                      _("The end index of the AtkHyperlink object"),
 146                                                      0,
 147                                                      G_MAXINT,
 148                                                      0,
 149                                                      G_PARAM_READABLE));
 150   g_object_class_install_property (gobject_class,
 151                                    PROP_START_INDEX,
 152                                    g_param_spec_int ("start-index",
 153                                                      _("Start index"),
 154                                                      _("The start index of the AtkHyperlink object"),
 155                                                      0,
 156                                                      G_MAXINT,
 157                                                      0,
 158                                                      G_PARAM_READABLE));
 159
 160   /**
 161    * AtkHyperlink::link-activated:
 162    * @atkhyperlink: the object which received the signal.
 163    *
 164    * The signal link-activated is emitted when a link is activated.
 165    */
 166   atk_hyperlink_signals[LINK_ACTIVATED] =
 167     g_signal_new ("link_activated",
 168                   G_TYPE_FROM_CLASS (klass),
 169                   G_SIGNAL_RUN_LAST,
 170                   G_STRUCT_OFFSET (AtkHyperlinkClass, link_activated),
 171                   NULL, NULL,
 172                   g_cclosure_marshal_VOID__VOID,
 173                   G_TYPE_NONE,
 174                   0);
 175
 176 }
 177
 178 static void
 179 atk_hyperlink_init  (AtkHyperlink        *link,
 180                      AtkHyperlinkClass   *klass)
 181 {
 182 }
 183
 184 static void
 185 atk_hyperlink_real_get_property (GObject    *object,
 186                                  guint      prop_id,
 187                                  GValue     *value,
 188                                  GParamSpec *pspec)
 189 {
 190   AtkHyperlink* link;
 191
 192   link = ATK_HYPERLINK (object);
 193
 194   switch (prop_id)
 195     {
 196     case PROP_SELECTED_LINK:
 197       // This property is deprecated, also the method to get the value
 198       g_value_set_boolean (value, FALSE);
 199       break;
 200     case PROP_NUMBER_ANCHORS:
 201       g_value_set_int (value,  atk_hyperlink_get_n_anchors (link));
 202       break;
 203     case PROP_END_INDEX:
 204       g_value_set_int (value, atk_hyperlink_get_end_index (link));
 205       break;
 206     case PROP_START_INDEX:
 207       g_value_set_int (value, atk_hyperlink_get_start_index (link));
 208       break;
 209     default:
 210       break;
 211     }
 212 }
 213
 214 /**
 215  * atk_hyperlink_get_uri:
 216  * @link_: an #AtkHyperlink
 217  * @i: a (zero-index) integer specifying the desired anchor
 218  *
 219  * Get a the URI associated with the anchor specified
 220  * by @i of @link_.
 221  *
 222  * Multiple anchors are primarily used by client-side image maps.
 223  *
 224  * Returns: a string specifying the URI
 225  **/
 226 gchar*
 227 atk_hyperlink_get_uri (AtkHyperlink *link,
 228                        gint         i)
 229 {
 230   AtkHyperlinkClass *klass;
 231
 232   g_return_val_if_fail (ATK_IS_HYPERLINK (link), NULL);
 233
 234   klass = ATK_HYPERLINK_GET_CLASS (link);
 235   if (klass->get_uri)
 236     return (klass->get_uri) (link, i);
 237   else
 238     return NULL;
 239 }
 240
 241 /**
 242  * atk_hyperlink_get_object:
 243  * @link_: an #AtkHyperlink
 244  * @i: a (zero-index) integer specifying the desired anchor
 245  *
 246  * Returns the item associated with this hyperlinks nth anchor.
 247  * For instance, the returned #AtkObject will implement #AtkText
 248  * if @link_ is a text hyperlink, #AtkImage if @link_ is an image
 249  * hyperlink etc.
 250  *
 251  * Multiple anchors are primarily used by client-side image maps.
 252  *
 253  * Returns: (transfer none): an #AtkObject associated with this hyperlinks
 254  * i-th anchor
 255  **/
 256 AtkObject*
 257 atk_hyperlink_get_object (AtkHyperlink *link,
 258                           gint         i)
 259 {
 260   AtkHyperlinkClass *klass;
 261
 262   g_return_val_if_fail (ATK_IS_HYPERLINK (link), NULL);
 263
 264   klass = ATK_HYPERLINK_GET_CLASS (link);
 265   if (klass->get_object)
 266     return (klass->get_object) (link, i);
 267   else
 268     return NULL;
 269 }
 270
 271 /**
 272  * atk_hyperlink_get_end_index:
 273  * @link_: an #AtkHyperlink
 274  *
 275  * Gets the index with the hypertext document at which this link ends.
 276  *
 277  * Returns: the index with the hypertext document at which this link ends
 278  **/
 279 gint
 280 atk_hyperlink_get_end_index (AtkHyperlink *link)
 281 {
 282   AtkHyperlinkClass *klass;
 283
 284   g_return_val_if_fail (ATK_IS_HYPERLINK (link), 0);
 285
 286   klass = ATK_HYPERLINK_GET_CLASS (link);
 287   if (klass->get_end_index)
 288     return (klass->get_end_index) (link);
 289   else
 290     return 0;
 291 }
 292
 293 /**
 294  * atk_hyperlink_get_start_index:
 295  * @link_: an #AtkHyperlink
 296  *
 297  * Gets the index with the hypertext document at which this link begins.
 298  *
 299  * Returns: the index with the hypertext document at which this link begins
 300  **/
 301 gint
 302 atk_hyperlink_get_start_index (AtkHyperlink *link)
 303 {
 304   AtkHyperlinkClass *klass;
 305
 306   g_return_val_if_fail (ATK_IS_HYPERLINK (link), 0);
 307
 308   klass = ATK_HYPERLINK_GET_CLASS (link);
 309   if (klass->get_start_index)
 310     return (klass->get_start_index) (link);
 311   else
 312     return 0;
 313 }
 314
 315 /**
 316  * atk_hyperlink_is_valid:
 317  * @link_: an #AtkHyperlink
 318  *
 319  * Since the document that a link is associated with may have changed
 320  * this method returns %TRUE if the link is still valid (with
 321  * respect to the document it references) and %FALSE otherwise.
 322  *
 323  * Returns: whether or not this link is still valid
 324  **/
 325 gboolean
 326 atk_hyperlink_is_valid (AtkHyperlink *link)
 327 {
 328   AtkHyperlinkClass *klass;
 329
 330   g_return_val_if_fail (ATK_IS_HYPERLINK (link), FALSE);
 331
 332   klass = ATK_HYPERLINK_GET_CLASS (link);
 333   if (klass->is_valid)
 334     return (klass->is_valid) (link);
 335   else
 336     return FALSE;
 337 }
 338
 339 /**
 340  * atk_hyperlink_is_inline:
 341  * @link_: an #AtkHyperlink
 342  *
 343  * Indicates whether the link currently displays some or all of its
 344  *           content inline.  Ordinary HTML links will usually return
 345  *           %FALSE, but an inline &lt;src&gt; HTML element will return
 346  *           %TRUE.
 347  *
 348  * Returns: whether or not this link displays its content inline.
 349  *
 350  **/
 351 gboolean
 352 atk_hyperlink_is_inline (AtkHyperlink *link)
 353 {
 354   AtkHyperlinkClass *klass;
 355
 356   g_return_val_if_fail (ATK_IS_HYPERLINK (link), FALSE);
 357
 358   klass = ATK_HYPERLINK_GET_CLASS (link);
 359   if (klass->link_state)
 360     return (klass->link_state (link) & ATK_HYPERLINK_IS_INLINE);
 361   else
 362     return FALSE;
 363 }
 364
 365 /**
 366  * atk_hyperlink_get_n_anchors:
 367  * @link_: an #AtkHyperlink
 368  *
 369  * Gets the number of anchors associated with this hyperlink.
 370  *
 371  * Returns: the number of anchors associated with this hyperlink
 372  **/
 373 gint
 374 atk_hyperlink_get_n_anchors (AtkHyperlink *link)
 375 {
 376   AtkHyperlinkClass *klass;
 377
 378   g_return_val_if_fail (ATK_IS_HYPERLINK (link), 0);
 379
 380   klass = ATK_HYPERLINK_GET_CLASS (link);
 381   if (klass->get_n_anchors)
 382     return (klass->get_n_anchors) (link);
 383   else
 384     return 0;
 385 }
 386
 387 /**
 388  * atk_hyperlink_is_selected_link:
 389  * @link_: an #AtkHyperlink
 390  *
 391  * Determines whether this AtkHyperlink is selected
 392  *
 393  * Since: 1.4
 394  *
 395  * Deprecated: This method is deprecated since ATK version 1.8.
 396  * Please use ATK_STATE_FOCUSABLE for all links, and ATK_STATE_FOCUSED
 397  * for focused links.
 398  *
 399  * Returns: True if the AtkHyperlink is selected, False otherwise
 400  **/
 401 gboolean
 402 atk_hyperlink_is_selected_link (AtkHyperlink *link)
 403 {
 404   AtkHyperlinkClass *klass;
 405
 406   g_return_val_if_fail (ATK_IS_HYPERLINK (link), FALSE);
 407
 408   klass = ATK_HYPERLINK_GET_CLASS (link);
 409   if (klass->is_selected_link)
 410     return (klass->is_selected_link) (link);
 411   else
 412     return FALSE;
 413 }
 414
 415 static void atk_hyperlink_action_iface_init (AtkActionIface *iface)
 416 {
 417   /*
 418    * We do nothing here
 419    *
 420    * When we come to derive a class from AtkHyperlink we will provide an
 421    * implementation of the AtkAction interface.
 422    */
 423 }