« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

Describes the structure of a top-level window. It is the root node of a XUL document. It is by default a horizontally oriented box. As it is a box, all box attributes can be used. By default, the window will have a platform-specific frame around it.

To set an icon for the window, create a platform-specific icon file <windowid>.ico and/or <windowid>.xpm and place or install these files into the <mozilla-directory>/chrome/icons/default/ directory. The <windowid> is the value of the id attribute on the window. This allows you to have a different icon for each window.

Without including the css file at "chrome://global/skin/", the window will not be stylized and will be invisible and glitchy when opened as a dialog.

Note: Starting in Gecko 1.9.2, you can detect when a window is activated or deactivated by watching for the "activate" and "deactivate" events. See Window activation events.

More information is available in the XUL tutorial.

Attributes
accelerated, chromemargin, disablechrome, disablefastfind, drawintitlebar, fullscreenbutton, height, hidechrome, id, lightweightthemes, lightweightthemesfooter, screenX, screenY, sizemode, title, width, windowtype

Examples

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<!--  run this example using  copy & paste  in this live XUL editor:  https://github.com/KM-200/xul      -->
<!--   Extremely recommended to keep this css include!! -->
<window id="rootWnd" title="Register Online!"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <vbox>
    <hbox>
      <image src="application_form.png"/>
      <description>Register Online!</description>
    </hbox>
    <groupbox align="start">
      <caption label="Your Information"/>
      <radiogroup>
        <vbox>
          <hbox>
            <label control="your-fname" value="Enter first name:"/>
            <textbox id="your-fname" value="Johan"/>
          </hbox>
          <hbox>
            <label control="your-lname" value="Enter last name:"/>
            <textbox id="your-lname" value="Hernandez"/>
          </hbox>
          <hbox>
            <button oncommand="alert('save!')">
              <description>Save</description>
            </button>
          </hbox>
        </vbox>
      </radiogroup>
    </groupbox>
  </vbox>
</window>

Attributes

accelerated
Type: boolean
Set this attribute to true to allow hardware layer managers to accelerate the window.
activetitlebarcolor
Type: color string
Specify background color of the window's titlebar when it is active (foreground). Moreover this hides separator between titlebar and window contents. This only affects Mac OS X.
chromemargin
Type: margin string
Controls the amount of chrome that should be visible on each side of the window. The specified string should contain four numbers, separated by commas, indicating the margin in pixels for the top, right, bottom, and left edges of the window, respectively. This value may be -1 to use the default margin for that side on the current platform, 0 to have no system border (that is, to extend the client area to the edge of the window), or a value greater than zero to indicate how much less than the default default width you wish the margin on that side to be. If this value turns out to be less than 0, 0 is used.
disablechrome
Type: boolean
Set this attribute to true to disable chrome in the window. This is used to hide chrome when showing in-browser UI such as the about:addons page, and causes the toolbars to be hidden, with only the tab strip (and, if currently displayed, the add-on bar) left showing.
Note: This has no effect if the tabs on top preference is turned off.
disablefastfind
Type: boolean
Put disablefastfind="true" on the root element of a XUL document, which is intended to be loaded in a tab, to disable the find bar for the tab with this document. This is used to prevent the find bar from being displayed when it's not supported by the content (such as in the Add-ons manager tab).
drawintitlebar
Type: boolean
If this attribute is true, the top of the window's content area will begin at the top edge of the title bar, instead of below the title bar. This allows the window to draw in the title bar. This is supported only from window elements, and is ignored on platforms that don't support drawing into the title bar.
fullscreenbutton
Type: boolean
Set this attribute to true to display a button in the window chrome to allow the user to switch the window into full screen mode. Supported on Mac OS X 10.7 Lion and later and on Windows. The window receives a "fullscreen" event once the change has been made.
height
Type: string (representing an integer)
The preferred height of the element in pixels. The actual displayed height may be different if the element or its contents have a minimum or maximum height. The CSS height property may also be used.
hidechrome
Type: boolean
Set this attribute to true to have the chrome including the titlebar hidden.
id
Type: unique id
A unique identifier so that you can identify the element with. You can use this as a parameter to getElementById() and other DOM functions and to reference the element in style sheets.
inactivetitlebarcolor
Type: color string
Specify background color of the window's titlebar when it is inactive (background). Moreover this hides separator between titlebar and window contents. This affects only on Mac OS X.
lightweightthemes
Type: boolean
true if the window supports lightweight themes, otherwise false.
lightweightthemesfooter
Type: id
Specifies the ID of an element to which a lightweight theme's footer image will be applied.
screenX
Type: integer
The horizontal position at which the window appears on the screen.
screenY
Type: integer
The vertical position at which the window appears on the screen.
sizemode
Type: one of the values below
The state of the window. It can have one of the following values:
maximized
The window is maximized, and occupies the full size of the screen.
normal
The window appears in a normal state at the desired size.

