nsIXULWindow

xpfe/appshell/nsIXULWindow.idlScriptable

Please add a summary to this article.

Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

An nsIXULWindow is created as part of the creation of a top-level chrome window. When the window is destroyed, it will fire a "xul-window-destroyed" notification through the global observer service. This signals the application in case it needs to quit.

Method overview

void addChildWindow(in nsIXULWindow aChild);

void applyChromeFlags(); Native code only!

void assumeChromeFlagsAreFrozen();

void center(in nsIXULWindow aRelative, in boolean aScreen, in boolean aAlert);

nsIXULWindow createNewWindow(in PRInt32 aChromeFlags, in nsIAppShell aAppShell);

nsIDocShellTreeItem getContentShellById(in wstring ID);

void removeChildWindow(in nsIXULWindow aChild);

void showModal();

Attributes

Attribute	Type	Description
`chromeFlags`	`PRUint32`	`chromeFlags` are from `nsIWebBrowserChrome`.
`contextFlags`	`PRUint32`	`contextFlags` are from `nsIWindowCreator2`.
`docShell`	`nsIDocShell`	The `docshell` owning the XUL for this window. Read only.
`intrinsicallySized`	`boolean`	Indicates if this window is instrinsically sized.
`primaryContentShell`	`nsIDocShellTreeItem`	The primary content shell. Note: That this is a `docshell` tree item and therefore can not be assured of what object it is. It could be an editor, a `docshell`, or a browser object. Or down the road any other object that supports being a DocShellTreeItem Query accordingly to determine the capabilities. Read only.
`XULBrowserWindow`	`nsIXULBrowserWindow`	Provides access to the `XULBrowserWindow` object offering a way for the browser to update the user interface of the enclosing XUL window.
`zLevel`	`unsigned long`	One of the Z level constants below. On some platforms, windows with a higher zLevel will be kept above windows with a lower zLevel.

Constants

Constant	Value	Description
`lowestZ`	`0`
`loweredZ`	`4`	The Z level of an independent window opened with the "alwaysLowered" chrome flag.
`normalZ`	`5`	The default Z level of an independent window.
`raisedZ`	`6`	The Z level of an independent window opened with the "alwaysRaised" chrome flag.
`highestZ`	`9`

Methods

addChildWindow()

Tell this window that it has picked up a child XUL window.Note that XUL windows do not currently track child XUL windows.

void addChildWindow(
  in nsIXULWindow aChild
);

Parameters

aChild: The child window being added.

Native code only!

applyChromeFlags

Back-door method to force application of chrome flags at a particular time. Do NOT call this unless you know what you are doing! In particular, calling this when this XUL window does not yet have a document in its docshell could cause problems.

void applyChromeFlags();

Parameters

None.

assumeChromeFlagsAreFrozen()

Begin assuming chromeFlags do not change hereafter, and assert if they do change. The state change is one-way and idempotent.

void assumeChromeFlagsAreFrozen();

Parameters

None.

center()

Move the window to a centered position.

void center(
  in nsIXULWindow aRelative,
  in boolean aScreen,
  in boolean aAlert
);

Parameters

aRelative: If not null, the window relative to which the window is moved. See aScreen parameter for details.
aScreen: true to center the window relative to the screen containing aRelative if aRelative is not null. If aRelative is null then relative to the screen of the opener window if it was initialized by passing it to nsWebShellWindow::Initialize. Failing that relative to the main screen. false to center it relative to aRelative itself (aRelative must be set in this case.)
aAlert: true to move the window to an alert position, generally centered horizontally and 1/3 down from the top.

createNewWindow()

Create a new window.

nsIXULWindow createNewWindow(
  in PRInt32 aChromeFlags,
  in nsIAppShell aAppShell
);

Parameters

aChromeFlags: See nsIWebBrowserChrome.
aAppShell: The app shell passed to nsIAppShellService's CreateTopLevelWindow method.

Return value

The newly minted window. In the case of a content window, the function creates a browser window and waits for it to load. You can then load a document into the window's primary content shell.

getContentShellById()

The content shell specified by the supplied id.

Note: That this is a docshell tree item and therefore can not be assured of what object it is. It could be an editor, a docshell, or a browser object. Or down the road any other object that supports being a DocShellTreeItem Query accordingly to determine the capabilities.

nsIDocShellTreeItem getContentShellById(
  in wstring ID
);

Parameters

ID: The ID of the content shell, which is the same as the "type" attribute on the containing frame element.

Return value

The tree item corresponding to the given ID, if any.

removeChildWindow()

Tell this window that it has lost a child XUL window. Note that XUL windows do not currently track child XUL windows.

void removeChildWindow(
  in nsIXULWindow aChild
);

Parameters

aChild: The child window being removed.

showModal()

Shows the window as a modal window. That is, ensures that it is visible and runs a local event loop, exiting only once the window has been closed.

void showModal();

Parameters

None.