Property Types

Please read the Adding Configurable Panel Properties guide before continuing, if you haven't already done so. As that guide states, each property has a type that defines its appearance in the Panel Properties dialog. This type is specified by setting the <property> element's type attribute. This article will list the available types and give specific detail for each type.

text

A property of this type displays an editable text-box control in the dialog box that allows the user to type in any text.

number

Displays a text-box control in the dialog box. The data is validated - only numbers can be entered, and no other characters. This number is a whole number - a period ('.') cannot be entered.

checkbox

Displays a checkbox control in the dialog box, that allows users to configure a yes/no option.

When you get the value of this property in the panel's script:
-1 represents the state where the checkbox is checked,
0 represents the state where the checkbox is NOT checked.

listbox

Displays a list box control in the dialog box - a list of values from which the user can choose one value. The list items that the user can select in the list are specified as children of the <property> element, inside an <items> child, like in the following example.

<property name="listProperty" label="Choose an item:" type="listbox" default="firstValue"> <items> <item label="This is the First Value" value="firstValue" /> <item label="Nothing Important Here" value="blahBlah" /> <item label="Choose Me!" value="chooseMe" /> </items> </property>

The label attribute is the name of the list item as shown to the user. value is the real value of the property that will be returned in the panel's script.

color

Displays a color picker control in the dialog box that allows the user to choose any RGB color.

The default value of this property is set using HTML-style hexadecimal values, for example, "#FF00FF" for magenta.

<property ... type="color" default="#FF00FF">

However, the value of this property in the script is a decimal representation of the color value. To convert this value to the hex representation (in order to display it in an HTML Details Windows, for example), use the following line of code:

var hexColor = "#" + parseInt(config.GetSetting("myColorProperty")).toString(16);

Warning: the color property type is buggy in build 116, but fixed in later builds.

file

Displays a text box in which the path can be manually entered. Next to the text box, there is a Browse button that when clicked opens the standard Open File or Save File dialog boxes where the user can open/save a file.

A style attribute may be added to the <property> element. The value of this attribute can be either "open" or "save", displaying either the Open File or the Save File dialog boxes, respectively.

Additionally, if you want to specify file type filters for the Open/Save dialogs, this property can contain an <items> child, which contains several <item> elements to list the available file types. For example:

<property name="someFile" label="Choose a file:" type="file" default="$appData\myfile.tmp" style="open"> <items> <item label="My Panel Files (*.tmp, *.test, *.exe)" value="*.tmp;*.test;*.exe" /> <item label="All Files" value="*.*" /> </items> </property>

The label is the text displayed to the user, and the value is the actual file extensions, seperated by semi-colons (';').

directory

Displays a text box in which the directory path can be manually typed. Next to the text box, there is a Browse button that opens the standard Open Folder dialog where the user can choose a directory.

Note: the default value of this property (the default attribute) can contain the $appData flag that will be replaced by Desktop Sidebar with the actual Application Data directory path.