Getting started with XULRunner

  • Revision slug: Getting_started_with_XULRunner
  • Revision title: Getting started with XULRunner
  • Revision id: 45027
  • Created:
  • Creator: Skierpage
  • Is current revision? No
  • Comment /* Alternative: Use Firefox3 -app to run XUL apps */ remove references to Minefield and Gran Paradiso

Revision Content

{{template.Next("Windows and menus in XULRunner")}} This article explores the Mozilla platform by building a basic desktop application using XULRunner. Given that Firefox, Thunderbird, and multiple other applications are written using the platform, it a safe bet that it can be used to build a basic application.

I want to build a simple XUL-based desktop application. If you’re going to build a XUL-based desktop application, you’ll probably need to install XULRunner. Let's start by installing XULRunner installed and making sure it runs a bare-bones application.

Step 1: Download XULRunner

You can find a download link on the main XULRunner page here on MDC.

The XULRunner download for Windows is a zip file, not a true install. As a developer, I like the idea that XULRunner only needs to be unzipped onto my machine. I am assuming that it doesn’t need to hook into my Windows system and that’s a good thing.

The Mac version of XULRunner is distributed as a standard Mac OS X installer.

Step 2: Install XULRunner

On Windows, unzip the archive someplace reasonable. I unzipped it to a new <tt>C:\program files\xulrunner</tt> folder. Pretty simple so far. On the Mac, just run the installer, which installs XULRunner as <tt>XUL.Framework</tt> in the <tt>/Library/Frameworks</tt> directory.

Time to start a simple, bare bones application shell. Call it a XUL “Hello World” if you want. Google turned up a nice tutorial here. It is definitely worth reading. Using the tutorial, I created a simple bootstrap application. All of what you see below can be found in Ryan’s tutorial and the XULRunner documentation here on MDC.

Step 3: Create the application folder structure

On Windows, I created the root in a new <tt>c:\program files\myapp</tt> folder, but you can create it wherever you like. Here is the subfolder structure:

/myapp
  /chrome
    /content
      main.xul
    chrome.manifest
  /defaults
    /preferences
      prefs.js
  application.ini

Notice that there are 4 files in the folder structure: <tt>application.ini</tt>, <tt>chrome.manifest</tt>, <tt>prefs.js</tt>, and <tt>main.xul</tt>.

Step 4: <tt>Set up application.ini</tt>

The <tt>application.ini</tt> file acts as the XULRunner entry point for your application. It specifies how your application intends to use the XULRunner platform as well as configure some information that XULRunner uses to run your application. Here is mine:

[App]
Vendor=Finkle
Name=Test App
Version=1.0
BuildID=20060101
Copyright=Copyright (c) 2006 Mark Finkle
ID=xulapp@starkravingfinkle.org

[Gecko]
MinVersion=1.8
MaxVersion=1.9.0.*

not really... You can find more information about the <tt>application.ini</tt> file in the article {{mediawiki.internal('XULRunner:Deploying XULRunner 1.8', "en")}}.

Step 5: Set up the chrome manifest

The chrome manifest file is used by XULRunner to define specific URIs which in turn are used to locate application resources. This will become clearer when we see how the “chrome://” URI is used. Application chrome can be in a single or a few JAR files or uncompressed as folders and files. I am using the uncompressed method for now. Here is my manifest:

 content myapp file:content/
Note: Make sure your application name is lowercase and longer than 3 characters

Step 6: Set up preferences

The <tt>prefs.js</tt> file tells XULRunner the name of the XUL file to use as the main window. Here is mine:

 pref("toolkit.defaultChromeURI", "chrome://myapp/content/main.xul");

XULRunner preferences include:

toolkit.defaultChromeURI
Specifies the default window to open when the application is launched.
toolkit.defaultChromeFeatures
Specifies the features passed to window.open() when the main application window is opened.
toolkit.singletonWindowType
Allows configuring the application to allow only one instance at a time.

This is described in further detail in XULRunner:Specifying Startup Chrome Window.

Step 7: Create some XUL

Finally, we need to create a simple XUL window, which is described in the file <tt>main.xul</tt>. Nothing fancy here, just the minimum we need to make a window. No menus or anything:

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<window id="main" title="My App" width="300" height="300"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <caption label="Hello World"/>
</window>
Note: Make sure there is no extra whitespace at the beginning of the XML/XUL file

Step 8: Run the application

The moment of truth. We need to get XULRunner to launch the bare-bones application. From a Windows command prompt opened to the <tt>C:\program files\myapp</tt> folder, we should be able to execute this:

 xulrunner.exe application.ini

