This element is used to construct a step-by-step wizard found in some applications to guide users through a task. It is used for a window with several steps contained on several pages. This element provides the header and buttons along the bottom, and also handles navigation between the pages. Each page should be constructed using a wizardpage
. The pages are displayed in the order that they are placed in the wizard
, unless you use the next
and pageid
attributes on the pages to change the sequence. The wizard will rendered in a manner suitable for the user's selected theme and platform. In newer versions of Mozilla, a statusbar
may be placed directly inside the wizard element which will be shared among all pages.
More information is available in the XUL tutorial.
- Attributes
- firstpage, lastpage, pagestep, title, windowtype
- Properties
- canAdvance, canRewind, currentPage, onFirstPage, onLastPage, pageCount, pageIndex, pageStep, title, wizardPages
Examples
<?xml version="1.0"?> <?xml-stylesheet href="chrome://global/skin/" type="text/css"?> <wizard id="theWizard" title="Secret Code Wizard" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"> <script> function checkCode(){ document.getElementById('theWizard').canAdvance = (document.getElementById('secretCode').value == "cabbage"); } </script> <wizardpage onpageshow="checkCode();"> <label value="Enter the secret code:"/> <textbox id="secretCode" onkeyup="checkCode();"/> </wizardpage> <wizardpage> <label value="That is the correct secret code."/> </wizardpage> </wizard>
Attributes
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.
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.
- Use the
canCancel
property to indicate to the user (by disabling the Cancel button) that they cannot can
pagestep
- Type: integer
- The index of the current page.
title
- Type: string
- The text to appear in the title bar of the window.
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
canAdvance
- Type: boolean
- This property is set to
true
if the user can press the Next button to go to the next page. If this property isfalse
, the user cannot navigate to the next page. Set this property totrue
to indicate that the user can go to the next page. Set tofalse
to disallow moving to the next page. This has the effect of enabling or disabling the Next button, or, on the last page of the wizard, the Finish button.
canRewind
- Type: boolean
- This property is set to
true
if the user can press the Back button to go to the previous page. If this property isfalse
, the user cannot navigate to the previous page. Set this property totrue
to indicate that the user can go back a page. Set tofalse
to disallow moving to the previous page. This has the effect of enabling or disabling the Back button.
currentPage
- Type:
wizardpage
element - This property returns the
wizardpage
element that is currently displayed. You can modify this value to change the current page.
onFirstPage
- Type: boolean
- This property is set to
true
if the user is on the first page, which may or may not be the first index.
onLastPage
- Type: boolean
- This property is set to
true
if the user is on the last page of the wizard.
pageIndex
- Type: integer
- This property returns the index of the currently selected page. You can change the selected page by modifying this property.
pageStep
- Type: integer
- This property returns the number of pages that the user has navigated through so far, meaning that the user would press the Back button this many times to go back to the beginning. This property is different than
pageIndex
, because pages are not necessarily navigated in order.
wizardPages
- Type: DOM NodeList of
wizardpage
elements - This property holds the list of
wizardpage
elements in thewizard
.
Methods
advance( pageID )
- Return type: no return value
- Call this method to go to the next page. This is equivalent to pressing the Next button. The
canAdvance
property must be set totrue
for the page to be changed. The pageID argument allows you to specify the index of the page to which to jump. Supplynull
as the argument to go to the next page in the sequence.
cancel()
- Return type: no return value
- Call this method to cancel and close the wizard.
getButton( type )
- Return type: button element
- Returns the
button
element in the dialog corresponding to the given type.
getPageById( pageID )
- Return type:
wizardpage
element - Returns the
wizardpage
element corresponding to the specified pageID.
goTo( pageID )
- Return type: no return value
- This method is used to change which page is currently displayed, specified by the pageID argument. The page will be changed regardless of the value of
canAdvance
orcanRewind
.
rewind()
- Return type: no return value
- Call this method to go back a page. It is equivalent to pressing the Back button. The
canRewind
property must be set totrue
for the page to be changed.