atk/atkcomponent.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 "atkcomponent.h"
  23
  24 /**
  25  * SECTION:atkcomponent
  26  * @Short_description: The ATK interface provided by UI components
  27  * which occupy a physical area on the screen.
  28  * which the user can activate/interact with.
  29  * @Title:AtkComponent
  30  *
  31  * #AtkComponent should be implemented by most if not all UI elements
  32  * with an actual on-screen presence, i.e. components which can be
  33  * said to have a screen-coordinate bounding box.  Virtually all
  34  * widgets will need to have #AtkComponent implementations provided
  35  * for their corresponding #AtkObject class.  In short, only UI
  36  * elements which are *not* GUI elements will omit this ATK interface.
  37  *
  38  * A possible exception might be textual information with a
  39  * transparent background, in which case text glyph bounding box
  40  * information is provided by #AtkText.
  41  */
  42
  43 enum {
  44   BOUNDS_CHANGED,
  45   LAST_SIGNAL
  46 };
  47
  48 static void       atk_component_base_init (AtkComponentIface *class);
  49
  50 static gboolean   atk_component_real_contains                (AtkComponent *component,
  51                                                               gint         x,
  52                                                               gint         y,
  53                                                               AtkCoordType coord_type);
  54
  55 static AtkObject* atk_component_real_ref_accessible_at_point (AtkComponent *component,
  56                                                               gint         x,
  57                                                               gint         y,
  58                                                               AtkCoordType coord_type);
  59
  60 static void      atk_component_real_get_position             (AtkComponent *component,
  61                                                               gint         *x,
  62                                                               gint         *y,
  63                                                               AtkCoordType coord_type);
  64
  65 static void      atk_component_real_get_size                 (AtkComponent *component,
  66                                                               gint         *width,
  67                                                               gint         *height);
  68
  69 static guint atk_component_signals[LAST_SIGNAL] = { 0 };
  70
  71 GType
  72 atk_component_get_type (void)
  73 {
  74   static GType type = 0;
  75
  76   if (!type) {
  77     static const GTypeInfo tinfo =
  78     {
  79       sizeof (AtkComponentIface),
  80       (GBaseInitFunc) atk_component_base_init,
  81       (GBaseFinalizeFunc) NULL,
  82
  83     };
  84
  85     type = g_type_register_static (G_TYPE_INTERFACE, "AtkComponent", &tinfo, 0);
  86   }
  87
  88   return type;
  89 }
  90
  91 static void
  92 atk_component_base_init (AtkComponentIface *class)
  93 {
  94   static gboolean initialized = FALSE;
  95
  96   if (! initialized)
  97     {
  98       class->ref_accessible_at_point = atk_component_real_ref_accessible_at_point;
  99       class->contains = atk_component_real_contains;
 100       class->get_position = atk_component_real_get_position;
 101       class->get_size = atk_component_real_get_size;
 102
 103
 104       /**
 105        * AtkComponent::bounds-changed:
 106        * @atkcomponent: the object which received the signal.
 107        * @arg1: The AtkRectangle giving the new position and size.
 108        *
 109        * The 'bounds-changed" signal is emitted when the bposition or
 110        * size of the component changes.
 111        */
 112       atk_component_signals[BOUNDS_CHANGED] =
 113         g_signal_new ("bounds_changed",
 114                       ATK_TYPE_COMPONENT,
 115                       G_SIGNAL_RUN_LAST,
 116                       G_STRUCT_OFFSET (AtkComponentIface, bounds_changed),
 117                       (GSignalAccumulator) NULL, NULL,
 118                       g_cclosure_marshal_VOID__BOXED,
 119                       G_TYPE_NONE, 1,
 120                       ATK_TYPE_RECTANGLE | G_SIGNAL_TYPE_STATIC_SCOPE);
 121
 122       initialized = TRUE;
 123     }
 124 }
 125
 126
 127 /**
 128  * atk_component_add_focus_handler:
 129  * @component: The #AtkComponent to attach the @handler to
 130  * @handler: The #AtkFocusHandler to be attached to @component
 131  *
 132  * Add the specified handler to the set of functions to be called
 133  * when this object receives focus events (in or out). If the handler is
 134  * already added it is not added again
 135  *
 136  * Deprecated: This method is deprecated since ATK version 2.9.4. If
 137  * you need to track when an object gains or lose the focus, use
 138  * state-changed:focused notification instead.
 139  *
 140  * Returns: a handler id which can be used in atk_component_remove_focus_handler()
 141  * or zero if the handler was already added.
 142  **/
 143 guint
 144 atk_component_add_focus_handler (AtkComponent    *component,
 145                                  AtkFocusHandler handler)
 146 {
 147   AtkComponentIface *iface = NULL;
 148   g_return_val_if_fail (ATK_IS_COMPONENT (component), 0);
 149
 150   iface = ATK_COMPONENT_GET_IFACE (component);
 151
 152   if (iface->add_focus_handler)
 153     return (iface->add_focus_handler) (component, handler);
 154   else
 155     return 0;
 156 }
 157
 158 /**
 159  * atk_component_remove_focus_handler:
 160  * @component: the #AtkComponent to remove the focus handler from
 161  * @handler_id: the handler id of the focus handler to be removed
 162  * from @component
 163  *
 164  * Remove the handler specified by @handler_id from the list of
 165  * functions to be executed when this object receives focus events
 166  * (in or out).
 167  *
 168  * Deprecated: This method is deprecated since ATK version 2.9.4. If
 169  * you need to track when an object gains or lose the focus, use
 170  * state-changed:focused notification instead.
 171  *
 172  **/
 173 void
 174 atk_component_remove_focus_handler (AtkComponent    *component,
 175                                     guint           handler_id)
 176 {
 177   AtkComponentIface *iface = NULL;
 178   g_return_if_fail (ATK_IS_COMPONENT (component));
 179
 180   iface = ATK_COMPONENT_GET_IFACE (component);
 181
 182   if (iface->remove_focus_handler)
 183     (iface->remove_focus_handler) (component, handler_id);
 184 }
 185
 186 /**
 187  * atk_component_contains:
 188  * @component: the #AtkComponent
 189  * @x: x coordinate
 190  * @y: y coordinate
 191  * @coord_type: specifies whether the coordinates are relative to the screen
 192  * or to the components top level window
 193  *
 194  * Checks whether the specified point is within the extent of the @component.
 195  *
 196  * Toolkit implementor note: ATK provides a default implementation for
 197  * this virtual method. In general there are little reason to
 198  * re-implement it.
 199  *
 200  * Returns: %TRUE or %FALSE indicating whether the specified point is within
 201  * the extent of the @component or not
 202  **/
 203 gboolean
 204 atk_component_contains (AtkComponent    *component,
 205                         gint            x,
 206                         gint            y,
 207                         AtkCoordType    coord_type)
 208 {
 209   AtkComponentIface *iface = NULL;
 210   g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
 211
 212   iface = ATK_COMPONENT_GET_IFACE (component);
 213
 214   if (iface->contains)
 215     return (iface->contains) (component, x, y, coord_type);
 216   else
 217     return FALSE;
 218 }
 219
 220 /**
 221  * atk_component_ref_accessible_at_point:
 222  * @component: the #AtkComponent
 223  * @x: x coordinate
 224  * @y: y coordinate
 225  * @coord_type: specifies whether the coordinates are relative to the screen
 226  * or to the components top level window
 227  *
 228  * Gets a reference to the accessible child, if one exists, at the
 229  * coordinate point specified by @x and @y.
 230  *
 231  * Returns: (transfer full): a reference to the accessible child, if one exists
 232  **/
 233 AtkObject*
 234 atk_component_ref_accessible_at_point (AtkComponent    *component,
 235                                        gint            x,
 236                                        gint            y,
 237                                        AtkCoordType    coord_type)
 238 {
 239   AtkComponentIface *iface = NULL;
 240   g_return_val_if_fail (ATK_IS_COMPONENT (component), NULL);
 241
 242   iface = ATK_COMPONENT_GET_IFACE (component);
 243
 244   if (iface->ref_accessible_at_point)
 245     return (iface->ref_accessible_at_point) (component, x, y, coord_type);
 246   else
 247     return NULL;
 248 }
 249
 250 /**
 251  * atk_component_get_extents:
 252  * @component: an #AtkComponent
 253  * @x: address of #gint to put x coordinate
 254  * @y: address of #gint to put y coordinate
 255  * @width: address of #gint to put width
 256  * @height: address of #gint to put height
 257  * @coord_type: specifies whether the coordinates are relative to the screen
 258  * or to the components top level window
 259  *
 260  * Gets the rectangle which gives the extent of the @component.
 261  *
 262  **/
 263 void
 264 atk_component_get_extents    (AtkComponent    *component,
 265                               gint            *x,
 266                               gint            *y,
 267                               gint            *width,
 268                               gint            *height,
 269                               AtkCoordType    coord_type)
 270 {
 271   AtkComponentIface *iface = NULL;
 272   gint local_x, local_y, local_width, local_height;
 273   gint *real_x, *real_y, *real_width, *real_height;
 274
 275   g_return_if_fail (ATK_IS_COMPONENT (component));
 276
 277   if (x)
 278     real_x = x;
 279   else
 280     real_x = &local_x;
 281   if (y)
 282     real_y = y;
 283   else
 284     real_y = &local_y;
 285   if (width)
 286     real_width = width;
 287   else
 288     real_width = &local_width;
 289   if (height)
 290     real_height = height;
 291   else
 292     real_height = &local_height;
 293
 294   iface = ATK_COMPONENT_GET_IFACE (component);
 295
 296   if (iface->get_extents)
 297     (iface->get_extents) (component, real_x, real_y, real_width, real_height, coord_type);
 298 }
 299
 300 /**
 301  * atk_component_get_position:
 302  * @component: an #AtkComponent
 303  * @x: address of #gint to put x coordinate position
 304  * @y: address of #gint to put y coordinate position
 305  * @coord_type: specifies whether the coordinates are relative to the screen
 306  * or to the components top level window
 307  *
 308  * Gets the position of @component in the form of
 309  * a point specifying @component's top-left corner.
 310  *
 311  * Deprecated: Since 2.12. Use atk_component_get_extents() instead.
 312  **/
 313 void
 314 atk_component_get_position   (AtkComponent    *component,
 315                               gint            *x,
 316                               gint            *y,
 317                               AtkCoordType    coord_type)
 318 {
 319   AtkComponentIface *iface = NULL;
 320   gint local_x, local_y;
 321   gint *real_x, *real_y;
 322
 323   g_return_if_fail (ATK_IS_COMPONENT (component));
 324
 325   if (x)
 326     real_x = x;
 327   else
 328     real_x = &local_x;
 329   if (y)
 330     real_y = y;
 331   else
 332     real_y = &local_y;
 333
 334   iface = ATK_COMPONENT_GET_IFACE (component);
 335
 336   if (iface->get_position)
 337     (iface->get_position) (component, real_x, real_y, coord_type);
 338 }
 339
 340 /**
 341  * atk_component_get_size:
 342  * @component: an #AtkComponent
 343  * @width: address of #gint to put width of @component
 344  * @height: address of #gint to put height of @component
 345  *
 346  * Gets the size of the @component in terms of width and height.
 347  *
 348  * Deprecated: Since 2.12. Use atk_component_get_extents() instead.
 349  **/
 350 void
 351 atk_component_get_size       (AtkComponent    *component,
 352                               gint            *width,
 353                               gint            *height)
 354 {
 355   AtkComponentIface *iface = NULL;
 356   gint local_width, local_height;
 357   gint *real_width, *real_height;
 358
 359   g_return_if_fail (ATK_IS_COMPONENT (component));
 360
 361   if (width)
 362     real_width = width;
 363   else
 364     real_width = &local_width;
 365   if (height)
 366     real_height = height;
 367   else
 368     real_height = &local_height;
 369
 370   g_return_if_fail (ATK_IS_COMPONENT (component));
 371
 372   iface = ATK_COMPONENT_GET_IFACE (component);
 373
 374   if (iface->get_size)
 375     (iface->get_size) (component, real_width, real_height);
 376 }
 377
 378 /**
 379  * atk_component_get_layer:
 380  * @component: an #AtkComponent
 381  *
 382  * Gets the layer of the component.
 383  *
 384  * Returns: an #AtkLayer which is the layer of the component
 385  **/
 386 AtkLayer
 387 atk_component_get_layer (AtkComponent *component)
 388 {
 389   AtkComponentIface *iface;
 390
 391   g_return_val_if_fail (ATK_IS_COMPONENT (component), ATK_LAYER_INVALID);
 392
 393   iface = ATK_COMPONENT_GET_IFACE (component);
 394   if (iface->get_layer)
 395     return (iface->get_layer) (component);
 396   else
 397     return ATK_LAYER_WIDGET;
 398 }
 399
 400 /**
 401  * atk_component_get_mdi_zorder:
 402  * @component: an #AtkComponent
 403  *
 404  * Gets the zorder of the component. The value G_MININT will be returned
 405  * if the layer of the component is not ATK_LAYER_MDI or ATK_LAYER_WINDOW.
 406  *
 407  * Returns: a gint which is the zorder of the component, i.e. the depth at
 408  * which the component is shown in relation to other components in the same
 409  * container.
 410  **/
 411 gint
 412 atk_component_get_mdi_zorder (AtkComponent *component)
 413 {
 414   AtkComponentIface *iface;
 415
 416   g_return_val_if_fail (ATK_IS_COMPONENT (component), G_MININT);
 417
 418   iface = ATK_COMPONENT_GET_IFACE (component);
 419   if (iface->get_mdi_zorder)
 420     return (iface->get_mdi_zorder) (component);
 421   else
 422     return G_MININT;
 423 }
 424
 425 /**
 426  * atk_component_get_alpha:
 427  * @component: an #AtkComponent
 428  *
 429  * Returns the alpha value (i.e. the opacity) for this
 430  * @component, on a scale from 0 (fully transparent) to 1.0
 431  * (fully opaque).
 432  *
 433  * Returns: An alpha value from 0 to 1.0, inclusive.
 434  * Since: 1.12
 435  **/
 436 gdouble
 437 atk_component_get_alpha (AtkComponent    *component)
 438 {
 439   AtkComponentIface *iface;
 440
 441   g_return_val_if_fail (ATK_IS_COMPONENT (component), G_MININT);
 442
 443   iface = ATK_COMPONENT_GET_IFACE (component);
 444   if (iface->get_alpha)
 445     return (iface->get_alpha) (component);
 446   else
 447     return (gdouble) 1.0;
 448 }
 449
 450 /**
 451  * atk_component_grab_focus:
 452  * @component: an #AtkComponent
 453  *
 454  * Grabs focus for this @component.
 455  *
 456  * Returns: %TRUE if successful, %FALSE otherwise.
 457  **/
 458 gboolean
 459 atk_component_grab_focus (AtkComponent    *component)
 460 {
 461   AtkComponentIface *iface = NULL;
 462   g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
 463
 464   iface = ATK_COMPONENT_GET_IFACE (component);
 465
 466   if (iface->grab_focus)
 467     return (iface->grab_focus) (component);
 468   else
 469     return FALSE;
 470 }
 471
 472 /**
 473  * atk_component_set_extents:
 474  * @component: an #AtkComponent
 475  * @x: x coordinate
 476  * @y: y coordinate
 477  * @width: width to set for @component
 478  * @height: height to set for @component
 479  * @coord_type: specifies whether the coordinates are relative to the screen
 480  * or to the components top level window
 481  *
 482  * Sets the extents of @component.
 483  *
 484  * Returns: %TRUE or %FALSE whether the extents were set or not
 485  **/
 486 gboolean
 487 atk_component_set_extents   (AtkComponent    *component,
 488                              gint            x,
 489                              gint            y,
 490                              gint            width,
 491                              gint            height,
 492                              AtkCoordType    coord_type)
 493 {
 494   AtkComponentIface *iface = NULL;
 495   g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
 496
 497   iface = ATK_COMPONENT_GET_IFACE (component);
 498
 499   if (iface->set_extents)
 500     return (iface->set_extents) (component, x, y, width, height, coord_type);
 501   else
 502     return FALSE;
 503 }
 504
 505 /**
 506  * atk_component_set_position:
 507  * @component: an #AtkComponent
 508  * @x: x coordinate
 509  * @y: y coordinate
 510  * @coord_type: specifies whether the coordinates are relative to the screen
 511  * or to the components top level window
 512  *
 513  * Sets the postition of @component.
 514  *
 515  * Returns: %TRUE or %FALSE whether or not the position was set or not
 516  **/
 517 gboolean
 518 atk_component_set_position   (AtkComponent    *component,
 519                               gint            x,
 520                               gint            y,
 521                               AtkCoordType    coord_type)
 522 {
 523   AtkComponentIface *iface = NULL;
 524   g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
 525
 526   iface = ATK_COMPONENT_GET_IFACE (component);
 527
 528   if (iface->set_position)
 529     return (iface->set_position) (component, x, y, coord_type);
 530   else
 531     return FALSE;
 532 }
 533
 534 /**
 535  * atk_component_set_size:
 536  * @component: an #AtkComponent
 537  * @width: width to set for @component
 538  * @height: height to set for @component
 539  *
 540  * Set the size of the @component in terms of width and height.
 541  *
 542  * Returns: %TRUE or %FALSE whether the size was set or not
 543  **/
 544 gboolean
 545 atk_component_set_size       (AtkComponent    *component,
 546                               gint            x,
 547                               gint            y)
 548 {
 549   AtkComponentIface *iface = NULL;
 550   g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
 551
 552   iface = ATK_COMPONENT_GET_IFACE (component);
 553
 554   if (iface->set_size)
 555     return (iface->set_size) (component, x, y);
 556   else
 557     return FALSE;
 558 }
 559
 560 static gboolean
 561 atk_component_real_contains (AtkComponent *component,
 562                              gint         x,
 563                              gint         y,
 564                              AtkCoordType coord_type)
 565 {
 566   gint real_x, real_y, width, height;
 567
 568   real_x = real_y = width = height = 0;
 569
 570   atk_component_get_extents (component, &real_x, &real_y, &width, &height, coord_type);
 571
 572   if ((x >= real_x) &&
 573       (x < real_x + width) &&
 574       (y >= real_y) &&
 575       (y < real_y + height))
 576     return TRUE;
 577   else
 578     return FALSE;
 579 }
 580
 581 static AtkObject*
 582 atk_component_real_ref_accessible_at_point (AtkComponent *component,
 583                                             gint         x,
 584                                             gint         y,
 585                                             AtkCoordType coord_type)
 586 {
 587   gint count, i;
 588
 589   count = atk_object_get_n_accessible_children (ATK_OBJECT (component));
 590
 591   for (i = 0; i < count; i++)
 592   {
 593     AtkObject *obj;
 594
 595     obj = atk_object_ref_accessible_child (ATK_OBJECT (component), i);
 596
 597     if (obj != NULL)
 598     {
 599       if (atk_component_contains (ATK_COMPONENT (obj), x, y, coord_type))
 600       {
 601         return obj;
 602       }
 603       else
 604       {
 605         g_object_unref (obj);
 606       }
 607     }
 608   }
 609   return NULL;
 610 }
 611
 612 static void
 613 atk_component_real_get_position (AtkComponent *component,
 614                                  gint         *x,
 615                                  gint         *y,
 616                                  AtkCoordType coord_type)
 617 {
 618   gint width, height;
 619
 620   atk_component_get_extents (component, x, y, &width, &height, coord_type);
 621 }
 622
 623 static void
 624 atk_component_real_get_size (AtkComponent *component,
 625                              gint         *width,
 626                              gint         *height)
 627 {
 628   gint x, y;
 629   AtkCoordType coord_type;
 630
 631   /*
 632    * Pick one coordinate type; it does not matter for size
 633    */
 634   coord_type = ATK_XY_WINDOW;
 635
 636   atk_component_get_extents (component, &x, &y, width, height, coord_type);
 637 }
 638
 639 static AtkRectangle *
 640 atk_rectangle_copy (const AtkRectangle *rectangle)
 641 {
 642   AtkRectangle *result = g_new (AtkRectangle, 1);
 643   *result = *rectangle;
 644
 645   return result;
 646 }
 647
 648 GType
 649 atk_rectangle_get_type (void)
 650 {
 651   static GType our_type = 0;
 652
 653   if (our_type == 0)
 654     our_type = g_boxed_type_register_static ("AtkRectangle",
 655                                              (GBoxedCopyFunc)atk_rectangle_copy,
 656                                              (GBoxedFreeFunc)g_free);
 657   return our_type;
 658 }
 659