gecko-dev/docshell/base/nsIDocShellTreeOwner.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * ***** 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 the Mozilla browser.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications, Inc.
 * Portions created by the Initial Developer are Copyright (C) 1999
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Travis Bogard <travis@netscape.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of 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"

/**
 * The nsIDocShellTreeOwner
 */

interface nsIDocShellTreeItem;

[scriptable, uuid(9e508466-5ebb-4618-abfa-9ad47bed0b2e)]
interface nsIDocShellTreeOwner : nsISupports
{
	/*
	Return the child DocShellTreeItem with the specified name.
	name - This is the name of the item that is trying to be found.
	aRequestor - This is the docshellTreeItem that is requesting the find.  This
	parameter is used to identify when the child is asking its parent to find
	a child with the specific name.  The parent uses this parameter to ensure
	a resursive state does not occur by not again asking the requestor for find
	a shell by the specified name.  Inversely the child uses it to ensure it
	does not ask its parent to do the search if its parent is the one that
	asked it to search.
	aOriginalRequestor - The original treeitem that made the request, if any.
	This is used to ensure that we don't run into cross-site issues.

	*/
	nsIDocShellTreeItem findItemWithName(in wstring name, 
		in nsIDocShellTreeItem aRequestor,
		in nsIDocShellTreeItem aOriginalRequestor);

	/*
	Called when a content shell is added to the the docShell Tree.
	aContentShell - the docShell that has been added.
	aPrimary - true if this is the primary content shell
	aID - the ID of the docShell that has been added.
	*/
	void contentShellAdded(in nsIDocShellTreeItem aContentShell, 
		in boolean aPrimary, in wstring aID);

	/*
	Returns the Primary Content Shell
	*/
	readonly attribute nsIDocShellTreeItem primaryContentShell;

	/*
	Tells the tree owner to size its window or parent window in such a way
	that the shell passed along will be the size specified.
	*/
	void sizeShellTo(in nsIDocShellTreeItem shell, in long cx, in long cy);

	/*
	Sets the persistence of different attributes of the window.
	*/
	void setPersistence(in boolean aPersistPosition,
                            in boolean aPersistSize,
                            in boolean aPersistSizeMode);

	/*
	Gets the current persistence states of the window.
	*/
	void getPersistence(out boolean aPersistPosition,
                            out boolean aPersistSize,
                            out boolean aPersistSizeMode);
};

/**
 * Interface added to handle window targeting in tabbrowser.  This is a total
 * hack that's only needed to work around the fact that the tree owner api is
 * really pretty useless for dealing with multiple "real" browsers in the same
 * "docshell tree" and that there's no way to set up multiple treeowners in
 * XUL-land right now.  Gecko 1.9 will NOT be shipping this interface, and
 * nsIDocShellTreeOwner will hopefully be improved significantly.
 *
 * @status TEMPORARY
 */
[scriptable, uuid(3c2a6927-e923-4ea8-bbda-a335c768ce4e)]
interface nsIDocShellTreeOwner_MOZILLA_1_8_BRANCH : nsIDocShellTreeOwner
{
  /**
   * Called when a content shell is added to the docshell tree.  This is _only_
   * called for "root" content shells (that is, ones whose parent is a chrome
   * shell).
   *
   * @param aContentShell the shell being added.
   * @param aPrimary whether the shell is primary.
   * @param aTargetable whether the shell can be a target for named window
   *                    targeting.
   * @param aID the "id" of the shell.  What this actually means is undefined.
   *            Don't rely on this for anything.
   */
  void contentShellAdded2(in nsIDocShellTreeItem aContentShell,
			  in boolean aPrimary, in boolean aTargetable,
			  in AString aID);

  /**
   * Called when a content shell is removed from the docshell tree.  This is
   * _only_ called for "root" content shells (that is, ones whose parent is a
   * chrome shell).  Note that if aContentShell was never added,
   * contentShellRemoved should just do nothing.
   *
   * @param aContentShell the shell being removed.
   */
  void contentShellRemoved(in nsIDocShellTreeItem aContentShell);
};