From e98b748461acfcfc261dc47290947b614417eef7 Mon Sep 17 00:00:00 2001 From: Samuel Thibault Date: Tue, 13 Feb 2018 13:29:53 +0100 Subject: atkcomponent: Add ScrollTo and ScrollToPoint component interfaces --- atk/atkcomponent.c | 66 ++++++++++++++++++++++++++++++++++++++++++++++++--- atk/atkcomponent.h | 52 ++++++++++++++++++++++++++++++++++++++++ atk/atkutil.h | 7 ++++-- atk/atkversion.h.in | 14 +++++++++++ docs/atk-sections.txt | 3 +++ 5 files changed, 137 insertions(+), 5 deletions(-) diff --git a/atk/atkcomponent.c b/atk/atkcomponent.c index f0beb10..dd3895d 100644 --- a/atk/atkcomponent.c +++ b/atk/atkcomponent.c @@ -507,10 +507,13 @@ atk_component_set_extents (AtkComponent *component, * @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 @@ -556,6 +559,63 @@ atk_component_set_size (AtkComponent *component, return FALSE; } +/** + * atk_component_scroll_to (AtkComponent *accessible, AtkScrollType type) + * @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. + * + * Since: 2.30 + * + * Returns: whether scrolling was successful. + */ +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); + else + return FALSE; +} + +/** + * atk_component_scroll_to_point (AtkComponent *accessible, AtkScrollType type, gint x, gint y) + * @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. + * + * Since: 2.30 + * + * Returns: whether scrolling was successful. + */ +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); + else + return FALSE; +} + static gboolean atk_component_real_contains (AtkComponent *component, gint x, diff --git a/atk/atkcomponent.h b/atk/atkcomponent.h index d20fdc2..22155c1 100644 --- a/atk/atkcomponent.h +++ b/atk/atkcomponent.h @@ -29,6 +29,36 @@ G_BEGIN_DECLS +/** + *AtkScrollType: + *@ATK_SCROLL_TOP_LEFT: Scroll the object vertically and horizontally to the top + *left corner of the window. + *@ATK_SCROLL_BOTTOM_RIGHT: Scroll the object vertically and horizontally to the + *bottom right corner of the window. + *@ATK_SCROLL_TOP_EDGE: Scroll the object vertically to the top edge of the + window. + *@ATK_SCROLL_BOTTOM_EDGE: Scroll the object vertically to the bottom edge of + *the window. + *@ATK_SCROLL_LEFT_EDGE: Scroll the object vertically and horizontally to the + *left edge of the window. + *@ATK_SCROLL_RIGHT_EDGE: Scroll the object vertically and horizontally to the + *right edge of the window. + *@ATK_SCROLL_ANYWHERE: Scroll the object vertically and horizontally so that + *as much as possible of the object becomes visible. The exact placement is + *determined by the application. + * + * Specifies where an object should be placed on the screen when using scroll_to. + **/ +typedef enum { + ATK_SCROLL_TOP_LEFT, + ATK_SCROLL_BOTTOM_RIGHT, + ATK_SCROLL_TOP_EDGE, + ATK_SCROLL_BOTTOM_EDGE, + ATK_SCROLL_LEFT_EDGE, + ATK_SCROLL_RIGHT_EDGE, + ATK_SCROLL_ANYWHERE +} AtkScrollType; + /* * The AtkComponent interface should be supported by any object that is * rendered on the screen. The interface provides the standard mechanism @@ -156,6 +186,18 @@ struct _AtkComponentIface void (* bounds_changed) (AtkComponent *component, AtkRectangle *bounds); gdouble (* get_alpha) (AtkComponent *component); + + /* + * Scrolls this object so it becomes visible on the screen. + * Since ATK 2.30 + */ + gboolean (*scroll_to) (AtkComponent *component, + AtkScrollType type); + + gboolean (*scroll_to_point) (AtkComponent *component, + AtkCoordType coords, + gint x, + gint y); }; ATK_AVAILABLE_IN_ALL @@ -219,6 +261,16 @@ gboolean atk_component_set_size (AtkComponent *com ATK_AVAILABLE_IN_ALL gdouble atk_component_get_alpha (AtkComponent *component); +ATK_AVAILABLE_IN_2_30 +gboolean atk_component_scroll_to (AtkComponent *component, + AtkScrollType type); + +ATK_AVAILABLE_IN_2_30 +gboolean atk_component_scroll_to_point (AtkComponent *component, + AtkCoordType coords, + gint x, + gint y); + G_END_DECLS #endif /* __ATK_COMPONENT_H__ */ diff --git a/atk/atkutil.h b/atk/atkutil.h index d69df88..e3a6e4b 100644 --- a/atk/atkutil.h +++ b/atk/atkutil.h @@ -176,15 +176,18 @@ GType atk_util_get_type (void); /** *AtkCoordType: *@ATK_XY_SCREEN: specifies xy coordinates relative to the screen - *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's + *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's * top-level window + *@ATK_XY_PARENT: specifies xy coordinates relative to the widget's + * immediate parent. * *Specifies how xy coordinates are to be interpreted. Used by functions such *as atk_component_get_position() and atk_text_get_character_extents() **/ typedef enum { ATK_XY_SCREEN, - ATK_XY_WINDOW + ATK_XY_WINDOW, + ATK_XY_PARENT }AtkCoordType; ATK_DEPRECATED_IN_2_10 diff --git a/atk/atkversion.h.in b/atk/atkversion.h.in index bba9f49..c5ec017 100644 --- a/atk/atkversion.h.in +++ b/atk/atkversion.h.in @@ -376,6 +376,20 @@ # define ATK_AVAILABLE_IN_2_14 _ATK_EXTERN #endif +#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_30 +# define ATK_DEPRECATED_IN_2_30 ATK_DEPRECATED +# define ATK_DEPRECATED_IN_2_30_FOR(f) ATK_DEPRECATED_FOR(f) +#else +# define ATK_DEPRECATED_IN_2_30 _ATK_EXTERN +# define ATK_DEPRECATED_IN_2_30_FOR(f) _ATK_EXTERN +#endif + +#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_30 +# define ATK_AVAILABLE_IN_2_30 ATK_UNAVAILABLE(2, 30) +#else +# define ATK_AVAILABLE_IN_2_30 _ATK_EXTERN +#endif + ATK_AVAILABLE_IN_2_8 guint atk_get_major_version (void) G_GNUC_CONST; ATK_AVAILABLE_IN_2_8 diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt index 1224f31..816144e 100644 --- a/docs/atk-sections.txt +++ b/docs/atk-sections.txt @@ -39,6 +39,8 @@ atk_component_set_extents atk_component_set_position atk_component_set_size atk_component_get_alpha +atk_component_scroll_to +atk_component_scroll_to_point ATK_COMPONENT ATK_IS_COMPONENT @@ -211,6 +213,7 @@ ATK_IS_IMPLEMENTOR ATK_IMPLEMENTOR ATK_TYPE_ROLE ATK_TYPE_LAYER +ATK_TYPE_SCROLL_TYPE atk_implementor_get_type atk_object_get_type atk_role_get_type -- cgit v1.2.1