gecko-dev/docshell/base/nsIContentViewer.idl

/* 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 "nsTArray.h"
#include "nsRect.h"

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

[ptr] native nsIWidgetPtr(nsIWidget);
[ref] native nsIntRectRef(nsIntRect);
[ptr] native nsPresContextPtr(nsPresContext);
[ptr] native nsViewPtr(nsView);
[ptr] native nsDOMNavigationTimingPtr(nsDOMNavigationTiming);
[ref] native nsIContentViewerTArray(nsTArray<nsCOMPtr<nsIContentViewer> >);
[ptr] native Encoding(const mozilla::Encoding);
[ptr] native PresShellPtr(mozilla::PresShell);
[ptr] native WindowGlobalChildPtr(mozilla::dom::WindowGlobalChild);

[scriptable, builtinclass, uuid(2da17016-7851-4a45-a7a8-00b360e01595)]
interface nsIContentViewer : 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;

  /**
   * aPermitUnloadFlags are passed to PermitUnload to indicate what action to take
   * if a beforeunload handler wants to prompt the user.  It is also used by
   * permitUnloadInternal to ensure we only prompt once.
   *
   * 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.
   */
  const unsigned long ePrompt = 0;
  const unsigned long eDontPromptAndDontUnload = 1;
  const unsigned long eDontPromptAndUnload = 2;

  /**
   * 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, and if it does, takes action directed by aPermitUnloadFlags.
   * The result is returned.
   */
  boolean permitUnload([optional] in unsigned long aPermitUnloadFlags);

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

  /**
   * As above, but this passes around the aPermitUnloadFlags argument to keep
   * track of whether the user has responded to a prompt.
   * Used internally by the scriptable version to ensure we only prompt once.
   */
  [noscript,nostdcall] boolean permitUnloadInternal(inout unsigned long aPermitUnloadFlags);

  /**
   * 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;

  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 nsIContentViewer previousViewer;

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

  void show();
  void hide();

  attribute boolean sticky;

  /*
   * This is called when the DOM window wants to be closed.  Returns true
   * if the window can close immediately.  Otherwise, returns false and will
   * close the DOM window as soon as practical.
   */

  boolean requestWindowClose(in boolean isPrintPending);

  /**
   * 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);

  /**
   * 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;

  /**
   * The value used to override devicePixelRatio and media queries dppx.
   * Default is 0.0, that means no overriding is done (only a positive value
   * is applied).
   */
  attribute float overrideDPPX;

  /** Disable entire author style level (including HTML presentation hints) */
  attribute boolean authorStyleDisabled;

  /**
   * XXX comm-central only: bug 829543.
   */
  attribute ACString hintCharacterSet;

  /**
   * XXX comm-central only: bug 829543.
   */
  attribute int32_t hintCharacterSetSource;

  /**
   * Requests the size of the content to the container.
   */
  void getContentSize(out long width, out long height);

  /**
   * Returns the preferred width and height of the content, constrained to the
   * given maximum values. If either maxWidth or maxHeight is less than zero,
   * that dimension is not constrained.
   *
   * All input and output values are in device pixels, rather than CSS pixels.
   */
  void getContentSizeConstrained(in long maxWidth, in long maxHeight,
                                 out long width, out long height);

  /**
   * Append |this| and all of its descendants to the given array,
   * in depth-first pre-order traversal.
   */
  [noscript] void appendSubtree(in nsIContentViewerTArray array);

  /**
   * Instruct the refresh driver to discontinue painting until further
   * notice.
   */
  void pausePainting();

  /**
   * Instruct the refresh driver to resume painting after a previous call to
   * pausePainting().
   */
  void resumePainting();

  /*
   * Render the document as if being viewed on a device with the specified
   * media type. This will cause a reflow.
   *
   * @param mediaType The media type to be emulated
   */
  void emulateMedium(in AString aMediaType);

  /*
   * Restore the viewer's natural media type
   */
  void stopEmulatingMedium();

  cenum PrefersColorScheme : 8 {
    PREFERS_COLOR_SCHEME_LIGHT,
    PREFERS_COLOR_SCHEME_DARK,
    PREFERS_COLOR_SCHEME_NONE, /* This clears the override. */
  };

  /*
   * Emulate or stop emulating the prefers color scheme on this page and
   * subdocuments.
   */
  void emulatePrefersColorScheme(in nsIContentViewer_PrefersColorScheme aPrefersColorScheme);

  [noscript, notxpcom] Encoding getHintCharset();
  [noscript, notxpcom] void setHintCharset(in Encoding aEncoding);
};