nsIXULWindow

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()

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

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.

Document Tags and Contributors

 Contributors to this page: Sheppy, berkerpeksag, Neil, trevorh
 Last updated by: Sheppy,