AtkRelation

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

## Synopsis

    struct              AtkRelation;
    enum                AtkRelationType;
    AtkRelationType     atk_relation_type_register          (const gchar *name);
    const gchar *       atk_relation_type_get_name          (AtkRelationType type);
    AtkRelationType     atk_relation_type_for_name          (const gchar *name);
    AtkRelation *       atk_relation_new                    (AtkObject **targets,
                                                             gint n_targets,
                                                             AtkRelationType relationship);
    AtkRelationType     atk_relation_get_relation_type      (AtkRelation *relation);
    GPtrArray *         atk_relation_get_target             (AtkRelation *relation);
    void                atk_relation_add_target             (AtkRelation *relation,
                                                             AtkObject *target);
    gboolean            atk_relation_remove_target          (AtkRelation *relation,
                                                             AtkObject *target);

## Object Hierarchy

      GObject
       +----AtkRelation

## Properties

      "relation-type"            AtkRelationType       : Read / Write
      "target"                   GValueArray*          : Read / Write

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

## Details

### struct AtkRelation

    struct AtkRelation;

The AtkRelation structure should not be accessed directly.

### enum AtkRelationType

    typedef enum {
      ATK_RELATION_NULL = 0,
      ATK_RELATION_CONTROLLED_BY,
      ATK_RELATION_CONTROLLER_FOR,
      ATK_RELATION_LABEL_FOR,
      ATK_RELATION_LABELLED_BY,
      ATK_RELATION_MEMBER_OF,
      ATK_RELATION_NODE_CHILD_OF,
      ATK_RELATION_FLOWS_TO,
      ATK_RELATION_FLOWS_FROM,
      ATK_RELATION_SUBWINDOW_OF,
      ATK_RELATION_EMBEDS,
      ATK_RELATION_EMBEDDED_BY,
      ATK_RELATION_POPUP_FOR,
      ATK_RELATION_PARENT_WINDOW_OF,
      ATK_RELATION_DESCRIBED_BY,
      ATK_RELATION_DESCRIPTION_FOR,
      ATK_RELATION_NODE_PARENT_OF,
      ATK_RELATION_LAST_DEFINED
    } AtkRelationType;

Describes the type of the relation

`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` | Inverse 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` | Indicates that another object provides descriptive information about this object; more verbose than ATK_RELATION_LABELLED_BY.
`ATK_RELATION_DESCRIPTION_FOR` | Indicates that an object provides descriptive information about another object; more verbose than ATK_RELATION_LABEL_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_LAST_DEFINED` | Not used, this value indicates the end of the enumeration.

### atk_relation_type_register ()

    AtkRelationType     atk_relation_type_register          (const gchar *name);

Associate `name` with a new AtkRelationType

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

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

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

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

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

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

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

`relation` : | an AtkRelation
`target` : | an AtkObject
Returns : | TRUE if the removal is successful.

## Property Details

### The `"relation-type"` property

      "relation-type"            AtkRelationType       : Read / Write

The type of the relation.

Default value: ATK_RELATION_NULL

### The `"target"` property

      "target"                   GValueArray*          : Read / Write

An array of the targets for the relation.