XUL Programmer's Reference Manual

<window> Attributes

Attributes Common Children
title toolbar
titlemodified html:script 
titlemenuseparator menubar
id box
xmlns keyset
onload  
onunload  
windowtype Methods
align open()
width, height openDialog()
persist sizeToContent() 
x, y  
ondraggesture  

The root element in a XUL file and the top level of the interface it defines is the <window> widget. All XUL files must contain one and only one window element. The entire XUL interface is defined within this root element.
 

 

title
Description
The title attribute specifies the name that appears in the title bar of the window. It is used in conjunction with the other title attributes to handle the display of information in the title bar at various times.
Syntax
title="window title"
where window title is a string containing the name of the window
Example
<window id="sample"
title="Sample Window"
titlemodifier=" Sample">
Notes
When no content appears in the browser, the title attribute is used for the title. When content is loaded, the title bar displays the name of the content and then the titlemodifier instead. For example, when netscape's Netcenter is loaded in the Mozilla browser, the title bar displays "Netcenter - Mozilla."

If you are titling your windows, make sure you use all the title attributes to avoid naming inconsistencies in the title bar.
 

titlemodifier
Description
The titlemodifier attribute specifies the portion of the title that appears after the content is named.
Syntax
titlemodifier="window title"
where window title is a string containing the name of the window
Example
<window id="sample"
title="Sample Window"
titlemodifier=" Sample">
Notes
When content is loaded in the browser, the title bar displays the name of the content and then the titlemodifier instead. For example, when netscape's Netcenter is loaded in the Mozilla browser, the title bar displays "Netcenter - Mozilla."

If you are titling your windows, make sure you use all the title attributes to avoid naming inconsistencies in the title bar. When there is no content loaded, the browser uses the regular title attribute.

 
titlemenuseparator
Description
The titlemenuseparator attribute specifies the string that separates the content name and the titlemodifier.
Syntax
titlemenuseparator="characters"
where characters is a string representing the separator
Example
<window id="sample"
title="Sample Window"
titlemodifier=" Sample"
titlemenuseparator=" - ">
Notes
When content is loaded in the browser, the title bar displays the name of the content and the titlemodifier separated by the titlemenuseparator. The example XUL above, when browsing the Netcenter site, would result in a title bar displaying "Netcenter - Sample."

If you are titling your windows, make sure you use all the title attributes to avoid naming inconsistencies in the title bar. When there is no content loaded, the browser uses the regular title attribute.

xmlns
Description
The xmlns window attribute is used to make xml namespace declarations for the XUL file. 
Syntax
The three commonly declared namespaces in a XUL file are:
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
Notes
The three namespace declarations listed above seldom vary. The first is the standard namespace declaration for HTML 4.0, and the second is the namespace declaration for RDF, which is used to organize and display resources in the browser. The last one, though subject to change as XUL becomes fully standardized, is the namespace declaration for XUL itself. Gecko requires this declaration in order to resolve the XML elements in your XUL file to XUL widgets.
 
onload
Description
onload is an event handler attribute for the root window element. The load event is fired each time the window defined by the <window> element is loaded, or opened, but before the window is displayed.
Syntax
<window id="id"
title="title"
onload="javascript or javascript function call"
Example
<window id="main-window"
title="Mozilla"
onload="StartupConfig()"
Notes
To create a callback for the load event, place javascript in the onload event listener. The javascript can be a series of javascript statements separated by semicolons or a call to a javascript function defined elsewhere. Any configuration or content changes which must be made before the window displays should be placed in this callback.


 

onunload
Description
onunload is an event listener for the root window element. The unload event is fired each time the window defined by the <window> element is closed or exited, but before the window actually disappears.
Syntax
<window id="id"
title="title"
onunload="javascript or javascript function call"
Example
<window id="main-window"
title="Mozilla"
onunload="WindowCloseExtras()>"
Notes
None.
 
 
open()
Description
open is the window element's method for opening other XUL windows and dialogs.
Syntax
window.open(URL[, windowName[, windowFeatures]]) 
Example
window.open("chrome://help/content/help.xul", "Help Window", "chrome")
Notes
The windowFeatures argument allows you to specify additional features of the window being opened. 

