/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Netscape 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/NPL/
 *
 * 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.org code.
 *
 * The Initial Developer of the Original Code is 
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1999
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * 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 NPL, 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 NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */
 
#include "nsISupports.idl"
#include "nsISimpleEnumerator.idl"

%{C++
#define NS_WINDOWMEDIATOR_CID \
{ 0x0659cb83, 0xfaad, 0x11d2, { 0x8e, 0x19, 0xb2, 0x06, 0x62, 0x0a, 0x65, 0x7c } }

#define NS_WINDOWMEDIATOR_CONTRACTID \
  "@mozilla.org/appshell/window-mediator;1"
%}

interface nsIXULWindow;
interface nsIWidget;
interface nsIDOMWindowInternal;
interface nsIWindowMediatorListener;

[scriptable, uuid(0659cb81-faad-11d2-8e19-b206620a657c)]
interface nsIWindowMediator: nsISupports
{

	/*
		iterates over the windows of type inType in the order that
		they were created. If inType is null iterates over all
		windows.  This enumerator returns domWindows.
	*/
	
	nsISimpleEnumerator getEnumerator( in wstring inType );

	/*
		iterates over the XUL windows of type inType in the order that
		they were created.  If inType is null iterates over all
		windows.  This enumerator returns xulWindows.
	*/

	nsISimpleEnumerator getXULWindowEnumerator( in wstring inType); 

	/* These iterate over the windows of type inType in z-order.
	   If inType is null, it iterates over all windows.
	   This iterator returns domWindows. Note this interface makes
	   no requirement that if windows are re-ordered while z-order
	   enumerator(s) are active, a window couldn't be revisited
	   (if you don't fail to get my double-negative meaning.)
	*/
	nsISimpleEnumerator getZOrderDOMWindowEnumerator(in wstring aWindowType, in boolean aFrontToBack);
	nsISimpleEnumerator getZOrderXULWindowEnumerator(in wstring aWindowType, in boolean aFrontToBack);

	/*
		Returns the window of type inType ( if null return any window
		type ) which has the most recent time stamp
	*/
	nsIDOMWindowInternal getMostRecentWindow( in wstring inType );
	
	/* Add the webshellwindow to the list */
	[noscript] void registerWindow( in nsIXULWindow inWindow);
	
	/* remove the window from the list */
	[noscript] void unregisterWindow( in nsIXULWindow inWindow );
	
	/* Call when the window gains focus. Used to determine the most recent window */
    [noscript] void updateWindowTimeStamp( in nsIXULWindow inWindow );
			
    /* */
    [noscript] void updateWindowTitle(in nsIXULWindow inWindow, in wstring inTitle );
    
    /* z-ordering: */
    
    const unsigned long zLevelTop    = 1;
    const unsigned long zLevelBottom = 2;
    const unsigned long zLevelBelow  = 3; // below some window
    
    /*   A window wants to be moved in z-order. Calculate whether and how
         it should be constrained. Note this method is advisory only:
         it changes nothing either in WindowMediator's internal state
         or with the window.
         Note it compares the nsIXULWindow to nsIWidgets. A pure interface
         would use all nsIXULWindows. But we expect this to be called from
         callbacks originating in native window code. They are expected to
         hand us comparison values which are pulled from general storage
         in the native widget, and may not correspond to an nsIWidget at all.
         For that reason this interface requires only objects one step
         removed from the native window (nsIWidgets), and its implementation
         must be very understanding of what may be completely invalid
         pointers in those parameters.
         
         @param inWindow the window in question
         @param inPosition requested position
         values: zLevelTop: topmost window. zLevelBottom: bottom.
         zLevelBelow: below ioBelow.  (the value of ioBelow will be
         ignored for zLevelTop and Bottom.)
         @param inBelow if inPosition==zLevelBelow, the window
         below which inWindow wants to be placed. Otherwise this
         variable is ignored.
         @param outPosition constrained position, values like inPosition.
         @param outBelow if outPosition==zLevelBelow, the window
         below which inWindow should be placed. Otherwise this
         this value will be null.
         @return PR_TRUE if the position returned is different from
         the position given.
    */

    [noscript] boolean calculateZPosition(in nsIXULWindow   inWindow,
                                          in unsigned long  inPosition,
                                          in nsIWidget      inBelow,
                                          out unsigned long outPosition,
                                          out nsIWidget     outBelow);
    
    /* a window has been positioned behind another. Inform WindowMediator
     @param inWindow the window in question
     @param inPosition new position
     values: zLevelTop: topmost window. zLevelBottom: bottom.
           zLevelBelow: below inBelow. (inBelow is ignored for
                        other values of inPosition.)
     @param inBelow the window inWindow is behind, if zLevelBelow
    */
    [noscript] void setZPosition(in nsIXULWindow inWindow,
                                 in unsigned long inPosition,
                                 in nsIXULWindow inBelow);

    /** 
     * addListener
     * keeps strong ref? (to be decided)
     */
    void addListener(in nsIWindowMediatorListener listener);

    /**
     * removeListener
     */
    void removeListener(in nsIWindowMediatorListener listener);
    
};
