/gecko_sdk/idl/nsIDOMWindowUtils.idl

  1/* -*- Mode: IDL; 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 * Mozilla.org
 19 * Portions created by the Initial Developer are Copyright (C) 2004
 20 * the Initial Developer. All Rights Reserved.
 21 *
 22 * Contributor(s):
 23 *
 24 * Alternatively, the contents of this file may be used under the terms of
 25 * either of the GNU General Public License Version 2 or later (the "GPL"),
 26 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 27 * in which case the provisions of the GPL or the LGPL are applicable instead
 28 * of those above. If you wish to allow use of your version of this file only
 29 * under the terms of either the GPL or the LGPL, and not to allow others to
 30 * use your version of this file under the terms of the MPL, indicate your
 31 * decision by deleting the provisions above and replace them with the notice
 32 * and other provisions required by the GPL or the LGPL. If you do not delete
 33 * the provisions above, a recipient may use your version of this file under
 34 * the terms of any one of the MPL, the GPL or the LGPL.
 35 *
 36 * ***** END LICENSE BLOCK ***** */
 37
 38#include "nsISupports.idl"
 39
 40/**
 41 * nsIDOMWindowUtils is intended for infrequently-used methods related
 42 * to the current nsIDOMWindow.  Some of the methods may require
 43 * elevated privileges; the method implementations should contain the
 44 * necessary security checks.  Access this interface by calling
 45 * getInterface on a DOMWindow.
 46 */
 47
 48interface nsIDOMElement;
 49
 50[scriptable, uuid(1cfc1a0a-e348-4b18-b61b-935c192f85c4)]
 51interface nsIDOMWindowUtils : nsISupports {
 52
 53  /**
 54   * Image animation mode of the window. When this attribute's value
 55   * is changed, the implementation should set all images in the window
 56   * to the given value. That is, when set to kDontAnimMode, all images
 57   * will stop animating. The attribute's value must be one of the
 58   * animationMode values from imgIContainer.
 59   * @note Images may individually override the window's setting after
 60   *       the window's mode is set. Therefore images given different modes
 61   *       since the last setting of the window's mode may behave
 62   *       out of line with the window's overall mode.
 63   * @note The attribute's value is the window's overall mode. It may
 64   *       for example continue to report kDontAnimMode after all images
 65   *       have subsequently been individually animated.
 66   * @note Only images immediately in this window are affected;
 67   *       this is not recursive to subwindows.
 68   * @see imgIContainer
 69   */
 70  attribute unsigned short imageAnimationMode;
 71
 72  /**
 73   * Whether the charset of the window's current document has been forced by
 74   * the user.
 75   * Cannot be accessed from unprivileged context (not content-accessible)
 76   */
 77  readonly attribute boolean docCharsetIsForced;
 78
 79  /**
 80   * Function to get metadata associated with the window's current document
 81   * @param aName the name of the metadata.  This should be all lowercase.
 82   * @return the value of the metadata, or the empty string if it's not set
 83   *
 84   * Will throw a DOM security error if called without UniversalXPConnect
 85   * privileges.
 86   */
 87  AString getDocumentMetadata(in AString aName);
 88
 89  /**
 90   * Force an immediate redraw of this window.
 91   */
 92  void redraw();
 93
 94  /** Synthesize a mouse event for a window. The event types supported
 95   *  are: 
 96   *    mousedown, mouseup, mousemove, mouseover, mouseout, contextmenu
 97   *
 98   * Events are sent in coordinates offset by aX and aY from the window.
 99   *
100   * Note that additional events may be fired as a result of this call. For
101   * instance, typically a click event will be fired as a result of a
102   * mousedown and mouseup in sequence.
103   *
104   * Normally at this level of events, the mouseover and mouseout events are
105   * only fired when the window is entered or exited. For inter-element
106   * mouseover and mouseout events, a movemove event fired on the new element
107   * should be sufficient to generate the correct over and out events as well.
108   *
109   * Cannot be accessed from unprivileged context (not content-accessible)
110   * Will throw a DOM security error if called without UniversalXPConnect
111   * privileges.
112   *
113   * @param aType event type
114   * @param aX x offset
115   * @param aY y offset
116   * @param aButton button to synthesize
117   * @param aClickCount number of clicks that have been performed
118   * @param aModifiers modifiers pressed, using constants defined in nsIDOMNSEvent
119   */
120  void sendMouseEvent(in AString aType,
121                      in long aX,
122                      in long aY,
123                      in long aButton,
124                      in long aClickCount,
125                      in long aModifiers);
126
127  /**
128   * Synthesize a key event to the window. The event types supported are:
129   *   keydown, keyup, keypress
130   *
131   * Key events generally end up being sent to the focused node.
132   *
133   * Cannot be accessed from unprivileged context (not content-accessible)
134   * Will throw a DOM security error if called without UniversalXPConnect
135   * privileges.
136   *
137   * @param aType event type
138   * @param aKeyCode key code
139   * @param aCharCode character code
140   * @param aModifiers modifiers pressed, using constants defined in nsIDOMNSEvent
141   */
142  void sendKeyEvent(in AString aType,
143                    in long aKeyCode,
144                    in long aCharCode,
145                    in long aModifiers);
146
147  /**
148   * See nsIWidget::SynthesizeNativeKeyEvent
149   *
150   * Cannot be accessed from unprivileged context (not content-accessible)
151   * Will throw a DOM security error if called without UniversalXPConnect
152   * privileges.
153   */
154  void sendNativeKeyEvent(in long aNativeKeyboardLayout,
155                          in long aNativeKeyCode,
156                          in long aModifierFlags,
157                          in AString aCharacters,
158                          in AString aUnmodifiedCharacters);
159
160  /**
161   * Focus the element aElement. The element should be in the same document
162   * that the window is displaying. Pass null to blur the element, if any,
163   * that currently has focus, and focus the document.
164   *
165   * Cannot be accessed from unprivileged context (not content-accessible)
166   * Will throw a DOM security error if called without UniversalXPConnect
167   * privileges.
168   *
169   * @param aElement the element to focus
170   */
171  void focus(in nsIDOMElement aElement);
172
173  /**
174   * Force a garbage collection. This will run the cycle-collector twice to
175   * make sure all garbage is collected.
176   *
177   * Will throw a DOM security error if called without UniversalXPConnect
178   * privileges in non-debug builds. Available to all callers in debug builds.
179   */
180  void garbageCollect();
181};