summaryrefslogtreecommitdiffstats
path: root/docshell/base/nsIDocumentViewer.idl
blob: 27510dc87905a41e1f222449810e3a2a71e6243c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIDocShell;
interface nsISHEntry;
interface nsIPrintSettings;
webidl Document;
webidl Node;

%{ C++
#include "mozilla/Maybe.h"
#include "nsTArray.h"
#include "nsRect.h"
#include "Units.h"

class nsIWidget;
class nsPresContext;
class nsView;
class nsDOMNavigationTiming;
namespace mozilla {
class Encoding;
class PresShell;
namespace dom {
class WindowGlobalChild;
} // namespace dom
namespace layout {
class RemotePrintJobChild;
} // namespace layout
} // namespace mozilla
%}

[ptr] native nsIWidgetPtr(nsIWidget);
[ref] native nsIntRectRef(nsIntRect);
[ptr] native nsPresContextPtr(nsPresContext);
[ptr] native nsViewPtr(nsView);
[ptr] native nsDOMNavigationTimingPtr(nsDOMNavigationTiming);
[ptr] native Encoding(const mozilla::Encoding);
[ptr] native PresShellPtr(mozilla::PresShell);
[ptr] native RemotePrintJobChildPtr(mozilla::layout::RemotePrintJobChild);
[ptr] native WindowGlobalChildPtr(mozilla::dom::WindowGlobalChild);

[scriptable, builtinclass, uuid(48118355-e9a5-4452-ab18-59cc426fb817)]
interface nsIDocumentViewer : nsISupports
{
  [noscript] void init(in nsIWidgetPtr aParentWidget,
                       [const] in nsIntRectRef aBounds,
                       in WindowGlobalChildPtr aWindowActor);

  attribute nsIDocShell container;

  [noscript,notxpcom,nostdcall] void loadStart(in Document aDoc);
  [can_run_script] void loadComplete(in nsresult aStatus);
  [notxpcom,nostdcall] readonly attribute boolean loadCompleted;

  [notxpcom,nostdcall] readonly attribute boolean isStopped;

   /**
   * aAction is passed to PermitUnload to indicate what action to take
   * if a beforeunload handler wants to prompt the user.
   *
   * ePrompt: Prompt and return the user's choice (default).
   * eDontPromptAndDontUnload: Don't prompt and return false (unload not permitted)
   *                           if the document (or its children) asks us to prompt.
   * eDontPromptAndUnload: Don't prompt and return true (unload permitted) no matter what.
   *
   * NOTE: Keep this in sync with PermitUnloadAction in WindowGlobalActors.webidl.
   */
  cenum PermitUnloadAction : 8 {
    ePrompt = 0,
    eDontPromptAndDontUnload = 1,
    eDontPromptAndUnload = 2
  };

  /**
   * The result of dispatching a "beforeunload" event. If `eAllowNavigation`,
   * no "beforeunload" listener requested to prevent the navigation, or its
   * request was ignored. If `eRequestBlockNavigation`, a listener did request
   * to block the navigation, and the user should be prompted.
   */
  cenum PermitUnloadResult : 8 {
    eAllowNavigation = 0,
    eRequestBlockNavigation = 1,
  };

  /**
   * Overload PermitUnload method for C++ consumers with no aPermitUnloadFlags
   * argument.
   */
  %{C++
    nsresult PermitUnload(bool* canUnload) {
      return PermitUnload(ePrompt, canUnload);
    }
  %}

  /**
   * Checks if the document wants to prevent unloading by firing beforeunload on
   * the document.
   * The result is returned.
   */
  boolean permitUnload([optional] in nsIDocumentViewer_PermitUnloadAction aAction);

  /**
   * Exposes whether we're blocked in a call to permitUnload.
   */
  readonly attribute boolean inPermitUnload;

  /**
   * Dispatches the "beforeunload" event and returns the result, as documented
   * in the `PermitUnloadResult` enum.
   */
  [noscript,nostdcall,notxpcom] nsIDocumentViewer_PermitUnloadResult dispatchBeforeUnload();

  /**
   * Exposes whether we're in the process of firing the beforeunload event.
   * In this case, the corresponding docshell will not allow navigation.
   */
  readonly attribute boolean beforeUnloadFiring;

  [can_run_script] void pageHide(in boolean isUnload);

  /**
   * All users of a content viewer are responsible for calling both
   * close() and destroy(), in that order.
   *
   * close() should be called when the load of a new page for the next
   * content viewer begins, and destroy() should be called when the next
   * content viewer replaces this one.
   *
   * |historyEntry| sets the session history entry for the content viewer.  If
   * this is null, then Destroy() will be called on the document by close().
   * If it is non-null, the document will not be destroyed, and the following
   * actions will happen when destroy() is called (*):
   *  - Sanitize() will be called on the viewer's document
   *  - The content viewer will set the contentViewer property on the
   *    history entry, and release its reference (ownership reversal).
   *  - hide() will be called, and no further destruction will happen.
   *
   *  (*) unless the document is currently being printed, in which case
   *      it will never be saved in session history.
   *
   */
  void close(in nsISHEntry historyEntry);
  void destroy();

  void stop();

  /**
   * Returns the same thing as getDocument(), but for use from script
   * only.  C++ consumers should use getDocument().
   */
  readonly attribute Document DOMDocument;

  /**
   * Returns DOMDocument without addrefing.
   */
  [noscript,notxpcom,nostdcall] Document getDocument();

  /**
   * Allows setting the document.
   */
  [noscript,nostdcall] void setDocument(in Document aDocument);

