gecko-dev/xpfe/appshell/public/nsIWindowMediator.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * 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 Netscape are
 * Copyright (C) 1999 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */
 
#include "nsISupports.idl"
#include "nsIEnumerator.idl"
#include "nsIRDFDataSource.idl"
#include "domstubs.idl"

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

interface nsIXULWindow;
interface nsIWidget;


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

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

	/*
		Returns the window of type inType ( if null return any window type ) which has the most recent
		time stamp
	*/
	nsIDOMWindow getMostRecentWindow( in wstring inType );
	
	/*
		Get window given an RDF resource.
	*/
	nsIDOMWindow getWindowForResource( in wstring inResource );
	
	/* */
	nsIDOMWindow convertISupportsToDOMWindow( in nsISupports inWindow );
	
	/* 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] PRBool 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);
};

%{C++
extern nsresult NS_NewWindowMediatorFactory(nsIFactory** aResult);
%}