/* -*- 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"
#include "nsIDocShellTreeItemTmp.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;

        /**
         * Compares the provided name against the item's name and
         * returns the appropriate result.
         *
         * @return <CODE>PR_TRUE</CODE> if names match;
         *         <CODE>PR_FALSE</CODE> otherwise.
         */
        boolean nameEquals(in wstring name);

	/*
	Definitions for the item types.
	*/
	const long typeChrome=0;            // typeChrome must equal 0
	const long typeContent=1;           // typeContent must equal 1
	const long typeContentWrapper=2;    // typeContentWrapper must equal 2
	const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3

	const long typeAll=0x7FFFFFFF;

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

	/*
	Deprecated method signature. See nsIDocShellTreeItemTmp for the
	new signature and details.
	*/
	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;

	/* The offset of yourself in your parent's child list */
	attribute long childOffset;
};

