nsIDOMWindowUtils.idl 79 KB
Newer Older
1
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2
3
4
/* 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/. */
5
6

#include "nsISupports.idl"
7
#include "domstubs.idl"
8
9

/**
10
11
12
13
14
 * nsIDOMWindowUtils is intended for infrequently-used methods related
 * to the current nsIDOMWindow.  Some of the methods may require
 * elevated privileges; the method implementations should contain the
 * necessary security checks.  Access this interface by calling
 * getInterface on a DOMWindow.
15
16
17
18
19
 *
 * WARNING: Do not use 'out jsval' parameters in this file.
 *          SpecialPowers, which is used to access nsIDOMWindowUtils
 *          in plain mochitests, does not know how to handle them.
 *          (Use 'jsval' return values instead.)
20
21
 */

22
23
%{C++
#include "nsColor.h"
24
class gfxContext;
25
struct nsRect;
26
27
%}

28
29
30
31
[ref] native nsConstRect(const nsRect);
native nscolor(nscolor);
[ptr] native gfxContext(gfxContext);

32
interface nsIArray;
33
interface nsICycleCollectorListener;
34
interface nsIPreloadedStyleSheet;
35
interface nsITransferable;
36
interface nsIQueryContentEventResult;
37
interface nsIDOMWindow;
38
interface nsIFile;
39
interface nsIURI;
40
interface nsIRunnable;
41
interface nsITranslationNodeList;
42
interface nsIJSRAIIHelper;
43
interface nsIContentPermissionRequest;
44
interface nsIObserver;
45

46
webidl Animation;
47
webidl DOMRect;
48
webidl Element;
49
webidl EventTarget;
50
webidl Event;
51
webidl Node;
52
webidl NodeList;
53
webidl Storage;
54

55
[builtinclass, scriptable, uuid(4d6732ca-9da7-4176-b8a1-8dde15cd0bf9)]
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
interface nsIDOMWindowUtils : nsISupports {

  /**
   * Image animation mode of the window. When this attribute's value
   * is changed, the implementation should set all images in the window
   * to the given value. That is, when set to kDontAnimMode, all images
   * will stop animating. The attribute's value must be one of the
   * animationMode values from imgIContainer.
   * @note Images may individually override the window's setting after
   *       the window's mode is set. Therefore images given different modes
   *       since the last setting of the window's mode may behave
   *       out of line with the window's overall mode.
   * @note The attribute's value is the window's overall mode. It may
   *       for example continue to report kDontAnimMode after all images
   *       have subsequently been individually animated.
   * @note Only images immediately in this window are affected;
   *       this is not recursive to subwindows.
   * @see imgIContainer
   */
75
76
  attribute unsigned short imageAnimationMode;

77
78
  /**
   * Whether the charset of the window's current document has been forced by
79
80
   * the user.
   * Cannot be accessed from unprivileged context (not content-accessible)
81
82
83
   */
  readonly attribute boolean docCharsetIsForced;

84
85
86
87
88
  /**
   * Return the conversion of a physical millimeter in CSS pixels.
   */
  readonly attribute float physicalMillimeterInCSSPixels;

89
90
91
92
  /**
   * Function to get metadata associated with the window's current document
   * @param aName the name of the metadata.  This should be all lowercase.
   * @return the value of the metadata, or the empty string if it's not set
93
   *
94
   * Will throw a DOM security error if called without chrome privileges.
95
96
   */
  AString getDocumentMetadata(in AString aName);
97

98
99
100
  /**
   * Force a synchronous layer transaction for this window if necessary.
   */
101
  [can_run_script]
102
103
  void updateLayerTree();

104
105
106
107
108
  /**
   * Get the last used layer transaction id for this window's refresh driver.
   */
  readonly attribute unsigned long long lastTransactionId;

109
110
  /**
   * Information retrieved from the <meta name="viewport"> tag.
111
   * See Document::GetViewportInfo for more information.
112
113
114
115
116
117
   */
  void getViewportInfo(in uint32_t aDisplayWidth, in uint32_t aDisplayHeight,
                       out double aDefaultZoom, out boolean aAllowZoom,
                       out double aMinZoom, out double aMaxZoom,
                       out uint32_t aWidth, out uint32_t aHeight,
                       out boolean aAutoSize);
118
119
120
121
122
  /*
   * Information retrieved from the viewport-fit value of <meta name="viewport">
   * element.
   */
  AString getViewportFitInfo();
123

124
125
126
127
128
  /**
   * Information about the window size in device pixels.
   */
  void getContentViewerSize(out uint32_t aDisplayWidth, out uint32_t aDisplayHeight);

129
  /**
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
   * For any scrollable element, this allows you to override the
   * visible region and draw more than what is visible, which is
   * useful for asynchronous drawing. The "displayport" will be
   * <xPx, yPx, widthPx, heightPx> in units of CSS pixels,
   * regardless of the size of the enclosing container.  This
   * will *not* trigger reflow.
   *
   * For the root scroll area, pass in the root document element.
   * For scrollable elements, pass in the container element (for
   * instance, the element with overflow: scroll).
   *
   * <x, y> is relative to the top-left of what would normally be
   * the visible area of the element. This means that the pixels
   * rendered to the displayport take scrolling into account,
   * for example.
   *
   * It's legal to set a displayport that extends beyond the overflow
   * area in any direction (left/right/top/bottom).
148
   *
149
150
151
   * It's also legal to set a displayport that extends beyond the
   * area's bounds.  No pixels are rendered outside the area bounds.
   *
152
   * The caller of this method must have chrome privileges.
153
154
155
156
157
   *
   * Calling this will always force a recomposite, so it should be
   * avoided if at all possible. Client code should do checks before
   * calling this so that duplicate sets are not made with the same
   * displayport.
158
159
160
161
   *
   * aPriority is recorded along with the displayport rectangle. If this
   * method is called with a lower priority than the current priority, the
   * call is ignored.
162
   */
163
164
  void setDisplayPortForElement(in float aXPx, in float aYPx,
                                in float aWidthPx, in float aHeightPx,
165
                                in Element aElement,
166
                                in uint32_t aPriority);
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
  /**
   * An alternate way to represent a displayport rect as a set of margins and a
   * base rect to apply those margins to. A consumer of pixels may ask for as
   * many extra pixels as it would like in each direction. Layout then sets
   * the base rect to the "visible rect" of the element, which is just the
   * subrect of the element that is drawn (it does not take in account content
   * covering the element).
   *
   * If both a displayport rect and displayport margins with corresponding base
   * rect are set with the same priority then the margins will take precendence.
   *
   * Specifying an alignment value will ensure that after the base rect has
   * been expanded by the displayport margins, it will be further expanded so
   * that each edge is located at a multiple of the "alignment" value.
   *
   * Note that both the margin values and alignment are treated as values in
183
   * ScreenPixels. Refer to layout/base/Units.h for a description of this unit.
184
185
186
187
188
189
   * The base rect values are in app units.
   */
  void setDisplayPortMarginsForElement(in float aLeftMargin,
                                       in float aTopMargin,
                                       in float aRightMargin,
                                       in float aBottomMargin,
190
                                       in Element aElement,
191
192
193
194
195
196
                                       in uint32_t aPriority);

  void setDisplayPortBaseForElement(in int32_t aX,
                                    in int32_t aY,
                                    in int32_t aWidth,
                                    in int32_t aHeight,
197
                                    in Element aElement);
198

199
200
201
202
203
204
205
206
207
208
209
210
211
212
  /**
   * If |aElement| is a scroll container, returns the amount of layout
   * space taken up by its scrollbars (that is, the width of the vertical
   * scrollbar and the height of the horizontal scrollbar) in CSS pixels;
   * otherwise returns zero.
   *
   * Note that on some platforms, scrollbars don't take up layout space
   * ("overlay scrollbars"). On such platforms, the returned sizes are
   * always zero.
   */
  void getScrollbarSizes(in Element aElement,
                         out uint32_t aVerticalScrollbarWidth,
                         out uint32_t aHorizontalScrollbarHeight);

213
  /**
214
215
   * Get/set the resolution at which rescalable web content is drawn for
   * testing purposes.
216
217
218
219
220
   *
   * Setting a new resolution does *not* trigger reflow.  This API is
   * entirely separate from textZoom and fullZoom; a resolution scale
   * can be applied together with both textZoom and fullZoom.
   *
221
   * The effect of this API is for gfx code to allocate more or fewer
222
   * pixels for rescalable content by a factor of |resolution| in
223
   * both dimensions.
224
   *
225
   * In addition, the content is scaled by the amount of the resolution,
226
   * so that it is displayed at a correspondingly larger or smaller size,
227
   * without the need for the caller to set an additional transform.
228
   *
229
230
231
   * The purpose of this API is to allow tests to simulate many of the effects
   * a non-reflowing scale-zoom, e.g. for pinch-zoom on mobile platforms, and
   * should be only used for testing purposes.
232
233
   *
   * The caller of this method must have chrome privileges.
234
235
   *
   * This is intended to be used by test code only!
236
   */
237
  void setResolutionAndScaleTo(in float aResolution);
238

239
  float getResolution();
240

241
242
  /**
   * Set a resolution on the presShell which is the "restored" from history.
243
244
245
   * The display dimensions are compared to their current values and used
   * to scale the resolution value if necessary, e.g. if the device was
   * rotated between saving and restoring of the session data.
246
247
248
   * This resolution should be used when painting for the first time. Calling
   * this too late may have no effect.
   */
249
250
251
  void setRestoreResolution(in float aResolution,
                            in uint32_t aDisplayWidth,
                            in uint32_t aDisplayHeight);
252

253
254
255
256
257
  /**
   * Whether the next paint should be flagged as the first paint for a document.
   * This gives a way to track the next paint that occurs after the flag is
   * set. The flag gets cleared after the next paint.
   *
258
   * Can only be accessed with chrome privileges.
259
260
261
   */
  attribute boolean isFirstPaint;

262
  uint32_t getPresShellId();
263

264
265
266
  /**
   * Following modifiers are for sent*Event() except sendNative*Event().
   * NOTE: MODIFIER_ALT, MODIFIER_CONTROL, MODIFIER_SHIFT and MODIFIER_META
267
   *       are must be same values as Event_Binding::*_MASK for backward
268
269
270
271
272
273
274
275
276
   *       compatibility.
   */
  const long MODIFIER_ALT        = 0x0001;
  const long MODIFIER_CONTROL    = 0x0002;
  const long MODIFIER_SHIFT      = 0x0004;
  const long MODIFIER_META       = 0x0008;
  const long MODIFIER_ALTGRAPH   = 0x0010;
  const long MODIFIER_CAPSLOCK   = 0x0020;
  const long MODIFIER_FN         = 0x0040;
277
278
279
280
281
282
  const long MODIFIER_FNLOCK     = 0x0080;
  const long MODIFIER_NUMLOCK    = 0x0100;
  const long MODIFIER_SCROLLLOCK = 0x0200;
  const long MODIFIER_SYMBOL     = 0x0400;
  const long MODIFIER_SYMBOLLOCK = 0x0800;
  const long MODIFIER_OS         = 0x1000;
283

284
  /** Synthesize a mouse event. The event types supported are:
285
286
   *    mousedown, mouseup, mousemove, mouseover, mouseout, mousecancel,
   *    contextmenu, MozMouseHittest
287
288
289
290
291
292
293
294
295
296
297
298
   *
   * Events are sent in coordinates offset by aX and aY from the window.
   *
   * Note that additional events may be fired as a result of this call. For
   * instance, typically a click event will be fired as a result of a
   * mousedown and mouseup in sequence.
   *
   * Normally at this level of events, the mouseover and mouseout events are
   * only fired when the window is entered or exited. For inter-element
   * mouseover and mouseout events, a movemove event fired on the new element
   * should be sufficient to generate the correct over and out events as well.
   *
299
   * Cannot be accessed from unprivileged context (not content-accessible)
300
   * Will throw a DOM security error if called without chrome privileges.
301
   *
302
303
304
305
   * The event is dispatched via the toplevel window, so it could go to any
   * window under the toplevel window, in some cases it could never reach this
   * window at all.
   *
306
307
308
309
310
   * NOTE: mousecancel is used to represent the vanishing of an input device
   * such as a pen leaving its digitizer by synthesizing a WidgetMouseEvent,
   * whose mMessage is eMouseExitFromWidget and mExitFrom is
   * WidgetMouseEvent::eTopLevel.
   *
311
   * @param aType event type
312
313
   * @param aX x offset in CSS pixels
   * @param aY y offset in CSS pixels
314
315
   * @param aButton button to synthesize
   * @param aClickCount number of clicks that have been performed
316
   * @param aModifiers modifiers pressed, using constants defined as MODIFIER_*
317
   * @param aIgnoreRootScrollFrame whether the event should ignore viewport bounds
318
   *                           during dispatch
319
   * @param aPressure touch input pressure: 0.0 -> 1.0
320
   * @param aInputSourceArg input source, see MouseEvent for values,
321
   *        defaults to mouse input.
322
   * @param aIsDOMEventSynthesized controls Event.isSynthesized value
323
324
325
326
   *                               that helps identifying test related events,
   *                               defaults to true
   * @param aIsWidgetEventSynthesized controls WidgetMouseEvent.mReason value
   *                                  defaults to false (WidgetMouseEvent::eReal)
327
328
   * @param aIdentifier A unique identifier for the pointer causing the event,
   *                    defaulting to nsIDOMWindowUtils::DEFAULT_MOUSE_POINTER_ID.
329
330
   *
   * returns true if the page called prevent default on this event
331
   */
332
  [optional_argc, can_run_script]
333
334
335
336
337
338
339
340
  boolean sendMouseEvent(in AString aType,
                         in float aX,
                         in float aY,
                         in long aButton,
                         in long aClickCount,
                         in long aModifiers,
                         [optional] in boolean aIgnoreRootScrollFrame,
                         [optional] in float aPressure,
341
                         [optional] in unsigned short aInputSourceArg,
342
                         [optional] in boolean aIsDOMEventSynthesized,
343
                         [optional] in boolean aIsWidgetEventSynthesized,
344
345
                         [optional] in long aButtons,
                         [optional] in unsigned long aIdentifier);
346

347
348
349
350
351
352
  /** Synthesize a touch event. The event types supported are:
   *    touchstart, touchend, touchmove, and touchcancel
   *
   * Events are sent in coordinates offset by aX and aY from the window.
   *
   * Cannot be accessed from unprivileged context (not content-accessible)
353
   * Will throw a DOM security error if called without chrome privileges.
354
355
356
357
358
359
360
361
362
363
364
365
366
   *
   * The event is dispatched via the toplevel window, so it could go to any
   * window under the toplevel window, in some cases it could never reach this
   * window at all.
   *
   * @param aType event type
   * @param xs array of offsets in CSS pixels for each touch to be sent
   * @param ys array of offsets in CSS pixels for each touch to be sent
   * @param rxs array of radii in CSS pixels for each touch to be sent
   * @param rys array of radii in CSS pixels for each touch to be sent
   * @param rotationAngles array of angles in degrees for each touch to be sent
   * @param forces array of forces (floats from 0 to 1) for each touch to be sent
   * @param count number of touches in this set
367
   * @param aModifiers modifiers pressed, using constants defined as MODIFIER_*
368
369
370
371
372
   * @param aIgnoreRootScrollFrame whether the event should ignore viewport bounds
   *                           during dispatch
   *
   * returns true if the page called prevent default on this touch event
   */
373
  [can_run_script]
374
  boolean sendTouchEvent(in AString aType,
375
376
377
378
379
380
381
                         in Array<uint32_t> aIdentifiers,
                         in Array<int32_t> aXs,
                         in Array<int32_t> aYs,
                         in Array<uint32_t> aRxs,
                         in Array<uint32_t> aRys,
                         in Array<float> aRotationAngles,
                         in Array<float> aForces,
382
383
384
                         in long aModifiers,
                         [optional] in boolean aIgnoreRootScrollFrame);

385
386
387
  /** The same as sendMouseEvent but ensures that the event is dispatched to
   *  this DOM window or one of its children.
   */
388
  [optional_argc, can_run_script]
389
390
391
392
393
394
  void sendMouseEventToWindow(in AString aType,
                              in float aX,
                              in float aY,
                              in long aButton,
                              in long aClickCount,
                              in long aModifiers,
395
396
                              [optional] in boolean aIgnoreRootScrollFrame,
                              [optional] in float aPressure,
397
                              [optional] in unsigned short aInputSourceArg,
398
                              [optional] in boolean aIsDOMEventSynthesized,
399
                              [optional] in boolean aIsWidgetEventSynthesized,
400
401
                              [optional] in long aButtons,
                              [optional] in unsigned long aIdentifier);
402

403
404
405
  /** The same as sendTouchEvent but ensures that the event is dispatched to
   *  this DOM window or one of its children.
   */
406
  [can_run_script]
407
  boolean sendTouchEventToWindow(in AString aType,
408
409
410
411
412
413
414
                                 in Array<uint32_t> aIdentifiers,
                                 in Array<int32_t> aXs,
                                 in Array<int32_t> aYs,
                                 in Array<uint32_t> aRxs,
                                 in Array<uint32_t> aRys,
                                 in Array<float> aRotationAngles,
                                 in Array<float> aForces,
415
416
417
                                 in long aModifiers,
                                 [optional] in boolean aIgnoreRootScrollFrame);

418
419
  /** Synthesize a wheel event for a window. The event types supported is only
   *  wheel.
420
421
422
423
   *
   * Events are sent in coordinates offset by aX and aY from the window.
   *
   * Cannot be accessed from unprivileged context (not content-accessible)
424
   * Will throw a DOM security error if called without chrome privileges.
425
   *
426
427
428
429
430
   * @param aX                 x offset in CSS pixels
   * @param aY                 y offset in CSS pixels
   * @param aDeltaX            deltaX value.
   * @param aDeltaY            deltaY value.
   * @param aDeltaZ            deltaZ value.
431
432
   * @param aDeltaMode         deltaMode value which must be one of the
   *                           WheelEvent DOM_DELTA_* constants.
433
434
435
   * @param aModifiers         modifiers pressed, using constants defined as
   *                           MODIFIER_*
   * @param aLineOrPageDeltaX  If you set this value non-zero for
436
   *                           DOM_DELTA_PIXEL event, EventStateManager will
437
438
439
   *                           dispatch NS_MOUSE_SCROLL event for horizontal
   *                           scroll.
   * @param aLineOrPageDeltaY  If you set this value non-zero for
440
   *                           DOM_DELTA_PIXEL event, EventStateManager will
441
442
443
   *                           dispatch NS_MOUSE_SCROLL event for vertical
   *                           scroll.
   * @param aOptions           Set following flags.
444
   */
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
  const unsigned long WHEEL_EVENT_CAUSED_BY_NO_LINE_OR_PAGE_DELTA_DEVICE = 0x0001;
  const unsigned long WHEEL_EVENT_CAUSED_BY_MOMENTUM                     = 0x0002;
  const unsigned long WHEEL_EVENT_CUSTOMIZED_BY_USER_PREFS               = 0x0004;
  // If any of the following flags is specified this method will throw an
  // exception in case the relevant overflowDelta has an unexpected value.
  const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_X_ZERO      = 0x0010;
  const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_X_POSITIVE  = 0x0020;
  const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_X_NEGATIVE  = 0x0040;
  const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_Y_ZERO      = 0x0100;
  const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_Y_POSITIVE  = 0x0200;
  const unsigned long WHEEL_EVENT_EXPECTED_OVERFLOW_DELTA_Y_NEGATIVE  = 0x0400;
  void sendWheelEvent(in float aX,
                      in float aY,
                      in double aDeltaX,
                      in double aDeltaY,
                      in double aDeltaZ,
                      in unsigned long aDeltaMode,
                      in long aModifiers,
                      in long aLineOrPageDeltaX,
                      in long aLineOrPageDeltaY,
                      in unsigned long aOptions);
466

467
468
469
470
  /**
   * See nsIWidget::SynthesizeNativeKeyEvent
   *
   * Cannot be accessed from unprivileged context (not content-accessible)
471
   * Will throw a DOM security error if called without chrome privileges.
472
473
   *
   * When you use this for tests, use the constants defined in NativeKeyCodes.js
474
475
476
477
   *
   * NOTE: The synthesized native event will be fired asynchronously, and upon
   * completion the observer, if provided, will be notified with a "keyevent"
   * topic.
478
479
480
481
482
   */
  void sendNativeKeyEvent(in long aNativeKeyboardLayout,
                          in long aNativeKeyCode,
                          in long aModifierFlags,
                          in AString aCharacters,
483
484
                          in AString aUnmodifiedCharacters,
                          [optional] in nsIObserver aObserver);
485

486
487
488
489
490
  /**
   * See nsIWidget::SynthesizeNativeMouseEvent
   *
   * Will be called on the widget that contains aElement.
   * Cannot be accessed from unprivileged context (not content-accessible)
491
   * Will throw a DOM security error if called without chrome privileges.
492
493
494
495
   *
   * NOTE: The synthesized native event will be fired asynchronously, and upon
   * completion the observer, if provided, will be notified with a "mouseevent"
   * topic.
496
497
498
499
500
   */
  void sendNativeMouseEvent(in long aScreenX,
                            in long aScreenY,
                            in long aNativeMessage,
                            in long aModifierFlags,
501
                            in Element aElement,
502
                            [optional] in nsIObserver aObserver);
503
504
505
506
507
  /**
   * See nsIWidget::SynthesizeNativeMouseMove and sendNativeMouseEvent
   */
  void sendNativeMouseMove(in long aScreenX,
                           in long aScreenY,
508
                           in Element aElement,
509
                           [optional] in nsIObserver aObserver);
510

511
512
513
514
515
516
  /**
   * Suppress animations that are applied to a window by OS when
   * resizing, moving, changing size mode, ...
   */
  void suppressAnimation(in boolean aSuppress);

517
518
519
520
521
522
523
524
525
526
527
  /**
   * The values for sendNativeMouseScrollEvent's aAdditionalFlags.
   */

  /**
   * If MOUSESCROLL_PREFER_WIDGET_AT_POINT is set, widget will dispatch
   * the event to a widget which is under the cursor.  Otherwise, dispatch to
   * a default target on the platform.  E.g., on Windows, it's focused window.
   */
  const unsigned long MOUSESCROLL_PREFER_WIDGET_AT_POINT = 0x00000001;

528
529
530
531
532
  /**
   * Interpret the scroll delta values as lines rather than pixels.
   */
  const unsigned long MOUSESCROLL_SCROLL_LINES = 0x00000002;

533
534
535
536
537
538
539
540
541
542
543
  /**
   * The platform specific values of aAdditionalFlags.  Must be over 0x00010000.
   */

  /**
   * If MOUSESCROLL_WIN_SCROLL_LPARAM_NOT_NULL is set and aNativeMessage is
   * WM_VSCROLL or WM_HSCROLL, widget will set the window handle to the lParam
   * instead of NULL.
   */
  const unsigned long MOUSESCROLL_WIN_SCROLL_LPARAM_NOT_NULL = 0x00010000;

544
545
546
547
548
  /**
   * See nsIWidget::SynthesizeNativeMouseScrollEvent
   *
   * Will be called on the widget that contains aElement.
   * Cannot be accessed from unprivileged context (not content-accessible)
549
   * Will throw a DOM security error if called without chrome privileges.
550
   *
551
552
553
   * NOTE: The synthesized native event will be fired asynchronously, and upon
   * completion the observer, if provided, will be notified with a
   * "mousescrollevent" topic.
554
555
556
557
   *
   * @param aNativeMessage
   *   On Windows:  WM_MOUSEWHEEL (0x020A), WM_MOUSEHWHEEL(0x020E),
   *                WM_VSCROLL (0x0115) or WM_HSCROLL (0x114).
558
559
560
561
562
563
564
565
566
   */
  void sendNativeMouseScrollEvent(in long aScreenX,
                                  in long aScreenY,
                                  in unsigned long aNativeMessage,
                                  in double aDeltaX,
                                  in double aDeltaY,
                                  in double aDeltaZ,
                                  in unsigned long aModifierFlags,
                                  in unsigned long aAdditionalFlags,
567
                                  in Element aElement,
568
                                  [optional] in nsIObserver aObserver);
569

570
  /**
571
572
   * Touch states for sendNativeTouchPoint. These values match
   * nsIWidget's TouchPointerState.
573
574
   */

575
576
577
578
579
580
581
582
583
584
585
586
  // The pointer is in a hover state above the digitizer
  const long TOUCH_HOVER   = 0x01;
  // The pointer is in contact with the digitizer
  const long TOUCH_CONTACT = 0x02;
  // The pointer has been removed from the digitizer detection area
  const long TOUCH_REMOVE  = 0x04;
  // The pointer has been canceled. Will cancel any pending os level
  // gestures that would be triggered as a result of completion of the
  // input sequence. This may not cancel moz platform related events
  // that might get tirggered by input already delivered.
  const long TOUCH_CANCEL  = 0x08;

587
  /**
588
589
590
591
592
593
594
595
   * Create a new or update an existing touch point on the digitizer.
   * To trigger os level gestures, individual touch points should
   * transition through a complete set of touch states which should be
   * sent as individual calls. For example:
   * tap - msg1:TOUCH_CONTACT, msg2:TOUCH_REMOVE
   * drag - msg1-n:TOUCH_CONTACT (moving), msgn+1:TOUCH_REMOVE
   * hover drag - msg1-n:TOUCH_HOVER (moving), msgn+1:TOUCH_REMOVE
   *
596
   * Widget support: Windows 8.0+, Winrt/Win32. Other widgets will throw.
597
   *
598
599
600
601
   * NOTE: The synthesized native event will be fired asynchronously, and upon
   * completion the observer, if provided, will be notified with a "touchpoint"
   * topic.
   *
602
603
604
605
606
607
   * @param aPointerId The touch point id to create or update.
   * @param aTouchState one or more of the touch states listed above
   * @param aScreenX, aScreenY screen coords of this event
   * @param aPressure 0.0 -> 1.0 float val indicating pressure
   * @param aOrientation 0 -> 359 degree value indicating the
   * orientation of the pointer. Use 90 for normal taps.
608
   */
609
610
611
612
613
  void sendNativeTouchPoint(in unsigned long aPointerId,
                            in unsigned long aTouchState,
                            in long aScreenX,
                            in long aScreenY,
                            in double aPressure,
614
615
                            in unsigned long aOrientation,
                            [optional] in nsIObserver aObserver);
616
617

  /**
618
619
620
621
622
623
624
625
626
627
628
629
630
631
   * Simulates native touch based taps on the input digitizer. Events
   * triggered by this call are injected at the os level. Events do not
   * bypass widget level input processing and as such can be used to
   * test widget event logic and async pan-zoom controller functionality.
   * Cannot be accessed from an unprivileged context.
   *
   * Long taps (based on the aLongTap parameter) will be completed
   * asynchrnously after the call returns. Long tap delay is based on
   * the ui.click_hold_context_menus.delay pref or 1500 msec if pref
   * is not set.
   *
   * Widget support: Windows 8.0+, Winrt/Win32. Other widgets will
   * throw.
   *
632
633
634
635
   * NOTE: The synthesized native event will be fired asynchronously, and upon
   * completion the observer, if provided, will be notified, with a "touchtap"
   * topic.
   *
636
637
638
   * @param aScreenX, aScreenY screen coords of this event
   * @param aLongTap true if the tap should be long, false for a short
   * tap.
639
   */
640
641
  void sendNativeTouchTap(in long aScreenX,
                          in long aScreenY,
642
643
                          in boolean aLongTap,
                          [optional] in nsIObserver aObserver);
644
645

  /**
646
647
648
649
650
   * Cancel any existing touch points or long tap delays. Calling this is safe
   * even if you're sure there aren't any pointers recorded. You should call
   * this when tests shut down to reset the digitizer driver. Not doing so can
   * leave the digitizer in an undetermined state which can screw up subsequent
   * tests and native input.
651
652
653
654
   *
   * NOTE: The synthesized native event will be fired asynchronously, and upon
   * completion the observer, if provided, will be notified with a "cleartouch"
   * topic.
655
   */
656
  void clearNativeTouchSequence([optional] in nsIObserver aObserver);
657

658
659
660
661
  /**
   * See nsIWidget::ActivateNativeMenuItemAt
   *
   * Cannot be accessed from unprivileged context (not content-accessible)
662
   * Will throw a DOM security error if called without chrome privileges.
663
664
665
   */
  void activateNativeMenuItemAt(in AString indexString);

666
  /**
667
   * See nsIWidget::ForceUpdateNativeMenuAt
668
   *
669
   * Cannot be accessed from unprivileged context (not content-accessible)
670
   * Will throw a DOM security error if called without chrome privileges.
671
   */
672
  void forceUpdateNativeMenuAt(in AString indexString);
673

674
675
676
677
678
679
680
681
682
  /**
   * Returns the current selection as plaintext. Note that the result may be
   * different from the result of sendQueryContentEvent(QUERY_SELECTED_TEXT).
   * This result is computed by native API with transferable data. In other
   * words, when the OS treats the selection as plaintext, it treats current
   * selection as this result.
   */
  AString GetSelectionAsPlaintext();

683
  /**
684
   * Force a garbage collection followed by a cycle collection.
685
   *
686
687
   * Will throw a DOM security error if called without chrome privileges in
   * non-debug builds. Available to all callers in debug builds.
688
689
   *
   * @param aListener listener that receives information about the CC graph
690
   */
691
  void garbageCollect([optional] in nsICycleCollectorListener aListener);
692

693
694
695
  /**
   * Force a cycle collection without garbage collection.
   *
696
697
   * Will throw a DOM security error if called without chrome privileges in
   * non-debug builds. Available to all callers in debug builds.
698
699
   *
   * @param aListener listener that receives information about the CC graph
700
701
   */
  void cycleCollect([optional] in nsICycleCollectorListener aListener);
702

703
704
705
706
707
708
  /**
   * Trigger whichever GC or CC timer is currently active and waiting to fire.
   * Don't do this too much for initiating heavy actions, like the start of a IGC.
   */
  void runNextCollectorTimer();

709
  /** Synthesize a simple gesture event for a window. The event types
710
711
712
713
714
   *  supported are: MozSwipeGestureMayStart, MozSwipeGestureStart,
   *  MozSwipeGestureUpdate, MozSwipeGestureEnd, MozSwipeGesture,
   *  MozMagnifyGestureStart, MozMagnifyGestureUpdate, MozMagnifyGesture,
   *  MozRotateGestureStart, MozRotateGestureUpdate, MozRotateGesture,
   *  MozPressTapGesture, MozTapGesture, and MozEdgeUIGesture.
715
716
717
   *
   * Cannot be accessed from unprivileged context (not
   * content-accessible) Will throw a DOM security error if called
718
   * without chrome privileges.
719
720
   *
   * @param aType event type
721
722
   * @param aX x offset in CSS pixels
   * @param aY y offset in CSS pixels
723
   * @param aDirection direction, using constants defined in SimpleGestureEvent.webidl
724
   * @param aDelta  amount of magnification or rotation for magnify and rotation events
725
   * @param aModifiers modifiers pressed, using constants defined in Event.webidl
726
   * @param aClickCount For tap gestures, the number of taps.
727
728
   */
  void sendSimpleGestureEvent(in AString aType,
729
730
                              in float aX,
                              in float aY,
731
732
                              in unsigned long aDirection,
                              in double aDelta,
733
734
                              in long aModifiers,
                              [optional] in unsigned long aClickCount);
735
736
737
738
739
740
741
742
743

  /**
   * Retrieve the element at point aX, aY in the window's document.
   *
   * @param aIgnoreRootScrollFrame whether or not to ignore the root scroll
   *        frame when retrieving the element. If false, this method returns
   *        null for coordinates outside of the viewport.
   * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
   */
744
745
746
747
  Element elementFromPoint(in float aX,
                           in float aY,
                           in boolean aIgnoreRootScrollFrame,
                           in boolean aFlushLayout);
748

749
750
751
752
753
754
755
756
757
758
759
760
761
  /**
   * Retrieve all nodes that intersect a rect in the window's document.
   *
   * @param aX x reference for the rectangle in CSS pixels
   * @param aY y reference for the rectangle in CSS pixels
   * @param aTopSize How much to expand up the rectangle
   * @param aRightSize How much to expand right the rectangle
   * @param aBottomSize How much to expand down the rectangle
   * @param aLeftSize How much to expand left the rectangle
   * @param aIgnoreRootScrollFrame whether or not to ignore the root scroll
   *        frame when retrieving the element. If false, this method returns
   *        null for coordinates outside of the viewport.
   * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
762
763
   * @param aOnlyVisible Set to true if you only want nodes that pass a visibility
   *        hit test.
764
   */
765
766
767
768
769
770
771
  NodeList nodesFromRect(in float aX,
                         in float aY,
                         in float aTopSize,
                         in float aRightSize,
                         in float aBottomSize,
                         in float aLeftSize,
                         in boolean aIgnoreRootScrollFrame,
772
773
                         in boolean aFlushLayout,
                         in boolean aOnlyVisible);
774

775
776
777
778
779
780
781
782

