gecko-dev/toolkit/components/windowwatcher/nsPIWindowWatcher.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * 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/. */

/* Private "control" methods on the Window Watcher. These are annoying
   bookkeeping methods, not part of the public (embedding) interface.
*/

#include "nsISupports.idl"

%{ C++
#include "mozilla/dom/UserActivation.h"
class nsDocShellLoadState;
namespace mozilla::dom {
class WindowFeatures;
}
%}

webidl BrowsingContext;
interface mozIDOMWindowProxy;
interface nsISimpleEnumerator;
interface nsIWebBrowserChrome;
interface nsIDocShellTreeItem;
interface nsIArray;
interface nsIRemoteTab;
interface nsIOpenWindowInfo;
native nsDocShellLoadStatePtr(nsDocShellLoadState*);
[ref] native WindowFeaturesRef(const mozilla::dom::WindowFeatures);
[ref] native UserActivationModifiersRef(const mozilla::dom::UserActivation::Modifiers);

[uuid(d162f9c4-19d5-4723-931f-f1e51bfa9f68)]
interface nsPIWindowWatcher : nsISupports
{
  /** A window has been created. Add it to our list.
      @param aWindow the window to add
      @param aChrome the corresponding chrome window. The DOM window
                     and chrome will be mapped together, and the corresponding
                     chrome can be retrieved using the (not private)
                     method getChromeForWindow. If null, any extant mapping
                     will be cleared.
  */
  void addWindow(in mozIDOMWindowProxy aWindow,
                 in nsIWebBrowserChrome aChrome);

  /** A window has been closed. Remove it from our list.
      @param aWindow the window to remove
  */
  void removeWindow(in mozIDOMWindowProxy aWindow);

  cenum PrintKind : 8 {
    PRINT_NONE,
    PRINT_INTERNAL,
    PRINT_WINDOW_DOT_PRINT,
  };

  /** Like the public interface's open(), but can handle openDialog-style
      arguments and calls which shouldn't result in us navigating the window.

      @param aParent parent window, if any. Null if no parent.  If it is
             impossible to get to an nsIWebBrowserChrome from aParent, this
             method will effectively act as if aParent were null.
      @param aURL url to which to open the new window. Must already be
             escaped, if applicable. can be null.
      @param aName window name from JS window.open. can be null.  If a window
             with this name already exists, the openWindow call may just load
             aUrl in it (if aUrl is not null) and return it.
      @param aFeatures window features from JS window.open. can be null.
      @param aModifiers The modifiers associated with the user activation,
             or UserActivation::Modifiers::None() if this is not initiated by
             user activation. This is used to determine where the new window is
             located (e.g. new foreground tab, new background tab, new window).
      @param aCalledFromScript true if we were called from script.
      @param aDialog use dialog defaults (see nsGlobalWindowOuter::OpenInternal)
      @param aNavigate true if we should navigate the new window to the
             specified URL.
      @param aArgs Window argument
      @param aIsPopupSpam true if the window is a popup spam window; used for
                          popup blocker internals.
      @param aForceNoOpener If true, force noopener behavior.  This means not
                            looking for existing windows with the given name,
                            not setting an opener on the newly opened window,
                            and returning null from this method.
      @param aLoadState if aNavigate is true, this allows the caller to pass in
                        an nsIDocShellLoadState to use for the navigation.
                       Callers can pass in null if they want the windowwatcher
                       to just construct a loadinfo itself.  If aNavigate is
                       false, this argument is ignored.

      @return the new window

      @note This method may examine the JS context stack for purposes of
            determining the security context to use for the search for a given
            window named aName.
      @note This method should try to set the default charset for the new
            window to the default charset of the document in the calling window
            (which is determined based on the JS stack and the value of
            aParent).  This is not guaranteed, however.
  */
  [noscript]
  BrowsingContext openWindow2(in mozIDOMWindowProxy aParent, in ACString aUrl,
                              in ACString aName, in ACString aFeatures,
                              in UserActivationModifiersRef aModifiers,
                              in boolean aCalledFromScript,
                              in boolean aDialog,
                              in boolean aNavigate,
                              in nsISupports aArgs,
                              in boolean aIsPopupSpam,
                              in boolean aForceNoOpener,
                              in boolean aForceNoReferrer,
                              in nsPIWindowWatcher_PrintKind aPrintKind,
                              in nsDocShellLoadStatePtr aLoadState);

  /**
   * Opens a new window so that the window that aOpeningTab belongs to
   * is set as the parent window. The newly opened window will also
   * inherit load context information from aOpeningTab.
   *
   * @param aOpeningTab
   *        The nsIRemoteTab that is requesting the new window be opened.
   * @param aFeatures
   *        Window features if called with window.open or similar.
   * @param aModifiers
   *        The modifiers associated with the user activation, or
   *        UserActivation::Modifiers::None() if this is not initiated by
   *        user activation.
   * @param aCalledFromJS
   *        True if called via window.open or similar.
   * @param aOpenerFullZoom
   *        The current zoom multiplier for the opener tab. This is then
   *        applied to the newly opened window.
   * @param aOpenWindowInfo
   *        Information used to create the initial content browser in the new
   *        window.
   *
   * @return the nsIRemoteTab of the initial browser for the newly opened
   *         window.
   */
  nsIRemoteTab openWindowWithRemoteTab(in nsIRemoteTab aOpeningTab,
                                       in WindowFeaturesRef aFeatures,
                                       in UserActivationModifiersRef aModifiers,
                                       in boolean aCalledFromJS,
                                       in float aOpenerFullZoom,
                                       in nsIOpenWindowInfo aOpenWindowInfo);
};