Category: Javascript

Last time I covered some simple XUL for creating windows, menus and toolbars. This time I’ll look at dialogs, your own and common OS dialogs too. Dialogs are pretty fundamental to a desktop application. Certain types of dialogs are used over and over. So much so that the OS can provide a default implementation. File open and save are good examples. Whenever possible, it is a good idea to reuse these ‘native’ dialogs so users get a consistent experience across applications.

Custom Dialogs

Building dialogs in XUL is very similar to creating windows. Each dialog seems to be in it’s own XUL file. Also like windows, XUL provides a

function openDialog() {
  window.openDialog("chrome://basicapp/content/dialog.xul", "newdlg", "modal");
}

function doFileOpen() {
  /* See: http://developer.mozilla.org/en/docs/XUL_Tutorial:Open_and_Save_Dialogs */
  
  var nsIFilePicker = Components.interfaces.nsIFilePicker;
  var fp = Components.classes["@mozilla.org/filepicker;1"].createInstance(nsIFilePicker);

  fp.init(window, "Open File", nsIFilePicker.modeOpen);
  fp.appendFilters(nsIFilePicker.filterText | nsIFilePicker.filterAll);
  
  var res = fp.show();
  if (res == nsIFilePicker.returnOK) {
    var thefile = fp.file;
    alert(thefile.leafName);
    // --- do something with the file here ---
  }  
}

I want to build a simple XUL-based Windows desktop application. If you’re going to build a XUL-based desktop application, you’ll probably need to install XULRunner. In this post, I try to get XULRunner installed and make sure it runs a bare-bones application.

Step 1 – Download XULRunner: The Mozilla developer page lists 1.8.0.1 as the most recent release, but I see there is also a 1.8.0.4, so that is the one I downloaded. UPDATE: 1.8.0.4 release and SDK are available from Mozilla FTP.

The XULRunner download 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.

Step 2 – Install XULRunner: I unzipped the archive to a new “c:\program files\xulrunner” folder. Pretty simple so far.

Time to start a simple, bare bones application shell. Call it a XUL “Hello World” if you want, but I need to make sure that XULRunner will work at all. Googling turned up a nice tutorial here. It is definately 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 Mozilla XULRunner documentation pages.

Step 3 – Create application folder struture: I create the root in a new “c:\program files\xulapp” folder. Here is the subfolder structure:

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

Notice that there are 4 files in the folder structure: application.ini, chrome.manifest, prefs.js & main.xul

Step 4 – Setup application.ini: The application.ini file acts as the XULRunner entry point for your application. It seems to be used to configure 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.8

Step 5 – Setup Chrome Manifest: The chrome manifest file is used by XULRunner to define specific URI’s which in turn are used to locate application resources. This will become clearer when we see how the “chrome://” URI is used. Applications can be distributed compressed in a JAR file or uncompressed as folders and files. I am using the uncompressed method for now. Here is my manifest:

content myapp file:content/

Step 6 – Setup Preferences: The prefs.js files is used to tell 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
• toolkit.defaultChromeFeatures
• toolkit.singletonWindowType

Step 7 – Create some XUL: Finally, we need to create a simple XUL window. Nothing fancy here, just the minimum we need to make a window. No menus or anything:

Step 8 – Run the App: The moment of truth. We need to get XULRunner to launch the bare-bones application. From a command prompt opened to the “c:\program files\myapp” 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

Success! Here is a screenshot of the bare bones application running on Win2K:

My next step will be to add much more to the bare bones application. I want to explore as much of XUL as I can as fast as I can. For those that want to skip straight to the end, here is a ZIP of the My App application:

My App sample

After a short break, I am back to working with the Mozilla platform (XUL, JavaScript & XPCOM). I want to begin exploring the platform by building a basic desktop application using XULRunner. Given that Firefox, Thunderbird and the rest of the Mozilla suite is written using the platform, it a safe bet that it can be used to build a basic application. However, I know nearly nothing of the Mozilla platform, so I need to start somewhere.

I consider a basic desktop application to at least be able to support:

• Main window, popup windows and dialogs (modal and non-modal)
• Menus and toolbars (with images and themes)
• Basic assortment of controls (edits, buttons, checkboxes, radiobuttons, lists, trees & tabs)
• OS common dialogs (file open & save at a minimum)
• Clipboard operations
• Printing
• Help system

Alright, I am off to build my basic application. I’ll update this post as I go. I wouldn’t go so far as to call it a tutorial, but I’ll link to any tutorials I find along the way.

Update:

1. Getting Started with XULRunner
2. UI Basics [Part 1]
3. UI Basics [Part 2]