  /**
   * Get a list of nodes that have meaningful textual content to
   * be translated. The implementation of this algorithm is in flux
   * as we experiment and refine which approach works best.
   *
   * This method requires chrome privileges.
   */
783
  nsITranslationNodeList getTranslationNodes(in Node aRoot);
784

785
786
787
788
789
  /**
   * Compare the two canvases, returning the number of differing pixels and
   * the maximum difference in a channel.  This will throw an error if
   * the dimensions of the two canvases are different.
   *
790
   * This method requires chrome privileges.
791
   */
792
793
  uint32_t compareCanvases(in nsISupports aCanvas1,
                           in nsISupports aCanvas2,
794
                           out unsigned long aMaxDifference);
795
796
797
798
799
800

  /**
   * Returns true if a MozAfterPaint event has been queued but not yet
   * fired.
   */
  readonly attribute boolean isMozAfterPaintPending;
801

802
803
804
805
  /**
   * Suppresses/unsuppresses user initiated event handling in window's document
   * and subdocuments.
   *
806
807
   * @throw NS_ERROR_DOM_SECURITY_ERR if called without chrome privileges and
   *        NS_ERROR_FAILURE if window doesn't have a document.
808
809
810
   */
  void suppressEventHandling(in boolean aSuppress);

811
812
813
814
  /**
   * Disable or enable non synthetic test mouse events on *all* windows.
   *
   * Cannot be accessed from unprivileged context (not content-accessible).
815
   * Will throw a DOM security error if called without chrome privileges.
816
817
818
819
820
   *
   * @param aDisable  If true, disable all non synthetic test mouse events
   *               on all windows.  Otherwise, enable them.
   */
  void disableNonTestMouseEvents(in boolean aDisable);
821
822
823
824
825
826
827
828

