If you want to make a program that you plan to give to other people to use, you will probably find that they will want some sort of preferences dialog. Something to change the settings of the program to match their particular set up. In today's example, we want users to be able to make an email checker. The email checker is different for each user. They have their server, user name and password. So how do we let users of our widget set these things?
In DesktopX 2, you would do this on your own by creating your own special panels that you designed yourself. This had the benefit of letting the author have a lot more control over presentation but it was very time consuming. Some widget enabling programs do all this in a separate XML file that the program then uses to create a standard preferences dialog. This is, in my view, superior to what was in DesktopX 2.
So let's think about how we want users to enter in their User Name, Password, and Server name. In DesktopX 3 you create a widget like this:
Widget.Preference(PREFERENCENAME).Type = TYPE
So we authors would fill in PREFRENCENAME and TYPE . For the former, you can call it anything like "Password". For the latter, you have to pick one of the control types DesktopX 3 supports which 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.
So in this case I would pick two text fields for the server name and user name and the password field for the password (password being the same as text but obfuscated).
The screenshot above contains the example code for our mail preference. There's a second piece we need, and that is, what we do when someone actually does something in the preferences:
A new call is added by the system: Widget_OnPreferenceChange. In this case, we call a function called RefreshData that we've written and another one called CheckMail that we've written.
sLogin = Widget.Preference("User").Value 'object.localstorage("MailLogin")
sPass = Widget.Preference("Password").Value 'object.localstorage("MailPass")
sServer = Widget.Preference("Server").Value 'object.localstorage("MailServer")
sType = Widget.Preference("Type").Value 'object.localstorage("Type")
In this function, we save the data from our preferences dialog with the DesktopX storage system so that you don't have to keep entering this data every time you load the widget.
When the widget is made, the preferences tab becomes part of the properties dialog for that widget. So now I can not only control how the widget looks and behaves and set the hot key to activate it, but I can now configure it right from the same place.