Of course, xulrunner.exe must be in the PATH. Because of where I unzipped XULRunner, I could also try this if xulrunner.exe is not in the PATH:

 ..\xulrunner\xulrunner.exe application.ini

On the Mac, you can run the application by opening a Terminal window, navigating to the <tt>myapp</tt> directory, and typing:

 /Library/Frameworks/XUL.framework/xulrunner-bin application.ini

You should now see a window that looks something like this. This particular screenshot is from Windows 2000.

Image:XULSampleMyapp.png

Alternative: Use Firefox3 -app to run XUL apps

With Firefox 3 you can tell the firefox executable to run a XUL application from the command line, instead of the Firefox browser that normally starts. This is similar to starting a XUL app using XULRunner. See {{template.Bug(388833)}}

Download the sample project.

{{template.Next("Windows and menus in XULRunner")}}

Original Document Information

  • Author: Mark Finkle
  • Last Updated Date: October 2, 2006
{{ wiki.languages( { "ja": "ja/Getting_started_with_XULRunner", "ko": "ko/Getting_started_with_XULRunner" } ) }}

Revision Source

<p>
{{template.Next("Windows and menus in XULRunner")}}
This article explores the Mozilla platform by building a basic desktop application using <a href="en/XULRunner">XULRunner</a>. Given that Firefox, Thunderbird, and multiple other applications are written using the platform, it a safe bet that it can be used to build a basic application.
</p><p>I want to build a simple XUL-based desktop application. If you’re going to build a XUL-based desktop application, you’ll probably need to install XULRunner. Let's start by installing XULRunner installed and making sure it runs a bare-bones application.
</p>
<h2 name="Step_1:_Download_XULRunner">Step 1: Download XULRunner</h2>
<p>You can find a download link on the main <a href="en/XULRunner">XULRunner</a> page here on MDC.
</p><p>The XULRunner download for Windows is a zip file, not a true install. As a developer, I like the idea that XULRunner only needs to be unzipped onto my machine. I am assuming that it doesn’t need to hook into my Windows system and that’s a good thing.
</p><p>The Mac version of XULRunner is distributed as a standard Mac OS X installer.
</p>
<h2 name="Step_2:__Install_XULRunner">Step 2:  Install XULRunner</h2>
<p>On Windows, unzip the archive someplace reasonable.  I unzipped it to a new <tt>C:\program files\xulrunner</tt> folder. Pretty simple so far.  On the Mac, just run the installer, which installs XULRunner as <tt>XUL.Framework</tt> in the <tt>/Library/Frameworks</tt> directory.
</p><p>Time to start a simple, bare bones application shell. Call it a XUL “Hello World” if you want. Google turned up a nice tutorial <a class="external" href="http://blogs.acceleration.net/ryan/archive/2005/05/06/1073.aspx">here</a>. It is definitely worth reading. Using the tutorial, I created a simple bootstrap application. All of what you see below can be found in Ryan’s tutorial and the <a href="en/XULRunner">XULRunner</a> documentation here on MDC.
</p>
<h2 name="Step_3:_Create_the_application_folder_structure">Step 3: Create the application folder structure</h2>
<p>On Windows, I created the root in a new <tt>c:\program files\myapp</tt> folder, but you can create it wherever you like.  Here is the subfolder structure:
</p>
<pre>/myapp
  /chrome
    /content
      main.xul
    chrome.manifest
  /defaults
    /preferences
      prefs.js
  application.ini
</pre>
<p>Notice that there are 4 files in the folder structure: <tt>application.ini</tt>, <tt>chrome.manifest</tt>, <tt>prefs.js</tt>, and <tt>main.xul</tt>.
</p>
<h2 name="Step_4:_Set_up_application.ini">Step 4: <tt>Set up application.ini</tt></h2>
<p>The <tt><a href="en/XUL_Application_Packaging">application.ini</a></tt> file acts as the XULRunner entry point for your application. It specifies how your application intends to use the XULRunner platform as well as configure some information that XULRunner uses to run your application. Here is mine:
</p>
<pre>[App]
Vendor=Finkle
Name=Test App
Version=1.0
BuildID=20060101
Copyright=Copyright (c) 2006 Mark Finkle
ID=xulapp@starkravingfinkle.org