  [noscript] void getBounds(in nsIntRectRef aBounds);
  [noscript] void setBounds([const] in nsIntRectRef aBounds);
  /**
   * The 'aFlags' argument to setBoundsWithFlags is a set of these bits.
   */
  const unsigned long eDelayResize = 1;
  [noscript] void setBoundsWithFlags([const] in nsIntRectRef aBounds,
                                     in unsigned long aFlags);

  /**
   * The previous content viewer, which has been |close|d but not
   * |destroy|ed.
   */
  [notxpcom,nostdcall] attribute nsIDocumentViewer previousViewer;

  void move(in long aX, in long aY);

  void show();
  void hide();

  attribute boolean sticky;

  /**
   * Attach the content viewer to its DOM window and docshell.
   * @param aState A state object that might be useful in attaching the DOM
   *               window.
   * @param aSHEntry The history entry that the content viewer was stored in.
   *                 The entry must have the docshells for all of the child
   *                 documents stored in its child shell list.
   */
  void open(in nsISupports aState, in nsISHEntry aSHEntry);

  /**
   * Clears the current history entry.  This is used if we need to clear out
   * the saved presentation state.
   */
  void clearHistoryEntry();

  /**
   * Change the layout to view the document with page layout (like print preview), but
   * dynamic and editable (like Galley layout).
   */
  void setPageModeForTesting(in boolean aPageMode,
                             in nsIPrintSettings aPrintSettings);

  /**
   * Sets the print settings for print / print-previewing a subdocument.
   */
  [can_run_script, noscript]
  void setPrintSettingsForSubdocument(in nsIPrintSettings aPrintSettings,
                                      in RemotePrintJobChildPtr aRemotePrintJob);

  /**
   * Get the history entry that this viewer will save itself into when
   * destroyed.  Can return null
   */
  readonly attribute nsISHEntry historyEntry;

  /**
   * Indicates when we're in a state where content shouldn't be allowed to
   * trigger a tab-modal prompt (as opposed to a window-modal prompt) because
   * we're part way through some operation (eg beforeunload) that shouldn't be
   * rentrant if the user closes the tab while the prompt is showing.
   * See bug 613800.
   */
  readonly attribute boolean isTabModalPromptAllowed;

  /**
   * Returns whether this content viewer is in a hidden state.
   *
   * @note Only Gecko internal code should set the attribute!
   */
  attribute boolean isHidden;

  // presShell can be null.
  [notxpcom,nostdcall] readonly attribute PresShellPtr presShell;
  // presContext can be null.
  [notxpcom,nostdcall] readonly attribute nsPresContextPtr presContext;
  // aDocument must not be null.
  [noscript] void setDocumentInternal(in Document aDocument,
                                      in boolean aForceReuseInnerWindow);
  /**
   * Find the view to use as the container view for MakeWindow. Returns
   * null if this will be the root of a view manager hierarchy. In that
   * case, if mParentWidget is null then this document should not even
   * be displayed.
   */
  [noscript,notxpcom,nostdcall] nsViewPtr findContainerView();
  /**
   * Set collector for navigation timing data (load, unload events).
   */
  [noscript,notxpcom,nostdcall] void setNavigationTiming(in nsDOMNavigationTimingPtr aTiming);

  /**
   * The actual full zoom in effect, as modified by the device context.
   * For a requested full zoom, the device context may choose a slightly
   * different effectiveFullZoom to accomodate integer rounding of app units
   * per dev pixel. This property returns the actual zoom amount in use,
   * though it may not be good user experience to report that a requested zoom
   * of 90% is actually 89.1%, for example. This value is provided primarily to
   * support media queries of dppx values, because those queries are matched
   * against the actual native device pixel ratio and the actual full zoom.
   *
   * You should only need this for testing.
   */
  readonly attribute float deviceFullZoomForTest;

  /**
   * Disable entire author style level (including HTML presentation hints),
   * for this viewer but not any child viewers.
   */
  attribute boolean authorStyleDisabled;

  /**
   * Returns the preferred width and height of the content, constrained to the
   * given maximum values. If either maxWidth or maxHeight is less than or
   * equal to zero, that dimension is not constrained.
   *
   * If a pref width is provided, it is max'd with the min-content size.
   *
   * All input and output values are in CSS pixels.
   */
  void getContentSize(in long maxWidth,
                      in long maxHeight,
                      in long prefWidth,
                      out long width,
                      out long height);

%{C++
  mozilla::Maybe<mozilla::CSSIntSize> GetContentSize(int32_t aMaxWidth = 0, int32_t aMaxHeight = 0, int32_t aPrefWidth = 0) {
    int32_t w = 0;
    int32_t h = 0;
    if (NS_SUCCEEDED(GetContentSize(aMaxWidth, aMaxHeight, aPrefWidth, &w, &h))) {
      return mozilla::Some(mozilla::CSSIntSize(w, h));
    }
    return mozilla::Nothing();
  }
%}

  [noscript, notxpcom] Encoding getReloadEncodingAndSource(out int32_t aSource);
  [noscript, notxpcom] void setReloadEncodingAndSource(in Encoding aEncoding, in int32_t aSource);
  [noscript, notxpcom] void forgetReloadEncoding();
};

%{C++
namespace mozilla {
namespace dom {

using XPCOMPermitUnloadAction = nsIDocumentViewer::PermitUnloadAction;
using PermitUnloadResult = nsIDocumentViewer::PermitUnloadResult;

} // namespace dom
} // namespace mozilla
%}