AtkRelation: ATK - Accessibility Toolkit

## AtkRelation AtkRelation — An object used to describe a relation between a object and one or more other objects. |

## Functions

AtkRelationType | atk_relation_type_register ()
const gchar * | atk_relation_type_get_name ()
AtkRelationType | atk_relation_type_for_name ()
AtkRelation * | atk_relation_new ()
AtkRelationType | atk_relation_get_relation_type ()
GPtrArray * | atk_relation_get_target ()
void | atk_relation_add_target ()
gboolean | atk_relation_remove_target ()

## Properties

AtkRelationType | relation-type | Read / Write
GValueArray * | target | Read / Write

## Types and Values

struct | AtkRelation
enum | AtkRelationType

## Object Hierarchy

        GEnum
        ╰── AtkRelationType
        GObject
        ╰── AtkRelation

## Includes

    #include <atk/atk.h>

## Description

An AtkRelation describes a relation between an object and one or more other objects. The actual relations that an object has with other objects are defined as an AtkRelationSet, which is a set of AtkRelations.

## Functions

### atk_relation_type_register ()

    AtkRelationType
    atk_relation_type_register (const gchar *name);

Associate `name` with a new AtkRelationType

#### Parameters

name | a name string |

#### Returns

an AtkRelationType associated with `name`

### atk_relation_type_get_name ()

    const gchar *
    atk_relation_type_get_name (AtkRelationType type);

Gets the description string describing the AtkRelationType `type` .

#### Parameters

type | The AtkRelationType whose name is required |

#### Returns

the string describing the AtkRelationType

### atk_relation_type_for_name ()

    AtkRelationType
    atk_relation_type_for_name (const gchar *name);

Get the AtkRelationType type corresponding to a relation name.

#### Parameters

name | a string which is the (non-localized) name of an ATK relation type. |

#### Returns

the AtkRelationType enumerated type corresponding to the specified name, or ATK_RELATION_NULL if no matching relation type is found.

### atk_relation_new ()

    AtkRelation *
    atk_relation_new (AtkObject **targets,
                      gint n_targets,
                      AtkRelationType relationship);

Create a new relation for the specified key and the specified list of targets. See also `atk_object_add_relationship()`.

#### Parameters

targets | an array of pointers to AtkObjects. | [array length=n_targets]
n_targets | number of AtkObjects pointed to by `targets` |
relationship | an AtkRelationType with which to create the new AtkRelation |

#### Returns

a pointer to a new AtkRelation

### atk_relation_get_relation_type ()

    AtkRelationType
    atk_relation_get_relation_type (AtkRelation *relation);

Gets the type of `relation`

#### Parameters

relation | an AtkRelation |

#### Returns

the type of `relation`

### atk_relation_get_target ()

    GPtrArray *
    atk_relation_get_target (AtkRelation *relation);

Gets the target list of `relation`

#### Parameters

relation | an AtkRelation |

#### Returns

the target list of `relation` .

[transfer none][element-type Atk.Object]

### atk_relation_add_target ()

    void
    atk_relation_add_target (AtkRelation *relation,
                             AtkObject *target);

Adds the specified AtkObject to the target for the relation, if it is not already present. See also `atk_object_add_relationship()`.

#### Parameters

relation | an AtkRelation |
target | an AtkObject |

Since: 1.9

### atk_relation_remove_target ()

    gboolean
    atk_relation_remove_target (AtkRelation *relation,
                                AtkObject *target);

Remove the specified AtkObject from the target for the relation.

#### Parameters

relation | an AtkRelation |
target | an AtkObject |

#### Returns

TRUE if the removal is successful.

## Types and Values

### struct AtkRelation

    struct AtkRelation;

### enum AtkRelationType

Describes the type of the relation

#### Members

ATK_RELATION_NULL | Not used, represens "no relationship" or an error condition. |
ATK_RELATION_CONTROLLED_BY | Indicates an object controlled by one or more target objects. |
ATK_RELATION_CONTROLLER_FOR | Indicates an object is an controller for one or more target objects. |
ATK_RELATION_LABEL_FOR | Indicates an object is a label for one or more target objects. |
ATK_RELATION_LABELLED_BY | Indicates an object is labelled by one or more target objects. |
ATK_RELATION_MEMBER_OF | Indicates an object is a member of a group of one or more target objects. |
ATK_RELATION_NODE_CHILD_OF | Indicates an object is a cell in a treetable which is displayed because a cell in the same column is expanded and identifies that cell. |
ATK_RELATION_FLOWS_TO | Indicates that the object has content that flows logically to another AtkObject in a sequential way, (for instance text-flow). |
ATK_RELATION_FLOWS_FROM | Indicates that the object has content that flows logically from another AtkObject in a sequential way, (for instance text-flow). |
ATK_RELATION_SUBWINDOW_OF | Indicates a subwindow attached to a component but otherwise has no connection in the UI heirarchy to that component. |
ATK_RELATION_EMBEDS | Indicates that the object visually embeds another object's content, i.e. this object's content flows around another's content. |
ATK_RELATION_EMBEDDED_BY | Reciprocal of `ATK_RELATION_EMBEDS`, indicates that this object's content is visualy embedded in another object. |
ATK_RELATION_POPUP_FOR | Indicates that an object is a popup for another object. |
ATK_RELATION_PARENT_WINDOW_OF | Indicates that an object is a parent window of another object. |
ATK_RELATION_DESCRIBED_BY | Reciprocal of `ATK_RELATION_DESCRIPTION_FOR`. Indicates that one or more target objects provide descriptive information about this object. This relation type is most appropriate for information that is not essential as its presentation may be user-configurable and/or limited to an on-demand mechanism such as an assistive technology command. For brief, essential information such as can be found in a widget's on-screen label, use `ATK_RELATION_LABELLED_BY`. For an on-screen error message, use `ATK_RELATION_ERROR_MESSAGE`. For lengthy extended descriptive information contained in an on-screen object, consider using `ATK_RELATION_DETAILS` as assistive technologies may provide a means for the user to navigate to objects containing detailed descriptions so that their content can be more closely reviewed. |
ATK_RELATION_DESCRIPTION_FOR | Reciprocal of `ATK_RELATION_DESCRIBED_BY`. Indicates that this object provides descriptive information about the target object(s). See also `ATK_RELATION_DETAILS_FOR` and `ATK_RELATION_ERROR_FOR`. |
ATK_RELATION_NODE_PARENT_OF | Indicates an object is a cell in a treetable and is expanded to display other cells in the same column. |
ATK_RELATION_DETAILS | Reciprocal of `ATK_RELATION_DETAILS_FOR`. Indicates that this object has a detailed or extended description, the contents of which can be found in the target object(s). This relation type is most appropriate for information that is sufficiently lengthy as to make navigation to the container of that information desirable. For less verbose information suitable for announcement only, see `ATK_RELATION_DESCRIBED_BY`. If the detailed information describes an error condition, `ATK_RELATION_ERROR_FOR` should be used instead. `Since` : ATK-2.26. |
ATK_RELATION_DETAILS_FOR | Reciprocal of `ATK_RELATION_DETAILS`. Indicates that this object provides a detailed or extended description about the target object(s). See also `ATK_RELATION_DESCRIPTION_FOR` and `ATK_RELATION_ERROR_FOR`. `Since` : ATK-2.26. |
ATK_RELATION_ERROR_MESSAGE | Reciprocal of `ATK_RELATION_ERROR_FOR`. Indicates that this object has one or more errors, the nature of which is described in the contents of the target object(s). Objects that have this relation type should also contain `ATK_STATE_INVALID_ENTRY` in their AtkStateSet. `Since` : ATK-2.26. |
ATK_RELATION_ERROR_FOR | Reciprocal of `ATK_RELATION_ERROR_MESSAGE`. Indicates that this object contains an error message describing an invalid condition in the target object(s). `Since` : ATK_2.26. |
ATK_RELATION_LAST_DEFINED | Not used, this value indicates the end of the enumeration. |

## Property Details

### The `“relation-type”` property

      “relation-type”            AtkRelationType

The type of the relation.

Owner: AtkRelation

Flags: Read / Write

Default value: ATK_RELATION_NULL

### The `“target”` property

      “target”                   GValueArray *

An array of the targets for the relation.

Owner: AtkRelation

Flags: Read / Write