docshell/base/nsIDocumentViewer.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIDocShell;
   8 interface nsISHEntry;
   9 interface nsIPrintSettings;
  10 webidl Document;
  11 webidl Node;
  12
  13 %{ C++
  14 #include "mozilla/Maybe.h"
  15 #include "nsTArray.h"
  16 #include "nsRect.h"
  17 #include "Units.h"
  18
  19 class nsIWidget;
  20 class nsPresContext;
  21 class nsView;
  22 class nsDOMNavigationTiming;
  23 namespace mozilla {
  24 class Encoding;
  25 class PresShell;
  26 namespace dom {
  27 class WindowGlobalChild;
  28 } // namespace dom
  29 namespace layout {
  30 class RemotePrintJobChild;
  31 } // namespace layout
  32 } // namespace mozilla
  33 %}
  34
  35 [ptr] native nsIWidgetPtr(nsIWidget);
  36 [ref] native nsIntRectRef(nsIntRect);
  37 [ptr] native nsPresContextPtr(nsPresContext);
  38 [ptr] native nsViewPtr(nsView);
  39 [ptr] native nsDOMNavigationTimingPtr(nsDOMNavigationTiming);
  40 [ptr] native Encoding(const mozilla::Encoding);
  41 [ptr] native PresShellPtr(mozilla::PresShell);
  42 [ptr] native RemotePrintJobChildPtr(mozilla::layout::RemotePrintJobChild);
  43 [ptr] native WindowGlobalChildPtr(mozilla::dom::WindowGlobalChild);
  44
  45 [scriptable, builtinclass, uuid(48118355-e9a5-4452-ab18-59cc426fb817)]
  46 interface nsIDocumentViewer : nsISupports
  47 {
  48   [noscript] void init(in nsIWidgetPtr aParentWidget,
  49                        [const] in nsIntRectRef aBounds,
  50                        in WindowGlobalChildPtr aWindowActor);
  51
  52   attribute nsIDocShell container;
  53
  54   [noscript,notxpcom,nostdcall] void loadStart(in Document aDoc);
  55   [can_run_script] void loadComplete(in nsresult aStatus);
  56   [notxpcom,nostdcall] readonly attribute boolean loadCompleted;
  57
  58   [notxpcom,nostdcall] readonly attribute boolean isStopped;
  59
  60    /**
  61    * aAction is passed to PermitUnload to indicate what action to take
  62    * if a beforeunload handler wants to prompt the user.
  63    *
  64    * ePrompt: Prompt and return the user's choice (default).
  65    * eDontPromptAndDontUnload: Don't prompt and return false (unload not permitted)
  66    *                           if the document (or its children) asks us to prompt.
  67    * eDontPromptAndUnload: Don't prompt and return true (unload permitted) no matter what.
  68    *
  69    * NOTE: Keep this in sync with PermitUnloadAction in WindowGlobalActors.webidl.
  70    */
  71   cenum PermitUnloadAction : 8 {
  72     ePrompt = 0,
  73     eDontPromptAndDontUnload = 1,
  74     eDontPromptAndUnload = 2
  75   };
  76
  77   /**
  78    * The result of dispatching a "beforeunload" event. If `eAllowNavigation`,
  79    * no "beforeunload" listener requested to prevent the navigation, or its
  80    * request was ignored. If `eRequestBlockNavigation`, a listener did request
  81    * to block the navigation, and the user should be prompted.
  82    */
  83   cenum PermitUnloadResult : 8 {
  84     eAllowNavigation = 0,
  85     eRequestBlockNavigation = 1,
  86   };
  87
  88   /**
  89    * Overload PermitUnload method for C++ consumers with no aPermitUnloadFlags
  90    * argument.
  91    */
  92   %{C++
  93     nsresult PermitUnload(bool* canUnload) {
  94       return PermitUnload(ePrompt, canUnload);
  95     }
  96   %}
  97
  98   /**
  99    * Checks if the document wants to prevent unloading by firing beforeunload on
 100    * the document.
 101    * The result is returned.
 102    */
 103   boolean permitUnload([optional] in nsIDocumentViewer_PermitUnloadAction aAction);
 104
 105   /**
 106    * Exposes whether we're blocked in a call to permitUnload.
 107    */
 108   readonly attribute boolean inPermitUnload;
 109
 110   /**
 111    * Dispatches the "beforeunload" event and returns the result, as documented
 112    * in the `PermitUnloadResult` enum.
 113    */
 114   [noscript,nostdcall,notxpcom] nsIDocumentViewer_PermitUnloadResult dispatchBeforeUnload();
 115
 116   /**
 117    * Exposes whether we're in the process of firing the beforeunload event.
 118    * In this case, the corresponding docshell will not allow navigation.
 119    */
 120   readonly attribute boolean beforeUnloadFiring;
 121
 122   [can_run_script] void pageHide(in boolean isUnload);
 123
 124   /**
 125    * All users of a content viewer are responsible for calling both
 126    * close() and destroy(), in that order.
 127    *
 128    * close() should be called when the load of a new page for the next
 129    * content viewer begins, and destroy() should be called when the next
 130    * content viewer replaces this one.
 131    *
 132    * |historyEntry| sets the session history entry for the content viewer.  If
 133    * this is null, then Destroy() will be called on the document by close().
 134    * If it is non-null, the document will not be destroyed, and the following
 135    * actions will happen when destroy() is called (*):
 136    *  - Sanitize() will be called on the viewer's document
 137    *  - The content viewer will set the contentViewer property on the
 138    *    history entry, and release its reference (ownership reversal).
 139    *  - hide() will be called, and no further destruction will happen.
 140    *
 141    *  (*) unless the document is currently being printed, in which case
 142    *      it will never be saved in session history.
 143    *
 144    */
 145   void close(in nsISHEntry historyEntry);
 146   void destroy();
 147
 148   void stop();
 149
 150   /**
 151    * Returns the same thing as getDocument(), but for use from script
 152    * only.  C++ consumers should use getDocument().
 153    */
 154   readonly attribute Document DOMDocument;
 155
 156   /**
 157    * Returns DOMDocument without addrefing.
 158    */
 159   [noscript,notxpcom,nostdcall] Document getDocument();
 160
 161   /**
 162    * Allows setting the document.
 163    */
 164   [noscript,nostdcall] void setDocument(in Document aDocument);
 165
 166   [noscript] void getBounds(in nsIntRectRef aBounds);
 167   [noscript] void setBounds([const] in nsIntRectRef aBounds);
 168   /**
 169    * The 'aFlags' argument to setBoundsWithFlags is a set of these bits.
 170    */
 171   const unsigned long eDelayResize = 1;
 172   [noscript] void setBoundsWithFlags([const] in nsIntRectRef aBounds,
 173                                      in unsigned long aFlags);
 174
 175   /**
 176    * The previous content viewer, which has been |close|d but not
 177    * |destroy|ed.
 178    */
 179   [notxpcom,nostdcall] attribute nsIDocumentViewer previousViewer;
 180
 181   void move(in long aX, in long aY);
 182
 183   void show();
 184   void hide();
 185
 186   attribute boolean sticky;
 187
 188   /**
 189    * Attach the content viewer to its DOM window and docshell.
 190    * @param aState A state object that might be useful in attaching the DOM
 191    *               window.
 192    * @param aSHEntry The history entry that the content viewer was stored in.
 193    *                 The entry must have the docshells for all of the child
 194    *                 documents stored in its child shell list.
 195    */
 196   void open(in nsISupports aState, in nsISHEntry aSHEntry);
 197
 198   /**
 199    * Clears the current history entry.  This is used if we need to clear out
 200    * the saved presentation state.
 201    */
 202   void clearHistoryEntry();
 203
 204   /**
 205    * Change the layout to view the document with page layout (like print preview), but
 206    * dynamic and editable (like Galley layout).
 207    */
 208   void setPageModeForTesting(in boolean aPageMode,
 209                              in nsIPrintSettings aPrintSettings);
 210
 211   /**
 212    * Sets the print settings for print / print-previewing a subdocument.
 213    */
 214   [can_run_script, noscript]
 215   void setPrintSettingsForSubdocument(in nsIPrintSettings aPrintSettings,
 216                                       in RemotePrintJobChildPtr aRemotePrintJob);
 217
 218   /**
 219    * Get the history entry that this viewer will save itself into when
 220    * destroyed.  Can return null
 221    */
 222   readonly attribute nsISHEntry historyEntry;
 223
 224   /**
 225    * Indicates when we're in a state where content shouldn't be allowed to
 226    * trigger a tab-modal prompt (as opposed to a window-modal prompt) because
 227    * we're part way through some operation (eg beforeunload) that shouldn't be
 228    * rentrant if the user closes the tab while the prompt is showing.
 229    * See bug 613800.
 230    */
 231   readonly attribute boolean isTabModalPromptAllowed;
 232
 233   /**
 234    * Returns whether this content viewer is in a hidden state.
 235    *
 236    * @note Only Gecko internal code should set the attribute!
 237    */
 238   attribute boolean isHidden;
 239
 240   // presShell can be null.
 241   [notxpcom,nostdcall] readonly attribute PresShellPtr presShell;
 242   // presContext can be null.
 243   [notxpcom,nostdcall] readonly attribute nsPresContextPtr presContext;
 244   // aDocument must not be null.
 245   [noscript] void setDocumentInternal(in Document aDocument,
 246                                       in boolean aForceReuseInnerWindow);
 247   /**
 248    * Find the view to use as the container view for MakeWindow. Returns
 249    * null if this will be the root of a view manager hierarchy. In that
 250    * case, if mParentWidget is null then this document should not even
 251    * be displayed.
 252    */
 253   [noscript,notxpcom,nostdcall] nsViewPtr findContainerView();
 254   /**
 255    * Set collector for navigation timing data (load, unload events).
 256    */
 257   [noscript,notxpcom,nostdcall] void setNavigationTiming(in nsDOMNavigationTimingPtr aTiming);
 258
 259   /**
 260    * The actual full zoom in effect, as modified by the device context.
 261    * For a requested full zoom, the device context may choose a slightly
 262    * different effectiveFullZoom to accomodate integer rounding of app units
 263    * per dev pixel. This property returns the actual zoom amount in use,
 264    * though it may not be good user experience to report that a requested zoom
 265    * of 90% is actually 89.1%, for example. This value is provided primarily to
 266    * support media queries of dppx values, because those queries are matched
 267    * against the actual native device pixel ratio and the actual full zoom.
 268    *
 269    * You should only need this for testing.
 270    */
 271   readonly attribute float deviceFullZoomForTest;
 272
 273   /**
 274    * Disable entire author style level (including HTML presentation hints),
 275    * for this viewer but not any child viewers.
 276    */
 277   attribute boolean authorStyleDisabled;
 278
 279   /**
 280    * Returns the preferred width and height of the content, constrained to the
 281    * given maximum values. If either maxWidth or maxHeight is less than or
 282    * equal to zero, that dimension is not constrained.
 283    *
 284    * If a pref width is provided, it is max'd with the min-content size.
 285    *
 286    * All input and output values are in CSS pixels.
 287    */
 288   void getContentSize(in long maxWidth,
 289                       in long maxHeight,
 290                       in long prefWidth,
 291                       out long width,
 292                       out long height);
 293
 294 %{C++
 295   mozilla::Maybe<mozilla::CSSIntSize> GetContentSize(int32_t aMaxWidth = 0, int32_t aMaxHeight = 0, int32_t aPrefWidth = 0) {
 296     int32_t w = 0;
 297     int32_t h = 0;
 298     if (NS_SUCCEEDED(GetContentSize(aMaxWidth, aMaxHeight, aPrefWidth, &w, &h))) {
 299       return mozilla::Some(mozilla::CSSIntSize(w, h));
 300     }
 301     return mozilla::Nothing();
 302   }
 303 %}
 304
 305   [noscript, notxpcom] Encoding getReloadEncodingAndSource(out int32_t aSource);
 306   [noscript, notxpcom] void setReloadEncodingAndSource(in Encoding aEncoding, in int32_t aSource);
 307   [noscript, notxpcom] void forgetReloadEncoding();
 308 };
 309
 310 %{C++
 311 namespace mozilla {
 312 namespace dom {
 313
 314 using XPCOMPermitUnloadAction = nsIDocumentViewer::PermitUnloadAction;
 315 using PermitUnloadResult = nsIDocumentViewer::PermitUnloadResult;
 316
 317 } // namespace dom
 318 } // namespace mozilla
 319 %}