accessible/public/nsIAccessibleRetrieval.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 2003
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Original Author: Aaron Leventhal (aaronl@netscape.com)
  23  * Contributor(s): Kyle Yuan (kyle.yuan@sun.com)
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsISupports.idl"
  40
  41 interface nsIDOMNode;
  42 interface nsIAccessible;
  43 interface nsIWeakReference;
  44 interface nsIPresShell;
  45 interface nsIDOMWindow;
  46 interface nsIAccessNode;
  47 interface nsIDOMDOMStringList;
  48
  49
  50 /**
  51  * An interface for in-process accessibility clients
  52  * wishing to get an nsIAccessible or nsIAccessNode for
  53  * a given DOM node.
  54  * More documentation at:
  55  *   http://www.mozilla.org/projects/ui/accessibility
  56  *
  57  * @status UNDER_REVIEW
  58  */
  59 [scriptable, uuid(244e4c67-a1d3-44f2-9cab-cdaa31b68046)]
  60 interface nsIAccessibleRetrieval : nsISupports
  61 {
  62   /**
  63    * Return an nsIAccessible for a DOM node in pres shell 0.
  64    * Create a new accessible of the appropriate type if necessary,
  65    * or use one from the accessibility cache if it already exists.
  66    * @param aNode The DOM node to get an accessible for.
  67    * @return The nsIAccessible for the given DOM node.
  68    */
  69   nsIAccessible getAccessibleFor(in nsIDOMNode aNode);
  70
  71   /**
  72    * The same like getAccessibleFor method except it returns accessible only if
  73    * it is attached, i.e. accessible is certified to be a descendent of the root
  74    * accessible.
  75    *
  76    * @param aNode - the DOM node to get an accessible for.
  77    *
  78    * @return - the accessible for the given DOM node.
  79    */
  80   nsIAccessible getAttachedAccessibleFor(in nsIDOMNode aNode);
  81
  82   /**
  83    * Return an DOM node that is relevant to attached accesible check. This
  84    * node is either from bindings chain if given node is anonymous and owner
  85    * binding denies accessible in anonymous content or given node (it's not
  86    * important whether it is accessible or not). This method doesn't create
  87    * accessible object for returned node.
  88    *
  89    * @param aNode - the DOM node to get relevant content node.
  90    *
  91    * @return - the DOM node for parent attached accessible
  92    */
  93   nsIDOMNode getRelevantContentNodeFor(in nsIDOMNode aNode);
  94
  95   /**
  96    * Return an nsIAccessible for a DOM node in pres shell for this DOM window.
  97    * Create a new accessible of the appropriate type if necessary,
  98    * or use one from the accessibility cache if it already exists.
  99    * @param aNode   The DOM node to get an accessible for.
 100    * @param aDOMWin The DOM window containing the node.
 101    * @return The nsIAccessible for the given DOM node.
 102    */
 103   nsIAccessible getAccessibleInWindow(in nsIDOMNode aNode, in nsIDOMWindow aDOMWin);
 104
 105   /**
 106    * Return an nsIAccessible for a DOM node in the given weak shell.
 107    * Create a new accessible of the appropriate type if necessary,
 108    * or use one from the accessibility cache if it already exists.
 109    * @param aNode      The DOM node to get an accessible for.
 110    * @param aPresShell The presentation shell which contains layout info for the DOM node.
 111    * @return The nsIAccessible for the given DOM node.
 112    */
 113   nsIAccessible getAccessibleInWeakShell(in nsIDOMNode aNode, in nsIWeakReference aPresShell);
 114
 115   /**
 116    * Return an nsIAccessible for a DOM node in the given pres shell.
 117    * Create a new accessible of the appropriate type if necessary,
 118    * or use one from the accessibility cache if it already exists.
 119    * @param aNode      The DOM node to get an accessible for.
 120    * @param aPresShell The presentation shell which contains layout info for the DOM node.
 121    * @return The nsIAccessible for the given DOM node.
 122    */
 123   nsIAccessible getAccessibleInShell(in nsIDOMNode aNode, in nsIPresShell aPresShell);
 124
 125    /**
 126     * Return an nsIAccessNode for an already created DOM node in the given weak shell.
 127     * Does not create a new one -- only returns cached access nodes.
 128     * @param aNode      The DOM node to get an access node for.
 129     * @param aPresShell The presentation shell which contains layout info for the DOM node.
 130     * @return The nsIAccessNode for the given DOM node or null if
 131     *         an access node does not already exist for this DOM node.
 132     */
 133   nsIAccessNode getCachedAccessNode(in nsIDOMNode aNode, in nsIWeakReference aShell);
 134
 135    /**
 136     * Return an nsIAccessible for an already created DOM node in the given weak shell.
 137     * Does not create a new one -- only returns cached accessibles.
 138     * @param aNode      The DOM node to get an accessible for.
 139     * @param aPresShell The presentation shell which contains layout info for the DOM node.
 140     * @return The nsIAccessible for the given DOM node or null if
 141     *         an accessible does not already exist for this DOM node.
 142     */
 143   nsIAccessible getCachedAccessible(in nsIDOMNode aNode, in nsIWeakReference aShell);
 144
 145    /**
 146     * Returns accessible role as a string.
 147     *
 148     * @param aRole - the accessible role constants.
 149     */
 150   AString getStringRole(in unsigned long aRole);
 151
 152    /**
 153     * Returns list which contains accessible states as a strings.
 154     *
 155     * @param aStates - accessible states.
 156     * @param aExtraStates - accessible extra states.
 157     */
 158   nsIDOMDOMStringList getStringStates(in unsigned long aStates,
 159                                       in unsigned long aExtraStates);
 160
 161   /**
 162    * Get the type of accessible event as a string.
 163    *
 164    * @param aEventType - the accessible event type constant
 165    * @return - accessible event type presented as human readable string
 166    */
 167   AString getStringEventType(in unsigned long aEventType);
 168
 169   /**
 170    * Get the type of accessible relation as a string.
 171    *
 172    * @param aRelationType - the accessible relation type constant
 173    * @return - accessible relation type presented as human readable string
 174    */
 175   AString getStringRelationType(in unsigned long aRelationType);
 176 };
 177
 178
 179 %{ C++
 180
 181 // for component registration
 182 // {663CA4A8-D219-4000-925D-D8F66406B626}
 183 #define NS_ACCESSIBLE_RETRIEVAL_CID \
 184 { 0x663ca4a8, 0xd219, 0x4000, { 0x92, 0x5d, 0xd8, 0xf6, 0x64, 0x6, 0xb6, 0x26 } }
 185
 186 %}