Creating a Window

We're going to be creating a simple find files utility throughout this tutorial. First, however, we should look at the basic syntax of a XUL file.

Creating a XUL File

A XUL file can be given any name but it really should have a .xul extension. The simplest XUL file has the following structure:

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<window
    id="findfile-window"
    title="Find Files"
    orient="horizontal"
    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 ...
</window>

This window will not do anything since it doesn't contain any UI elements. Those will be added in the next section. Here is a line by line breakdown of the code above:

  1. <?xml version="1.0"?>
    This line simply declares that this is an XML file. You would normally add this line as is at the top of each xul file, much like one would put the HTML tag at the top of an HTML file.
  2. <?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
    This line is used to specify the style sheets to use for the file. This is the syntax that XML files use to import style sheets. In this case, we import the styles found in the global/skin chrome directory. We didn't specify a specific file so Mozilla will determine which files in the directory to use. In the case, the all-important global.css file is selected. This file contains all the default declarations for all of the XUL elements. Because XML does not have any knowledge of how elements should be displayed, the file indicates how. Generally, you will put this line at the top of every XUL file. You can also import other style sheets using a similar syntax. Note that you would normally import the global style sheet from within your own style sheet file.
  3. <window
    This line declares that you are describing a window. Each user interface window is described in a separate file. This tag is much like the BODY tag in HTML which surrounds the entire content. Several attributes can be placed in the window tag -- in this case there are four. In the example, each attribute is placed on a separate line but they do not have to be.
  4. id="findfile-window"
    The id attribute is used as an identifier so that the window can be referred to by scripts. You will usually put an id attribute on all elements. The name can be anything you want although it should be something relevant.
  5. title="Find Files"
    The title attribute describes the text that would appear on the title bar of the window when it is displayed. In this case the text 'Find Files' will appear.
  6. orient="horizontal"
    The orient attribute specifies the arrangement of the items in the window. The value horizontal indicates that items should be placed horizontally across the window. You may also use the value vertical, which means that the items are placed in a column. This is the default value, so you may leave the attribute off entirely if you wish to have vertical orientation.
  7. xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    This line declares the namespace for XUL, which you should put on the window element to indicate that all of its children are XUL. Note that this URL is never actually downloaded. Mozilla will recognize this URL internally.
  8. ...
    This is where the elements (the buttons, menus and other user interface components) would be declared. We'll add some of these in the next set of sections.
  9. </window>
    And finally, we need to close the window tag at the end of the file.

Opening a Window

In order to open a XUL window, there are several methods that can be used. If you are only in the development stage, you can just type the URL (whether a chrome:, file: or other URL type) into the location bar in a Mozilla browser window. You should also be able to double-click the file in your file manager, assuming that XUL files are associated with Mozilla. The XUL window will appear in the browser window as opposed to a new window, but this is often sufficient during the early stages of development.

The correct way, of course, is to open the window using JavaScript. No new syntax is necessary as you can use the window.open() function as one can do for HTML documents. However, one additional flag, called 'chrome' is necessary to indicate to the browser that this is a chrome document to open. This will open the window without the toolbars and menus and so forth that a normal browser window has. The syntax is described below:

window.open(url,windowname,flags);

where the flags contains the flag "chrome".

Example:
window.open("chrome://navigator/content/navigator.xul", "bmarks", "chrome,width=600,height=300");

Let's begin by creating the basic file for the find file dialog. Create a file called findfile.xul and put it in a new directory somewhere. It doesn't matter where you put it, but the chrome/findfile/content directory is a suitable place. Add the XUL template shown at the top of this page to the file and save it.

You can use the command-line parameter '-chrome' to specify the XUL file to open when Mozilla starts. If this is not specified, the default window open will open. (Usually the browser window.) For example, we could open the find files dialog with either of the following:

mozilla -chrome chrome://findfile/content/findfile.xul
mozilla -chrome resource:/chrome/findfile/content/findfile.xul

If you run this command from a command-line (assuming you have one on your platform), the find files dialog will open by default instead of the Mozilla browser window. Of course, because we haven't put any UI elements in the window, you won't see a window appear. We'll add some elements in the next section.

To see the effect though, the following will open the bookmarks window:

mozilla -chrome chrome://communicator/content/bookmarks/bookmarksManager.xul

The '-chrome' argument doesn't give the file any additional privileges. Instead, it causes the specified file to open as a top-level window without any browser chrome, such as the address field or menu. Only chrome URLs have additional privileges.


(Next) In the next section, we will add some buttons to the window.

Add a note User Contributed Notes
September 27, 2005, 11:04 pm ashishwave at yahoo dot com
It is not necessary to add firefox or mozilla directory to PATH. you can prefix "start" with the commandline to achieve the same thing on MS windows, like:
start firefox -chrome file:///C:\test\abc.xul
start mozilla -chrome file:///C:\test\abc.xul
bye :-)
Ashish Ranjan
September 27, 2005, 3:19 pm liam_chasteen at hotmail dot com
If you have firefox configured to automatically open new pages in a seperate tab, you may also want to change your file association to open your xul files in a new window instead of a tab, with the "-new" option:

firefox.exe -new -chrome "file://%1"
April 29, 2005, 8:53 am darel dot finkbeiner at gmail dot com
If you are using Firefox (at least on Linux) and want to read this tutorial and still open your app in a new window without dealing with multiple profiles:

Use Tools->JavaScript Console
put in the "window.open(url,windowname,flags)" code for your app and hit "Evaluate".

Simple, no muss, no fuss.
October 7, 2004, 1:08 am kct at himalay dot org
Suppose your file is at,
H:\work\xul\findfiles.xul

then you can also use,
mozilla --chrome file:///H:\work\xul\findfiles.xul

Note that it won't have any extra privileges since it is not a chrome URL - Neil
August 3, 2004, 5:22 am andrazt at hotmail dot com
To get this to work on Mac OSX you'll need to actually go into the Mozilla.app.. Here is an example with firefox.

/Applications/Firefox.app/Contents/MacOS/firefox -chrome chrome://findfile/content/findfile.xul

It might be easier to add this to your path.
May 31, 2004, 6:28 am courcy dot michael at wanadoo dot fr
For the XP window user you must set the PATH to be able to execute mozilla from the command line.

Configuration Panel->System->Advanced->Environnement Variable

Then Select the PATH variable and add after the last semi-colon the path to the directory that contains mozilla.exe

In my case i did so
....ython23;C:\Program Files\mozilla.org\Mozilla;
March 1, 2004, 8:11 am xul at brownfamily dot org dot uk
if you double click the xul file and get the message 'c is not a registered protocol' you need to update the xul file association.
Instead of:
firefox.exe -chrome "%1"
try:
firefox.exe -chrome "file://%1"
February 23, 2004, 7:42 am phani at myrealbox dot com
If you were unable to get a window from using
mozilla -chrome chrome://findfile/content/findfile.xul (like I did),
then try the second command
mozilla -chrome resource:/chrome/findfile/content/findfile/findfile.xul
My guess is that the first one didnot work for me coz the entries in the installed-chrome.txt need to be modified. The second command gives the complete path, so it worked.

True, although the application wont' have chrome privileges in this case. - Neil

Copyright © 1999 - 2005 XULPlanet.com