dom/interfaces/base/nsIDOMWindowUtils.idl@b8a032363ba2
dom/interfaces/base/nsIDOMWindowUtils.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 /**
9 * nsIDOMWindowUtils is intended for infrequently-used methods related
10 * to the current nsIDOMWindow. Some of the methods may require
11 * elevated privileges; the method implementations should contain the
12 * necessary security checks. Access this interface by calling
13 * getInterface on a DOMWindow.
14 */
16 %{C++
17 #include "nsColor.h"
18 class gfxContext;
19 class nsRect;
20 %}
22 [ref] native nsConstRect(const nsRect);
23 native nscolor(nscolor);
24 [ptr] native gfxContext(gfxContext);
25 typedef unsigned long long nsViewID;
27 interface nsICycleCollectorListener;
28 interface nsIDOMNode;
29 interface nsIDOMNodeList;
30 interface nsIDOMElement;
31 interface nsIDOMHTMLCanvasElement;
32 interface nsIDOMEvent;
33 interface nsITransferable;
34 interface nsIQueryContentEventResult;
35 interface nsIDOMWindow;
36 interface nsIDOMBlob;
37 interface nsIDOMFile;
38 interface nsIFile;
39 interface nsIDOMClientRect;
40 interface nsIURI;
41 interface nsIDOMEventTarget;
42 interface nsIRunnable;
43 interface nsICompositionStringSynthesizer;
44 interface nsITranslationNodeList;
46 [scriptable, uuid(d4ed34fc-9c07-4cef-b9e1-623794558db3)]
47 interface nsIDOMWindowUtils : nsISupports {
49 /**
50 * Image animation mode of the window. When this attribute's value
51 * is changed, the implementation should set all images in the window
52 * to the given value. That is, when set to kDontAnimMode, all images
53 * will stop animating. The attribute's value must be one of the
54 * animationMode values from imgIContainer.
55 * @note Images may individually override the window's setting after
56 * the window's mode is set. Therefore images given different modes
57 * since the last setting of the window's mode may behave
58 * out of line with the window's overall mode.
59 * @note The attribute's value is the window's overall mode. It may
60 * for example continue to report kDontAnimMode after all images
61 * have subsequently been individually animated.
62 * @note Only images immediately in this window are affected;
63 * this is not recursive to subwindows.
64 * @see imgIContainer
65 */
66 attribute unsigned short imageAnimationMode;
68 /**
69 * Whether the charset of the window's current document has been forced by
70 * the user.
71 * Cannot be accessed from unprivileged context (not content-accessible)
72 */
73 readonly attribute boolean docCharsetIsForced;
75 /**
76 * Get current cursor type from this window
77 * @return the current value of nsCursor
78 */
79 short getCursorType();
81 /**
82 * Function to get metadata associated with the window's current document
83 * @param aName the name of the metadata. This should be all lowercase.
84 * @return the value of the metadata, or the empty string if it's not set
85 *
86 * Will throw a DOM security error if called without chrome privileges.
87 */
88 AString getDocumentMetadata(in AString aName);
90 /**
91 * Force an immediate redraw of this window. The parameter specifies
92 * the number of times to redraw, and the return value is the length,
93 * in milliseconds, that the redraws took. If aCount is not specified
94 * or is 0, it is taken to be 1.
95 */
96 unsigned long redraw([optional] in unsigned long aCount);
98 /**
99 * Set the CSS viewport to be |widthPx| x |heightPx| in units of CSS
100 * pixels, regardless of the size of the enclosing widget/view.
101 * This will trigger reflow.
102 *
103 * The caller of this method must have chrome privileges.
104 */
105 void setCSSViewport(in float aWidthPx, in float aHeightPx);
107 /**
108 * Information retrieved from the <meta name="viewport"> tag.
109 * See nsContentUtils::GetViewportInfo for more information.
110 */
111 void getViewportInfo(in uint32_t aDisplayWidth, in uint32_t aDisplayHeight,
112 out double aDefaultZoom, out boolean aAllowZoom,
113 out double aMinZoom, out double aMaxZoom,
114 out uint32_t aWidth, out uint32_t aHeight,
115 out boolean aAutoSize);
117 /**
118 * For any scrollable element, this allows you to override the
119 * visible region and draw more than what is visible, which is
120 * useful for asynchronous drawing. The "displayport" will be
121 * <xPx, yPx, widthPx, heightPx> in units of CSS pixels,
122 * regardless of the size of the enclosing container. This
123 * will *not* trigger reflow.
124 *
125 * For the root scroll area, pass in the root document element.
126 * For scrollable elements, pass in the container element (for
127 * instance, the element with overflow: scroll).
128 *
129 * <x, y> is relative to the top-left of what would normally be
130 * the visible area of the element. This means that the pixels
131 * rendered to the displayport take scrolling into account,
132 * for example.
133 *
134 * It's legal to set a displayport that extends beyond the overflow
135 * area in any direction (left/right/top/bottom).
136 *
137 * It's also legal to set a displayport that extends beyond the
138 * area's bounds. No pixels are rendered outside the area bounds.
139 *
140 * The caller of this method must have chrome privileges.
141 *
142 * Calling this will always force a recomposite, so it should be
143 * avoided if at all possible. Client code should do checks before
144 * calling this so that duplicate sets are not made with the same
145 * displayport.
146 *
147 * aPriority is recorded along with the displayport rectangle. If this
148 * method is called with a lower priority than the current priority, the
149 * call is ignored.
150 */
151 void setDisplayPortForElement(in float aXPx, in float aYPx,
152 in float aWidthPx, in float aHeightPx,
153 in nsIDOMElement aElement,
154 in uint32_t aPriority);
155 /**
156 * An alternate way to represent a displayport rect as a set of margins and a
157 * base rect to apply those margins to. A consumer of pixels may ask for as
158 * many extra pixels as it would like in each direction. Layout then sets
159 * the base rect to the "visible rect" of the element, which is just the
160 * subrect of the element that is drawn (it does not take in account content
161 * covering the element).
162 *
163 * If both a displayport rect and displayport margins with corresponding base
164 * rect are set with the same priority then the margins will take precendence.
165 *
166 * Specifying an alignment value will ensure that after the base rect has
167 * been expanded by the displayport margins, it will be further expanded so
168 * that each edge is located at a multiple of the "alignment" value.
169 *
170 * Note that both the margin values and alignment are treated as values in
171 * LayerPixels. Refer to layout/base/Units.h for a description of this unit.
172 * The base rect values are in app units.
173 */
174 void setDisplayPortMarginsForElement(in float aLeftMargin,
175 in float aTopMargin,
176 in float aRightMargin,
177 in float aBottomMargin,
178 in uint32_t aAlignmentX,
179 in uint32_t aAlignmentY,
180 in nsIDOMElement aElement,
181 in uint32_t aPriority);
183 void setDisplayPortBaseForElement(in int32_t aX,
184 in int32_t aY,
185 in int32_t aWidth,
186 in int32_t aHeight,
187 in nsIDOMElement aElement);
189 /**
190 * When a display port is set, this allows a sub-section of that
191 * display port to be marked as 'critical'. In this scenario, the
192 * area outside of this rectangle may be rendered at a lower
193 * detail (for example, by reducing its resolution), or not rendered
194 * at all under some circumstances.
195 * This call will have no effect if a display port has not been set.
196 */
197 void setCriticalDisplayPortForElement(in float aXPx, in float aYPx,
198 in float aWidthPx, in float aHeightPx,
199 in nsIDOMElement aElement);
201 /**
202 * Get/set the resolution at which rescalable web content is drawn.
203 * Currently this is only (some) thebes content.
204 *
205 * Setting a new resolution does *not* trigger reflow. This API is
206 * entirely separate from textZoom and fullZoom; a resolution scale
207 * can be applied together with both textZoom and fullZoom.
208 *
209 * The effect of is API for gfx code to allocate more or fewer
210 * pixels for rescalable content by a factor of |resolution| in
211 * either or both dimensions. setResolution() together with
212 * setDisplayport() can be used to implement a non-reflowing
213 * scale-zoom in concert with another entity that can draw with a
214 * scale. For example, to scale a content |window| inside a
215 * <browser> by a factor of 2.0
216 *
217 * window.setDisplayport(x, y, oldW / 2.0, oldH / 2.0);
218 * window.setResolution(2.0, 2.0);
219 * // elsewhere
220 * browser.setViewportScale(2.0, 2.0);
221 *
222 * The caller of this method must have chrome privileges.
223 */
224 void setResolution(in float aXResolution, in float aYResolution);
226 void getResolution(out float aXResolution, out float aYResolution);
228 /**
229 * Whether the resolution has been set by the user.
230 * This gives a way to check whether the provided resolution is the default
231 * value or restored from a previous session.
232 *
233 * Can only be accessed with chrome privileges.
234 */
235 readonly attribute boolean isResolutionSet;
237 /**
238 * Whether the next paint should be flagged as the first paint for a document.
239 * This gives a way to track the next paint that occurs after the flag is
240 * set. The flag gets cleared after the next paint.
241 *
242 * Can only be accessed with chrome privileges.
243 */
244 attribute boolean isFirstPaint;
246 void getPresShellId(out uint32_t aPresShellId);
248 /**
249 * Following modifiers are for sent*Event() except sendNative*Event().
250 * NOTE: MODIFIER_ALT, MODIFIER_CONTROL, MODIFIER_SHIFT and MODIFIER_META
251 * are must be same values as nsIDOMNSEvent::*_MASK for backward
252 * compatibility.
253 */
254 const long MODIFIER_ALT = 0x0001;
255 const long MODIFIER_CONTROL = 0x0002;
256 const long MODIFIER_SHIFT = 0x0004;
257 const long MODIFIER_META = 0x0008;
258 const long MODIFIER_ALTGRAPH = 0x0010;
259 const long MODIFIER_CAPSLOCK = 0x0020;
260 const long MODIFIER_FN = 0x0040;
261 const long MODIFIER_NUMLOCK = 0x0080;
262 const long MODIFIER_SCROLLLOCK = 0x0100;
263 const long MODIFIER_SYMBOLLOCK = 0x0200;
264 const long MODIFIER_OS = 0x0400;
266 /** Synthesize a mouse event. The event types supported are:
267 * mousedown, mouseup, mousemove, mouseover, mouseout, contextmenu,
268 * MozMouseHitTest
269 *
270 * Events are sent in coordinates offset by aX and aY from the window.
271 *
272 * Note that additional events may be fired as a result of this call. For
273 * instance, typically a click event will be fired as a result of a
274 * mousedown and mouseup in sequence.
275 *
276 * Normally at this level of events, the mouseover and mouseout events are
277 * only fired when the window is entered or exited. For inter-element
278 * mouseover and mouseout events, a movemove event fired on the new element
279 * should be sufficient to generate the correct over and out events as well.
280 *
281 * Cannot be accessed from unprivileged context (not content-accessible)
282 * Will throw a DOM security error if called without chrome privileges.
283 *
284 * The event is dispatched via the toplevel window, so it could go to any
285 * window under the toplevel window, in some cases it could never reach this
286 * window at all.
287 *
288 * @param aType event type
289 * @param aX x offset in CSS pixels
290 * @param aY y offset in CSS pixels
291 * @param aButton button to synthesize
292 * @param aClickCount number of clicks that have been performed
293 * @param aModifiers modifiers pressed, using constants defined as MODIFIER_*
294 * @param aIgnoreRootScrollFrame whether the event should ignore viewport bounds
295 * during dispatch
296 * @param aPressure touch input pressure: 0.0 -> 1.0
297 * @param aInputSourceArg input source, see nsIDOMMouseEvent for values,
298 * defaults to mouse input.
299 * @param aIsSynthesized controls nsIDOMEvent.isSynthesized value
300 * that helps identifying test related events,
301 * defaults to true
302 *
303 * returns true if the page called prevent default on this event
304 */
305 [optional_argc]
306 boolean sendMouseEvent(in AString aType,
307 in float aX,
308 in float aY,
309 in long aButton,
310 in long aClickCount,
311 in long aModifiers,
312 [optional] in boolean aIgnoreRootScrollFrame,
313 [optional] in float aPressure,
314 [optional] in unsigned short aInputSourceArg,
315 [optional] in boolean aIsSynthesized);
318 /** Synthesize a pointer event. The event types supported are:
319 * pointerdown, pointerup, pointermove, pointerover, pointerout
320 *
321 * Events are sent in coordinates offset by aX and aY from the window.
322 *
323 * Note that additional events may be fired as a result of this call. For
324 * instance, typically a click event will be fired as a result of a
325 * mousedown and mouseup in sequence.
326 *
327 * Normally at this level of events, the pointerover and pointerout events are
328 * only fired when the window is entered or exited. For inter-element
329 * pointerover and pointerout events, a movemove event fired on the new element
330 * should be sufficient to generate the correct over and out events as well.
331 *
332 * Cannot be accessed from unprivileged context (not content-accessible)
333 * Will throw a DOM security error if called without chrome privileges.
334 *
335 * The event is dispatched via the toplevel window, so it could go to any
336 * window under the toplevel window, in some cases it could never reach this
337 * window at all.
338 *
339 * @param aType event type
340 * @param aX x offset in CSS pixels
341 * @param aY y offset in CSS pixels
342 * @param aButton button to synthesize
343 * @param aClickCount number of clicks that have been performed
344 * @param aModifiers modifiers pressed, using constants defined as MODIFIER_*
345 * @param aIgnoreRootScrollFrame whether the event should ignore viewport bounds
346 * during dispatch
347 * @param aPressure touch input pressure: 0.0 -> 1.0
348 * @param aInputSourceArg input source, see nsIDOMMouseEvent for values,
349 * defaults to mouse input.
350 * @param aPointerId A unique identifier for the pointer causing the event. default is 0
351 * @param aWidth The width (magnitude on the X axis), default is 0
352 * @param aHeight The height (magnitude on the Y axis), default is 0
353 * @param aTilt The plane angle between the Y-Z plane
354 * and the plane containing both the transducer (e.g. pen stylus) axis and the Y axis. default is 0
355 * @param aTiltX The plane angle between the X-Z plane
356 * and the plane containing both the transducer (e.g. pen stylus) axis and the X axis. default is 0
357 * @param aIsPrimary Indicates if the pointer represents the primary pointer of this pointer type.
358 * @param aIsSynthesized controls nsIDOMEvent.isSynthesized value
359 * that helps identifying test related events,
360 * defaults to true
361 *
362 * returns true if the page called prevent default on this event
363 */
365 [optional_argc]
366 boolean sendPointerEvent(in AString aType,
367 in float aX,
368 in float aY,
369 in long aButton,
370 in long aClickCount,
371 in long aModifiers,
372 [optional] in boolean aIgnoreRootScrollFrame,
373 [optional] in float aPressure,
374 [optional] in unsigned short aInputSourceArg,
375 [optional] in long aPointerId,
376 [optional] in long aWidth,
377 [optional] in long aHeight,
378 [optional] in long tiltX,
379 [optional] in long tiltY,
380 [optional] in boolean aIsPrimary,
381 [optional] in boolean aIsSynthesized);
383 /** Synthesize a touch event. The event types supported are:
384 * touchstart, touchend, touchmove, and touchcancel
385 *
386 * Events are sent in coordinates offset by aX and aY from the window.
387 *
388 * Cannot be accessed from unprivileged context (not content-accessible)
389 * Will throw a DOM security error if called without chrome privileges.
390 *
391 * The event is dispatched via the toplevel window, so it could go to any
392 * window under the toplevel window, in some cases it could never reach this
393 * window at all.
394 *
395 * @param aType event type
396 * @param xs array of offsets in CSS pixels for each touch to be sent
397 * @param ys array of offsets in CSS pixels for each touch to be sent
398 * @param rxs array of radii in CSS pixels for each touch to be sent
399 * @param rys array of radii in CSS pixels for each touch to be sent
400 * @param rotationAngles array of angles in degrees for each touch to be sent
401 * @param forces array of forces (floats from 0 to 1) for each touch to be sent
402 * @param count number of touches in this set
403 * @param aModifiers modifiers pressed, using constants defined as MODIFIER_*
404 * @param aIgnoreRootScrollFrame whether the event should ignore viewport bounds
405 * during dispatch
406 *
407 * returns true if the page called prevent default on this touch event
408 */
409 boolean sendTouchEvent(in AString aType,
410 [array, size_is(count)] in uint32_t aIdentifiers,
411 [array, size_is(count)] in int32_t aXs,
412 [array, size_is(count)] in int32_t aYs,
413 [array, size_is(count)] in uint32_t aRxs,
414 [array, size_is(count)] in uint32_t aRys,
415 [array, size_is(count)] in float aRotationAngles,
416 [array, size_is(count)] in float aForces,
417 in uint32_t count,
418 in long aModifiers,
419 [optional] in boolean aIgnoreRootScrollFrame);
421 /** The same as sendMouseEvent but ensures that the event is dispatched to
422 * this DOM window or one of its children.
423 */
424 [optional_argc]
425 void sendMouseEventToWindow(in AString aType,
426 in float aX,
427 in float aY,
428 in long aButton,
429 in long aClickCount,
430 in long aModifiers,
431 [optional] in boolean aIgnoreRootScrollFrame,
432 [optional] in float aPressure,
433 [optional] in unsigned short aInputSourceArg,
434 [optional] in boolean aIsSynthesized);
436 /** The same as sendTouchEvent but ensures that the event is dispatched to
437 * this DOM window or one of its children.
438 */
439 boolean sendTouchEventToWindow(in AString aType,
440 [array, size_is(count)] in uint32_t aIdentifiers,
441 [array, size_is(count)] in int32_t aXs,
442 [array, size_is(count)] in int32_t aYs,
443 [array, size_is(count)] in uint32_t aRxs,
444 [array, size_is(count)] in uint32_t aRys,
445 [array, size_is(count)] in float aRotationAngles,
446 [array, size_is(count)] in float aForces,
447 in uint32_t count,
448 in long aModifiers,
449 [optional] in boolean aIgnoreRootScrollFrame);
451 /** Synthesize a wheel event for a window. The event types supported is only
452 * wheel.
453 *
454 * Events are sent in coordinates offset by aX and aY from the window.
455 *
456 * Cannot be accessed from unprivileged context (not content-accessible)
457 * Will throw a DOM security error if called without chrome privileges.
458 *
459 * @param aX x offset in CSS pixels
460 * @param aY y offset in CSS pixels
461 * @param aDeltaX deltaX value.
462 * @param aDeltaY deltaY value.
463 * @param aDeltaZ deltaZ value.
464 * @param aDeltaMode deltaMode value which must be one of
465 * nsIDOMWheelEvent::DOM_DELTA_*.
466 * @param aModifiers modifiers pressed, using constants defined as
467 * MODIFIER_*
468 * @param aLineOrPageDeltaX If you set this value non-zero for
469 * DOM_DELTA_PIXEL event, EventStateManager will
470 * dispatch NS_MOUSE_SCROLL event for horizontal
471 * scroll.
472 * @param aLineOrPageDeltaY If you set this value non-zero for
473 * DOM_DELTA_PIXEL event, EventStateManager will
474 * dispatch NS_MOUSE_SCROLL event for vertical
475 * scroll.
476 * @param aOptions Set following flags.
477 */
478 const unsigned long WHEEL_EVENT_CAUSED_BY_PIXEL_ONLY_DEVICE = 0x0001;
479 const unsigned long WHEEL_EVENT_CAUSED_BY_MOMENTUM = 0x0002;
480 const unsigned long WHEEL_EVENT_CUSTOMIZED_BY_USER_PREFS = 0x0004;
481 // If any of the following flags is specified this method will throw an
482 // exception in case the relevant overflowDelta has an unexpected value.
483 const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_X_ZERO = 0x0010;
484 const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_X_POSITIVE = 0x0020;
485 const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_X_NEGATIVE = 0x0040;
486 const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_Y_ZERO = 0x0100;
487 const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_Y_POSITIVE = 0x0200;
488 const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_Y_NEGATIVE = 0x0400;
489 void sendWheelEvent(in float aX,
490 in float aY,
491 in double aDeltaX,
492 in double aDeltaY,
493 in double aDeltaZ,
494 in unsigned long aDeltaMode,
495 in long aModifiers,
496 in long aLineOrPageDeltaX,
497 in long aLineOrPageDeltaY,
498 in unsigned long aOptions);
500 /**
501 * Synthesize a key event to the window. The event types supported are:
502 * keydown, keyup, keypress
503 *
504 * Key events generally end up being sent to the focused node.
505 *
506 * Cannot be accessed from unprivileged context (not content-accessible)
507 * Will throw a DOM security error if called without chrome privileges.
508 *
509 * @param aType event type
510 * @param aKeyCode key code
511 * @param aCharCode character code
512 * @param aModifiers modifiers pressed, using constants defined as MODIFIER_*
513 * @param aAdditionalFlags special flags for the key event, see KEY_FLAG_*.
514 *
515 * @return false if the event had preventDefault() called on it,
516 * true otherwise. In other words, true if and only if the
517 * default action was taken.
518 */
520 // If this is set, preventDefault() the event before dispatch.
521 const unsigned long KEY_FLAG_PREVENT_DEFAULT = 0x0001;
523 // if one of these flags is set, the KeyboardEvent.location will be the value.
524 // Otherwise, it will be computed from aKeyCode.
525 const unsigned long KEY_FLAG_LOCATION_STANDARD = 0x0010;
526 const unsigned long KEY_FLAG_LOCATION_LEFT = 0x0020;
527 const unsigned long KEY_FLAG_LOCATION_RIGHT = 0x0040;
528 const unsigned long KEY_FLAG_LOCATION_NUMPAD = 0x0080;
529 const unsigned long KEY_FLAG_LOCATION_MOBILE = 0x0100;
530 const unsigned long KEY_FLAG_LOCATION_JOYSTICK = 0x0200;
532 boolean sendKeyEvent(in AString aType,
533 in long aKeyCode,
534 in long aCharCode,
535 in long aModifiers,
536 [optional] in unsigned long aAdditionalFlags);
538 /**
539 * See nsIWidget::SynthesizeNativeKeyEvent
540 *
541 * Cannot be accessed from unprivileged context (not content-accessible)
542 * Will throw a DOM security error if called without chrome privileges.
543 *
544 * When you use this for tests, use the constants defined in NativeKeyCodes.js
545 */
546 void sendNativeKeyEvent(in long aNativeKeyboardLayout,
547 in long aNativeKeyCode,
548 in long aModifierFlags,
549 in AString aCharacters,
550 in AString aUnmodifiedCharacters);
552 /**
553 * See nsIWidget::SynthesizeNativeMouseEvent
554 *
555 * Will be called on the widget that contains aElement.
556 * Cannot be accessed from unprivileged context (not content-accessible)
557 * Will throw a DOM security error if called without chrome privileges.
558 */
559 void sendNativeMouseEvent(in long aScreenX,
560 in long aScreenY,
561 in long aNativeMessage,
562 in long aModifierFlags,
563 in nsIDOMElement aElement);
565 /**
566 * The values for sendNativeMouseScrollEvent's aAdditionalFlags.
567 */
569 /**
570 * If MOUSESCROLL_PREFER_WIDGET_AT_POINT is set, widget will dispatch
571 * the event to a widget which is under the cursor. Otherwise, dispatch to
572 * a default target on the platform. E.g., on Windows, it's focused window.
573 */
574 const unsigned long MOUSESCROLL_PREFER_WIDGET_AT_POINT = 0x00000001;
576 /**
577 * The platform specific values of aAdditionalFlags. Must be over 0x00010000.
578 */
580 /**
581 * If MOUSESCROLL_WIN_SCROLL_LPARAM_NOT_NULL is set and aNativeMessage is
582 * WM_VSCROLL or WM_HSCROLL, widget will set the window handle to the lParam
583 * instead of NULL.
584 */
585 const unsigned long MOUSESCROLL_WIN_SCROLL_LPARAM_NOT_NULL = 0x00010000;
587 /**
588 * See nsIWidget::SynthesizeNativeMouseScrollEvent
589 *
590 * Will be called on the widget that contains aElement.
591 * Cannot be accessed from unprivileged context (not content-accessible)
592 * Will throw a DOM security error if called without chrome privileges.
593 *
594 * NOTE: The synthesized native event may be fired asynchronously.
595 *
596 * @param aNativeMessage
597 * On Windows: WM_MOUSEWHEEL (0x020A), WM_MOUSEHWHEEL(0x020E),
598 * WM_VSCROLL (0x0115) or WM_HSCROLL (0x114).
599 */
600 void sendNativeMouseScrollEvent(in long aScreenX,
601 in long aScreenY,
602 in unsigned long aNativeMessage,
603 in double aDeltaX,
604 in double aDeltaY,
605 in double aDeltaZ,
606 in unsigned long aModifierFlags,
607 in unsigned long aAdditionalFlags,
608 in nsIDOMElement aElement);
610 /**
611 * Touch states for sendNativeTouchPoint. These values match
612 * nsIWidget's TouchPointerState.
613 */
615 // The pointer is in a hover state above the digitizer
616 const long TOUCH_HOVER = 0x01;
617 // The pointer is in contact with the digitizer
618 const long TOUCH_CONTACT = 0x02;
619 // The pointer has been removed from the digitizer detection area
620 const long TOUCH_REMOVE = 0x04;
621 // The pointer has been canceled. Will cancel any pending os level
622 // gestures that would be triggered as a result of completion of the
623 // input sequence. This may not cancel moz platform related events
624 // that might get tirggered by input already delivered.
625 const long TOUCH_CANCEL = 0x08;
627 /**
628 * Create a new or update an existing touch point on the digitizer.
629 * To trigger os level gestures, individual touch points should
630 * transition through a complete set of touch states which should be
631 * sent as individual calls. For example:
632 * tap - msg1:TOUCH_CONTACT, msg2:TOUCH_REMOVE
633 * drag - msg1-n:TOUCH_CONTACT (moving), msgn+1:TOUCH_REMOVE
634 * hover drag - msg1-n:TOUCH_HOVER (moving), msgn+1:TOUCH_REMOVE
635 *
636 * Widget support: Windows 8.0+, Winrt/Win32. Other widgets will
637 * throw.
638 *
639 * @param aPointerId The touch point id to create or update.
640 * @param aTouchState one or more of the touch states listed above
641 * @param aScreenX, aScreenY screen coords of this event
642 * @param aPressure 0.0 -> 1.0 float val indicating pressure
643 * @param aOrientation 0 -> 359 degree value indicating the
644 * orientation of the pointer. Use 90 for normal taps.
645 */
646 void sendNativeTouchPoint(in unsigned long aPointerId,
647 in unsigned long aTouchState,
648 in long aScreenX,
649 in long aScreenY,
650 in double aPressure,
651 in unsigned long aOrientation);
653 /**
654 * Simulates native touch based taps on the input digitizer. Events
655 * triggered by this call are injected at the os level. Events do not
656 * bypass widget level input processing and as such can be used to
657 * test widget event logic and async pan-zoom controller functionality.
658 * Cannot be accessed from an unprivileged context.
659 *
660 * Long taps (based on the aLongTap parameter) will be completed
661 * asynchrnously after the call returns. Long tap delay is based on
662 * the ui.click_hold_context_menus.delay pref or 1500 msec if pref
663 * is not set.
664 *
665 * Widget support: Windows 8.0+, Winrt/Win32. Other widgets will
666 * throw.
667 *
668 * @param aScreenX, aScreenY screen coords of this event
669 * @param aLongTap true if the tap should be long, false for a short
670 * tap.
671 */
672 void sendNativeTouchTap(in long aScreenX,
673 in long aScreenY,
674 in boolean aLongTap);
676 /**
677 * Cancel any existing touch points or long tap delays. Calling this is safe
678 * even if you're sure there aren't any pointers recorded. You should call
679 * this when tests shut down to reset the digitizer driver. Not doing so can
680 * leave the digitizer in an undetermined state which can screw up subsequent
681 * tests and native input.
682 */
683 void clearNativeTouchSequence();
685 /**
686 * See nsIWidget::ActivateNativeMenuItemAt
687 *
688 * Cannot be accessed from unprivileged context (not content-accessible)
689 * Will throw a DOM security error if called without chrome privileges.
690 */
691 void activateNativeMenuItemAt(in AString indexString);
693 /**
694 * See nsIWidget::ForceUpdateNativeMenuAt
695 *
696 * Cannot be accessed from unprivileged context (not content-accessible)
697 * Will throw a DOM security error if called without chrome privileges.
698 */
699 void forceUpdateNativeMenuAt(in AString indexString);
701 /**
702 * Focus the element aElement. The element should be in the same document
703 * that the window is displaying. Pass null to blur the element, if any,
704 * that currently has focus, and focus the document.
705 *
706 * Cannot be accessed from unprivileged context (not content-accessible)
707 * Will throw a DOM security error if called without chrome privileges.
708 *
709 * @param aElement the element to focus
710 *
711 * Do not use this method. Just use element.focus if available or
712 * nsIFocusManager::SetFocus instead.
713 *
714 */
715 void focus(in nsIDOMElement aElement);
717 /**
718 * Force a garbage collection followed by a cycle collection.
719 *
720 * Will throw a DOM security error if called without chrome privileges in
721 * non-debug builds. Available to all callers in debug builds.
722 *
723 * @param aListener listener that receives information about the CC graph
724 * (see @mozilla.org/cycle-collector-logger;1 for a logger
725 * component)
726 * @param aExtraForgetSkippableCalls indicates how many times
727 * nsCycleCollector_forgetSkippable will
728 * be called before running cycle collection.
729 * -1 prevents the default
730 * nsCycleCollector_forgetSkippable call
731 * which happens after garbage collection.
732 */
733 void garbageCollect([optional] in nsICycleCollectorListener aListener,
734 [optional] in long aExtraForgetSkippableCalls);
736 /**
737 * Force a cycle collection without garbage collection.
738 *
739 * Will throw a DOM security error if called without chrome privileges in
740 * non-debug builds. Available to all callers in debug builds.
741 *
742 * @param aListener listener that receives information about the CC graph
743 * (see @mozilla.org/cycle-collector-logger;1 for a logger
744 * component)
745 * @param aExtraForgetSkippableCalls indicates how many times
746 * nsCycleCollector_forgetSkippable will
747 * be called before running cycle collection.
748 * -1 prevents the default
749 * nsCycleCollector_forgetSkippable call
750 * which happens after garbage collection.
751 */
752 void cycleCollect([optional] in nsICycleCollectorListener aListener,
753 [optional] in long aExtraForgetSkippableCalls);
755 /**
756 * Trigger whichever GC or CC timer is currently active and waiting to fire.
757 * Don't do this too much for initiating heavy actions, like the start of a IGC.
758 */
759 void runNextCollectorTimer();
761 /** Synthesize a simple gesture event for a window. The event types
762 * supported are: MozSwipeGestureStart, MozSwipeGestureUpdate,
763 * MozSwipeGestureEnd, MozSwipeGesture, MozMagnifyGestureStart,
764 * MozMagnifyGestureUpdate, MozMagnifyGesture, MozRotateGestureStart,
765 * MozRotateGestureUpdate, MozRotateGesture, MozPressTapGesture,
766 * MozTapGesture, and MozEdgeUIGesture.
767 *
768 * Cannot be accessed from unprivileged context (not
769 * content-accessible) Will throw a DOM security error if called
770 * without chrome privileges.
771 *
772 * @param aType event type
773 * @param aX x offset in CSS pixels
774 * @param aY y offset in CSS pixels
775 * @param aDirection direction, using constants defined in nsIDOMSimpleGestureEvent
776 * @param aDelta amount of magnification or rotation for magnify and rotation events
777 * @param aModifiers modifiers pressed, using constants defined in nsIDOMNSEvent
778 * @param aClickCount For tap gestures, the number of taps.
779 */
780 void sendSimpleGestureEvent(in AString aType,
781 in float aX,
782 in float aY,
783 in unsigned long aDirection,
784 in double aDelta,
785 in long aModifiers,
786 [optional] in unsigned long aClickCount);
788 /**
789 * Retrieve the element at point aX, aY in the window's document.
790 *
791 * @param aIgnoreRootScrollFrame whether or not to ignore the root scroll
792 * frame when retrieving the element. If false, this method returns
793 * null for coordinates outside of the viewport.
794 * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
795 */
796 nsIDOMElement elementFromPoint(in float aX,
797 in float aY,
798 in boolean aIgnoreRootScrollFrame,
799 in boolean aFlushLayout);
801 /**
802 * Retrieve all nodes that intersect a rect in the window's document.
803 *
804 * @param aX x reference for the rectangle in CSS pixels
805 * @param aY y reference for the rectangle in CSS pixels
806 * @param aTopSize How much to expand up the rectangle
807 * @param aRightSize How much to expand right the rectangle
808 * @param aBottomSize How much to expand down the rectangle
809 * @param aLeftSize How much to expand left the rectangle
810 * @param aIgnoreRootScrollFrame whether or not to ignore the root scroll
811 * frame when retrieving the element. If false, this method returns
812 * null for coordinates outside of the viewport.
813 * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
814 */
815 nsIDOMNodeList nodesFromRect(in float aX,
816 in float aY,
817 in float aTopSize,
818 in float aRightSize,
819 in float aBottomSize,
820 in float aLeftSize,
821 in boolean aIgnoreRootScrollFrame,
822 in boolean aFlushLayout);
825 /**
826 * Get a list of nodes that have meaningful textual content to
827 * be translated. The implementation of this algorithm is in flux
828 * as we experiment and refine which approach works best.
829 *
830 * This method requires chrome privileges.
831 */
832 nsITranslationNodeList getTranslationNodes(in nsIDOMNode aRoot);
834 /**
835 * Compare the two canvases, returning the number of differing pixels and
836 * the maximum difference in a channel. This will throw an error if
837 * the dimensions of the two canvases are different.
838 *
839 * This method requires chrome privileges.
840 */
841 uint32_t compareCanvases(in nsIDOMHTMLCanvasElement aCanvas1,
842 in nsIDOMHTMLCanvasElement aCanvas2,
843 out unsigned long aMaxDifference);
845 /**
846 * Returns true if a MozAfterPaint event has been queued but not yet
847 * fired.
848 */
849 readonly attribute boolean isMozAfterPaintPending;
851 /**
852 * Suppresses/unsuppresses user initiated event handling in window's document
853 * and subdocuments.
854 *
855 * @throw NS_ERROR_DOM_SECURITY_ERR if called without chrome privileges and
856 * NS_ERROR_FAILURE if window doesn't have a document.
857 */
858 void suppressEventHandling(in boolean aSuppress);
860 void clearMozAfterPaintEvents();
862 /**
863 * Disable or enable non synthetic test mouse events on *all* windows.
864 *
865 * Cannot be accessed from unprivileged context (not content-accessible).
866 * Will throw a DOM security error if called without chrome privileges.
867 *
868 * @param aDisable If true, disable all non synthetic test mouse events
869 * on all windows. Otherwise, enable them.
870 */
871 void disableNonTestMouseEvents(in boolean aDisable);
873 /**
874 * Returns the scroll position of the window's currently loaded document.
875 *
876 * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
877 * @see nsIDOMWindow::scrollX/Y
878 */
879 void getScrollXY(in boolean aFlushLayout, out long aScrollX, out long aScrollY);
881 /**
882 * Returns the scroll position of the window's currently loaded document.
883 *
884 * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
885 * @see nsIDOMWindow::scrollX/Y
886 */
887 void getScrollXYFloat(in boolean aFlushLayout, out float aScrollX, out float aScrollY);
889 /**
890 * Returns the scrollbar width of the window's scroll frame.
891 *
892 * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
893 */
894 void getScrollbarSize(in boolean aFlushLayout, out long aWidth, out long aHeight);
896 /**
897 * Returns the given element's bounds without flushing pending layout changes.
898 */
899 nsIDOMClientRect getBoundsWithoutFlushing(in nsIDOMElement aElement);
901 /**
902 * Returns the bounds of the window's currently loaded document. This will
903 * generally be (0, 0, pageWidth, pageHeight) but in some cases (e.g. RTL
904 * documents) may have a negative left value.
905 */
906 nsIDOMClientRect getRootBounds();
908 /**
909 * Get IME open state. TRUE means 'Open', otherwise, 'Close'.
910 * This property works only when IMEEnabled is IME_STATUS_ENABLED.
911 */
912 readonly attribute boolean IMEIsOpen;
914 /**
915 * WARNING: These values must be same as nsIWidget's values.
916 */
918 /**
919 * DISABLED means users cannot use IME completely.
920 * Note that this state is *not* same as |ime-mode: disabled;|.
921 */
922 const unsigned long IME_STATUS_DISABLED = 0;
924 /**
925 * ENABLED means users can use all functions of IME. This state is same as
926 * |ime-mode: normal;|.
927 */
928 const unsigned long IME_STATUS_ENABLED = 1;
930 /**
931 * PASSWORD means users cannot use most functions of IME. But on GTK2,
932 * users can use "Simple IM" which only supports dead key inputting.
933 * The behavior is same as the behavior of the native password field.
934 * This state is same as |ime-mode: disabled;|.
935 */
936 const unsigned long IME_STATUS_PASSWORD = 2;
938 /**
939 * PLUGIN means a plug-in has focus. At this time we should not touch to
940 * controlling the IME state.
941 */
942 const unsigned long IME_STATUS_PLUGIN = 3;
944 /**
945 * Get IME status, see above IME_STATUS_* definitions.
946 */
947 readonly attribute unsigned long IMEStatus;
949 /**
950 * Get the number of screen pixels per CSS pixel.
951 */
952 readonly attribute float screenPixelsPerCSSPixel;
954 /**
955 * Get the current zoom factor.
956 * This is _approximately_ the same as nsIMarkupDocumentViewer.fullZoom,
957 * but takes into account Gecko's quantization of the zoom factor, which is
958 * implemented by adjusting the (integer) number of appUnits per devPixel.
959 */
960 readonly attribute float fullZoom;
962 /**
963 * Dispatches aEvent via the nsIPresShell object of the window's document.
964 * The event is dispatched to aTarget, which should be an object
965 * which implements nsIContent interface (#element, #text, etc).
966 *
967 * Cannot be accessed from unprivileged context (not
968 * content-accessible) Will throw a DOM security error if called
969 * without chrome privileges.
970 *
971 * @note Event handlers won't get aEvent as parameter, but a similar event.
972 * Also, aEvent should not be reused.
973 */
974 boolean dispatchDOMEventViaPresShell(in nsIDOMNode aTarget,
975 in nsIDOMEvent aEvent,
976 in boolean aTrusted);
978 /**
979 * Sets WidgetEvent::mFlags::mOnlyChromeDispatch to true to ensure that
980 * the event is propagated only to chrome.
981 * Event's .target property will be aTarget.
982 * Returns the same value as what EventTarget.dispatchEvent does.
983 */
984 boolean dispatchEventToChromeOnly(in nsIDOMEventTarget aTarget,
985 in nsIDOMEvent aEvent);
987 /**
988 * Returns the real classname (possibly of the mostly-transparent security
989 * wrapper) of aObj.
990 */
991 [implicit_jscontext] string getClassName(in jsval aObject);
993 /**
994 * Generate a content command event.
995 *
996 * Cannot be accessed from unprivileged context (not content-accessible)
997 * Will throw a DOM security error if called without chrome privileges.
998 *
999 * @param aType Type of command content event to send. Can be one of "cut",
1000 * "copy", "paste", "delete", "undo", "redo", or "pasteTransferable".
1001 * @param aTransferable an instance of nsITransferable when aType is
1002 * "pasteTransferable"
1003 */
1004 void sendContentCommandEvent(in AString aType,
1005 [optional] in nsITransferable aTransferable);
1007 /**
1008 * Synthesize a composition event to the window.
1009 *
1010 * Cannot be accessed from unprivileged context (not content-accessible)
1011 * Will throw a DOM security error if called without chrome privileges.
1012 *
1013 * @param aType The event type: "compositionstart", "compositionend" or
1014 * "compositionupdate".
1015 * @param aData The data property value. Note that this isn't applied
1016 * for compositionstart event because its value is the
1017 * selected text which is automatically computed.
1018 * @param aLocale The locale property value.
1019 */
1020 void sendCompositionEvent(in AString aType,
1021 in AString aData,
1022 in AString aLocale);
1024 /**
1025 * Creating synthesizer of composition string on the window.
1026 *
1027 * Cannot be accessed from unprivileged context (not content-accessible)
1028 * Will throw a DOM security error if called without chrome privileges.
1029 */
1030 nsICompositionStringSynthesizer createCompositionStringSynthesizer();
1032 /**
1033 * If sendQueryContentEvent()'s aAdditionalFlags argument is
1034 * QUERY_CONTENT_FLAG_USE_XP_LINE_BREAK, plain text generated from content
1035 * is created with "\n".
1036 * Otherwise, platform dependent. E.g., on Windows, "\r\n" is used.
1037 * aOffset and aLength are offset and length in/of the plain text content.
1038 * This flag also affects the result values such as offset, length and string.
1039 */
1040 const unsigned long QUERY_CONTENT_FLAG_USE_NATIVE_LINE_BREAK = 0x0000;
1041 const unsigned long QUERY_CONTENT_FLAG_USE_XP_LINE_BREAK = 0x0001;
1043 /**
1044 * Synthesize a query content event. Note that the result value returned here
1045 * is in LayoutDevice pixels rather than CSS pixels.
1046 *
1047 * @param aType One of the following const values. And see also each comment
1048 * for the other parameters and the result.
1049 * @param aAdditionalFlags See the description of QUERY_CONTENT_FLAG_*.
1050 */
1051 nsIQueryContentEventResult sendQueryContentEvent(
1052 in unsigned long aType,
1053 in unsigned long aOffset,
1054 in unsigned long aLength,
1055 in long aX,
1056 in long aY,
1057 [optional] in unsigned long aAdditionalFlags);
1059 // NOTE: following values are same as NS_QUERY_* in BasicEvents.h
1061 /**
1062 * QUERY_SELECTED_TEXT queries the first selection range's information.
1063 *
1064 * @param aOffset Not used.
1065 * @param aLength Not used.
1066 * @param aX Not used.
1067 * @param aY Not used.
1068 *
1069 * @return offset, reversed and text properties of the result are available.
1070 */
1071 const unsigned long QUERY_SELECTED_TEXT = 3200;
1073 /**
1074 * QUERY_TEXT_CONTENT queries the text at the specified range.
1075 *
1076 * @param aOffset The first character's offset. 0 is the first character.
1077 * @param aLength The length of getting text. If the aLength is too long,
1078 * the result text is shorter than this value.
1079 * @param aX Not used.
1080 * @param aY Not used.
1081 *
1082 * @return text property of the result is available.
1083 */
1084 const unsigned long QUERY_TEXT_CONTENT = 3201;
1086 /**
1087 * QUERY_CARET_RECT queries the (collapsed) caret rect of the offset.
1088 * If the actual caret is there at the specified offset, this returns the
1089 * actual caret rect. Otherwise, this guesses the caret rect from the
1090 * metrics of the text.
1091 *
1092 * @param aOffset The caret offset. 0 is the left side of the first
1093 * caracter in LTR text.
1094 * @param aLength Not used.
1095 * @param aX Not used.
1096 * @param aY Not used.
1097 *
1098 * @return left, top, width and height properties of the result are available.
1099 * The left and the top properties are offset in the client area of
1100 * the DOM window.
1101 */
1102 const unsigned long QUERY_CARET_RECT = 3203;
1104 /**
1105 * QUERY_TEXT_RECT queries the specified text's rect.
1106 *
1107 * @param aOffset The first character's offset. 0 is the first character.
1108 * @param aLength The length of getting text. If the aLength is too long,
1109 * the extra length is ignored.
1110 * @param aX Not used.
1111 * @param aY Not used.
1112 *
1113 * @return left, top, width and height properties of the result are available.
1114 * The left and the top properties are offset in the client area of
1115 * the DOM window.
1116 */
1117 const unsigned long QUERY_TEXT_RECT = 3204;
1119 /**
1120 * QUERY_TEXT_RECT queries the focused editor's rect.
1121 *
1122 * @param aOffset Not used.
1123 * @param aLength Not used.
1124 * @param aX Not used.
1125 * @param aY Not used.
1126 *
1127 * @return left, top, width and height properties of the result are available.
1128 */
1129 const unsigned long QUERY_EDITOR_RECT = 3205;
1131 /**
1132 * QUERY_CHARACTER_AT_POINT queries the character information at the
1133 * specified point. The point is offset in the window.
1134 * NOTE: If there are some panels at the point, this method send the query
1135 * event to the panel's widget automatically.
1136 *
1137 * @param aOffset Not used.
1138 * @param aLength Not used.
1139 * @param aX X offset in the widget.
1140 * @param aY Y offset in the widget.
1141 *
1142 * @return offset, notFound, left, top, width and height properties of the
1143 * result are available.
1144 */
1145 const unsigned long QUERY_CHARACTER_AT_POINT = 3208;
1147 /**
1148 * Called when the remote child frame has changed its fullscreen state,
1149 * when entering fullscreen, and when the origin which is fullscreen changes.
1150 * aFrameElement is the iframe element which contains the child-process
1151 * fullscreen document, and aNewOrigin is the origin of the new fullscreen
1152 * document.
1153 */
1154 void remoteFrameFullscreenChanged(in nsIDOMElement aFrameElement,
1155 in AString aNewOrigin);
1157 /**
1158 * Called when the remote frame has popped all fullscreen elements off its
1159 * stack, so that the operation can complete on the parent side.
1160 */
1161 void remoteFrameFullscreenReverted();
1163 /**
1164 * Called when the child frame has fully exit fullscreen, so that the parent
1165 * process can also fully exit.
1166 */
1167 void exitFullscreen();
1169 /**
1170 * If sendQueryContentEvent()'s aAdditionalFlags argument is
1171 * SELECTION_SET_FLAG_USE_NATIVE_LINE_BREAK, aOffset and aLength are offset
1172 * and length in/of plain text generated from content is created with "\n".
1173 * Otherwise, platform dependent. E.g., on Windows, "\r\n" is used.
1174 */
1175 const unsigned long SELECTION_SET_FLAG_USE_NATIVE_LINE_BREAK = 0x0000;
1176 const unsigned long SELECTION_SET_FLAG_USE_XP_LINE_BREAK = 0x0001;
1178 /**
1179 * If SELECTION_SET_FLAG_REVERSE is set, the selection is set from
1180 * |aOffset + aLength| to |aOffset|. Otherwise, it's set from |aOffset| to
1181 * |aOffset + aLength|.
1182 */
1183 const unsigned long SELECTION_SET_FLAG_REVERSE = 0x0002;
1185 /**
1186 * Synthesize a selection set event to the window.
1187 *
1188 * This sets the selection as the specified information.
1189 *
1190 * @param aOffset The caret offset of the selection start.
1191 * @param aLength The length of the selection. If this is too long, the
1192 * extra length is ignored.
1193 * @param aAdditionalFlags See the description of SELECTION_SET_FLAG_*.
1194 * @return True, if succeeded. Otherwise, false.
1195 */
1196 boolean sendSelectionSetEvent(in unsigned long aOffset,
1197 in unsigned long aLength,
1198 [optional] in unsigned long aAdditionalFlags);
1200 /* Selection behaviors - mirror nsIFrame's nsSelectionAmount constants */
1201 const unsigned long SELECT_CHARACTER = 0;
1202 const unsigned long SELECT_CLUSTER = 1;
1203 const unsigned long SELECT_WORD = 2;
1204 const unsigned long SELECT_LINE = 3;
1205 const unsigned long SELECT_BEGINLINE = 4;
1206 const unsigned long SELECT_ENDLINE = 5;
1207 const unsigned long SELECT_PARAGRAPH = 6;
1208 const unsigned long SELECT_WORDNOSPACE = 7;
1210 /**
1211 * Select content at a client point based on a selection behavior if the
1212 * underlying content is selectable. Selection will accumulate with any
1213 * existing selection, callers should clear selection prior if needed.
1214 * May fire selection changed events. Calls nsFrame's SelectByTypeAtPoint.
1215 *
1216 * @param aX, aY The selection point in client coordinates.
1217 * @param aSelectType The selection behavior requested.
1218 * @return True if a selection occured, false otherwise.
1219 * @throw NS_ERROR_DOM_SECURITY_ERR, NS_ERROR_UNEXPECTED for utils
1220 * issues, and NS_ERROR_INVALID_ARG for coordinates that are outside
1221 * this window.
1222 */
1223 boolean selectAtPoint(in float aX,
1224 in float aY,
1225 in unsigned long aSelectBehavior);
1227 /**
1228 * Perform the equivalent of:
1229 * window.getComputedStyle(aElement, aPseudoElement).
1230 * getPropertyValue(aPropertyName)
1231 * except that, when the link whose presence in history is allowed to
1232 * influence aElement's style is visited, get the value the property
1233 * would have if allowed all properties to change as a result of
1234 * :visited selectors (except for cases where getComputedStyle uses
1235 * data from the frame).
1236 *
1237 * This is easier to implement than adding our property restrictions
1238 * to this API, and is sufficient for the present testing
1239 * requirements (which are essentially testing 'color').
1240 */
1241 AString getVisitedDependentComputedStyle(in nsIDOMElement aElement,
1242 in AString aPseudoElement,
1243 in AString aPropertyName);
1245 /**
1246 * Returns the parent of obj.
1247 *
1248 * @param obj The JavaScript object whose parent is to be gotten.
1249 * @return the parent.
1250 */
1251 [implicit_jscontext] jsval getParent(in jsval obj);
1253 /**
1254 * Get the id of the outer window of this window. This will never throw.
1255 */
1256 readonly attribute unsigned long long outerWindowID;
1258 /**
1259 * Get the id of the current inner window of this window. If there
1260 * is no current inner window, throws NS_ERROR_NOT_AVAILABLE.
1261 */
1262 readonly attribute unsigned long long currentInnerWindowID;
1264 /**
1265 * Put the window into a state where scripts are frozen and events
1266 * suppressed, for use when the window has launched a modal prompt.
1267 */
1268 void enterModalState();
1270 /**
1271 * Resume normal window state, where scripts can run and events are
1272 * delivered.
1273 */
1274 void leaveModalState();
1276 /**
1277 * Is the window is in a modal state? [See enterModalState()]
1278 */
1279 [noscript] boolean isInModalState();
1281 /**
1282 * Suspend/resume timeouts on this window and its descendant windows.
1283 */
1284 void suspendTimeouts();
1285 void resumeTimeouts();
1287 /**
1288 * What type of layer manager the widget associated with this window is
1289 * using. "Basic" is unaccelerated; other types are accelerated. Throws an
1290 * error if there is no widget associated with this window.
1291 */
1292 readonly attribute AString layerManagerType;
1294 /**
1295 * True if the layer manager for the widget associated with this window is
1296 * forwarding layers to a remote compositor, false otherwise. Throws an
1297 * error if there is no widget associated with this window.
1298 */
1299 readonly attribute boolean layerManagerRemote;
1301 /**
1302 * Record (and return) frame-intervals for frames which were presented
1303 * between calling StartFrameTimeRecording and StopFrameTimeRecording.
1304 *
1305 * - Uses a cyclic buffer and serves concurrent consumers, so if Stop is called too late
1306 * (elements were overwritten since Start), result is considered invalid and hence empty.
1307 * - Buffer is capable of holding 10 seconds @ 60fps (or more if frames were less frequent).
1308 * Can be changed (up to 1 hour) via pref: toolkit.framesRecording.bufferSize.
1309 * - Note: the first frame-interval may be longer than expected because last frame
1310 * might have been presented some time before calling StartFrameTimeRecording.
1311 */
1313 /**
1314 * Returns a handle which represents current recording start position.
1315 */
1316 void startFrameTimeRecording([retval] out unsigned long startIndex);
1318 /**
1319 * Returns number of recorded frames since startIndex was issued,
1320 * and allocates+populates 2 arraye with the recorded data.
1321 * - Allocation is infallible. Should be released even if size is 0.
1322 */
1323 void stopFrameTimeRecording(in unsigned long startIndex,
1324 [optional] out unsigned long frameCount,
1325 [retval, array, size_is(frameCount)] out float frameIntervals);
1327 /**
1328 * Signals that we're begining to tab switch. This is used by painting code to
1329 * determine total tab switch time.
1330 */
1331 void beginTabSwitch();
1333 /**
1334 * The DPI of the display
1335 */
1336 readonly attribute float displayDPI;
1338 /**
1339 * Return the outer window with the given ID, if any. Can return null.
1340 * @deprecated Use nsIWindowMediator.getOuterWindowWithId. See bug 865664.
1341 */
1342 nsIDOMWindow getOuterWindowWithId(in unsigned long long aOuterWindowID);
1344 /**
1345 * Return this window's frame element.
1346 * Ignores all chrome/content or mozbrowser boundaries.
1347 */
1348 readonly attribute nsIDOMElement containerElement;
1350 [noscript] void RenderDocument(in nsConstRect aRect,
1351 in uint32_t aFlags,
1352 in nscolor aBackgroundColor,
1353 in gfxContext aThebesContext);
1355 /**
1356 * advanceTimeAndRefresh allows the caller to take over the refresh
1357 * driver timing for a window. A call to advanceTimeAndRefresh does
1358 * three things:
1359 * (1) It marks the refresh driver for this presentation so that it
1360 * no longer refreshes on its own, but is instead driven entirely
1361 * by the caller (except for the refresh that happens when a
1362 * document comes out of the bfcache).
1363 * (2) It advances the refresh driver's current refresh time by the
1364 * argument given. Negative advances are permitted.
1365 * (3) It does a refresh (i.e., notifies refresh observers) at that
1366 * new time.
1367 *
1368 * Note that this affects other connected docshells of the same type
1369 * in the same docshell tree, such as parent frames.
1370 *
1371 * When callers have completed their use of advanceTimeAndRefresh,
1372 * they must call restoreNormalRefresh.
1373 */
1374 void advanceTimeAndRefresh(in long long aMilliseconds);
1376 /**
1377 * Undoes the effects of advanceTimeAndRefresh.
1378 */
1379 void restoreNormalRefresh();
1381 /**
1382 * Reports whether the current state is test-controlled refreshes
1383 * (see advanceTimeAndRefresh and restoreNormalRefresh above).
1384 */
1385 readonly attribute bool isTestControllingRefreshes;
1387 /**
1388 * Set async scroll offset on an element. The next composite will render
1389 * with that offset if async scrolling is enabled, and then the offset
1390 * will be removed. Only call this while test-controlled refreshes is enabled.
1391 */
1392 void setAsyncScrollOffset(in nsIDOMNode aNode, in int32_t aX, in int32_t aY);
1394 /**
1395 * Method for testing nsStyleAnimation::ComputeDistance.
1396 *
1397 * Returns the distance between the two values as reported by
1398 * nsStyleAnimation::ComputeDistance for the given element and
1399 * property.
1400 */
1401 double computeAnimationDistance(in nsIDOMElement element,
1402 in AString property,
1403 in AString value1,
1404 in AString value2);
1406 /**
1407 * Wrap an nsIFile in an nsIDOMFile
1408 */
1409 nsIDOMFile wrapDOMFile(in nsIFile aFile);
1411 /**
1412 * Get the type of the currently focused html input, if any.
1413 */
1414 readonly attribute string focusedInputType;
1416 /**
1417 * Given a view ID from the compositor process, retrieve the element
1418 * associated with a view. For scrollpanes for documents, the root
1419 * element of the document is returned.
1420 */
1421 nsIDOMElement findElementWithViewId(in nsViewID aId);
1423 /**
1424 * Find the view ID for a given element. This is the reverse of
1425 * findElementWithViewId().
1426 */
1427 nsViewID getViewId(in nsIDOMElement aElement);
1429 /**
1430 * Checks the layer tree for this window and returns true
1431 * if all layers have transforms that are translations by integers,
1432 * no leaf layers overlap, and the union of the leaf layers is exactly
1433 * the bounds of the window. Always returns true in non-DEBUG builds.
1434 */
1435 boolean leafLayersPartitionWindow();
1437 /**
1438 * true if the (current inner) window may have event listeners for touch events.
1439 */
1440 readonly attribute boolean mayHaveTouchEventListeners;
1442 /**
1443 * Check if any ThebesLayer painting has been done for this element,
1444 * clears the painted flags if they have.
1445 */
1446 boolean checkAndClearPaintedState(in nsIDOMElement aElement);
1448 /**
1449 * Internal file constructor intended for testing of File objects.
1450 * Example of constructor usage:
1451 * getFile("myfile.txt", [b1, "foo"], { type: "text/plain" })
1452 */
1453 [optional_argc, implicit_jscontext]
1454 nsIDOMFile getFile(in DOMString aName, [optional] in jsval aBlobParts,
1455 [optional] in jsval aParameters);
1457 /**
1458 * Internal blob constructor intended for testing of Blob objects.
1459 * Example of constructor usage:
1460 * getBlob([b1, "foo"], { type: "text/plain" })
1461 */
1462 [optional_argc, implicit_jscontext]
1463 nsIDOMBlob getBlob([optional] in jsval aBlobParts,
1464 [optional] in jsval aParameters);
1466 /**
1467 * Get internal id of the stored blob, file or file handle.
1468 */
1469 [implicit_jscontext] long long getFileId(in jsval aFile);
1471 /**
1472 * Get file ref count info for given database and file id.
1473 *
1474 */
1475 [implicit_jscontext]
1476 boolean getFileReferences(in AString aDatabaseName, in long long aId,
1477 [optional] in jsval aOptions,
1478 [optional] out long aRefCnt,
1479 [optional] out long aDBRefCnt,
1480 [optional] out long aSliceRefCnt);
1482 /**
1483 * Return whether incremental GC has been disabled due to a binary add-on.
1484 */
1485 [implicit_jscontext]
1486 boolean isIncrementalGCEnabled();
1488 /**
1489 * Begin opcode-level profiling of all JavaScript execution in the window's
1490 * runtime.
1491 */
1492 [implicit_jscontext]
1493 void startPCCountProfiling();
1495 /**
1496 * Stop opcode-level profiling of JavaScript execution in the runtime, and
1497 * collect all counts for use by getPCCount methods.
1498 */
1499 [implicit_jscontext]
1500 void stopPCCountProfiling();
1502 /**
1503 * Purge collected PC counters.
1504 */
1505 [implicit_jscontext]
1506 void purgePCCounts();
1508 /**
1509 * Get the number of scripts with opcode-level profiling information.
1510 */
1511 [implicit_jscontext]
1512 long getPCCountScriptCount();
1514 /**
1515 * Get a JSON string for a short summary of a script and the PC counts
1516 * accumulated for it.
1517 */
1518 [implicit_jscontext]
1519 AString getPCCountScriptSummary(in long script);
1521 /**
1522 * Get a JSON string with full information about a profiled script,
1523 * including the decompilation of the script and placement of decompiled
1524 * operations within it, and PC counts for each operation.
1525 */
1526 [implicit_jscontext]
1527 AString getPCCountScriptContents(in long script);
1529 /**
1530 * Returns true if painting is suppressed for this window and false
1531 * otherwise.
1532 */
1533 readonly attribute boolean paintingSuppressed;
1535 /**
1536 * Returns an array of plugins on the page for opt-in activation.
1537 *
1538 * Cannot be accessed from unprivileged context (not content-accessible).
1539 * Will throw a DOM security error if called without chrome privileges.
1540 *
1541 */
1542 [implicit_jscontext]
1543 readonly attribute jsval plugins;
1545 /**
1546 * Set the scrollport size for the purposes of clamping scroll positions for
1547 * the root scroll frame of this document to be (aWidth,aHeight) in CSS pixels.
1548 *
1549 * The caller of this method must have chrome privileges.
1550 */
1551 void setScrollPositionClampingScrollPortSize(in float aWidth, in float aHeight);
1553 /**
1554 * Set margins for the layout of fixed position elements in the content
1555 * document. These are used on mobile, where the viewable area can be
1556 * temporarily obscured by the browser chrome. In this situation, we're ok
1557 * with scrollable page content being obscured, but fixed position content
1558 * cannot be revealed without removing the obscuring chrome, so we use these
1559 * margins so that it can remain visible.
1560 *
1561 * The caller of this method must have chrome privileges.
1562 */
1563 void setContentDocumentFixedPositionMargins(in float aTop, in float aRight,
1564 in float aBottom, in float aLeft);
1566 /**
1567 * These are used to control whether dialogs (alert, prompt, confirm) are
1568 * allowed.
1569 */
1570 void disableDialogs();
1571 void enableDialogs();
1572 bool areDialogsEnabled();
1574 const unsigned long AGENT_SHEET = 0;
1575 const unsigned long USER_SHEET = 1;
1576 const unsigned long AUTHOR_SHEET = 2;
1577 /**
1578 * Synchronously loads a style sheet from |sheetURI| and adds it to the list
1579 * of additional style sheets of the document.
1580 *
1581 * These additional style sheets are very much like user/agent sheets loaded
1582 * with loadAndRegisterSheet. The only difference is that they are applied only
1583 * on the document owned by this window.
1584 *
1585 * Sheets added via this API take effect immediately on the document.
1586 */
1587 void loadSheet(in nsIURI sheetURI,
1588 in unsigned long type);
1590 /**
1591 * Remove the document style sheet at |sheetURI| from the list of additional
1592 * style sheets of the document. The removal takes effect immediately.
1593 */
1594 void removeSheet(in nsIURI sheetURI,
1595 in unsigned long type);
1597 /**
1598 * Returns true if a user input is being handled.
1599 *
1600 * This calls EventStateManager::IsHandlingUserInput().
1601 */
1602 readonly attribute boolean isHandlingUserInput;
1604 /**
1605 * After calling the method, the window for which this DOMWindowUtils
1606 * was created can be closed using scripts.
1607 */
1608 void allowScriptsToClose();
1610 /**
1611 * Is the parent window's main widget visible? If it isn't, we probably
1612 * don't want to display any dialogs etc it may request. This corresponds
1613 * to the visibility check in nsWindowWatcher::OpenWindowInternal().
1614 *
1615 * Will throw a DOM security error if called without chrome privileges or
1616 * NS_ERROR_NOT_AVAILABLE in the unlikely event that the parent window's
1617 * main widget can't be reached.
1618 */
1619 readonly attribute boolean isParentWindowMainWidgetVisible;
1621 /**
1622 * In certain cases the event handling of nodes, form controls in practice,
1623 * may be disabled. Such cases are for example the existence of disabled
1624 * attribute or -moz-user-input: none/disabled.
1625 */
1626 boolean isNodeDisabledForEvents(in nsIDOMNode aNode);
1628 /**
1629 * Setting paintFlashing to true will flash newly painted area.
1630 */
1631 attribute boolean paintFlashing;
1633 /**
1634 * Allows running of a "synchronous section", in the form of an nsIRunnable
1635 * once the event loop has reached a "stable state". We've reached a stable
1636 * state when the currently executing task/event has finished, see:
1637 * http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#synchronous-section
1638 * In practice this runs aRunnable once the currently executing event
1639 * finishes. If called multiple times per task/event, all the runnables will
1640 * be executed, in the order in which runInStableState() was called.
1641 *
1642 * XXX - This can wreak havoc if you're not using this for very simple
1643 * purposes, eg testing or setting a flag.
1644 */
1645 void runInStableState(in nsIRunnable runnable);
1647 /**
1648 * Run the given runnable before the next iteration of the event loop (this
1649 * includes native events too). If a nested loop is spawned within the current
1650 * event then the runnable will not be run until that loop has terminated.
1651 *
1652 * XXX - This can wreak havoc if you're not using this for very simple
1653 * purposes, eg testing or setting a flag.
1654 */
1655 void runBeforeNextEvent(in nsIRunnable runnable);
1657 /*
1658 * Returns the value of a given property animated on the compositor thread.
1659 * If the property is NOT currently being animated on the compositor thread,
1660 * returns an empty string.
1661 */
1662 AString getOMTAStyle(in nsIDOMElement aElement, in AString aProperty);
1664 /*
1665 * Returns the value of a given property. If the property is animated off
1666 * the main thread, this function will fetch the correct value from the
1667 * compositor.
1668 */
1669 AString getOMTAOrComputedStyle(in nsIDOMElement aElement,
1670 in AString aProperty);
1672 /**
1673 * With this it's possible to mute all the MediaElements in this window.
1674 * We have audioMuted and audioVolume to preserve the volume across
1675 * mute/umute.
1676 */
1677 attribute boolean audioMuted;
1679 /**
1680 * range: greater or equal to 0. The real volume level is affected by the
1681 * volume of all ancestor windows.
1682 */
1683 attribute float audioVolume;
1684 };
1686 [scriptable, uuid(c694e359-7227-4392-a138-33c0cc1f15a6)]
1687 interface nsITranslationNodeList : nsISupports {
1688 readonly attribute unsigned long length;
1689 nsIDOMNode item(in unsigned long index);
1691 // A translation root is a block element, or an inline element
1692 // which its parent is not a translation node.
1693 boolean isTranslationRootAtIndex(in unsigned long index);
1694 };
