Adding Configurable Panel Properties

About Panel Properties

Your panels can have settings that can be configured by the user to change the behavior of the panel. These settings will be saved automatically by Desktop Sidebar. This allows the panel to save all the customizations the user has made.

Defining Properties

In order for Desktop Sidebar to know about your panel's properties, you have to define them in the panel file. Properties are defined inside the main <panel> element, in an element named <properties>. The following example of a panel file illustrates where properties are defined.

The <properties> element contains <page> elements, one for each tab page in the panel's configuration dialog box (the Panel Properties dialog). The <page> element has a name attribute - this value will be the title of that tab page. In each <page> element, the actual properties are defined.

An example is better than any explanation, so here it is: the panel's <properties> element might look similar to the following (the blank areas will be explained in the next section).

The following image is an example from the real Azureus panel.

As you have probably understood, every property is defined by adding a <property> element inside any <page> element. The property will then be displayed inside that tab page. The <property> element has attributes that define what kind of property it is. The available attributes are:

• name - the internal identifier of the property by which it will be accessed from the panel's script. This attribute is required (the only exception is the tip below).
• label - the text that will be displayed next to the property in the Panel Properties dialog box.
• default - sets the default value that will be assigned to the property when a user first adds the panel to Desktop Sidebar.
• type - the type of the property, which defines its appearance in the Panel Properties dialog. Can be set to the values: "text", "number", "checkbox", "listbox", "color", "file", "directory". For more details, see the Property Types section.

In addition to the label, a property can contain a more detailed description that will accompany it in the Panel Properties dialog box. This description is written inside the element, like the following sample.

Tip: if you don't specify a type attribute for a property, it will only be displayed in the Panel Properties dialog box and will have no actual value. This feature can be used to create an About tab page for your panel, like the following example.

(Notice the use of the CDATA clause - this is in order to keep the text formatted exactly as it is, with line breaks and all. "CDATA" will not actually be shown.)

This will yield the nice result: