AtkComponent: ATK - Accessibility Toolkit

AtkComponent

AtkComponent — The ATK interface provided by UI components which occupy a physical area on the screen. which the user can activate/interact with.

Functions

Signals

void

bounds-changed

Run Last

Types and Values

	AtkComponent
struct	AtkComponentIface
struct	AtkRectangle
enum	AtkScrollType

Object Hierarchy

    GBoxed
    ╰── AtkRectangle
    GEnum
    ╰── AtkScrollType
    GInterface
    ╰── AtkComponent

Known Implementations

AtkComponent is implemented by AtkNoOpObject, AtkPlug and AtkSocket.

Includes

#include <atk/atk.h>

Description

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.

Functions

AtkFocusHandler ()

void
(*AtkFocusHandler) (AtkObject *object,
                    gboolean focus_in);

AtkFocusHandler has been deprecated since version 2.9.4 and should not be used in newly-written code.

Deprecated with atk_component_add_focus_handler() and atk_component_remove_focus_handler(). See those methods for more information.

The type of callback function used for atk_component_add_focus_handler() and atk_component_remove_focus_handler()

Parameters

object	the AtkObject that receives/lose the focus
focus_in	TRUE if the object receives the focus

atk_component_add_focus_handler ()

guint
atk_component_add_focus_handler (AtkComponent *component,
                                 AtkFocusHandler handler);

atk_component_add_focus_handler has been deprecated since version 2.9.4 and should not be used in newly-written code.

If you need to track when an object gains or lose the focus, use the “state-change” "focused" notification instead.

Add the specified handler to the set of functions to be called when this object receives focus events (in or out). If the handler is already added it is not added again

[skip]

Parameters

component	The AtkComponent to attach the `handler` to
handler	The AtkFocusHandler to be attached to `component`

Returns

a handler id which can be used in atk_component_remove_focus_handler() or zero if the handler was already added.

atk_component_contains ()

gboolean
atk_component_contains (AtkComponent *component,
                        gint x,
                        gint y,
                        AtkCoordType coord_type);

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.

Parameters

component	the AtkComponent
x	x coordinate
y	y coordinate
coord_type	specifies whether the coordinates are relative to the screen or to the components top level window

Returns

TRUE or FALSE indicating whether the specified point is within the extent of the component or not

atk_component_get_extents ()

void
atk_component_get_extents (AtkComponent *component,
                           gint *x,
                           gint *y,
                           gint *width,
                           gint *height,
                           AtkCoordType coord_type);

Gets the rectangle which gives the extent of the component .

If the extent can not be obtained (e.g. a non-embedded plug or missing support), all of x, y, width, height are set to -1.

Parameters

component	an AtkComponent
x	address of gint to put x coordinate.	[out][optional]
y	address of gint to put y coordinate.	[out][optional]
width	address of gint to put width.	[out][optional]
height	address of gint to put height.	[out][optional]
coord_type	specifies whether the coordinates are relative to the screen or to the components top level window

atk_component_get_layer ()

AtkLayer
atk_component_get_layer (AtkComponent *component);

Gets the layer of the component.

Parameters

component

an AtkComponent

Returns

an AtkLayer which is the layer of the component

atk_component_get_mdi_zorder ()

gint
atk_component_get_mdi_zorder (AtkComponent *component);

Gets the zorder of the component. The value G_MININT will be returned if the layer of the component is not ATK_LAYER_MDI or ATK_LAYER_WINDOW.

Parameters

component

an AtkComponent

Returns

a gint which is the zorder of the component, i.e. the depth at which the component is shown in relation to other components in the same container.

atk_component_get_position ()

void
atk_component_get_position (AtkComponent *component,
                            gint *x,
                            gint *y,
                            AtkCoordType coord_type);

atk_component_get_position is deprecated and should not be used in newly-written code.

Since 2.12. Use atk_component_get_extents() instead.

Gets the position of component in the form of a point specifying component 's top-left corner.

If the position can not be obtained (e.g. a non-embedded plug or missing support), x and y are set to -1.

Parameters

component	an AtkComponent
x	address of gint to put x coordinate position.	[out][optional]
y	address of gint to put y coordinate position.	[out][optional]
coord_type	specifies whether the coordinates are relative to the screen or to the components top level window

atk_component_get_size ()

void
atk_component_get_size (AtkComponent *component,
                        gint *width,
                        gint *height);

atk_component_get_size is deprecated and should not be used in newly-written code.

Since 2.12. Use atk_component_get_extents() instead.

Gets the size of the component in terms of width and height.

If the size can not be obtained (e.g. a non-embedded plug or missing support), width and height are set to -1.

Parameters

component	an AtkComponent
width	address of gint to put width of `component` .	[out][optional]
height	address of gint to put height of `component` .	[out][optional]

atk_component_grab_focus ()

gboolean
atk_component_grab_focus (AtkComponent *component);

Grabs focus for this component .

Parameters

component

an AtkComponent

Returns

TRUE if successful, FALSE otherwise.

atk_component_ref_accessible_at_point ()

AtkObject *
atk_component_ref_accessible_at_point (AtkComponent *component,
                                       gint x,
                                       gint y,
                                       AtkCoordType coord_type);

Gets a reference to the accessible child, if one exists, at the coordinate point specified by x and y .

Parameters

component	the AtkComponent
x	x coordinate
y	y coordinate
coord_type	specifies whether the coordinates are relative to the screen or to the components top level window

Returns

a reference to the accessible child, if one exists.

[nullable][transfer full]

atk_component_remove_focus_handler ()

void
atk_component_remove_focus_handler (AtkComponent *component,
                                    guint handler_id);

atk_component_remove_focus_handler has been deprecated since version 2.9.4 and should not be used in newly-written code.

If you need to track when an object gains or lose the focus, use the “state-change” "focused" notification instead.

Remove the handler specified by handler_id from the list of functions to be executed when this object receives focus events (in or out).

Parameters

component	the AtkComponent to remove the focus handler from
handler_id	the handler id of the focus handler to be removed from `component`

atk_component_set_extents ()

gboolean
atk_component_set_extents (AtkComponent *component,
                           gint x,
                           gint y,
                           gint width,
                           gint height,
                           AtkCoordType coord_type);

Sets the extents of component .

Parameters

component	an AtkComponent
x	x coordinate
y	y coordinate
width	width to set for `component`
height	height to set for `component`
coord_type	specifies whether the coordinates are relative to the screen or to the components top level window

Returns

TRUE or FALSE whether the extents were set or not

atk_component_set_position ()

gboolean
atk_component_set_position (AtkComponent *component,
                            gint x,
                            gint y,
                            AtkCoordType coord_type);

Sets the position of component .

Contrary to atk_component_scroll_to, this does not trigger any scrolling, this just moves component in its parent.

Parameters

component	an AtkComponent
x	x coordinate
y	y coordinate
coord_type	specifies whether the coordinates are relative to the screen or to the component's top level window

Returns

TRUE or FALSE whether or not the position was set or not

atk_component_set_size ()

gboolean
atk_component_set_size (AtkComponent *component,
                        gint width,
                        gint height);

Set the size of the component in terms of width and height.

Parameters

component	an AtkComponent
width	width to set for `component`
height	height to set for `component`

Returns

TRUE or FALSE whether the size was set or not

atk_component_get_alpha ()

gdouble
atk_component_get_alpha (AtkComponent *component);

Returns the alpha value (i.e. the opacity) for this component , on a scale from 0 (fully transparent) to 1.0 (fully opaque).

Parameters

component

an AtkComponent

Returns

An alpha value from 0 to 1.0, inclusive.

Since: 1.12

atk_component_scroll_to ()

gboolean
atk_component_scroll_to (AtkComponent *component,
                         AtkScrollType type);

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.

Parameters

