idl/Accessibility_Relation.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef _ACCESSIBILITY_RELATION_IDL
  24 #define _ACCESSIBILITY_RELATION_IDL
  25
  26 module Accessibility {
  27
  28     /**
  29      * RelationType specifies a relationship between objects (possibly one-to-many or many-to-one)
  30      * outside of the normal parent/child hierarchical relationship.  It allows better semantic
  31      * identification of how objects are associated with one another.
  32      * For instance the RELATION_LABELLED_BY relationship may be used to identify labelling information
  33      * that should accompany the accessibleName property when presenting an object's content or identity
  34      * to the end user.  Similarly, RELATION_CONTROLLER_FOR can be used to further specify the context
  35      * in which a valuator is useful, and/or the other UI components which are directly effected by
  36      * user interactions with the valuator.  Common examples include association of scrollbars with
  37      * the viewport or panel which they control.
  38      */
  39   enum RelationType {
  40     /** Not a meaningful relationship; clients should not normally encounter this RelationType value. */
  41     RELATION_NULL,
  42     /** Object is a label for one or more other objects. */
  43     RELATION_LABEL_FOR,
  44     /** Object is labelled by one or more other objects. */
  45     RELATION_LABELLED_BY,
  46     /** Object is an interactive object which modifies the state, onscreen location, or other attributes
  47      * of one or more target objects. */
  48     RELATION_CONTROLLER_FOR,
  49     /** Object state, position, etc. is modified/controlled by user interaction with one or
  50      * more other objects.   For instance a viewport or scroll pane may be CONTROLLED_BY scrollbars. */
  51     RELATION_CONTROLLED_BY,
  52     /** Object has a grouping relationship (e.g. ¨same group as¨) to one or more other objects.  */
  53     RELATION_MEMBER_OF,
  54     /** Object is a tooltip associated with another object. */
  55     RELATION_TOOLTIP_FOR,
  56     /** Reserved for future use. */
  57     RELATION_NODE_CHILD_OF,
  58     /** Used to indicate that a relationship exists, but its type is not specified in the enumeration
  59      * and must be obtained via a call to getRelationTypeName.  */
  60     RELATION_EXTENDED,
  61     /** Object renders content which flows logically to another object.
  62      * For instance, text in a paragraph may flow to another object which is not the
  63      * ¨next sibling¨ in the accessibility hierarchy. */
  64     RELATION_FLOWS_TO,
  65     /** Reciprocal of RELATION_FLOWS_TO. */
  66     RELATION_FLOWS_FROM,
  67     /** Object is visually and semantically considered a subwindow of another object, even though
  68      * it is not the object's child.  Useful when dealing with embedded applications and other cases
  69      * where the widget hierarchy does not map cleanly to the onscreen presentation.  */
  70     RELATION_SUBWINDOW_OF,
  71     /** Similar to SUBWINDOW_OF, but specifically used for cross-process embedding.  */
  72     RELATION_EMBEDS,
  73     /** Reciprocal of RELATION_EMBEDS; Used to denote content rendered by embedded renderers that
  74      * live in a separate process space from the embedding context.  */
  75     RELATION_EMBEDDED_BY,
  76     /** Denotes that the object is a transient window or frame associated with another onscreen object.
  77      * Similar to TOOLTIP_FOR, but more general.  Useful for windows which are technically
  78      * toplevels but which, for one or more reasons, do not explicitly cause their associated
  79      * window to lose ¨window focus¨.   Creation of a ROLE_WINDOW object with the POPUP_FOR relation
  80      * usually requires some presentation action on the part of assistive technology clients, even though
  81      * the previous toplevel ROLE_FRAME object may still be the active window.  */
  82     RELATION_POPUP_FOR,
  83     /** This is the reciprocal relation to RELATION_POPUP_FOR. */
  84     RELATION_PARENT_WINDOW_OF,
  85     /** Indicates that an object provides descriptive information
  86      * about another object; more verbose than RELATION_LABEL_FOR. */
  87     RELATION_DESCRIPTION_FOR,
  88     /** Indicates that another object provides descriptive information
  89      * about this object; more verbose than RELATION_LABELLED_BY. */
  90     RELATION_DESCRIBED_BY,
  91     /** Do not use as a parameter value, used to determine the size of the enumeration. */
  92     RELATION_LAST_DEFINED
  93   };
  94
  95   /**
  96    * An interface via which objects' non-hierarchical relationships to one another
  97    * are indicated.  An instance of Relations represents a "one-to-many" correspondance.
  98    *
  99    * @note This interface inherits from a base class implementing ref counts.
 100    */
 101   interface Relation : Bonobo::Unknown {
 102
 103     /** @returns the RelationType of this Relation. */
 104     RelationType        getRelationType ();
 105
 106     /** @returns an unlocalized string representing the relation type. */
 107     string              getRelationTypeName ();
 108
 109     /** @returns the number of objects to which this relationship applies. */
 110     short               getNTargets ();
 111
 112     /** @returns an Object which is the 'nth'target of this Relation, e.g. the Object at index i
 113      * in the list of Objects having the specified relationship to this Accessible.
 114      * \note This target should always implement Accessible, though it is returned as an Object.
 115      * (In this respect this method is probably ill-specified.)
 116      **/
 117     Object              getTarget (in short index);
 118
 119     /** \cond placeholders for future expansion */
 120     void unImplemented ();
 121     void unImplemented2 ();
 122     void unImplemented3 ();
 123     void unImplemented4 ();
 124     /** \endcond */
 125   };
 126 };
 127
 128 #endif