XUL Programmer's Reference Manual
|
<window>
Attributes
|
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.
|