[Gecko]
MinVersion=1.8
MaxVersion=1.9.0.*
</pre>
<p><span class="comment">not really... You can find more information about the &lt;tt&gt;application.ini&lt;/tt&gt; file in the article {{mediawiki.internal('XULRunner:Deploying XULRunner 1.8', "en")}}.</span>
</p>
<h2 name="Step_5:_Set_up_the_chrome_manifest">Step 5: Set up the chrome manifest</h2>
<p>The <a href="en/Chrome_Registration">chrome manifest</a> file is used by XULRunner to define specific URIs which in turn are used to locate application resources. This will become clearer when we see how the “chrome://” URI is used. Application chrome can be in a single or a few JAR files or uncompressed as folders and files. I am using the uncompressed method for now. Here is my manifest:
</p>
<pre class="eval"> content myapp file:content/
</pre>
<div class="note">Note: Make sure your application name is lowercase and longer than 3 characters</div>
<h2 name="Step_6:_Set_up_preferences">Step 6: Set up preferences</h2>
<p>The <tt>prefs.js</tt> file tells XULRunner the name of the XUL file to use as the main window. Here is mine:
</p>
<pre class="eval"> pref("toolkit.defaultChromeURI", "chrome://myapp/content/main.xul");
</pre>
<p>XULRunner preferences include:
</p>
<dl><dt> <code><a href="en/Toolkit.defaultChromeURI">toolkit.defaultChromeURI</a></code>
</dt><dd> Specifies the default window to open when the application is launched.
</dd><dt> <code><a href="en/Toolkit.defaultChromeFeatures">toolkit.defaultChromeFeatures</a></code>
</dt><dd> Specifies the features passed to <code><a href="en/Window.open">window.open()</a></code> when the main application window is opened.
</dd><dt> <code><a href="en/Toolkit.singletonWindowType">toolkit.singletonWindowType</a></code>
</dt><dd> Allows configuring the application to allow only one instance at a time.
</dd></dl>
<p>This is described in further detail in <a href="en/XULRunner/Specifying_Startup_Chrome_Window">XULRunner:Specifying Startup Chrome Window</a>.
</p>
<h2 name="Step_7:_Create_some_XUL">Step 7: Create some XUL</h2>
<p>Finally, we need to create a simple XUL window, which is described in the file <tt>main.xul</tt>. Nothing fancy here, just the minimum we need to make a window. No menus or anything:
</p>
<pre>&lt;?xml version="1.0"?&gt;
&lt;?xml-stylesheet href="chrome://global/skin/" type="text/css"?&gt;

&lt;window id="main" title="My App" width="300" height="300"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
  &lt;caption label="Hello World"/&gt;
&lt;/window&gt;
</pre>
<div class="note">Note: Make sure there is no extra whitespace at the beginning of the XML/XUL file</div>
<h2 name="Step_8:_Run_the_application">Step 8: Run the application</h2>
<p>The moment of truth. We need to get XULRunner to launch the bare-bones application. From a Windows command prompt opened to the <tt>C:\program files\myapp</tt> folder, we should be able to execute this:
</p>
<pre class="eval"> xulrunner.exe application.ini
</pre>
<p>Of course, xulrunner.exe must be in the <code>PATH</code>. Because of where I unzipped XULRunner, I could also try this if xulrunner.exe is not in the <code>PATH</code>:
</p>
<pre class="eval"> ..\xulrunner\xulrunner.exe application.ini
</pre>
<p>On the Mac, you can run the application by opening a Terminal window, navigating to the <tt>myapp</tt> directory, and typing:
</p>
<pre class="eval"> /Library/Frameworks/XUL.framework/xulrunner-bin application.ini
</pre>
<p>You should now see a window that looks something like this.  This particular screenshot is from Windows 2000.
</p><p><img alt="Image:XULSampleMyapp.png" src="File:en/Media_Gallery/XULSampleMyapp.png">
</p>
<h3 name="Alternative:_Use_Firefox3_-app_to_run_XUL_apps"> Alternative: Use Firefox3 -app to run XUL apps </h3>
<p>With Firefox 3
you can tell the firefox executable to run a XUL application from the command line,
instead of the Firefox browser that normally starts.
This is similar to starting a XUL app using XULRunner.
See {{template.Bug(388833)}}
</p><p>Download the <a class="external" href="http://developer.mozilla.org/samples/xulrunner/myapp.zip">sample project</a>.
</p><p>{{template.Next("Windows and menus in XULRunner")}}
</p>
<div class="originaldocinfo">
<h2 name="Original_Document_Information"> Original Document Information </h2>
<ul><li> Author: Mark Finkle
</li><li> Last Updated Date: October 2, 2006
</li></ul>
</div>
<div class="noinclude">
</div>
{{ wiki.languages( { "ja": "ja/Getting_started_with_XULRunner", "ko": "ko/Getting_started_with_XULRunner" } ) }}
Revert to this revision