Creating Python GUI Applications using XULRunner

Customizing the Application

The application UI is separated into three main components, the structure, the styling and the events. Generally in Mozilla these three parts are labeled as chrome. The chrome is where you'll spend most of your time making application changes and thankfully these parts are also generally platform independent, so most of the time you don't need to worry about what platform your application will be running upon... it will look and operate the same way on all platforms.

Structure

Structure is controlled by XUL which is an XML User Interface Language, quite similar to HTML. Your XUL files are stored in the pyxpcom_gui_app/chrome/content/*.xul. Taking a look at the main xul file pyxpcom_gui_app.xul shows the actual elements of the application, like the menus, the browser component and the statusbar.

Try adding a few items of your own above the <browser element and then restart the application:

  <label id="url_label" value="URL: " />
  <textbox id="url_textbox" value="http://www.python.org/" />
  <button id="url_button" label="Go" />
          

You'll notice that the items you have added are placed one by one vertically down the page, so a change in direction can easily be done through a XUL box (xul boxes are the bread and butter of component layout). In our case we need a horizontal box, which is the hbox.

  <hbox id="url_layout_box" align="center">
    <label id="url_label" value="URL: " />
    <textbox id="url_textbox" flex="1" value="http://www.python.org/" />
    <button id="url_button" label="Go" />
  </hbox>
          

You may notice the flex attribute on the textbox, this lets our textbox stretch itself in size to fill available horizontal space. The align="center" attribute on the hbox will ensure each element is placed into the center of the box.

Styling

Styling of the application widgets gets controlled by CSS. You'll notice there is a reference to the pyxpcom_gui_app.css at the top of the XUL file. This is the styling control used by your application (your xul file can reference multiple css files) and is stored at pyxpcom_gui_app/chrome/skin/standard/*.css. Try modifying the css to change some widgets, the example below changes the hbox background to a different shade of gray:

#url_layout_box {
  background-color: #CCCCCC !important;
}
            

CSS is great to use for updating images and button status, for example, setting an "action=stopped" attribute on a button element may be used for updating the button's image to a stop icon.

Events

The Events occurring in XUL applications are handled and controlled by script handlers, which can be written in either JavaScript or Python. You can setup a widget to respond to particular events, which will trigger your specified script functions.

As an example, here is how to modify the "Go" button you previously added to actually respond to click/command events. Update the XUL button to contain the following script handler:

<button id="url_button" label="Go" oncommand="goButtonOnCommand(event)" />
            
Now we need to add the handler script code for this function, which we add to the script handler file pyxpcom_gui_app.py:
def goButtonOnCommand(event):
    # Check if the textbox URL has changed.
    new_url = document.getElementById("url_textbox").value
    browser_elem = document.getElementById("browser")
    if browser_elem.getAttribute("src") != new_url:
        # Point the browser to the new URL.
        browser_elem.setAttribute("src", new_url)
            
Updating the textbox to be "http://www.mozilla.org/" and clicking on the "Go" button takes you to the new web page. You have the makings of your own custom browser.

What other methods are available on the document, what is this document anyway, you can find these things out at:

Try resizing your application, you'll notice how XUL handles the window resize automatically and in accordance with your flex attributes will resize the XUL elements to meet the new space.

Here is a list of other events that your XUL widgets can respond to: XUL Events.