gecko-dev/docshell/base/nsIContentViewer.idl

/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Mozilla Communicator client code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Ms2ger <ms2ger@gmail.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

interface nsIDOMDocument;
interface nsISHEntry;
interface nsIPrintSettings;


%{ C++
class nsIWidget;
class nsIDocument;
struct nsIntRect;
class nsIPresShell;
class nsPresContext;
class nsIView;
class nsDOMNavigationTiming;
%}

[ptr] native nsIWidgetPtr(nsIWidget);
[ptr] native nsIDocumentPtr(nsIDocument);
[ref] native nsIntRectRef(nsIntRect);
[ptr] native nsIPresShellPtr(nsIPresShell);
[ptr] native nsPresContextPtr(nsPresContext);
[ptr] native nsIViewPtr(nsIView);
[ptr] native nsDOMNavigationTimingPtr(nsDOMNavigationTiming);

[scriptable, builtinclass, uuid(26b2380b-4a1a-46cd-b7d8-7600e41c1688)]
interface nsIContentViewer : nsISupports
{

  [noscript] void init(in nsIWidgetPtr aParentWidget,
                       [const] in nsIntRectRef aBounds);

  attribute nsISupports container;

  void loadStart(in nsISupports aDoc);
  void loadComplete(in unsigned long aStatus);

  /**
   * Checks if the document wants to prevent unloading by firing beforeunload on
   * the document, and if it does, prompts the user. The result is returned.
   *
   * @param aCallerClosesWindow indicates that the current caller will close the
   *        window. If the method returns true, all subsequent calls will be
   *        ignored.
   */
  boolean permitUnload([optional] in boolean aCallerClosesWindow);

  /**
   * Works in tandem with permitUnload, if the caller decides not to close the
   * window it indicated it will, it is the caller's responsibility to reset
   * that with this method.
   *
   * @Note this method is only meant to be called on documents for which the
   *  caller has indicated that it will close the window. If that is not the case
   *  the behavior of this method is undefined.
   */
  void resetCloseWindow();
  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();

  attribute nsIDOMDocument DOMDocument;

  /**
   * Returns DOMDocument as nsIDocument and without addrefing.
   */
  [noscript,notxpcom] nsIDocumentPtr getDocument();

  [noscript] void getBounds(in nsIntRectRef aBounds);
  [noscript] void setBounds([const] in nsIntRectRef aBounds);

  /**
   * The previous content viewer, which has been |close|d but not
   * |destroy|ed.
   */
  [noscript] 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();

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

  [noscript] readonly attribute nsIPresShellPtr presShell;
  [noscript] readonly attribute nsPresContextPtr presContext;
  [noscript] void setDocumentInternal(in nsIDocumentPtr 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] nsIViewPtr findContainerView();
  /**
   * Set collector for navigation timing data (load, unload events).
   */
  [noscript,notxpcom,nostdcall] void setNavigationTiming(in nsDOMNavigationTimingPtr aTiming);
};