# AtkRelation

## Name

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

## Object Hierarchy

      GObject
       +----AtkRelation

## 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_LAST_DEFINED
    } AtkRelationType;

Describes the type of the relation

`ATK_RELATION_NULL`

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

  [not sure about this one, ask Peter]

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

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

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

`targets` :

  an array of pointers to AtkObjects

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