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.

<?xml version="1.0" encoding="utf-8"?> <plugin> <panel> <!-- Various panel elements go here... --> <properties> <!-- Define your properties here --> </properties> </panel> </plugin>

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).

<properties> <page name="General Settings"> <property ... /> <property ... /> </page> <page name="Another Tab"> <property ... /> </page> </properties>

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:

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.

<property name="test" label="Test Property:" type="text" default="testing the value"> This is the description of this test property. </property>

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.

<properties> <!-- Real pages and properties go here... --> <page name="About"> <property> <![CDATA[ This panel was developed by Myself. Copyright 2006. This panel does such and such and is very user friendly. :-) ]]> </property> </page> </properties>

(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: