Preferences API

Preferences API enables you to handle software Preferences mostly without programming. The framework is capable of generating a ready-to-use Preferences dialogue box simply by using a set of configuration files. Preferences data is also handled transparently for you by the Framework.


Preferences
API
Configuration file   Preferences Dialogue Box

 

Main features of the Preferences API

Using Preferences API is quite simple, and mostly requires two steps :

  1. write the configuration files describing the preferences of your software;
  2. write a few lines of Java code to enable your software application using Preferences API

Preferences API features:

  • automatic storage using the file system, which is the default settings of the framework;
  • global configuration (i.e. multi-user) vs. user-centric configuration;
  • handling of default values to restore a default configuration;
  • hierarchy of sections (i.e. tree view);
  • integrated inline help messages;
  • localized messages.

 

Start using the framework

To show you how to use Preferences API, we will take a simple example where we would like to add a Preferences dialogue box to an exisiting application ; this sample application is provided with our Tutorial and is called TutorialFourUIStarter (the tutorial package contains all the information related to this example: configuration files and Java code; it is part of download bundle).

The Preferences of our TutorialFourUIStarter enables a user to configure the access to the network though a proxy. So, let's see how to setup that feature with Preferences API.

 

Some definitions

First of all, let's introduce some terms used by Preferences API.

We are going to setup a PreferenceDialogBox, which is made of PreferenceSections that in turn contain PreferenceItems. The most basic dialogue box is made of a single PreferenceSection containing a single PreferenceItem.

These elements form the user interface part of Preferences API. These viewers have to take the information they have to display from some places. By default Preferences API relies on the file system and it needs two types of files for each PreferenceSection : a configuration file and a descriptor. The former contains the values (data part), whereas the latter describes these values (data model part).

To summarize, we setup Preferences API's Preferences Dialogue box with :

  1. a configuation file to store settings values (data);
  2. a descriptor file to describe the data with PreferenceItems and PreferenceForms (data model);
  3. a master descriptor file that assembles PreferenceSections into a PreferenceDialogBox (dialogue box).

More on this now.

 

Setting up a data

We want to configure an access to a proxy: we have to provide at least the proxy address and port. These preference (or configuration) values will be stored within a configuration file. Its unique role consists in storing user-defined values as a set of « key/value » pairs. In our example, we have chosen to define our 'proxy' configuration file as follows:

1
2
proxy.host=
proxy.post=

 

For now, we only declare the two keys, since values are optional at this stage.

 

Setting up a data model

Now, we have to tell Preferences API how to handle our data : this is the role of the descriptor file. Proxy host and port are a String and an Integer, respectively. Here is the way to declare the associated data model : for each PreferenceItem, we have to define a unique ID, a name, a description, a container type and a data type. These elements are used by Preferences API as follows:

  • name and description are used for display purpose within the dialogue box;
  • container and data type enable the automatic control of user-defined values: if we say that an Item if of Integer type, then Preferences API will control that for you;
  • the unique ID is for internal use, but you have to set it.

The general declaration of an item within the descriptor file is as follows:

1
2
3
4
5
item.XXX.name=
item.XXX.desc=
item.XXX.key=
item.XXX.ctype=
item.XXX.dtype=

 

All terms but XXX are reserved words of Preferences API. XXX is the unique ID of the PreferenceItem. Values for 'item.XXX.name' and 'item.XXX.desc' are intended for display purpose and are not constrained. Value for 'item.XXX.key' must be one of the keys declared in the configuration file. Possible values for 'item.XXX.ctype' is one of : atom, choice. Possible values for 'item.XXX.dtype' is one of : integer, real, string, boolean, folder, file.

Let's declare our two items for proxy host and port :

 

1
2
3
4
5
6
7
8
9
10
11
item.host.name=Proxy host
item.host.desc=IP address or name of your proxy computer
item.host.key=proxy.host
item.host.ctype=atom
item.host.dtype=string
 
item.port.name=Proxy port
item.port.desc=Provide here the proxy port (e.g. 3128)
item.port.key=proxy.port
item.port.ctype=atom
item.port.dtype=integer

 

One important notice here : you can see that items 'item.host.key' and 'item.port.key' refer to 'proxy.host' and 'proxy.port', respectively, as defined in the configuration file.

Usually, PreferenceItems are not alone within a section, and we can associate them within a form, using such a declaration:

1
2
form.YYY.name=
form.YYY.items=

 

All terms but YYY are reserved words of Preferences API. YYY is the unique ID of the PreferenceForm. Value for 'form.YYY.name' is intended for display purpose and it is not constrained. In our example, we use the following declaration in our descriptor file:

1
2
form.form1.name=Proxy configuration
form.form1.items=host,port

 

Finally, we declare the full list of items and forms available in our PreferenceSection, like this:

1
2
items=host,port
forms=form1

 

and we give a name and a description to our PreferenceSection, using 'section.name' and 'section.desc' reserved words:

1
2
section.name=Network
section.desc=Network configuration used to access the Internet

 

That's all for the data part.

 

Setting up a Preferences Dialogue Box

Let's now setup our Preferences dialogue box. Again, there is no need to write any Java code here. We just have to setup a descriptor file, as follows.

The general declaration of a section within the master descriptor file is :

1
2
3
4
5
6
7
section.ZZZ.name=
section.ZZZ.descriptor=
section.ZZZ.config=
#possible values: props/raw/none
section.ZZZ.type=props
#possible values: kvp/txt/none
section.ZZZ.editor=kvp

 

All words but ZZZ are reserved to Preferences API. ZZZ is the unique ID of the PreferenceSection. Value for 'section.ZZZ.name' is intended for display purpose and it is not constrained. Values for 'section.ZZZ.config' and 'section.ZZZ.descriptor' are configuration and descriptor file names (only use file name, no path). Value for 'section.ZZZ.type' can be one of : props, raw or none. Value for 'section.ZZZ.editor' can be one of : kvp, txt or none. Finally, value for 'section.ZZZ.parent' can be nothing or another PreferenceSection ID. We will give more details on all these elements later on.

For now, here is a valid declaration :

1
2
3
4
5
section.a.name=Network
section.a.descriptor=proxy.desc
section.a.config=proxy.config
section.a.type=props
section.a.editor=kvp

 

In this example, we give to our PreferenceSection the unique ID 'a', we ask Preferences API to use the provided Key-Value Pair editor (that's the meaning of value 'kvp' assigned to key 'section.a.editor') and we tell Preferences API that it is going to handle a properties configuration file (value 'props' assigned to 'section.a.type').

To finish the master descriptor, we list all available sections :

1
sections=a

 

and we give the Preferences dialogue box a header name :

1
pref.header=My Preferences

 

To summarize, we setup Preferences API's Preferences Dialogue box with :

  1. a configuation file to store the network proxy settings (data);
  2. a descriptor file to describe the data with PreferenceItems and PreferenceForms (data model);
  3. a master descriptor file that assembles PreferenceSections into a PreferenceDialogBox (dialogue box).

It's time to enable the display of the PreferenceDialogBox into our TutorialFourUIStarter application.

First, we put all the configuration/descriptor files within a directory of our choice, and we place the following peace of code while setting up our application:

1
EZEnvironment.setPreferencesConfigurationFile("/path_to_my_configuration_file");

 

When the user selects the Preferences command from the application main menu, the Preferences dialogue box is automatically displayed: