/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "domstubs.idl"
#include "nsIDOMDocument.idl"

interface nsIDOMXULCommandDispatcher;
interface nsIObserver;
interface nsIBoxObject;

[scriptable, uuid(efdb94fb-642f-4a79-ae20-9a5f7cb7f736)]
interface nsIDOMXULDocument : nsIDOMDocument
{
  attribute nsIDOMNode                          popupNode;

  /**
   * These attributes correspond to trustedGetPopupNode().rangeOffset and
   * rangeParent. They will help you find where in the DOM the popup is
   * happening. Can be accessed from chrome only, and only during a popup
   * event. Accessing any other time will be an error.
   */
  readonly attribute nsIDOMNode                 popupRangeParent;
  readonly attribute long                       popupRangeOffset;

  attribute nsIDOMNode                          tooltipNode;

  readonly attribute nsIDOMXULCommandDispatcher commandDispatcher;

  readonly attribute long                       width;
  readonly attribute long                       height;

  nsIDOMNodeList            getElementsByAttribute(in DOMString name,
                                                   in DOMString value);

  nsIDOMNodeList            getElementsByAttributeNS(in DOMString namespaceURI,
                                                     in DOMString name,
                                                     in DOMString value);

  void                      addBroadcastListenerFor(in nsIDOMElement broadcaster,
                                                    in nsIDOMElement observer,
                                                    in DOMString attr);

  void                      removeBroadcastListenerFor(in nsIDOMElement broadcaster,
                                                       in nsIDOMElement observer,
                                                       in DOMString attr);

  void                      persist(in DOMString id, in DOMString attr);

  nsIBoxObject getBoxObjectFor(in nsIDOMElement elt);

  /**
   * Loads a XUL overlay and merges it with the current document, notifying an
   * observer when the merge is complete. 
   * @param   url
   *          The URL of the overlay to load and merge
   * @param   observer
   *          An object implementing nsIObserver that will be notified with a
   *          message of topic "xul-overlay-merged" when the merge is complete. 
   *          The subject parameter of |observe| will QI to a nsIURI - the URI 
   *          of the merged overlay. This parameter is optional and may be null.
   *
   * NOTICE:  In the 2.0 timeframe this API will change such that the 
   *          implementation will fire a DOMXULOverlayMerged event upon merge
   *          completion rather than notifying an observer. Do not rely on this
   *          API's behavior _not_ to change because it will!
   *          - Ben Goodger (8/23/2005)
   */
  void                      loadOverlay(in DOMString url, in nsIObserver aObserver);
};