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 nsIDocument;
   9 interface nsIDOMDocument;
  10 interface nsIDOMNode;
  11 interface nsISHEntry;
  12 interface nsIPrintSettings;
  13
  14
  15 %{ C++
  16 #include "nsTArray.h"
  17
  18 class nsIWidget;
  19 struct nsIntRect;
  20 class nsIPresShell;
  21 class nsPresContext;
  22 class nsView;
  23 class nsDOMNavigationTiming;
  24 %}
  25
  26 [ptr] native nsIWidgetPtr(nsIWidget);
  27 [ref] native nsIntRectRef(nsIntRect);
  28 [ptr] native nsIPresShellPtr(nsIPresShell);
  29 [ptr] native nsPresContextPtr(nsPresContext);
  30 [ptr] native nsViewPtr(nsView);
  31 [ptr] native nsDOMNavigationTimingPtr(nsDOMNavigationTiming);
  32 [ref] native nsIContentViewerTArray(nsTArray<nsCOMPtr<nsIContentViewer> >);
  33
  34 [scriptable, builtinclass, uuid(702e0a92-7d63-490e-b5ee-d247e6bd4588)]
  35 interface nsIContentViewer : nsISupports
  36 {
  37
  38   [noscript] void init(in nsIWidgetPtr aParentWidget,
  39                        [const] in nsIntRectRef aBounds);
  40
  41   attribute nsIDocShell container;
  42
  43   [noscript,notxpcom,nostdcall] void loadStart(in nsIDocument aDoc);
  44   void loadComplete(in nsresult aStatus);
  45
  46   /**
  47    * Checks if the document wants to prevent unloading by firing beforeunload on
  48    * the document, and if it does, prompts the user. The result is returned.
  49    *
  50    * @param aCallerClosesWindow indicates that the current caller will close the
  51    *        window. If the method returns true, all subsequent calls will be
  52    *        ignored.
  53    */
  54   boolean permitUnload([optional] in boolean aCallerClosesWindow);
  55
  56   /**
  57    * Exposes whether we're blocked in a call to permitUnload.
  58    */
  59   readonly attribute boolean inPermitUnload;
  60
  61   /**
  62    * As above, but this passes around the aShouldPrompt argument to keep
  63    * track of whether the user has responded to a prompt.
  64    * Used internally by the scriptable version to ensure we only prompt once.
  65    */
  66   [noscript,nostdcall] boolean permitUnloadInternal(in boolean aCallerClosesWindow,
  67                                                     inout boolean aShouldPrompt);
  68
  69   /**
  70    * Exposes whether we're in the process of firing the beforeunload event.
  71    * In this case, the corresponding docshell will not allow navigation.
  72    */
  73   readonly attribute boolean beforeUnloadFiring;
  74
  75   /**
  76    * Works in tandem with permitUnload, if the caller decides not to close the
  77    * window it indicated it will, it is the caller's responsibility to reset
  78    * that with this method.
  79    *
  80    * @Note this method is only meant to be called on documents for which the
  81    *  caller has indicated that it will close the window. If that is not the case
  82    *  the behavior of this method is undefined.
  83    */
  84   void resetCloseWindow();
  85   void pageHide(in boolean isUnload);
  86
  87   /**
  88    * All users of a content viewer are responsible for calling both
  89    * close() and destroy(), in that order.
  90    *
  91    * close() should be called when the load of a new page for the next
  92    * content viewer begins, and destroy() should be called when the next
  93    * content viewer replaces this one.
  94    *
  95    * |historyEntry| sets the session history entry for the content viewer.  If
  96    * this is null, then Destroy() will be called on the document by close().
  97    * If it is non-null, the document will not be destroyed, and the following
  98    * actions will happen when destroy() is called (*):
  99    *  - Sanitize() will be called on the viewer's document
 100    *  - The content viewer will set the contentViewer property on the
 101    *    history entry, and release its reference (ownership reversal).
 102    *  - hide() will be called, and no further destruction will happen.
 103    *
 104    *  (*) unless the document is currently being printed, in which case
 105    *      it will never be saved in session history.
 106    *
 107    */
 108   void close(in nsISHEntry historyEntry);
 109   void destroy();
 110
 111   void stop();
 112
 113   attribute nsIDOMDocument DOMDocument;
 114
 115   /**
 116    * Returns DOMDocument as nsIDocument and without addrefing.
 117    */
 118   [noscript,notxpcom] nsIDocument getDocument();
 119
 120   [noscript] void getBounds(in nsIntRectRef aBounds);
 121   [noscript] void setBounds([const] in nsIntRectRef aBounds);
 122
 123   /**
 124    * The previous content viewer, which has been |close|d but not
 125    * |destroy|ed.
 126    */
 127   [noscript] attribute nsIContentViewer previousViewer;
 128
 129   void move(in long aX, in long aY);
 130
 131   void show();
 132   void hide();
 133
 134   attribute boolean sticky;
 135
 136   /*
 137    * This is called when the DOM window wants to be closed.  Returns true
 138    * if the window can close immediately.  Otherwise, returns false and will
 139    * close the DOM window as soon as practical.
 140    */
 141
 142   boolean requestWindowClose();
 143
 144   /**
 145    * Attach the content viewer to its DOM window and docshell.
 146    * @param aState A state object that might be useful in attaching the DOM
 147    *               window.
 148    * @param aSHEntry The history entry that the content viewer was stored in.
 149    *                 The entry must have the docshells for all of the child
 150    *                 documents stored in its child shell list.
 151    */
 152   void open(in nsISupports aState, in nsISHEntry aSHEntry);
 153
 154   /**
 155    * Clears the current history entry.  This is used if we need to clear out
 156    * the saved presentation state.
 157    */
 158   void clearHistoryEntry();
 159
 160   /**
 161    * Change the layout to view the document with page layout (like print preview), but
 162    * dynamic and editable (like Galley layout).
 163    */
 164   void setPageMode(in boolean aPageMode, in nsIPrintSettings aPrintSettings);
 165
 166   /**
 167    * Get the history entry that this viewer will save itself into when
 168    * destroyed.  Can return null
 169    */
 170   readonly attribute nsISHEntry historyEntry;
 171
 172   /**
 173    * Indicates when we're in a state where content shouldn't be allowed to
 174    * trigger a tab-modal prompt (as opposed to a window-modal prompt) because
 175    * we're part way through some operation (eg beforeunload) that shouldn't be
 176    * rentrant if the user closes the tab while the prompt is showing.
 177    * See bug 613800.
 178    */
 179   readonly attribute boolean isTabModalPromptAllowed;
 180
 181   /**
 182    * Returns whether this content viewer is in a hidden state.
 183    *
 184    * @note Only Gecko internal code should set the attribute!
 185    */
 186   attribute boolean isHidden;
 187
 188   [noscript] readonly attribute nsIPresShellPtr presShell;
 189   [noscript] readonly attribute nsPresContextPtr presContext;
 190   // aDocument must not be null.
 191   [noscript] void setDocumentInternal(in nsIDocument aDocument,
 192                                       in boolean aForceReuseInnerWindow);
 193   /**
 194    * Find the view to use as the container view for MakeWindow. Returns
 195    * null if this will be the root of a view manager hierarchy. In that
 196    * case, if mParentWidget is null then this document should not even
 197    * be displayed.
 198    */
 199   [noscript,notxpcom,nostdcall] nsViewPtr findContainerView();
 200   /**
 201    * Set collector for navigation timing data (load, unload events).
 202    */
 203   [noscript,notxpcom,nostdcall] void setNavigationTiming(in nsDOMNavigationTimingPtr aTiming);
 204   /*
 205   Scrolls to a given DOM content node.
 206   */
 207   void scrollToNode(in nsIDOMNode node);
 208
 209   /** The amount by which to scale all text. Default is 1.0. */
 210   attribute float textZoom;
 211
 212   /** The amount by which to scale all lengths. Default is 1.0. */
 213   attribute float fullZoom;
 214
 215   /** Disable entire author style level (including HTML presentation hints) */
 216   attribute boolean authorStyleDisabled;
 217
 218   /**
 219    * XXX comm-central only: bug 829543. Not the Character Encoding menu in
 220      * browser!
 221    */
 222   attribute ACString forceCharacterSet;
 223
 224   /**
 225    * XXX comm-central only: bug 829543.
 226    */
 227   attribute ACString hintCharacterSet;
 228
 229   /**
 230    * XXX comm-central only: bug 829543.
 231    */
 232   attribute int32_t hintCharacterSetSource;
 233
 234   /**
 235    * Requests the size of the content to the container.
 236    */
 237   void getContentSize(out long width, out long height);
 238
 239   /** The minimum font size  */
 240   attribute long minFontSize;
 241
 242   /**
 243    * Append |this| and all of its descendants to the given array,
 244    * in depth-first pre-order traversal.
 245    */
 246   [noscript] void appendSubtree(in nsIContentViewerTArray array);
 247
 248   /**
 249    * Set the maximum line width for the document.
 250    * NOTE: This will generate a reflow!
 251    *
 252    * @param maxLineWidth The maximum width of any line boxes on the page,
 253    *        in CSS pixels.
 254    */
 255   void changeMaxLineBoxWidth(in int32_t maxLineBoxWidth);
 256
 257   /**
 258    * Instruct the refresh driver to discontinue painting until further
 259    * notice.
 260    */
 261   void pausePainting();
 262
 263   /**
 264    * Instruct the refresh driver to resume painting after a previous call to
 265    * pausePainting().
 266    */
 267   void resumePainting();
 268
 269   /*
 270    * Render the document as if being viewed on a device with the specified
 271    * media type. This will cause a reflow.
 272    *
 273    * @param mediaType The media type to be emulated
 274    */
 275   void emulateMedium(in AString aMediaType);
 276
 277   /*
 278    * Restore the viewer's natural media type
 279    */
 280   void stopEmulatingMedium();
 281 };