  /**
   * Returns the scroll position of the window's currently loaded document.
   *
   * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
   * @see nsIDOMWindow::scrollX/Y
   */
  void getScrollXY(in boolean aFlushLayout, out long aScrollX, out long aScrollY);
829

830
831
832
833
834
835
836
837
  /**
   * Returns the scroll position of the window's currently loaded document.
   *
   * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
   * @see nsIDOMWindow::scrollX/Y
   */
  void getScrollXYFloat(in boolean aFlushLayout, out float aScrollX, out float aScrollY);

838
839
840
841
842
  /**
   * Returns the scrollbar width of the window's scroll frame.
   *
   * @param aFlushLayout flushes layout if true. Otherwise, no flush occurs.
   */
843
  void getScrollbarSize(in boolean aFlushLayout, out long aWidth, out long aHeight);
844

845
846
847
  /**
   * Returns the given element's bounds without flushing pending layout changes.
   */
848
  DOMRect getBoundsWithoutFlushing(in Element aElement);
849

850
851
852
853
854
855
856
  /**
   * Scroll the visual viewport to the given coordinates, relative to the
   * document origin.
   * Only applicable to the window associated with the root content document.
   * Note: this does not take effect right away. Rather, the visual scroll
   *       request is sent to APZ with the next transaction, and will be
   *       reflected in the main thread with the subsequent APZ repaint request.
857
   * Please see the caveats mentioned at PresShell::ScrollToVisual(), and
858
   * request APZ review if adding a new call to this.
859
   */
860
861
  const long UPDATE_TYPE_RESTORE = 0;
  const long UPDATE_TYPE_MAIN_THREAD = 1;
862
863
864
865
  const long SCROLL_MODE_INSTANT = 0;
  const long SCROLL_MODE_SMOOTH = 1;
  void scrollToVisual(in float aOffsetX, in float aOffsetY,
                      in long aUpdateType, in long aScrollMode);
866

867
868
  /**
   * Returns the offset of the window's visual viewport relative to the
869
   * layout viewport.
870
   */
871
  void getVisualViewportOffsetRelativeToLayoutViewport(out float aOffsetX,
872
873
                                                       out float aOffsetY);

874
875
876
877
878
  /**
   * Returns the scroll position of the window's visual viewport.
   */
  void getVisualViewportOffset(out long aOffsetX, out long aOffsetY);

879
880
881
882
883
884
  /**
   * Sets the maximum height of the dynamic toolbar in Screen pixel units.
   */
  [can_run_script]
  void setDynamicToolbarMaxHeight(in uint32_t aHeightInScreen);

885
  const long FLUSH_NONE = -1;
886
887
888
889
890
891
892
893
894
  const long FLUSH_STYLE = 0;
  const long FLUSH_LAYOUT = 1;
  const long FLUSH_DISPLAY = 2;

