* Boston, MA 02111-1307, USA.
*/
+#include "config.h"
#include "atkcomponent.h"
+/**
+ * SECTION:atkcomponent
+ * @Short_description: The ATK interface provided by UI components
+ * which occupy a physical area on the screen.
+ * which the user can activate/interact with.
+ * @Title:AtkComponent
+ *
+ * #AtkComponent should be implemented by most if not all UI elements
+ * with an actual on-screen presence, i.e. components which can be
+ * said to have a screen-coordinate bounding box. Virtually all
+ * widgets will need to have #AtkComponent implementations provided
+ * for their corresponding #AtkObject class. In short, only UI
+ * elements which are *not* GUI elements will omit this ATK interface.
+ *
+ * A possible exception might be textual information with a
+ * transparent background, in which case text glyph bounding box
+ * information is provided by #AtkText.
+ */
+
enum {
BOUNDS_CHANGED,
LAST_SIGNAL
class->get_position = atk_component_real_get_position;
class->get_size = atk_component_real_get_size;
+
+ /**
+ * AtkComponent::bounds-changed:
+ * @atkcomponent: the object which received the signal.
+ * @arg1: The AtkRectangle giving the new position and size.
+ *
+ * The 'bounds-changed" signal is emitted when the bposition or
+ * size of the component changes.
+ */
atk_component_signals[BOUNDS_CHANGED] =
g_signal_new ("bounds_changed",
ATK_TYPE_COMPONENT,
/**
- * atk_component_add_focus_handler:
+ * atk_component_add_focus_handler: (skip)
* @component: The #AtkComponent to attach the @handler to
* @handler: The #AtkFocusHandler to be attached to @component
*
* when this object receives focus events (in or out). If the handler is
* already added it is not added again
*
- * Returns: a handler id which can be used in atk_component_remove_focus_handler
+ * Deprecated: 2.9.4: If you need to track when an object gains or
+ * lose the focus, use the #AtkObject::state-change "focused" notification instead.
+ *
+ * Returns: a handler id which can be used in atk_component_remove_focus_handler()
* or zero if the handler was already added.
**/
guint
* Remove the handler specified by @handler_id from the list of
* functions to be executed when this object receives focus events
* (in or out).
+ *
+ * Deprecated: 2.9.4: If you need to track when an object gains or
+ * lose the focus, use the #AtkObject::state-change "focused" notification instead.
+ *
**/
void
atk_component_remove_focus_handler (AtkComponent *component,
*
* Checks whether the specified point is within the extent of the @component.
*
+ * Toolkit implementor note: ATK provides a default implementation for
+ * this virtual method. In general there are little reason to
+ * re-implement it.
+ *
* Returns: %TRUE or %FALSE indicating whether the specified point is within
* the extent of the @component or not
**/
* Gets a reference to the accessible child, if one exists, at the
* coordinate point specified by @x and @y.
*
- * Returns: a reference to the accessible child, if one exists
+ * Returns: (nullable) (transfer full): a reference to the accessible
+ * child, if one exists
**/
AtkObject*
atk_component_ref_accessible_at_point (AtkComponent *component,
/**
* atk_component_get_extents:
* @component: an #AtkComponent
- * @x: address of #gint to put x coordinate
- * @y: address of #gint to put y coordinate
- * @width: address of #gint to put width
- * @height: address of #gint to put height
+ * @x: (out) (optional): address of #gint to put x coordinate
+ * @y: (out) (optional): address of #gint to put y coordinate
+ * @width: (out) (optional): address of #gint to put width
+ * @height: (out) (optional): address of #gint to put height
* @coord_type: specifies whether the coordinates are relative to the screen
* or to the components top level window
*
/**
* atk_component_get_position:
* @component: an #AtkComponent
- * @x: address of #gint to put x coordinate position
- * @y: address of #gint to put y coordinate position
+ * @x: (out) (optional): address of #gint to put x coordinate position
+ * @y: (out) (optional): address of #gint to put y coordinate position
* @coord_type: specifies whether the coordinates are relative to the screen
* or to the components top level window
*
* Gets the position of @component in the form of
* a point specifying @component's top-left corner.
+ *
+ * Deprecated: Since 2.12. Use atk_component_get_extents() instead.
**/
void
atk_component_get_position (AtkComponent *component,
/**
* atk_component_get_size:
* @component: an #AtkComponent
- * @width: address of #gint to put width of @component
- * @height: address of #gint to put height of @component
+ * @width: (out) (optional): address of #gint to put width of @component
+ * @height: (out) (optional): address of #gint to put height of @component
*
* Gets the size of the @component in terms of width and height.
+ *
+ * Deprecated: Since 2.12. Use atk_component_get_extents() instead.
**/
void
atk_component_get_size (AtkComponent *component,
* (fully opaque).
*
* Returns: An alpha value from 0 to 1.0, inclusive.
- * @Since: ATK 1.12
+ * Since: 1.12
**/
gdouble
atk_component_get_alpha (AtkComponent *component)
}
/**
+ * atk_component_grab_highlight:
+ * @component: an #AtkComponent
+ *
+ * Grabs highlight for this @component.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ **/
+gboolean
+atk_component_grab_highlight (AtkComponent *component)
+{
+ AtkComponentIface *iface = NULL;
+ g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
+
+ iface = ATK_COMPONENT_GET_IFACE (component);
+
+ if (iface->grab_highlight)
+ return (iface->grab_highlight) (component);
+ else
+ return FALSE;
+}
+
+/**
+ * atk_component_clear_highlight:
+ * @component: an #AtkComponent
+ *
+ * Clears highlight for this @component.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ **/
+gboolean
+atk_component_clear_highlight (AtkComponent *component)
+{
+ AtkComponentIface *iface = NULL;
+ g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
+
+ iface = ATK_COMPONENT_GET_IFACE (component);
+
+ if (iface->clear_highlight)
+ return (iface->clear_highlight) (component);
+ else
+ return FALSE;
+}
+
+/**
+ * atk_component_get_highlight_index:
+ * @component: an #AtkComponent
+ *
+ * Returns: highlight index of the @component (if >0),
+ * 0 if highlight index is not set or -1 if an error occured.
+ *
+ **/
+gint
+atk_component_get_highlight_index (AtkComponent *component)
+{
+ AtkComponentIface *iface = NULL;
+ g_return_val_if_fail (ATK_IS_COMPONENT (component), -1);
+
+ iface = ATK_COMPONENT_GET_IFACE (component);
+
+ if (iface->get_highlight_index)
+ return (iface->get_highlight_index) (component);
+ else
+ return -1;
+}
+
+/**
* atk_component_set_extents:
* @component: an #AtkComponent
* @x: x coordinate
* @x: x coordinate
* @y: y coordinate
* @coord_type: specifies whether the coordinates are relative to the screen
- * or to the components top level window
+ * or to the component's top level window
+ *
+ * Sets the position of @component.
+ *
+ * Contrary to atk_component_scroll_to, this does not trigger any scrolling,
+ * this just moves @component in its parent.
*
- * Sets the postition of @component.
- *
* Returns: %TRUE or %FALSE whether or not the position was set or not
**/
gboolean
return FALSE;
}
+/**
+ * atk_component_scroll_to:
+ * @component: an #AtkComponent
+ * @type: specify where the object should be made visible.
+ *
+ * Makes @component visible on the screen by scrolling all necessary parents.
+ *
+ * Contrary to atk_component_set_position, this does not actually move
+ * @component in its parent, this only makes the parents scroll so that the
+ * object shows up on the screen, given its current position within the parents.
+ *
+ * Returns: whether scrolling was successful.
+ *
+ * Since: 2.30
+ */
+gboolean
+atk_component_scroll_to (AtkComponent *component,
+ AtkScrollType type)
+{
+ AtkComponentIface *iface = NULL;
+ g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
+
+ iface = ATK_COMPONENT_GET_IFACE (component);
+
+ if (iface->scroll_to)
+ return (iface->scroll_to) (component, type);
+
+ return FALSE;
+}
+
+/**
+ * atk_component_scroll_to_point:
+ * @component: an #AtkComponent
+ * @coords: specify whether coordinates are relative to the screen or to the
+ * parent object.
+ * @x: x-position where to scroll to
+ * @y: y-position where to scroll to
+ *
+ * Makes an object visible on the screen at a given position by scrolling all
+ * necessary parents.
+ *
+ * Returns: whether scrolling was successful.
+ *
+ * Since: 2.30
+ */
+gboolean
+atk_component_scroll_to_point (AtkComponent *component,
+ AtkCoordType coords,
+ gint x,
+ gint y)
+{
+ AtkComponentIface *iface = NULL;
+ g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
+
+ iface = ATK_COMPONENT_GET_IFACE (component);
+
+ if (iface->scroll_to_point)
+ return (iface->scroll_to_point) (component, coords, x, y);
+
+ return FALSE;
+}
+
static gboolean
atk_component_real_contains (AtkComponent *component,
gint x,
atk_component_get_extents (component, &x, &y, width, height, coord_type);
}
-gdouble
-atk_component_real_get_alpha (AtkComponent *component)
-{
- return (gdouble) 1.0;
-}
-
static AtkRectangle *
atk_rectangle_copy (const AtkRectangle *rectangle)
{
projects / platform / upstream / atk.git / blobdiff