This attribute is used to save and restore the state of a window (together with the persist attribute) and for CSS styles (e.g. to hide the resizer grippy on maximized windows).

Note: When a window is minimized, the sizemode attribute is not updated. This is done so that if a window is closed while minimized, its persisted sizemode attribute wouldn't be minimized.

Setting this attribute does not change the window state. Use window.maximize(), window.restore(), or window.minimize() to change the window state.

To get the window state from JavaScript code, use window.windowState. Listen to the sizemodechange event dispatched to the DOM window to get notified when the window state changes.

title
Type: string
The text to appear in the title bar of the window.
width
Type: string (representing an integer)
The preferred width of the element. The value should not include a unit as all values are in pixels. The actual displayed width may be different if the element or its contents have a minimum or maximum width, or the size is adjusted by the flexibility or alignment of its parent. The CSS width property may also be used.
windowtype
Type: string
Set to a string which can be used to identify the type of window. This might be used, for example, to distinguish between a browser window and an editor window. Some of Mozilla's window handling functions use this attribute to group windows of the same type together.

Values for window type as found on MXR: http://mxr.mozilla.org/mozilla-release/search?string=windowtype

navigator:browser - Looks like if window has gBrowser it has this window type

devtools:scratchpad - Scratchpad windows

navigator:view-source - The view source windows

 

Properties

Inherited Properties
align, , allowEvents, , boxObject, builder, , , , className, , , , , collapsed, contextMenu, controllers, database, datasources, dir, , , flex, height, hidden, id, , , left, , maxHeight, maxWidth, menu, minHeight, minWidth, , , , , , , observes, ordinal, orient, , pack, , persist, , , , ref, resource, , , , , statusText, style, ,, tooltip, tooltipText, top, width

Methods

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature, getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

See also: DOM window object methods 

Note

The error message "XML Parsing Error: undefined entity...<window" can be caused by a missing or unreachable DTD file referenced in the XUL file. A filename following the SYSTEM keyword in a DOCTYPE declaration may silently fail to load and the only error message will be an undefined entity error on the next XUL element.

prefwindow, dialog, dialogheader

User Notes

To change the Icon to a window's title bar check this page on Window icons.

To add a favicon to the address bar and browser tab (ie dialog is not a popup) then use the following code snippet to use the html namespace and link.

<window xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
	xmlns:html="http://www.w3.org/1999/xhtml">

<!-- Icon from chrome -->
<html:link rel="icon" href="chrome://myExtension/content/path/to/favicon.png"/>

<!-- From a remote site -->
<html:link rel="icon" href="http://www.mozilla.org/favicon.ico"/>

Since Firefox 3.6 the above listed code does not work correctly - it produces the following message: "Warning: XUL box for box element contained an inline link child, forcing all its children to be wrapped in a block". If this code is placed between window tags it messes up all other controls on the window. If it is placed between box tags, window controls are rendered fine, but still there is this error message. The problem can be solved as follows:

<html:link rel="icon" href="chrome://myExtension/content/path/to/favicon.png" style="display:none"/>

or

<html:head>
  <html:link rel="icon" href="chrome://myExtension/content/path/to/favicon.png"/>
</html:head>