gecko-dev/docshell/base/nsIDocShellTreeItem.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * 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 Netscape are
 * Copyright (C) 1999, Mozilla.  All Rights Reserved.
 * 
 * Contributor(s):
 *   Travis Bogard <travis@netscape.com>
 */

#include "nsISupports.idl"

interface nsIDocShellTreeOwner;


/**
 * The nsIDocShellTreeItem supplies the methods that are required of any item
 * that wishes to be able to live within the docshell tree either as a middle
 * node or a leaf. 
 */

[scriptable, uuid(B52AE780-A966-11d3-AFC7-00A024FFC08C)]
interface nsIDocShellTreeItem : nsISupports
{
	/*
	name of the DocShellTreeItem
	*/
	attribute wstring name;

	/*
	Definitions for the item types.
	*/
	const long typeChrome=0;
	const long typeContent=1;

	/*
	The type this item is.  
	*/
	attribute long itemType;

	/*
	Parent DocShell..  Note Implementers of this interface should NOT effect
	the lifetime of the parent DocShellTreeItem by holding this reference as it
	creates a cycle.  Parents when releasing this interface should set the
	parent to nsnull.  Implementers of this interface are guaranteed that when
	parent is set that the pointer is valid without having to addref.

	Further note however when others try to Get the interface you should add
	ref it before handing it to them.
	*/
	attribute nsIDocShellTreeItem parent;

	/*
	This is call returns the same thing parent does however if the parent is
	of a different itemType, it will instead return nsnull.  This call is a
	convience function for those wishing to not cross the boundaries at which
	item types change.
	*/
	readonly attribute nsIDocShellTreeItem sameTypeParent;

	/*
	Returns the root DocShellTreeItem.  This is a convience equivalent to 
	getting the parent and its parent until there isn't a parent.
	*/
	readonly attribute nsIDocShellTreeItem rootTreeItem;

	/*
	Returns the root DocShellTreeItem of the same type.  This is a convience 
	equivalent to getting the parent of the same type and its parent until 
	there isn't a parent.
	*/
	readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;

	/*
	Returns the docShellTreeItem with the specified name.  Search order is as 
	follows...
	1.)  Check name of self, if it matches return it.
	2.)  For each immediate child.
		a.) Check name of child and if it matches return it.
		b.)  Ask the child to perform the check
			i.) Do not ask a child if it is the aRequestor
			ii.) Do not ask a child if it is of a different item type.
	3.)  If there is a parent of the same item type ask parent to perform the check
		a.) Do not ask parent if it is the aRequestor
	4.)  If there is a tree owner ask the tree owner to perform the check
		a.)  Do not ask the tree owner if it is the aRequestor
		b.)  This should only be done if there is no parent of the same type.

	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 object 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 to 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.  Children also use this to test against the treeOwner;
	*/
	nsIDocShellTreeItem findItemWithName(in wstring name, in nsISupports aRequestor);

	/*
	The owner of the DocShell Tree.  This interface will be called upon when
	the docshell has things it needs to tell to the owner of the docshell.
	Note that docShell tree ownership does not cross tree types.  Meaning
	setting ownership on a chrome tree does not set ownership on the content 
	sub-trees.  A given tree's boundaries are identified by the type changes.
	Trees of different types may be connected, but should not be traversed
	for things such as ownership.
	
	Note implementers of this interface should NOT effect the lifetime of the 
	parent DocShell by holding this reference as it creates a cycle.  Owners
	when releasing this interface should set the treeOwner to nsnull.
	Implementers of this interface are guaranteed that when treeOwner is
	set that the poitner is valid without having to addref.
	
	Further note however when others try to get the interface it should be 
	addref'd before handing it to them. 
	*/
	attribute nsIDocShellTreeOwner treeOwner;
};