Creating a Preferences Window

Most toolbars include a window from where the appearance and behavior of the toolbar can be customized. This window is often called an “Options Windows” or a “Preferences Window”. This tutorial will take you through the process of creating one for a simple toolbar.

It may help to check the tutorial on DTX Windows, if you haven’t done it already.

The first step would be to create the XML for the preferences window. Go to your toolbar chrome\content folder. Create a file named “mypreferences.xml” and add the following lines:

<?xml version="1.0" encoding="utf-8" ?>
<prefwindow xmlns="http://www.vmn.net/dtx/v1"
id="mytoolbar-preferences"
center="true"
dialog="true"
ontop="true"
title="MyToolbar Preferences">
<prefpane
label="Toolbar"
id="mybar-pref-general"
for="mybar-home"
image="chrome://mytoolbar/skin/pref-main.png" />
<prefpane
label="Search"
id="mybar-pref-search"
for="mybar-search"
image="chrome://mytoolbar/skin/pref-search.png" />
</prefwindow>

The top node is a “prefwindow”. This is an element that inherits from the “window” element and adds some new traits that would make sense only in a Preferences Window.

The “center” attribute will center the window on screen. The “dialog” attribute will show a dialog border around the window. The “ontop” attribute will make sure the window remains on top of the toolbar at any given time. Finally, the “title” attribute sets the title that will be shown in the caption bar for the window.

Let’s then take a look at the child “prefpane” elements. A preference window may contain several panels that may be used to organize the toolbar preferences in different main topics. You can think of them as regular tabs where you can have a tab for each feature of the toolbar.

In this tutorial we will be adding two tabs: one for the general toolbar options and another for search options. That’s the reason there are two “prefpane” elements: the first one is for general options and the second for search options.

The “label” attribute sets the text that will appear on the tab. The “image” attribute can be used to set an icon for the tab. Tab icons may have any dimensions you want, but it is recommended they all have the same size. This will create a more pleasant look.

The “for” attribute actually controls the contents displayed on the panel once its tab is selected. This attribute contains the ID of an object in the toolbar that will provide the contents of the panel. For instance, in the search panel the “for” attribute is set to “mybar-search”. This means that there must be one element in the toolbar having “mybar-search” as its ID. The same applies to the “Toolbar” tab.

The XML for the toolbar would be something like the following:

<toolbar>
<toolbarbutton id="mybar-home" label="My Bar" />
<searchbar id="mybar-search" />
</toolbar>

When the preferences dialog is about to show, the contents of each panel is dynamically provided by the objects specified in the “for” attribute of the panel. In this case both the home “toolbarbutton” and the “searchbar” elements will be asked to contribute their options.

This is done by sending a special event: “getoptions”. The element may respond to the event by inserting a set of UI elements that control its appearance in a container that is passed along with the event. If a handler for this is not provided, the element may insert a default set of controls. For instance, the “searchbar” element will add checkboxes to control the word highlighter, suggestions and history options.

Let’s add a handler for this event in the home button as shown below:

<toolbar>
<toolbarbutton id="mybar-home" label="MyBar"
ongetoptions="mybar.getHomeOptions(this)" />
<searchbar id="mybar-search" />
</toolbar>
Now, when the home button is asked for its options, the “getHomeOptions()” function will be called to provide them. Let’s add this function to the toolbar’s JavaScript code:
mybar.getHomeOptions = function(event) {
var checkbox = mybar.framework.createElement("checkbox");
checkbox.setAttribute("label", "Show Search");
var search = mybar.toolbar.getElementById("mybar-search");
if (search.getAttribute("hidden") != "true")
checkbox.setAttribute("checked", "true");
else
checkbox.setAttribute("checked", "false");
checkbox.addEventListener("command",
function() {
if (checkbox.getAttribute("checked") == "true")
search.setAttribute("hidden", "false");
else
search.setAttribute("hidden", "true");
}
);
var panel = event.node;
panel.appendChild(checkbox);
}

This handler adds a checkbox to the options panel, and the checkbox controls whether the “searchbar” element is visible or not. Here is a more detailed look at the event handler:

var checkbox = mybar.framework.createElement("checkbox");
checkbox.setAttribute("label", "Show Search");

This creates a new instance of a “checkbox” element and sets the checkbox’s label to “Show Search”.

The next section will set the “checked” attribute for the checkbox. The checkbox should appear checked if the “searchbar” element is visible and not checked if the “searchbar” element is hidden:

var search = mybar.toolbar.getElementById("mybar-search");
if (search.getAttribute("hidden") != "true")
checkbox.setAttribute("checked", "true");
else
checkbox.setAttribute("checked", "false");

The next line adds an event handler for the checkbox. This handler will be called every time the user flips the state of the checkbox. Depending on whether the checkbox is checked or not, it will hide or show the “searchbar” element by modifying its “hidden” attribute.

As you can see, configuration of elements in DTX happens on the fly. This means users can immediately see on the toolbar the results of the changes they make. This also means there are no OK and Cancel buttons in the Options window.

If you want any of the changes made by the user to persist from one session to the next, you must set those attributes to persist. For instance, if we want the “searchbar” element to remain hidden, we would need to set its “persist” attribute.

The resulting XML would be as follows:
<toolbar>
<toolbarbutton id="mybar-home" label="MyBar"
persist="hidden"
ongetoptions="mybar.getHomeOptions(this)" />
<searchbar id="mybar-search" />
</toolbar>

This covers the basics of preferences in DTX. If you need more customization than this, it is also possible to sub-class the “prefwindow” element into a class of your own, but this is beyond the scope of this tutorial.

To actually display the Preferences window you may follow any method you want. We recommend you look at DTX windows tutorial to discover which alternative fits you best.