titlebar - The window can be created with or without a titlebar. 
close - The window can be created with or without a close widget. 
chrome - Normally, the URL given to window.open is treated as a content URL. That is, Mozilla generates a browser window and loads the given URL into its content area, as window.open has always behaved. However, the presence of a chrome flag in the windowFeatures parameter will cause the given URL to be treated as the window chrome, itself. It will be treated as the top-level window contents; it will not be
wrapped in a browser window. The window will also be sized to wrap its contents. 
dependent - The new window belongs to the calling window, on operating systems that support this behaviour. This is the kind of window that is minimized along with its parent/owner; a "popup" or "transient" window, or whatever word your OS has chosen to use. 
dialog - Use a dialog-style window border. 
modal - The window will be run modally. The call to window.open will not return until the user has dismissed the window. Note that modal implies dependent. 

When the windowFeatures argument is not given, the opener assumes that the specified resource is content for its own window and not a new window.

See openDialog() for an even more flexible method for opening new windows.

Default Behaviour - As always, if no parameter is passed, all chrome is assumed turned on. Exceptions are the behaviour flags chrome, dependent, dialog and modal: these are not turned on unless done explicitly. If any string at all, even a zero-length string, is given in the features parameter, any features not explicitly mentioned are assumed off. titlebar and close are the two exceptions: they are not considered off unless explicitly mentioned ("titlebar=no"), since anything else would break extant script.


 
 
 
openDialog()
Description
openDialog is an extension of the window elements open() method that provides some additional control over the process of opening new windows in the UI.
Syntax
window.openDialog(URL[, windowName[, windowFeatures[, args]]]) 
Example
window.openDialog("chrome://help/content/help.xul", 
  "Help Window", "chrome", 

  "special")
Notes
The windowFeatures argument allows you to specify additional features of the window being opened. 

titlebar - The window can be created with or without a titlebar. 
close - The window can be created with or without a close widget. 
chrome - Normally, the URL given to window.open is treated as a content URL. That is, Mozilla generates a browser window and loads the given URL into its content area, as window.open has always behaved. However, the presence of a chrome flag in the windowFeatures parameter will cause the given URL to be treated as the window chrome, itself. It will be treated as the top-level window contents; it will not be
wrapped in a browser window. The window will also be sized to wrap its contents. 
dependent - The new window belongs to the calling window, on operating systems that support this behaviour. This is the kind of window that is minimized along with its parent/owner; a "popup" or "transient" window, or whatever word your OS has chosen to use. 
dialog - Use a dialog-style window border. 
modal - The window will be run modally. The call to window.open will not return until the user has dismissed the window. Note that modal implies dependent. 

When the windowFeatures argument is not given, the opener assumes that the specified resource is content for its own window and not a new window.

The additional parameters you can pass in args will be bundled up in a JavaScript array and added to the newly created window as a property named arguments. They may be referenced in the JavaScript of the window at any time, including during the execution of an onload handler. These parameters may be used, then, to pass arguments to and from the dialog window.

Default behaviour - The chrome and dialog features are always assumed on, unless explicitly turned off ("chrome=no"). openDialog treats the absence of the features parameter as does window.open, (that is, an empty string sets all features to off) except chrome and dialog, which default to on. If the features parameter is a zero-length string, or contains only one or more of the behaviour features (chrome, dependent, dialog and modal) the chrome features are assumed "OS' choice." That is, window creation code is not given specific instructions, but is instead allowed to select the chrome that best fits a dialog 
on that operating system. 
 


 
 
 
sizeToContent()
Description
sizeToContent() is the window element's method for opening reflowing an open window.
Syntax
window.sizeToContent() 
Example
window.sizeToContent()
Notes
This reflows the window's content, and wraps the window around those contents. It functions even on fixed size windows (that is, windows with the "resizable" flag turned off.) This function's intended use is with intrinsically sized windows (those which are designed to wrap themselves to fit their content) after changing that content, presumably during the execution of an onload handler. 

 
 
 

 
 

Last updated: 2/17/00 Ian Oeschger