1 /* ATK - Accessibility Toolkit
2 * Copyright 2001 Sun Microsystems Inc.
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.
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.
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.
22 #include "atkcomponent.h"
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.
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.
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.
48 static void atk_component_base_init (AtkComponentIface *class);
50 static gboolean atk_component_real_contains (AtkComponent *component,
53 AtkCoordType coord_type);
55 static AtkObject* atk_component_real_ref_accessible_at_point (AtkComponent *component,
58 AtkCoordType coord_type);
60 static void atk_component_real_get_position (AtkComponent *component,
63 AtkCoordType coord_type);
65 static void atk_component_real_get_size (AtkComponent *component,
69 static guint atk_component_signals[LAST_SIGNAL] = { 0 };
72 atk_component_get_type (void)
74 static GType type = 0;
77 static const GTypeInfo tinfo =
79 sizeof (AtkComponentIface),
80 (GBaseInitFunc) atk_component_base_init,
81 (GBaseFinalizeFunc) NULL,
85 type = g_type_register_static (G_TYPE_INTERFACE, "AtkComponent", &tinfo, 0);
92 atk_component_base_init (AtkComponentIface *class)
94 static gboolean initialized = FALSE;
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;
105 * AtkComponent::bounds-changed:
106 * @atkcomponent: the object which received the signal.
107 * @arg1: The AtkRectangle giving the new position and size.
109 * The 'bounds-changed" signal is emitted when the bposition or
110 * size of the component changes.
112 atk_component_signals[BOUNDS_CHANGED] =
113 g_signal_new ("bounds_changed",
116 G_STRUCT_OFFSET (AtkComponentIface, bounds_changed),
117 (GSignalAccumulator) NULL, NULL,
118 g_cclosure_marshal_VOID__BOXED,
120 ATK_TYPE_RECTANGLE | G_SIGNAL_TYPE_STATIC_SCOPE);
128 * atk_component_add_focus_handler: (skip)
129 * @component: The #AtkComponent to attach the @handler to
130 * @handler: The #AtkFocusHandler to be attached to @component
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
136 * Deprecated: 2.9.4: If you need to track when an object gains or
137 * lose the focus, use the #AtkObject::state-change "focused" notification instead.
139 * Returns: a handler id which can be used in atk_component_remove_focus_handler()
140 * or zero if the handler was already added.
143 atk_component_add_focus_handler (AtkComponent *component,
144 AtkFocusHandler handler)
146 AtkComponentIface *iface = NULL;
147 g_return_val_if_fail (ATK_IS_COMPONENT (component), 0);
149 iface = ATK_COMPONENT_GET_IFACE (component);
151 if (iface->add_focus_handler)
152 return (iface->add_focus_handler) (component, handler);
158 * atk_component_remove_focus_handler:
159 * @component: the #AtkComponent to remove the focus handler from
160 * @handler_id: the handler id of the focus handler to be removed
163 * Remove the handler specified by @handler_id from the list of
164 * functions to be executed when this object receives focus events
167 * Deprecated: 2.9.4: If you need to track when an object gains or
168 * lose the focus, use the #AtkObject::state-change "focused" notification instead.
172 atk_component_remove_focus_handler (AtkComponent *component,
175 AtkComponentIface *iface = NULL;
176 g_return_if_fail (ATK_IS_COMPONENT (component));
178 iface = ATK_COMPONENT_GET_IFACE (component);
180 if (iface->remove_focus_handler)
181 (iface->remove_focus_handler) (component, handler_id);
185 * atk_component_contains:
186 * @component: the #AtkComponent
189 * @coord_type: specifies whether the coordinates are relative to the screen
190 * or to the components top level window
192 * Checks whether the specified point is within the extent of the @component.
194 * Toolkit implementor note: ATK provides a default implementation for
195 * this virtual method. In general there are little reason to
198 * Returns: %TRUE or %FALSE indicating whether the specified point is within
199 * the extent of the @component or not
202 atk_component_contains (AtkComponent *component,
205 AtkCoordType coord_type)
207 AtkComponentIface *iface = NULL;
208 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
210 iface = ATK_COMPONENT_GET_IFACE (component);
213 return (iface->contains) (component, x, y, coord_type);
219 * atk_component_ref_accessible_at_point:
220 * @component: the #AtkComponent
223 * @coord_type: specifies whether the coordinates are relative to the screen
224 * or to the components top level window
226 * Gets a reference to the accessible child, if one exists, at the
227 * coordinate point specified by @x and @y.
229 * Returns: (nullable) (transfer full): a reference to the accessible
230 * child, if one exists
233 atk_component_ref_accessible_at_point (AtkComponent *component,
236 AtkCoordType coord_type)
238 AtkComponentIface *iface = NULL;
239 g_return_val_if_fail (ATK_IS_COMPONENT (component), NULL);
241 iface = ATK_COMPONENT_GET_IFACE (component);
243 if (iface->ref_accessible_at_point)
244 return (iface->ref_accessible_at_point) (component, x, y, coord_type);
250 * atk_component_get_extents:
251 * @component: an #AtkComponent
252 * @x: (out) (optional): address of #gint to put x coordinate
253 * @y: (out) (optional): address of #gint to put y coordinate
254 * @width: (out) (optional): address of #gint to put width
255 * @height: (out) (optional): address of #gint to put height
256 * @coord_type: specifies whether the coordinates are relative to the screen
257 * or to the components top level window
259 * Gets the rectangle which gives the extent of the @component.
261 * If the extent can not be obtained (e.g. a non-embedded plug or missing
262 * support), all of x, y, width, height are set to -1.
266 atk_component_get_extents (AtkComponent *component,
271 AtkCoordType coord_type)
273 AtkComponentIface *iface = NULL;
274 gint local_x, local_y, local_width, local_height;
275 gint *real_x, *real_y, *real_width, *real_height;
277 g_return_if_fail (ATK_IS_COMPONENT (component));
290 real_width = &local_width;
292 real_height = height;
294 real_height = &local_height;
296 iface = ATK_COMPONENT_GET_IFACE (component);
298 if (iface->get_extents)
299 (iface->get_extents) (component, real_x, real_y, real_width, real_height, coord_type);
310 * atk_component_get_position:
311 * @component: an #AtkComponent
312 * @x: (out) (optional): address of #gint to put x coordinate position
313 * @y: (out) (optional): address of #gint to put y coordinate position
314 * @coord_type: specifies whether the coordinates are relative to the screen
315 * or to the components top level window
317 * Gets the position of @component in the form of
318 * a point specifying @component's top-left corner.
320 * If the position can not be obtained (e.g. a non-embedded plug or missing
321 * support), x and y are set to -1.
323 * Deprecated: Since 2.12. Use atk_component_get_extents() instead.
326 atk_component_get_position (AtkComponent *component,
329 AtkCoordType coord_type)
331 AtkComponentIface *iface = NULL;
332 gint local_x, local_y;
333 gint *real_x, *real_y;
335 g_return_if_fail (ATK_IS_COMPONENT (component));
346 iface = ATK_COMPONENT_GET_IFACE (component);
348 if (iface->get_position)
349 (iface->get_position) (component, real_x, real_y, coord_type);
358 * atk_component_get_size:
359 * @component: an #AtkComponent
360 * @width: (out) (optional): address of #gint to put width of @component
361 * @height: (out) (optional): address of #gint to put height of @component
363 * Gets the size of the @component in terms of width and height.
365 * If the size can not be obtained (e.g. a non-embedded plug or missing
366 * support), width and height are set to -1.
368 * Deprecated: Since 2.12. Use atk_component_get_extents() instead.
371 atk_component_get_size (AtkComponent *component,
375 AtkComponentIface *iface = NULL;
376 gint local_width, local_height;
377 gint *real_width, *real_height;
379 g_return_if_fail (ATK_IS_COMPONENT (component));
384 real_width = &local_width;
386 real_height = height;
388 real_height = &local_height;
390 g_return_if_fail (ATK_IS_COMPONENT (component));
392 iface = ATK_COMPONENT_GET_IFACE (component);
395 (iface->get_size) (component, real_width, real_height);
404 * atk_component_get_layer:
405 * @component: an #AtkComponent
407 * Gets the layer of the component.
409 * Returns: an #AtkLayer which is the layer of the component
412 atk_component_get_layer (AtkComponent *component)
414 AtkComponentIface *iface;
416 g_return_val_if_fail (ATK_IS_COMPONENT (component), ATK_LAYER_INVALID);
418 iface = ATK_COMPONENT_GET_IFACE (component);
419 if (iface->get_layer)
420 return (iface->get_layer) (component);
422 return ATK_LAYER_WIDGET;
426 * atk_component_get_mdi_zorder:
427 * @component: an #AtkComponent
429 * Gets the zorder of the component. The value G_MININT will be returned
430 * if the layer of the component is not ATK_LAYER_MDI or ATK_LAYER_WINDOW.
432 * Returns: a gint which is the zorder of the component, i.e. the depth at
433 * which the component is shown in relation to other components in the same
437 atk_component_get_mdi_zorder (AtkComponent *component)
439 AtkComponentIface *iface;
441 g_return_val_if_fail (ATK_IS_COMPONENT (component), G_MININT);
443 iface = ATK_COMPONENT_GET_IFACE (component);
444 if (iface->get_mdi_zorder)
445 return (iface->get_mdi_zorder) (component);
451 * atk_component_get_alpha:
452 * @component: an #AtkComponent
454 * Returns the alpha value (i.e. the opacity) for this
455 * @component, on a scale from 0 (fully transparent) to 1.0
458 * Returns: An alpha value from 0 to 1.0, inclusive.
462 atk_component_get_alpha (AtkComponent *component)
464 AtkComponentIface *iface;
466 g_return_val_if_fail (ATK_IS_COMPONENT (component), G_MININT);
468 iface = ATK_COMPONENT_GET_IFACE (component);
469 if (iface->get_alpha)
470 return (iface->get_alpha) (component);
472 return (gdouble) 1.0;
476 * atk_component_grab_focus:
477 * @component: an #AtkComponent
479 * Grabs focus for this @component.
481 * Returns: %TRUE if successful, %FALSE otherwise.
484 atk_component_grab_focus (AtkComponent *component)
486 AtkComponentIface *iface = NULL;
487 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
489 iface = ATK_COMPONENT_GET_IFACE (component);
491 if (iface->grab_focus)
492 return (iface->grab_focus) (component);
498 * atk_component_grab_highlight:
499 * @component: an #AtkComponent
501 * Grabs highlight for this @component.
503 * Returns: %TRUE if successful, %FALSE otherwise.
506 atk_component_grab_highlight (AtkComponent *component)
508 AtkComponentIface *iface = NULL;
509 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
511 iface = ATK_COMPONENT_GET_IFACE (component);
513 if (iface->grab_highlight)
514 return (iface->grab_highlight) (component);
520 * atk_component_clear_highlight:
521 * @component: an #AtkComponent
523 * Clears highlight for this @component.
525 * Returns: %TRUE if successful, %FALSE otherwise.
528 atk_component_clear_highlight (AtkComponent *component)
530 AtkComponentIface *iface = NULL;
531 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
533 iface = ATK_COMPONENT_GET_IFACE (component);
535 if (iface->clear_highlight)
536 return (iface->clear_highlight) (component);
542 * atk_component_get_highlight_index:
543 * @component: an #AtkComponent
545 * Returns: highlight index of the @component (if >0),
546 * 0 if highlight index is not set or -1 if an error occured.
550 atk_component_get_highlight_index (AtkComponent *component)
552 AtkComponentIface *iface = NULL;
553 g_return_val_if_fail (ATK_IS_COMPONENT (component), -1);
555 iface = ATK_COMPONENT_GET_IFACE (component);
557 if (iface->get_highlight_index)
558 return (iface->get_highlight_index) (component);
564 * atk_component_set_extents:
565 * @component: an #AtkComponent
568 * @width: width to set for @component
569 * @height: height to set for @component
570 * @coord_type: specifies whether the coordinates are relative to the screen
571 * or to the components top level window
573 * Sets the extents of @component.
575 * Returns: %TRUE or %FALSE whether the extents were set or not
578 atk_component_set_extents (AtkComponent *component,
583 AtkCoordType coord_type)
585 AtkComponentIface *iface = NULL;
586 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
588 iface = ATK_COMPONENT_GET_IFACE (component);
590 if (iface->set_extents)
591 return (iface->set_extents) (component, x, y, width, height, coord_type);
597 * atk_component_set_position:
598 * @component: an #AtkComponent
601 * @coord_type: specifies whether the coordinates are relative to the screen
602 * or to the component's top level window
604 * Sets the position of @component.
606 * Contrary to atk_component_scroll_to, this does not trigger any scrolling,
607 * this just moves @component in its parent.
609 * Returns: %TRUE or %FALSE whether or not the position was set or not
612 atk_component_set_position (AtkComponent *component,
615 AtkCoordType coord_type)
617 AtkComponentIface *iface = NULL;
618 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
620 iface = ATK_COMPONENT_GET_IFACE (component);
622 if (iface->set_position)
623 return (iface->set_position) (component, x, y, coord_type);
629 * atk_component_set_size:
630 * @component: an #AtkComponent
631 * @width: width to set for @component
632 * @height: height to set for @component
634 * Set the size of the @component in terms of width and height.
636 * Returns: %TRUE or %FALSE whether the size was set or not
639 atk_component_set_size (AtkComponent *component,
643 AtkComponentIface *iface = NULL;
644 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
646 iface = ATK_COMPONENT_GET_IFACE (component);
649 return (iface->set_size) (component, x, y);
655 * atk_component_scroll_to:
656 * @component: an #AtkComponent
657 * @type: specify where the object should be made visible.
659 * Makes @component visible on the screen by scrolling all necessary parents.
661 * Contrary to atk_component_set_position, this does not actually move
662 * @component in its parent, this only makes the parents scroll so that the
663 * object shows up on the screen, given its current position within the parents.
665 * Returns: whether scrolling was successful.
670 atk_component_scroll_to (AtkComponent *component,
673 AtkComponentIface *iface = NULL;
674 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
676 iface = ATK_COMPONENT_GET_IFACE (component);
678 if (iface->scroll_to)
679 return (iface->scroll_to) (component, type);
685 * atk_component_scroll_to_point:
686 * @component: an #AtkComponent
687 * @coords: specify whether coordinates are relative to the screen or to the
689 * @x: x-position where to scroll to
690 * @y: y-position where to scroll to
692 * Move the top-left of @component to a given position of the screen by
693 * scrolling all necessary parents.
695 * Returns: whether scrolling was successful.
700 atk_component_scroll_to_point (AtkComponent *component,
705 AtkComponentIface *iface = NULL;
706 g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
708 iface = ATK_COMPONENT_GET_IFACE (component);
710 if (iface->scroll_to_point)
711 return (iface->scroll_to_point) (component, coords, x, y);
717 atk_component_real_contains (AtkComponent *component,
720 AtkCoordType coord_type)
722 gint real_x, real_y, width, height;
724 real_x = real_y = width = height = 0;
726 atk_component_get_extents (component, &real_x, &real_y, &width, &height, coord_type);
729 (x < real_x + width) &&
731 (y < real_y + height))
738 atk_component_real_ref_accessible_at_point (AtkComponent *component,
741 AtkCoordType coord_type)
745 count = atk_object_get_n_accessible_children (ATK_OBJECT (component));
747 for (i = 0; i < count; i++)
751 obj = atk_object_ref_accessible_child (ATK_OBJECT (component), i);
755 if (atk_component_contains (ATK_COMPONENT (obj), x, y, coord_type))
761 g_object_unref (obj);
769 atk_component_real_get_position (AtkComponent *component,
772 AtkCoordType coord_type)
776 atk_component_get_extents (component, x, y, &width, &height, coord_type);
780 atk_component_real_get_size (AtkComponent *component,
785 AtkCoordType coord_type;
788 * Pick one coordinate type; it does not matter for size
790 coord_type = ATK_XY_WINDOW;
792 atk_component_get_extents (component, &x, &y, width, height, coord_type);
795 static AtkRectangle *
796 atk_rectangle_copy (const AtkRectangle *rectangle)
798 AtkRectangle *result = g_new (AtkRectangle, 1);
799 *result = *rectangle;
805 atk_rectangle_get_type (void)
807 static GType our_type = 0;
810 our_type = g_boxed_type_register_static ("AtkRectangle",
811 (GBoxedCopyFunc)atk_rectangle_copy,
812 (GBoxedFreeFunc)g_free);