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

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 ()

## Signals

void | bounds-changed | Run Last

## Types and Values

| AtkComponent
struct | AtkComponentIface
struct | AtkRectangle

## Object Hierarchy

        GInterface
        ╰── AtkComponent

## Known Implementations

AtkComponent is implemented by AtkNoOpObject.

## 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

#### 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` .

#### Parameters

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 |
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.

#### Parameters

component | an AtkComponent |
x | address of gint to put x coordinate position |
y | 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 |

### 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.

#### Parameters

component | an AtkComponent |
width | address of gint to put width of `component` |
height | address of gint to put height of `component` |

### 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 postition of `component` .

#### Parameters

component | an 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` 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

## Types and Values

### AtkComponent

    typedef struct _AtkComponent AtkComponent;

### struct AtkComponentIface

    struct AtkComponentIface {
      GTypeInterface parent;

      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);
    };

#### Members

GTypeInterface `parent`; |  |
`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 `get_extents` instead. |
`get_size` () | This virtual function is deprecated since 2.12 and it should not be overriden. Use `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` () |  |

### 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. |

## 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