docshell/base/nsIDocShell.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "domstubs.idl"
   8 #include "nsIDocShellTreeItem.idl"
   9 #include "nsIRequest.idl"
  10
  11 %{ C++
  12 #include "js/TypeDecls.h"
  13 #include "mozilla/Maybe.h"
  14 #include "mozilla/NotNull.h"
  15 #include "mozilla/UniquePtr.h"
  16 #include "nsCOMPtr.h"
  17 #include "nsIURI.h"
  18 class nsCommandManager;
  19 class nsPresContext;
  20 class nsDocShellLoadState;
  21 namespace mozilla {
  22 class Encoding;
  23 class HTMLEditor;
  24 class PresShell;
  25 namespace dom {
  26 class BrowsingContext;
  27 class ClientSource;
  28 } // namespace dom
  29 }
  30 %}
  31
  32 /**
  33  * The nsIDocShell interface.
  34  */
  35
  36 [ptr] native nsPresContext(nsPresContext);
  37 [ptr] native nsCommandManager(nsCommandManager);
  38 [ptr] native PresShell(mozilla::PresShell);
  39 [ref] native MaybeURI(mozilla::Maybe<nsCOMPtr<nsIURI>>);
  40 [ref] native Encoding(const mozilla::Encoding*);
  41       native UniqueClientSource(mozilla::UniquePtr<mozilla::dom::ClientSource>);
  42
  43 interface nsIURI;
  44 interface nsIChannel;
  45 interface nsIContentSecurityPolicy;
  46 interface nsIDocumentViewer;
  47 interface nsIEditor;
  48 interface nsIEditingSession;
  49 interface nsIInputStream;
  50 interface nsIRequest;
  51 interface nsISHEntry;
  52 interface nsILayoutHistoryState;
  53 interface nsISecureBrowserUI;
  54 interface nsIScriptGlobalObject;
  55 interface nsIStructuredCloneContainer;
  56 interface nsIDOMStorage;
  57 interface nsIPrincipal;
  58 interface nsIPrivacyTransitionObserver;
  59 interface nsIReflowObserver;
  60 interface nsIScrollObserver;
  61 interface nsIRemoteTab;
  62 interface nsIBrowserChild;
  63 interface nsICommandParams;
  64 interface nsILoadURIDelegate;
  65 native BrowserChildRef(already_AddRefed<nsIBrowserChild>);
  66 native nsDocShellLoadStatePtr(nsDocShellLoadState*);
  67
  68 webidl BrowsingContext;
  69 webidl ContentFrameMessageManager;
  70 webidl EventTarget;
  71 webidl Document;
  72
  73 /**
  74  * nsIDocShell is an interface corresponding to the native nsDocShell object,
  75  * which is a legacy in-process object roughly corresponding to a 'browsing
  76  * context', as created for a browser tab or an iframe, for example.
  77  *
  78  * nsIDocShell has a 1:1 relationship with its paired dom::BrowsingContext and
  79  * nsGlobalWindowOuter. It may be replaced during navigation.
  80  *
  81  * See also the comment documenting dom::BrowsingContext and the documentation
  82  * at:
  83  *
  84  * https://html.spec.whatwg.org/multipage/document-sequences.html#browsing-context
  85  * https://firefox-source-docs.mozilla.org/dom/navigation/embedding.html
  86  * https://firefox-source-docs.mozilla.org/dom/navigation/nav_replace.html
  87  */
  88 [scriptable, builtinclass, uuid(049234fe-da10-478b-bc5d-bc6f9a1ba63d)]
  89 interface nsIDocShell : nsIDocShellTreeItem
  90 {
  91   void setCancelContentJSEpoch(in long aEpoch);
  92
  93   /**
  94    * Loads a given URI.  This will give priority to loading the requested URI
  95    * in the object implementing this interface.  If it can't be loaded here
  96    * however, the URL dispatcher will go through its normal process of content
  97    * loading.
  98    *
  99    * @param aLoadState This is the extended load info for this load.
 100    * @param aSetNavigating If we should set isNavigating to true while initiating
 101    *                       the load.
 102    */
 103   [noscript]void loadURI(in nsDocShellLoadStatePtr aLoadState, in boolean aSetNavigating);
 104
 105   /**
 106    * Do either a history.pushState() or history.replaceState() operation,
 107    * depending on the value of aReplace.
 108    */
 109   [implicit_jscontext]
 110   void addState(in jsval aData, in AString aTitle,
 111                 in AString aURL, in boolean aReplace);
 112
 113   /**
 114    * Reset state to a new content model within the current document and the document
 115    * viewer.  Called by the document before initiating an out of band document.write().
 116    */
 117   void prepareForNewContentModel();
 118
 119   /**
 120    * Helper for the session store to change the URI associated with the
 121    * document.
 122    */
 123   void setCurrentURIForSessionStore(in nsIURI aURI);
 124
 125   /**
 126    * Notify the associated content viewer and all child docshells that they are
 127    * about to be hidden.  If |isUnload| is true, then the document is being
 128    * unloaded and all dynamic subframe history entries are removed as well.
 129    *
 130    * @param isUnload
 131    *        True to fire the unload event in addition to the pagehide event,
 132    *        and remove all dynamic subframe history entries.
 133    */
 134   [noscript] void firePageHideNotification(in boolean isUnload);
 135
 136   /**
 137    * Presentation context for the currently loaded document.  This may be null.
 138    */
 139   [notxpcom,nostdcall] readonly attribute nsPresContext presContext;
 140
 141   /**
 142    * Presentation shell for the currently loaded document.  This may be null.
 143    */
 144   [notxpcom,nostdcall] readonly attribute PresShell presShell;
 145
 146   /**
 147    * Presentation shell for the oldest document, if this docshell is
 148    * currently transitioning between documents.
 149    */
 150   [notxpcom,nostdcall] readonly attribute PresShell eldestPresShell;
 151
 152   /**
 153    * Document Viewer that is currently loaded for this DocShell.  This may
 154    * change as the underlying content changes.
 155    */
 156   [infallible] readonly attribute nsIDocumentViewer docViewer;
 157
 158   /**
 159    * Get the id of the outer window that is or will be in this docshell.
 160    */
 161   [infallible] readonly attribute unsigned long long outerWindowID;
 162
 163   /**
 164    * This attribute allows chrome to tie in to handle DOM events that may
 165    * be of interest to chrome.
 166    */
 167   attribute EventTarget chromeEventHandler;
 168
 169   /**
 170    * This allows chrome to set a custom User agent on a specific docshell
 171    */
 172   attribute AString customUserAgent;
 173
 174   /**
 175    * Whether CSS error reporting is enabled.
 176    */
 177   attribute boolean cssErrorReportingEnabled;
 178
 179   /**
 180    * Attribute stating if refresh based redirects can be allowed
 181    */
 182   attribute boolean allowMetaRedirects;
 183
 184   /**
 185    * Attribute stating if it should allow subframes (framesets/iframes) or not
 186    */
 187   attribute boolean allowSubframes;
 188
 189   /**
 190    * Attribute stating whether or not images should be loaded.
 191    */
 192   attribute boolean allowImages;
 193
 194   /**
 195    * Attribute stating whether or not media (audio/video) should be loaded.
 196    */
 197   [infallible] attribute boolean allowMedia;
 198
 199   /**
 200    * Attribute that determines whether DNS prefetch is allowed for this subtree
 201    * of the docshell tree.  Defaults to true.  Setting this will make it take
 202    * effect starting with the next document loaded in the docshell.
 203    */
 204   attribute boolean allowDNSPrefetch;
 205
 206   /**
 207    * Attribute that determines whether window control (move/resize) is allowed.
 208    */
 209   attribute boolean allowWindowControl;
 210
 211   /**
 212    * True if the docshell allows its content to be handled by a content listener
 213    * other than the docshell itself, including the external helper app service,
 214    * and false otherwise.  Defaults to true.
 215    */
 216   [infallible] attribute boolean allowContentRetargeting;
 217
 218   /**
 219    * True if new child docshells should allow content retargeting.
 220    * Setting allowContentRetargeting also overwrites this value.
 221    */
 222   [infallible] attribute boolean allowContentRetargetingOnChildren;
 223
 224   /**
 225    * Get an array of this docShell and its children.
 226    *
 227    * @param aItemType  - Only include docShells of this type, or if typeAll,
 228    *                     include all child shells.
 229    *                     Uses types from nsIDocShellTreeItem.
 230    * @param aDirection - Whether to enumerate forwards or backwards.
 231    */
 232
 233   cenum DocShellEnumeratorDirection : 8 {
 234     ENUMERATE_FORWARDS  = 0,
 235     ENUMERATE_BACKWARDS = 1
 236   };
 237
 238   Array<nsIDocShell> getAllDocShellsInSubtree(in long aItemType,
 239                                               in nsIDocShell_DocShellEnumeratorDirection aDirection);
 240
 241   /**
 242    * The type of application that created this window.
 243    *
 244    * DO NOT DELETE, see bug 176166. For firefox, this value will always be
 245    * UNKNOWN. However, it is used heavily in Thunderbird/comm-central and we
 246    * don't really have a great replacement at the moment, so we'll just leave it
 247    * here.
 248    */
 249   cenum AppType : 8 {
 250     APP_TYPE_UNKNOWN = 0,
 251     APP_TYPE_MAIL    = 1,
 252     APP_TYPE_EDITOR  = 2
 253   };
 254
 255   [infallible] attribute nsIDocShell_AppType appType;
 256
 257   /**
 258    * certain docshells (like the message pane)
 259    * should not throw up auth dialogs
 260    * because it can act as a password trojan
 261    */
 262   attribute boolean allowAuth;
 263
 264   /**
 265    * Set/Get the document scale factor.  When setting this attribute, a
 266    * NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
 267    * not supporting zoom.  Implementations not supporting zoom should return
 268    * 1.0 all the time for the Get operation.  1.0 by the way is the default
 269    * of zoom.  This means 100% of normal scaling or in other words normal size
 270    * no zoom.
 271    */
 272   attribute float zoom;
 273
 274   /*
 275    * Tells the docshell to offer focus to its tree owner.
 276    * This is currently only necessary for embedding chrome.
 277    * If forDocumentNavigation is true, then document navigation should be
 278    * performed, where only the root of documents are selected. Otherwise, the
 279    * next element in the parent should be returned. Returns true if focus was
 280    * successfully taken by the tree owner.
 281    */
 282   boolean tabToTreeOwner(in boolean forward, in boolean forDocumentNavigation);
 283
 284   /**
 285    * Current busy state for DocShell
 286    */
 287   cenum BusyFlags : 8 {
 288     BUSY_FLAGS_NONE             = 0,
 289     BUSY_FLAGS_BUSY             = 1,
 290     BUSY_FLAGS_BEFORE_PAGE_LOAD = 2,
 291     BUSY_FLAGS_PAGE_LOADING     = 4,
 292   };
 293
 294   [infallible] readonly attribute nsIDocShell_BusyFlags busyFlags;
 295
 296   /**
 297    * Load commands for the document
 298    */
 299   cenum LoadCommand : 8 {
 300     LOAD_CMD_NORMAL  = 0x1,   // Normal load
 301     LOAD_CMD_RELOAD  = 0x2,   // Reload
 302     LOAD_CMD_HISTORY = 0x4,   // Load from history
 303     LOAD_CMD_PUSHSTATE = 0x8, // History.pushState()
 304   };
 305
 306   /*
 307    * Attribute to access the loadtype for the document. LoadType Enum is
 308    * defined in nsDocShellLoadTypes.h
 309    */
 310   [infallible] attribute unsigned long loadType;
 311
 312   /*
 313    * Default load flags (as defined in nsIRequest) that will be set on all
 314    * requests made by this docShell and propagated to all child docShells and
 315    * to nsILoadGroup::defaultLoadFlags for the docShell's loadGroup.
 316    * Default is no flags.  Once set, only future requests initiated by the
 317    * docShell are affected, so in general, these flags should be set before
 318    * the docShell loads any content.
 319    */
 320   attribute nsLoadFlags defaultLoadFlags;
 321
 322   /*
 323    * returns true if the docshell is being destroyed, false otherwise
 324    */
 325   boolean isBeingDestroyed();
 326
 327   /*
 328    * Returns true if the docshell is currently executing the onLoad Handler
 329    */
 330   readonly attribute boolean isExecutingOnLoadHandler;
 331
 332   attribute nsILayoutHistoryState layoutHistoryState;
 333
 334   /**
 335    * Object used to delegate URI loading to an upper context.
 336    * Currently only set for GeckoView to allow handling of load requests
 337    * at the application level.
 338    */
 339   readonly attribute nsILoadURIDelegate loadURIDelegate;
 340
 341   /**
 342    * Cancel the XPCOM timers for each meta-refresh URI in this docshell,
 343    * and this docshell's children, recursively. The meta-refresh timers can be
 344    * restarted using resumeRefreshURIs().  If the timers are already suspended,
 345    * this has no effect.
 346    */
 347   void suspendRefreshURIs();
 348
 349   /**
 350    * Restart the XPCOM timers for each meta-refresh URI in this docshell,
 351    * and this docshell's children, recursively.  If the timers are already
 352    * running, this has no effect.
 353    */
 354   void resumeRefreshURIs();
 355
 356   /**
 357    * Begin firing WebProgressListener notifications for restoring a page
 358    * presentation. |viewer| is the content viewer whose document we are
 359    * starting to load.  If null, it defaults to the docshell's current content
 360    * viewer, creating one if necessary.  |top| should be true for the toplevel
 361    * docshell that is being restored; it will be set to false when this method
 362    * is called for child docshells.  This method will post an event to
 363    * complete the simulated load after returning to the event loop.
 364    */
 365   void beginRestore(in nsIDocumentViewer viewer, in boolean top);
 366
 367   /**
 368    * Finish firing WebProgressListener notifications and DOM events for
 369    * restoring a page presentation.  This should only be called via
 370    * beginRestore().
 371    */
 372   void finishRestore();
 373
 374   void clearCachedUserAgent();
 375
 376   void clearCachedPlatform();
 377
 378   /* Track whether we're currently restoring a document presentation. */
 379   readonly attribute boolean restoringDocument;
 380
 381   /* attribute to access whether error pages are enabled */
 382   attribute boolean useErrorPages;
 383
 384   /**
 385    * Display a load error in a frame while keeping that frame's currentURI
 386    * pointing correctly to the page where the error ocurred, rather than to
 387    * the error document page. You must provide either the aURI or aURL parameter.
 388    *
 389    * @param  aError         The error code to be displayed
 390    * @param  aURI           nsIURI of the page where the error happened
 391    * @param  aURL           wstring of the page where the error happened
 392    * @param  aFailedChannel The channel related to this error
 393    *
 394    * Returns whether or not we displayed an error page (note: will always
 395    * return false if in-content error pages are disabled!)
 396    */
 397   boolean displayLoadError(in nsresult aError,
 398                            in nsIURI aURI,
 399                            in wstring aURL,
 400                            [optional] in nsIChannel aFailedChannel);
 401
 402   /**
 403    * The channel that failed to load and resulted in an error page.
 404    * May be null. Relevant only to error pages.
 405    */
 406   readonly attribute nsIChannel failedChannel;
 407
 408   /**
 409    * Keeps track of the previous nsISHEntry index and the current
 410    * nsISHEntry index at the time that the doc shell begins to load.
 411    * Used for ContentViewer eviction.
 412    */
 413   readonly attribute long previousEntryIndex;
 414   readonly attribute long loadedEntryIndex;
 415
 416   /**
 417    * Notification that entries have been removed from the beginning of a
 418    * nsSHistory which has this as its rootDocShell.
 419    *
 420    * @param numEntries - The number of entries removed
 421    */
 422   void historyPurged(in long numEntries);
 423
 424   /**
 425    * Gets the channel for the currently loaded document, if any.
 426    * For a new document load, this will be the channel of the previous document
 427    * until after OnLocationChange fires.
 428    */
 429   readonly attribute nsIChannel currentDocumentChannel;
 430
 431   /**
 432    * Find out whether the docshell is currently in the middle of a page
 433    * transition. This is set just before the pagehide/unload events fire.
 434    */
 435   [infallible] readonly attribute boolean isInUnload;
 436
 437   /**
 438    * Disconnects this docshell's editor from its window, and stores the
 439    * editor data in the open document's session history entry.  This
 440    * should be called only during page transitions.
 441    */
 442   [noscript, notxpcom] void DetachEditorFromWindow();
 443
 444   /**
 445    * Propagated to the print preview document viewer.  Must only be called on
 446    * a document viewer that has been initialized for print preview.
 447    */
 448   void exitPrintPreview();
 449
 450   /**
 451    * The ID of the docshell in the session history.
 452    */
 453   readonly attribute nsIDRef historyID;
 454
 455   /**
 456    * Helper method for accessing this value from C++
 457    */
 458   [noscript, notxpcom] nsIDRef HistoryID();
 459
 460   /**
 461    * Create a new about:blank document and content viewer.
 462    * @param aPrincipal the principal to use for the new document.
 463    * @param aPartitionedPrincipal the partitioned principal to use for the new
 464    *        document.
 465    * @param aCsp the CSP to use for the new document.
 466    */
 467   void createAboutBlankDocumentViewer(in nsIPrincipal aPrincipal,
 468                                      in nsIPrincipal aPartitionedPrincipal,
 469                                      [optional] in nsIContentSecurityPolicy aCSP);
 470
 471   /**
 472    * Upon getting, returns the canonical encoding label of the document
 473    * currently loaded into this docshell.
 474    */
 475   readonly attribute ACString charset;
 476
 477   void forceEncodingDetection();
 478
 479   /**
 480    * In a child docshell, this is the charset of the parent docshell
 481    */
 482   [noscript, notxpcom, nostdcall] void setParentCharset(
 483     in Encoding parentCharset,
 484     in int32_t parentCharsetSource,
 485     in nsIPrincipal parentCharsetPrincipal);
 486   [noscript, notxpcom, nostdcall] void getParentCharset(
 487     out Encoding parentCharset,
 488     out int32_t parentCharsetSource,
 489     out nsIPrincipal parentCharsetPrincipal);
 490
 491   /**
 492    * Return a DOMHighResTimeStamp representing the number of
 493    * milliseconds from an arbitrary point in time.  The reference
 494    * point is shared by all DocShells and is also used by timestamps
 495    * on markers.
 496    */
 497   DOMHighResTimeStamp now();
 498
 499   /**
 500    * Add an observer to the list of parties to be notified when this docshell's
 501    * private browsing status is changed. |obs| must support weak references.
 502    */
 503   void addWeakPrivacyTransitionObserver(in nsIPrivacyTransitionObserver obs);
 504
 505   /**
 506    * Add an observer to the list of parties to be notified when reflows are
 507    * occurring. |obs| must support weak references.
 508    */
 509   void addWeakReflowObserver(in nsIReflowObserver obs);
 510
 511   /**
 512    * Remove an observer from the list of parties to be notified about reflows.
 513    */
 514   void removeWeakReflowObserver(in nsIReflowObserver obs);
 515
 516   /**
 517    * Notify all attached observers that a reflow has just occurred.
 518    *
 519    * @param interruptible if true, the reflow was interruptible.
 520    * @param start         timestamp when reflow started, in milliseconds since
 521    *                      navigationStart (accurate to 1/1000 of a ms)
 522    * @param end           timestamp when reflow ended, in milliseconds since
 523    *                      navigationStart (accurate to 1/1000 of a ms)
 524    */
 525   [noscript] void notifyReflowObservers(in boolean interruptible,
 526                                         in DOMHighResTimeStamp start,
 527                                         in DOMHighResTimeStamp end);
 528
 529   /**
 530    * Add an observer to the list of parties to be notified when scroll position
 531    * of some elements is changed.
 532    */
 533   [noscript] void addWeakScrollObserver(in nsIScrollObserver obs);
 534
 535   /**
 536    * Add an observer to the list of parties to be notified when scroll position
 537    * of some elements is changed.
 538    */
 539   [noscript] void removeWeakScrollObserver(in nsIScrollObserver obs);
 540
 541   /**
 542    * Notify all attached observers that the scroll position of some element
 543    * has changed.
 544    */
 545   [noscript] void notifyScrollObservers();
 546
 547   /**
 548    * Returns true if this docshell is the top level content docshell.
 549    */
 550   [infallible] readonly attribute boolean isTopLevelContentDocShell;
 551
 552   /**
 553    * True iff asynchronous panning and zooming is enabled for this
 554    * docshell.
 555    */
 556   readonly attribute boolean asyncPanZoomEnabled;
 557
 558   /**
 559    * Indicates whether the UI may enable the character encoding menu. The UI
 560    * must disable the menu when this property is false.
 561    */
 562   [infallible] readonly attribute boolean mayEnableCharacterEncodingMenu;
 563
 564            attribute  nsIEditor editor;
 565   readonly attribute  boolean   editable;             /* this docShell is editable */
 566   readonly attribute  boolean   hasEditingSession;    /* this docShell has an editing session */
 567
 568   /**
 569    * Make this docShell editable, setting a flag that causes
 570    * an editor to get created, either immediately, or after
 571    * a url has been loaded.
 572    *      @param  inWaitForUriLoad    true to wait for a URI before
 573    *                                  creating the editor.
 574    */
 575   void makeEditable(in boolean inWaitForUriLoad);
 576
 577   /**
 578    * Returns false for mLSHE, true for mOSHE
 579    */
 580   boolean getCurrentSHEntry(out nsISHEntry aEntry);
 581
 582   /**
 583     * Cherry picked parts of nsIController.
 584     * They are here, because we want to call these functions
 585     * from JS.
 586     */
 587   boolean isCommandEnabled(in string command);
 588   [can_run_script]
 589   void doCommand(in string command);
 590   [can_run_script]
 591   void doCommandWithParams(in string command, in nsICommandParams aParams);
 592
 593   /**
 594    * Invisible DocShell are dummy construct to simulate DOM windows
 595    * without any actual visual representation. They have to be marked
 596    * at construction time, to avoid any painting activity.
 597    */
 598   [noscript, notxpcom] boolean IsInvisible();
 599   [noscript, notxpcom] void SetInvisible(in boolean aIsInvisibleDocshell);
 600
 601 /**
 602  * Get the script global for the document in this docshell.
 603 */
 604   [noscript,notxpcom,nostdcall] nsIScriptGlobalObject GetScriptGlobalObject();
 605
 606   [noscript,notxpcom,nostdcall] Document getExtantDocument();
 607
 608   /**
 609    * This attribute determines whether a document which is not about:blank has
 610    * already be loaded by this docShell.
 611    */
 612   [infallible] readonly attribute boolean hasLoadedNonBlankURI;
 613
 614   /**
 615    * Allow usage of -moz-window-dragging:drag for content docshells.
 616    * True for top level chrome docshells. Throws if set to false with
 617    * top level chrome docshell.
 618    */
 619   attribute boolean windowDraggingAllowed;
 620
 621   /**
 622    * Sets/gets the current scroll restoration mode.
 623    * @see https://html.spec.whatwg.org/#dom-history-scroll-restoration
 624    */
 625   attribute boolean currentScrollRestorationIsManual;
 626
 627   /**
 628    * Setter and getter for the origin attributes living on this docshell.
 629    */
 630   [implicit_jscontext]
 631   jsval getOriginAttributes();
 632
 633   [implicit_jscontext]
 634   void setOriginAttributes(in jsval aAttrs);
 635
 636   /**
 637    * The editing session for this docshell.
 638    */
 639   readonly attribute nsIEditingSession editingSession;
 640
 641   /**
 642    * The browser child for this docshell.
 643    */
 644   [binaryname(ScriptableBrowserChild)] readonly attribute nsIBrowserChild browserChild;
 645   [noscript,notxpcom,nostdcall] BrowserChildRef GetBrowserChild();
 646
 647   [noscript,nostdcall,notxpcom] nsCommandManager GetCommandManager();
 648
 649   /**
 650    * Attribute that determines whether tracking protection is enabled.
 651    */
 652   attribute boolean useTrackingProtection;
 653
 654  /**
 655   * Fire a dummy location change event asynchronously.
 656   */
 657   [noscript] void dispatchLocationChangeEvent();
 658
 659
 660   /**
 661    * Start delayed autoplay media which are in the current document.
 662    */
 663   [noscript] void startDelayedAutoplayMediaComponents();
 664
 665   /**
 666    * Take ownership of the ClientSource representing an initial about:blank
 667    * document that was never needed.  As an optimization we avoid creating
 668    * this document if no code calls GetDocument(), but we still need a
 669    * ClientSource object to represent the about:blank window.  This may return
 670    * nullptr; for example if the docshell has created a real window and document
 671    * already.
 672    */
 673   [noscript, nostdcall, notxpcom]
 674   UniqueClientSource TakeInitialClientSource();
 675
 676   void setColorMatrix(in Array<float> aMatrix);
 677
 678   /**
 679    * Returns true if the current load is a forced reload,
 680    * e.g. started by holding shift whilst triggering reload.
 681    */
 682   readonly attribute boolean isForceReloading;
 683
 684   Array<float> getColorMatrix();
 685
 686 %{C++
 687   /**
 688    * These methods call nsDocShell::GetHTMLEditorInternal() and
 689    * nsDocShell::SetHTMLEditorInternal() with static_cast.
 690    */
 691   mozilla::HTMLEditor* GetHTMLEditor();
 692   nsresult SetHTMLEditor(mozilla::HTMLEditor* aHTMLEditor);
 693 %}
 694
 695   /**
 696    * The message manager for this docshell.  This does not throw, but
 697    * can return null if the docshell has no message manager.
 698    */
 699   [infallible] readonly attribute ContentFrameMessageManager messageManager;
 700
 701    /**
 702    * This returns a Promise which resolves to a boolean. True when the
 703    * document has Tracking Content that has been blocked from loading, false
 704    * otherwise.
 705    */
 706   Promise getHasTrackingContentBlocked();
 707
 708   /**
 709    * Return whether this docshell is "attempting to navigate" in the
 710    * sense that's relevant to document.open.
 711    */
 712   [notxpcom, nostdcall] readonly attribute boolean isAttemptingToNavigate;
 713
 714   /*
 715    * Whether or not this docshell is executing a nsIWebNavigation navigation
 716    * method.
 717    *
 718    * This will be true when the following methods are executing:
 719    *   nsIWebNavigation.binaryLoadURI
 720    *   nsIWebNavigation.goBack
 721    *   nsIWebNavigation.goForward
 722    *   nsIWebNavigation.gotoIndex
 723    *   nsIWebNavigation.loadURI
 724    */
 725   [infallible] readonly attribute boolean isNavigating;
 726
 727   /**
 728    * @see nsISHEntry synchronizeLayoutHistoryState().
 729    */
 730   void synchronizeLayoutHistoryState();
 731
 732   /**
 733    * This attempts to save any applicable layout history state (like
 734    * scroll position) in the nsISHEntry. This is normally done
 735    * automatically when transitioning from page to page in the
 736    * same process. We expose this function to support transitioning
 737    * from page to page across processes as a workaround for bug 1630234
 738    * until session history state is moved into the parent process.
 739    */
 740   void persistLayoutHistoryState();
 741 };