AccessibleComponent Interface
3
AT-SPI-CSPI Library

# AccessibleComponent Interface

An interface implemented by objects which occupy area on screen.

## Synopsis

    enum                AccessibleCoordType;
    enum                AccessibleComponentLayer;
    void                AccessibleComponent_ref             (AccessibleComponent *obj);
    void                AccessibleComponent_unref           (AccessibleComponent *obj);
    SPIBoolean          AccessibleComponent_contains        (AccessibleComponent *obj,
                                                             long int x,
                                                             long int y,
                                                             AccessibleCoordType ctype);
    Accessible*         AccessibleComponent_getAccessibleAtPoint
                                                            (AccessibleComponent *obj,
                                                             long int x,
                                                             long int y,
                                                             AccessibleCoordType ctype);
    void                AccessibleComponent_getExtents      (AccessibleComponent *obj,
                                                             long int *x,
                                                             long int *y,
                                                             long int *width,
                                                             long int *height,
                                                             AccessibleCoordType ctype);
    void                AccessibleComponent_getPosition     (AccessibleComponent *obj,
                                                             long int *x,
                                                             long int *y,
                                                             AccessibleCoordType ctype);
    void                AccessibleComponent_getSize         (AccessibleComponent *obj,
                                                             long int *width,
                                                             long int *height);
    AccessibleComponentLayer AccessibleComponent_getLayer   (AccessibleComponent *obj);
    short               AccessibleComponent_getMDIZOrder    (AccessibleComponent *obj);
    SPIBoolean          AccessibleComponent_grabFocus       (AccessibleComponent *obj);
    double              AccessibleComponent_getAlpha        (AccessibleComponent *obj);

## Description

The Component interface is implemented by objects which are visible, or are potentially visible, onscreen. The interface exposes onscreen bounds, the approximate "layer" in which the object resides, sometimes including z-order information, and allows objects to explicitly be told to request focus.

## Details

### enum AccessibleCoordType

    typedef enum {
      SPI_COORD_TYPE_SCREEN,
      SPI_COORD_TYPE_WINDOW
    } AccessibleCoordType;

Specifies how xy coordinates are to be interpreted. Used by functions such as `AccessibleComponent_getPosition()` and `AccessibleText_getCharacterExtents()`

`SPI_COORD_TYPE_SCREEN`

  specifies xy coordinates relative to the screen

`SPI_COORD_TYPE_WINDOW`

  specifies xy coordinates relative to an object's top-level window

### enum AccessibleComponentLayer

    typedef enum {
        SPI_LAYER_INVALID,
        SPI_LAYER_BACKGROUND,
        SPI_LAYER_CANVAS,
        SPI_LAYER_WIDGET,
        SPI_LAYER_MDI,
        SPI_LAYER_POPUP,
        SPI_LAYER_OVERLAY,
        SPI_LAYER_WINDOW,
        SPI_LAYER_LAST_DEFINED
    } AccessibleComponentLayer;

Describes the layer of a component.

These enumerated "layer values" are used when determining which UI rendering layer a component is drawn into, which can help in making determinations of when components occlude one another.

`SPI_LAYER_INVALID`

  The layer cannot be determined or is somehow undefined.

`SPI_LAYER_BACKGROUND`

  Component belongs to the destop background.

`SPI_LAYER_CANVAS`

  Component is a canvas backdrop or drawing area.

`SPI_LAYER_WIDGET`

  Component is a 'normal' widget.

`SPI_LAYER_MDI`

  Component is drawn in the MDI layer and may have valid Z-information relative to other MDI-layer components.

`SPI_LAYER_POPUP`

  Component is in the popup layer, above other widgets and MDI components.

`SPI_LAYER_OVERLAY`

  Component is in the overlay plane - this value is reserved for future use.

`SPI_LAYER_WINDOW`

  Component is in the window layer and have valid Z-information relative to other window-layer components.

`SPI_LAYER_LAST_DEFINED`

  Used to determine the last valid value in the enum, should not be encountered.

### AccessibleComponent_ref ()

    void                AccessibleComponent_ref             (AccessibleComponent *obj);

Increment the reference count for an AccessibleComponent.

`obj` :

  a pointer to an object implementing AccessibleComponent on which to operate.

### AccessibleComponent_unref ()

    void                AccessibleComponent_unref           (AccessibleComponent *obj);

Decrement the reference count for an AccessibleComponent.

`obj` :

  a pointer to the object implementing AccessibleComponent on which to operate.

### AccessibleComponent_contains ()

    SPIBoolean          AccessibleComponent_contains        (AccessibleComponent *obj,
                                                             long int x,
                                                             long int y,
                                                             AccessibleCoordType ctype);

