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