gecko/accessible/public/nsIAccessNode.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 2003
 * the Initial Developer. All Rights Reserved.
 *
 * Original Author: Aaron Leventhal (aaronl@netscape.com)
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"
	
interface nsIDOMNode;
interface nsIAccessibleDocument;

/**
 * An interface used by in-process accessibility clients
 * to get style, window, markup and other information about
 * a DOM node. When accessibility is active in Gecko,
 * every DOM node can have one nsIAccessNode for each
 * pres shell the DOM node is rendered in.
 * The nsIAccessNode implementations are instantiated lazily.
 * The nsIAccessNode tree for a given dom window
 * has a one to one relationship to the DOM tree.
 * If the DOM node for this access node is "accessible",
 * then a QueryInterface to nsIAccessible will succeed.
 *
 * @status UNDER_REVIEW
 */
[scriptable, uuid(0bd7ccde-486d-483c-a6df-79869cb6647d)]
interface nsIAccessNode : nsISupports
{
  /**
   * The DOM node this nsIAccessNode is associated with.
   */
  readonly attribute nsIDOMNode DOMNode;

  /**
   * The number of DOM children for the DOM node, which
   * matches the number of nsIAccessNode children for this
   * nsIAccessNode.
   */
  readonly attribute long numChildren;
  
  /**
   * Get the nth child of this node
   * @param childNum Zero-based child index
   * @return The nth nsIAccessNode child
   */
  nsIAccessNode getChildNodeAt(in long childNum);
  
  /**
   * The parent nsIAccessNode
   */
  readonly attribute nsIAccessNode parentNode;

  /**
   * The first nsIAccessNode child
   */
  readonly attribute nsIAccessNode firstChildNode;

  /**
   * The last nsIAccessNode child
   */
  readonly attribute nsIAccessNode lastChildNode;
  
  /**
   * The previous nsIAccessNode sibling
   */
  readonly attribute nsIAccessNode previousSiblingNode;

  /**
   * The next nsIAccessNode sibling
   */
  readonly attribute nsIAccessNode nextSiblingNode;

  /**
   * The nsIAccessibleDocument that this nsIAccessNode
   * resides in.
   */
  readonly attribute nsIAccessibleDocument accessibleDocument;
  
  /**
   * The innerHTML for the DOM node
   * This is a text string of all the markup inside the DOM
   * node, not including the start and end tag for the node.
   */
  readonly attribute DOMString innerHTML;

  /**
   * Makes an object visible on screen.
   *
   * @param topLeft - if false then it will scroll the shortest distance it
   *                  needs to put the element on-screen.
   */
  void scrollTo(in boolean aTopLeft);

  /**
   * The OS window handle for the window this node
   * is being displayed in.
   */
  [noscript] readonly attribute voidPtr ownerWindow;
  
  /**
   * A unique ID calculated for this DOM node, for the 
   * purposes of caching and referencing this object.
   */
  [noscript] readonly attribute voidPtr uniqueID;

  /**
   * Retrieve the computed style value for this DOM node, if it is a DOM element.
   * Note: the meanings of width, height and other size measurements depend
   * on the version of CSS being used. Therefore, for bounds information, 
   * it is better to use nsIAccessible::accGetBounds.
   * @param pseudoElt The pseudo element to retrieve style for, or NULL
   *                  for general computed style information for this node.
   * @param propertyName Retrieve the computed style value for this property name,
   *                     for example "border-bottom".
   */
  DOMString getComputedStyleValue(in DOMString pseudoElt, in DOMString propertyName);
};