Query whether a given AccessibleComponent contains a particular point.

`obj` :

  a pointer to the AccessibleComponent to query.

`x` :

  a long specifying the x coordinate in question.

`y` :

  a long specifying the y coordinate in question.

`ctype` :

  the desired coordinate system of the point (`x`, `y`) (e.g. SPI_COORD_TYPE_WINDOW, SPI_COORD_TYPE_SCREEN).

Returns :

  a TRUE if the specified component contains the point (`x`, `y`), otherwise FALSE.

### AccessibleComponent_getAccessibleAtPoint ()

    Accessible*         AccessibleComponent_getAccessibleAtPoint
                                                            (AccessibleComponent *obj,
                                                             long int x,
                                                             long int y,
                                                             AccessibleCoordType ctype);

Get the accessible child at a given coordinate within an AccessibleComponent.

`obj` :

  a pointer to the AccessibleComponent to query.

`x` :

  a long specifying the x coordinate of the point in question.

`y` :

  a long specifying the y coordinate of the point in question.

`ctype` :

  the coordinate system of the point (`x`, `y`) (e.g. SPI_COORD_TYPE_WINDOW, SPI_COORD_TYPE_SCREEN).

Returns :

  a pointer to an Accessible child of the specified component which contains the point (`x`, `y`), or NULL of no child contains the point.

### AccessibleComponent_getExtents ()

    void                AccessibleComponent_getExtents      (AccessibleComponent *obj,
                                                             long int *x,
                                                             long int *y,
                                                             long int *width,
                                                             long int *height,
                                                             AccessibleCoordType ctype);

Get the bounding box of the specified AccessibleComponent.

`obj` :

  a pointer to the AccessibleComponent to query.

`x` :

  a pointer to a long into which the minimum x coordinate will be returned.

`y` :

  a pointer to a long into which the minimum y coordinate will be returned.

`width` :

  a pointer to a long into which the x extents (width) will be returned.

`height` :

  a pointer to a long into which the y extents (height) will be returned.

`ctype` :

  the desired coordinate system into which to return the results, (e.g. SPI_COORD_TYPE_WINDOW, SPI_COORD_TYPE_SCREEN).

### AccessibleComponent_getPosition ()

    void                AccessibleComponent_getPosition     (AccessibleComponent *obj,
                                                             long int *x,
                                                             long int *y,
                                                             AccessibleCoordType ctype);

Get the minimum x and y coordinates of the specified AccessibleComponent.

`obj` :

  a pointer to the AccessibleComponent to query.

`x` :

  a pointer to a long into which the minimum x coordinate will be returned.

`y` :

  a pointer to a long into which the minimum y coordinate will be returned.

`ctype` :

  the desired coordinate system into which to return the results, (e.g. SPI_COORD_TYPE_WINDOW, SPI_COORD_TYPE_SCREEN).

### AccessibleComponent_getSize ()

    void                AccessibleComponent_getSize         (AccessibleComponent *obj,
                                                             long int *width,
                                                             long int *height);

Get the size of the specified AccessibleComponent.

`obj` :

  a pointer to the AccessibleComponent to query.

`width` :

  a pointer to a long into which the x extents (width) will be returned.

`height` :

  a pointer to a long into which the y extents (height) will be returned.

### AccessibleComponent_getLayer ()

    AccessibleComponentLayer AccessibleComponent_getLayer   (AccessibleComponent *obj);

Query which layer the component is painted into, to help determine its visibility in terms of stacking order.

`obj` :

  a pointer to the AccessibleComponent to query.

Returns :

  the AccessibleComponentLayer into which this component is painted.

### AccessibleComponent_getMDIZOrder ()

    short               AccessibleComponent_getMDIZOrder    (AccessibleComponent *obj);

Query the z stacking order of a component which is in the MDI or window layer. (Bigger z-order numbers mean nearer the top)

`obj` :

  a pointer to the AccessibleComponent to query.

Returns :

  a short integer indicating the stacking order of the component in the MDI layer, or -1 if the component is not in the MDI layer.

### AccessibleComponent_grabFocus ()

    SPIBoolean          AccessibleComponent_grabFocus       (AccessibleComponent *obj);

Attempt to set the keyboard input focus to the specified AccessibleComponent.

`obj` :

  a pointer to the AccessibleComponent on which to operate.

Returns :

  TRUE if successful, FALSE otherwise.

### AccessibleComponent_getAlpha ()

    double              AccessibleComponent_getAlpha        (AccessibleComponent *obj);

Get the opacity/alpha value of a component, if alpha blending is in use.

`obj` :

  The AccessibleComponent to be queried.

Returns :

  the opacity value of a component, as a double between 0.0 and 1.0.