Your DesktopX Documentation Resource Guide

Documentation Home

Quick Start

User's Guide

Developer's Guide

Resources

Tutorials

Widgets preferences

DesktopX 3.0 widgets and gadgets can use an integrated mechanism to manage user preferences.
A “preference” is a local per-user setting that is initially set to a default value and then maintained across multiple executions of the same widget for the same user.
Widget preferences can integrate into the standard widget properties dialog, or can be kept hidden if the author only likes to use persistency and not the interactive feature.

Preferences should be configured in script in Object_OnScriptEnter.
To add a preference object use:

Widget.AddPreference "PreferenceName"

To access a preference object use:

Widget.Preference("PreferenceName")

To access a preference property use:

Widget.Preference("PreferenceName").property

Example:

Widget.AddPreference "ZIPCode"
Widget.Preference("ZIPCode”).Type = "Text"
Widget.Preference("ZIPCode”).Caption = "ZIP Code"
Widget.Preference("ZIPCode ").DefaultValue = "12345"
Widget.Preference("ZIPCode").Description = "It defines the ZIP area code to be used by the weather widget"

It creates a ZIPCode item of Text type and is initially set to “12345” with the given description for the Properties panel.

To access the configured value you can later use:

Widget.Preference("ZIPCode ").Value

When the user changes the preferences through the Widget Properties dialog, the script that configured the preferences receives the following event:

Sub Widget_OnPreferencesChange()

Here is the complete Preference namespace reference:

Widget.AddPreference “name”

Adds a new preference item. The name should not contain spaces. Use Preference.Caption to assign a pretty name.

Preference.Type

String property. It defines Valid types are:
“Hidden”: No control will be displayed in the Widget properties panel. Hidden is the default type.
“Text”: Text box control type.
“Password”: Text box with obfuscated characters for password entries.
“Checkbox”: Checkbox control. Values for checkboxes are “1” or “0”.
“ComboEdit”: Editable text combobox control.
“ComboList”: Dropdown list combobox control.
“Slider”: Slider control. Values for sliders are still in string form.
"File": Edit control with Browse File feature
"Folder": Edit control with Browse Folder feature
"Font": It is a "ComboEdit" preference, but it is automatically filled with available Font names.
"Color": It provides a color picker preference.
"Hotkey": Hotkey selection control. You can directly pass preference value to Object.RegisterHotkey like:

Object.RegisterHotkey myHotkeyID, Widget.Preference("myHotkey").Value

Preference.Caption

Sets the pretty name used to name the preference in the Properties panel.

Preference.DefaultValue

Use to set the preference default value.

Preference.Description

Use to set the preference description that appears in the Widget properties panel.

Preference.AddValue

Use to add an item to a Combobox preference.
Example:

Widget.Preference("MyCombo1").AddValue "Green"
Widget.Preference("MyCombo1").AddValue "Red"

Preference.MinValue, Preference.MaxValue

Use to configure the minimum and maximum values of a slider preference.

Example:

Widget.Preference("Slidersample").MinValue = 1
Widget.Preference("Slidersample").MaxValue = 5

Preference.Ticks

It specifies the ticks distance for slider preferences.

Example:

Widget.Preference("Slidersample").MinValue = 10 ‘page size of 10 and displayed tick each 10 values.

Sub Widget_OnPreferencesChange

Sent when the user applies the preferences in the Widget properties panel.