  /**
   * Returns true if a flush of the given type is needed.
   */
  bool needsFlush(in long aFlushtype);

895
896
897
898
899
900
  /**
   * Flush pending layout-type notification without flushing throttled
   * animations.
   */
  void flushLayoutWithoutThrottledAnimations();

901
902
903
904
905
  /**
   * Returns the bounds of the window's currently loaded document. This will
   * generally be (0, 0, pageWidth, pageHeight) but in some cases (e.g. RTL
   * documents) may have a negative left value.
   */
906
  DOMRect getRootBounds();
907

908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
  /**
   * Get IME open state. TRUE means 'Open', otherwise, 'Close'.
   * This property works only when IMEEnabled is IME_STATUS_ENABLED.
   */
  readonly attribute boolean IMEIsOpen;

  /**
   * WARNING: These values must be same as nsIWidget's values.
   */

  /**
   * DISABLED means users cannot use IME completely.
   * Note that this state is *not* same as |ime-mode: disabled;|.
   */
  const unsigned long IME_STATUS_DISABLED = 0;

  /**
   * ENABLED means users can use all functions of IME. This state is same as
   * |ime-mode: normal;|.
   */
  const unsigned long IME_STATUS_ENABLED  = 1;

  /**
   * PASSWORD means users cannot use most functions of IME. But on GTK2,
   * users can use "Simple IM" which only supports dead key inputting.
   * The behavior is same as the behavior of the native password field.
   * This state is same as |ime-mode: disabled;|.
   */
  const unsigned long IME_STATUS_PASSWORD = 2;

  /**
   * PLUGIN means a plug-in has focus. At this time we should not touch to
   * controlling the IME state.
   */
  const unsigned long IME_STATUS_PLUGIN   = 3;

  /**
   * Get IME status, see above IME_STATUS_* definitions.
   */
  readonly attribute unsigned long IMEStatus;
948
949
950

  /**
   * Get the number of screen pixels per CSS pixel.
951
952
953
954
   *
   * This is the same as window.devicePixelRatio, except it bypasses
   * the fingerprinting resistance efforts that window.devicePixelRatio
   * does (which is fine as this is only exposed to browser internals).
955
956
   */
  readonly attribute float screenPixelsPerCSSPixel;
957

958
  /**
959
   * Get the number of screen pixels per CSS pixel,
960
961
962
963
964
965
966
967
968
   * not taking into account any override of the device pixel scale
   * that's imposed by Responsive Design Mode.
   *
   * This is needed to e.g. correctly translate "window.mozInnerScreenX/Y"
   * into device pixels even when "window" is the window of a document
   * inside an RDM pane.
   */
  readonly attribute float screenPixelsPerCSSPixelNoOverride;

969
970
  /**
   * Get the current zoom factor.
971
   * This is _approximately_ the same as nsIContentViewer.fullZoom,
Jonathan Kew's avatar