component	an AtkComponent
type	specify where the object should be made visible.

Returns

whether scrolling was successful.

Since: 2.30

atk_component_scroll_to_point ()

gboolean
atk_component_scroll_to_point (AtkComponent *component,
                               AtkCoordType coords,
                               gint x,
                               gint y);

Move the top-left of component to a given position of the screen by scrolling all necessary parents.

Parameters

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

Returns

whether scrolling was successful.

Since: 2.30

Types and Values

AtkComponent

typedef struct _AtkComponent AtkComponent;

struct AtkComponentIface

struct AtkComponentIface {
  guint          (* add_focus_handler)  (AtkComponent          *component,
                                         AtkFocusHandler        handler);

  gboolean       (* contains)           (AtkComponent          *component,
                                         gint                   x,
                                         gint                   y,
                                         AtkCoordType           coord_type);

  AtkObject*    (* ref_accessible_at_point)  (AtkComponent     *component,
                                         gint                   x,
                                         gint                   y,
                                         AtkCoordType           coord_type);
  void          (* get_extents)         (AtkComponent          *component,
                                         gint                  *x,
                                         gint                  *y,
                                         gint                  *width,
                                         gint                  *height,
                                         AtkCoordType          coord_type);
  void                     (* get_position)     (AtkComponent   *component,
                                                 gint           *x,
                                                 gint           *y,
                                                 AtkCoordType   coord_type);
  void                     (* get_size)                 (AtkComponent   *component,
                                                         gint           *width,
                                                         gint           *height);
  gboolean                 (* grab_focus)               (AtkComponent   *component);
  void                     (* remove_focus_handler)      (AtkComponent  *component,
                                                          guint         handler_id);
  gboolean                 (* set_extents)      (AtkComponent   *component,
                                                 gint           x,
                                                 gint           y,
                                                 gint           width,
                                                 gint           height,
                                                 AtkCoordType   coord_type);
  gboolean                 (* set_position)     (AtkComponent   *component,
                                                 gint           x,
                                                 gint           y,
                                                 AtkCoordType   coord_type);
  gboolean                 (* set_size)         (AtkComponent   *component,
                                                 gint           width,
                                                 gint           height);

  AtkLayer                 (* get_layer)        (AtkComponent   *component);
  gint                     (* get_mdi_zorder)   (AtkComponent   *component);

  /*
   * signal handlers
   */
  void                     (* bounds_changed)   (AtkComponent   *component,
                                                 AtkRectangle   *bounds);
  gdouble                  (* get_alpha)        (AtkComponent   *component);

  /*
   * Scrolls this object so it becomes visible on the screen.
   *
   * scroll_to lets the implementation compute an appropriate target
   * position on the screen, with type used as a positioning hint.
   *
   * scroll_to_point lets the client specify a precise target position
   * on the screen for the top-left of the object.
   *
   * Since ATK 2.30
   */
  gboolean                (*scroll_to)          (AtkComponent   *component,
                                                 AtkScrollType   type);

  gboolean                (*scroll_to_point)    (AtkComponent   *component,
                                                 AtkCoordType    coords,
                                                 gint            x,
                                                 gint            y);
};

The AtkComponent interface should be supported by any object that is rendered on the screen. The interface provides the standard mechanism for an assistive technology to determine and set the graphical representation of an object.

Members

`add_focus_handler` ()	This virtual function is deprecated since 2.9.4 and it should not be overriden. See `atk_component_add_focus_handler()` for more information.
`contains` ()
`ref_accessible_at_point` ()
`get_extents` ()
`get_position` ()	This virtual function is deprecated since 2.12 and it should not be overriden. Use `AtkComponentIface.get_extents` instead.
`get_size` ()	This virtual function is deprecated since 2.12 and it should not be overriden. Use `AtkComponentIface.get_extents` instead.
`grab_focus` ()
`remove_focus_handler` ()	This virtual function is deprecated since 2.9.4 and it should not be overriden. See `atk_component_remove_focus_handler()` for more information.
`set_extents` ()
`set_position` ()
`set_size` ()
`get_layer` ()
`get_mdi_zorder` ()
`bounds_changed` ()
`get_alpha` ()
`scroll_to` ()
`scroll_to_point` ()

