docshell/base/nsIContentViewer.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 "nsTArray.h"
  15 #include "nsRect.h"
  16
  17 class nsIWidget;
  18 class nsIPresShell;
  19 class nsPresContext;
  20 class nsView;
  21 class nsDOMNavigationTiming;
  22 namespace mozilla {
  23 class Encoding;
  24 }
  25 %}
  26
  27 [ptr] native nsIWidgetPtr(nsIWidget);
  28 [ref] native nsIntRectRef(nsIntRect);
  29 [ptr] native nsIPresShellPtr(nsIPresShell);
  30 [ptr] native nsPresContextPtr(nsPresContext);
  31 [ptr] native nsViewPtr(nsView);
  32 [ptr] native nsDOMNavigationTimingPtr(nsDOMNavigationTiming);
  33 [ref] native nsIContentViewerTArray(nsTArray<nsCOMPtr<nsIContentViewer> >);
  34 [ptr] native Encoding(const mozilla::Encoding);
  35
  36 [scriptable, builtinclass, uuid(2da17016-7851-4a45-a7a8-00b360e01595)]
  37 interface nsIContentViewer : nsISupports
  38 {
  39   [noscript] void init(in nsIWidgetPtr aParentWidget,
  40                        [const] in nsIntRectRef aBounds);
  41
  42   attribute nsIDocShell container;
  43
  44   [noscript,notxpcom,nostdcall] void loadStart(in Document aDoc);
  45   void loadComplete(in nsresult aStatus);
  46   [noscript] readonly attribute boolean loadCompleted;
  47
  48   [noscript] readonly attribute boolean isStopped;
  49
  50   /**
  51    * aPermitUnloadFlags are passed to PermitUnload to indicate what action to take
  52    * if a beforeunload handler wants to prompt the user.  It is also used by
  53    * permitUnloadInternal to ensure we only prompt once.
  54    *
  55    * ePrompt: Prompt and return the user's choice (default).
  56    * eDontPromptAndDontUnload: Don't prompt and return false (unload not permitted)
  57    *                           if the document (or its children) asks us to prompt.
  58    * eDontPromptAndUnload: Don't prompt and return true (unload permitted) no matter what.
  59    */
  60   const unsigned long ePrompt = 0;
  61   const unsigned long eDontPromptAndDontUnload = 1;
  62   const unsigned long eDontPromptAndUnload = 2;
  63
  64   /**
  65    * Overload PermitUnload method for C++ consumers with no aPermitUnloadFlags
  66    * argument.
  67    */
  68   %{C++
  69     nsresult PermitUnload(bool* canUnload) {
  70       return PermitUnload(ePrompt, canUnload);
  71     }
  72   %}
  73
  74   /**
  75    * Checks if the document wants to prevent unloading by firing beforeunload on
  76    * the document, and if it does, takes action directed by aPermitUnloadFlags.
  77    * The result is returned.
  78    */
  79   boolean permitUnload([optional] in unsigned long aPermitUnloadFlags);
  80
  81   /**
  82    * Exposes whether we're blocked in a call to permitUnload.
  83    */
  84   readonly attribute boolean inPermitUnload;
  85
  86   /**
  87    * As above, but this passes around the aPermitUnloadFlags argument to keep
  88    * track of whether the user has responded to a prompt.
  89    * Used internally by the scriptable version to ensure we only prompt once.
  90    */
  91   [noscript,nostdcall] boolean permitUnloadInternal(inout unsigned long aPermitUnloadFlags);
  92
  93   /**
  94    * Exposes whether we're in the process of firing the beforeunload event.
  95    * In this case, the corresponding docshell will not allow navigation.
  96    */
  97   readonly attribute boolean beforeUnloadFiring;
  98
  99   void pageHide(in boolean isUnload);
 100
 101   /**
 102    * All users of a content viewer are responsible for calling both
 103    * close() and destroy(), in that order.
 104    *
 105    * close() should be called when the load of a new page for the next
 106    * content viewer begins, and destroy() should be called when the next
 107    * content viewer replaces this one.
 108    *
 109    * |historyEntry| sets the session history entry for the content viewer.  If
 110    * this is null, then Destroy() will be called on the document by close().
 111    * If it is non-null, the document will not be destroyed, and the following
 112    * actions will happen when destroy() is called (*):
 113    *  - Sanitize() will be called on the viewer's document
 114    *  - The content viewer will set the contentViewer property on the
 115    *    history entry, and release its reference (ownership reversal).
 116    *  - hide() will be called, and no further destruction will happen.
 117    *
 118    *  (*) unless the document is currently being printed, in which case
 119    *      it will never be saved in session history.
 120    *
 121    */
 122   void close(in nsISHEntry historyEntry);
 123   void destroy();
 124
 125   void stop();
 126
 127   /**
 128    * Returns the same thing as getDocument(), but for use from script
 129    * only.  C++ consumers should use getDocument().
 130    */
 131   readonly attribute Document DOMDocument;
 132
 133   /**
 134    * Returns DOMDocument without addrefing.
 135    */
 136   [noscript,notxpcom,nostdcall] Document getDocument();
 137
 138   /**
 139    * Allows setting the document.
 140    */
 141   [noscript,nostdcall] void setDocument(in Document aDocument);
 142
 143   [noscript] void getBounds(in nsIntRectRef aBounds);
 144   [noscript] void setBounds([const] in nsIntRectRef aBounds);
 145   /**
 146    * The 'aFlags' argument to setBoundsWithFlags is a set of these bits.
 147    */
 148   const unsigned long eDelayResize = 1;
 149   [noscript] void setBoundsWithFlags([const] in nsIntRectRef aBounds,
 150                                      in unsigned long aFlags);
 151
 152   /**
 153    * The previous content viewer, which has been |close|d but not
 154    * |destroy|ed.
 155    */
 156   [noscript] attribute nsIContentViewer previousViewer;
 157
 158   void move(in long aX, in long aY);
 159
 160   void show();
 161   void hide();
 162
 163   attribute boolean sticky;
 164
 165   /*
 166    * This is called when the DOM window wants to be closed.  Returns true
 167    * if the window can close immediately.  Otherwise, returns false and will
 168    * close the DOM window as soon as practical.
 169    */
 170
 171   boolean requestWindowClose();
 172
 173   /**
 174    * Attach the content viewer to its DOM window and docshell.
 175    * @param aState A state object that might be useful in attaching the DOM
 176    *               window.
 177    * @param aSHEntry The history entry that the content viewer was stored in.
 178    *                 The entry must have the docshells for all of the child
 179    *                 documents stored in its child shell list.
 180    */
 181   void open(in nsISupports aState, in nsISHEntry aSHEntry);
 182
 183   /**
 184    * Clears the current history entry.  This is used if we need to clear out
 185    * the saved presentation state.
 186    */
 187   void clearHistoryEntry();
 188
 189   /**
 190    * Change the layout to view the document with page layout (like print preview), but
 191    * dynamic and editable (like Galley layout).
 192    */
 193   void setPageMode(in boolean aPageMode, in nsIPrintSettings aPrintSettings);
 194
 195   /**
 196    * Get the history entry that this viewer will save itself into when
 197    * destroyed.  Can return null
 198    */
 199   readonly attribute nsISHEntry historyEntry;
 200
 201   /**
 202    * Indicates when we're in a state where content shouldn't be allowed to
 203    * trigger a tab-modal prompt (as opposed to a window-modal prompt) because
 204    * we're part way through some operation (eg beforeunload) that shouldn't be
 205    * rentrant if the user closes the tab while the prompt is showing.
 206    * See bug 613800.
 207    */
 208   readonly attribute boolean isTabModalPromptAllowed;
 209
 210   /**
 211    * Returns whether this content viewer is in a hidden state.
 212    *
 213    * @note Only Gecko internal code should set the attribute!
 214    */
 215   attribute boolean isHidden;
 216
 217   [noscript] readonly attribute nsIPresShellPtr presShell;
 218   [noscript] readonly attribute nsPresContextPtr presContext;
 219   // aDocument must not be null.
 220   [noscript] void setDocumentInternal(in Document aDocument,
 221                                       in boolean aForceReuseInnerWindow);
 222   /**
 223    * Find the view to use as the container view for MakeWindow. Returns
 224    * null if this will be the root of a view manager hierarchy. In that
 225    * case, if mParentWidget is null then this document should not even
 226    * be displayed.
 227    */
 228   [noscript,notxpcom,nostdcall] nsViewPtr findContainerView();
 229   /**
 230    * Set collector for navigation timing data (load, unload events).
 231    */
 232   [noscript,notxpcom,nostdcall] void setNavigationTiming(in nsDOMNavigationTimingPtr aTiming);
 233   /*
 234   Scrolls to a given DOM content node.
 235   */
 236   void scrollToNode(in Node node);
 237
 238   /** The amount by which to scale all text. Default is 1.0. */
 239   attribute float textZoom;
 240
 241   /** The actual text zoom in effect, as modified by the system font scale. */
 242   readonly attribute float effectiveTextZoom;
 243
 244   /** The amount by which to scale all lengths. Default is 1.0. */
 245   attribute float fullZoom;
 246
 247   /**
 248    * The actual full zoom in effect, as modified by the device context.
 249    * For a requested full zoom, the device context may choose a slightly
 250    * different effectiveFullZoom to accomodate integer rounding of app units
 251    * per dev pixel. This property returns the actual zoom amount in use,
 252    * though it may not be good user experience to report that a requested zoom
 253    * of 90% is actually 89.1%, for example. This value is provided primarily to
 254    * support media queries of dppx values, because those queries are matched
 255    * against the actual native device pixel ratio and the actual full zoom.
 256    */
 257   readonly attribute float deviceFullZoom;
 258
 259   /**
 260    * The value used to override devicePixelRatio and media queries dppx.
 261    * Default is 0.0, that means no overriding is done (only a positive value
 262    * is applied).
 263    */
 264   attribute float overrideDPPX;
 265
 266   /** Disable entire author style level (including HTML presentation hints) */
 267   attribute boolean authorStyleDisabled;
 268
 269   /**
 270    * XXX comm-central only: bug 829543. Not the Character Encoding menu in
 271    * browser!
 272    */
 273   attribute ACString forceCharacterSet;
 274
 275   /**
 276    * XXX comm-central only: bug 829543.
 277    */
 278   attribute ACString hintCharacterSet;
 279
 280   /**
 281    * XXX comm-central only: bug 829543.
 282    */
 283   attribute int32_t hintCharacterSetSource;
 284
 285   /**
 286    * Requests the size of the content to the container.
 287    */
 288   void getContentSize(out long width, out long height);
 289
 290   /**
 291    * Returns the preferred width and height of the content, constrained to the
 292    * given maximum values. If either maxWidth or maxHeight is less than zero,
 293    * that dimension is not constrained.
 294    *
 295    * All input and output values are in device pixels, rather than CSS pixels.
 296    */
 297   void getContentSizeConstrained(in long maxWidth, in long maxHeight,
 298                                  out long width, out long height);
 299
 300   /** The minimum font size  */
 301   attribute long minFontSize;
 302
 303   /**
 304    * Append |this| and all of its descendants to the given array,
 305    * in depth-first pre-order traversal.
 306    */
 307   [noscript] void appendSubtree(in nsIContentViewerTArray array);
 308
 309   /**
 310    * Instruct the refresh driver to discontinue painting until further
 311    * notice.
 312    */
 313   void pausePainting();
 314
 315   /**
 316    * Instruct the refresh driver to resume painting after a previous call to
 317    * pausePainting().
 318    */
 319   void resumePainting();
 320
 321   /*
 322    * Render the document as if being viewed on a device with the specified
 323    * media type. This will cause a reflow.
 324    *
 325    * @param mediaType The media type to be emulated
 326    */
 327   void emulateMedium(in AString aMediaType);
 328
 329   /*
 330    * Restore the viewer's natural media type
 331    */
 332   void stopEmulatingMedium();
 333
 334   [noscript, notxpcom] Encoding getHintCharset();
 335   [noscript, notxpcom] void setHintCharset(in Encoding aEncoding);
 336   [noscript, notxpcom] Encoding getForceCharset();
 337   [noscript, notxpcom] void setForceCharset(in Encoding aEncoding);
 338 };