struct AtkRectangle

struct AtkRectangle {
  gint x;
  gint y;
  gint width;
  gint height;
};

A data structure for holding a rectangle. Those coordinates are relative to the component top-level parent.

Members

gint `x`;	X coordinate of the left side of the rectangle.
gint `y`;	Y coordinate of the top side of the rectangle.
gint `width`;	width of the rectangle.
gint `height`;	height of the rectangle.

enum AtkScrollType

Specifies where an object should be placed on the screen when using scroll_to.

Members

ATK_SCROLL_TOP_LEFT	Scroll the object vertically and horizontally to bring its top left corner to the top left corner of the window.
ATK_SCROLL_BOTTOM_RIGHT	Scroll the object vertically and horizontally to bring its bottom right corner to the bottom right corner of the window.
ATK_SCROLL_TOP_EDGE	Scroll the object vertically to bring its top edge to the top edge of the window.
ATK_SCROLL_BOTTOM_EDGE	Scroll the object vertically to bring its bottom edge to the bottom edge of the window.
ATK_SCROLL_LEFT_EDGE	Scroll the object vertically and horizontally to bring its left edge to the left edge of the window.
ATK_SCROLL_RIGHT_EDGE	Scroll the object vertically and horizontally to bring its right edge 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.

Since: 2.30

Signal Details

The `“bounds-changed”` signal

void
user_function (AtkComponent *atkcomponent,
               AtkRectangle *arg1,
               gpointer      user_data)

The 'bounds-changed" signal is emitted when the bposition or size of the component changes.

Parameters

atkcomponent	the object which received the signal.
arg1	The AtkRectangle giving the new position and size.
user_data	user data set when the signal handler was connected.

Flags: Run Last

void	(*AtkFocusHandler) ()
guint	atk_component_add_focus_handler ()
gboolean	atk_component_contains ()
void	atk_component_get_extents ()
AtkLayer	atk_component_get_layer ()
gint	atk_component_get_mdi_zorder ()
void	atk_component_get_position ()
void	atk_component_get_size ()
gboolean	atk_component_grab_focus ()
AtkObject *	atk_component_ref_accessible_at_point ()
void	atk_component_remove_focus_handler ()
gboolean	atk_component_set_extents ()
gboolean	atk_component_set_position ()
gboolean	atk_component_set_size ()
gdouble	atk_component_get_alpha ()
gboolean	atk_component_scroll_to ()
gboolean	atk_component_scroll_to_point ()

AtkComponent

Functions

Signals

Types and Values

Object Hierarchy

Known Implementations

Includes

Description

Functions

AtkFocusHandler ()

Parameters

atk_component_add_focus_handler ()

Parameters

Returns

atk_component_contains ()

Parameters

Returns

atk_component_get_extents ()

Parameters

atk_component_get_layer ()

Parameters

Returns

atk_component_get_mdi_zorder ()

Parameters

Returns

atk_component_get_position ()

Parameters

atk_component_get_size ()

Parameters

atk_component_grab_focus ()

Parameters

Returns

atk_component_ref_accessible_at_point ()

Parameters

Returns

atk_component_remove_focus_handler ()

Parameters

atk_component_set_extents ()

Parameters

Returns

atk_component_set_position ()

Parameters

Returns

atk_component_set_size ()

Parameters

Returns

atk_component_get_alpha ()

Parameters

Returns

atk_component_scroll_to ()

Parameters

Returns

atk_component_scroll_to_point ()

Parameters

Returns

Types and Values

AtkComponent

struct AtkComponentIface

Members

struct AtkRectangle

Members

enum AtkScrollType

Members

Signal Details

The “bounds-changed” signal

Parameters

The `“bounds-changed”` signal