How to use the Preferences Manager

Document #: ??
Authors: Louis Salvail (CWI)
Editor: (none)
Reviewer: (none)
Status: Draft Version. 2 for JDK1.1, SEMPER internal

To be done

General Overview

The Preferences Block works with 4 main classes:

Other classes are needed to help the three others:

How to create a Negotiation Field (other fields are similar)?

Just by specifying the available items, the fieldname and the formatting constraints (optional).
String it[] = new String[6];
it[0] = new String( "item 1" );
it[1] = new String( "item 2" );
it[2] = new String( "item 3" );
it[3] = new String( "item 4" );
it[4] = new String( "item 5" );
it[5] = new String( "item 6" );
PrefFieldNegotiable neg1 = new PrefFieldNegotiable( new String("neg1"), it, 4, cs);

Here cs is the constraints for the position of that field in the group. They are GridBagConstraints from the stantard awt package. If you are not concern with these constraints, you always have access to a constructor with no constraints. In that case defaults are used. Every field is then put one below the previous one. From the previous exemple: PrefFieldNegotiable neg1 = new PrefFieldNegotiable( new String("neg1"), it, 4);
Now the description for that field can be set by
neg1.setDescription("The description intendended to the user. /n This will appear when the left mouse button is doubleclicked.");
The surface of reaction to the double-clicked depends on the particular field. A PrefFieldString for instance, does not react on double-clicking over the text area but just on the label area. A PrefFieldList does not react on the list component but everywhere else. Therefore it is possible that before getting the description the mous has to be moved a bit.

How to create a Group?

groupe1 = new PrefGroup(new String("G1"), new String("Group 1"));
groupe2 = new PrefGroup(new String("G2"),new String("Group 2"));
This two lines create two groups . To put a field in a group just call the method put() provides by the PrefGroup class. To add neg1 in the group groupe1 just perform: groupe1.put(neg1);
You just have to continue like that until all fields are added in the group.

For more details on how to create groups see the file in the Test directory.

How to create a Preferences environment?

To create a preferences environment, you just have to add group in the Preferences class. If groupe1 and groupe2 have already been defined, you can add them by doing:

How to create subgroups?

In order to create a menu structure from which the user selects the group he wants to edit, the following can be used. Assume that group1,group2 and group3 have been defined and added to the preferences manager like described above: Preferences.addToSubGroup(groupe2.getName(),"SuperGroup");
The result is that:

By default when a new group is added to the preferences manager whithout specifiying in which subgroup it will appear, the group will be put at the root level. That means that the group will be accessible at the first level of the menu structure. Do not confuse groups and subgroups, they are different things. A group is a PrefGroup object while a subgroup is just a string. Subgroups are only used to display the menu structure. For the preferences manager all preferences groups are at the same level.

In order to retrieve the menu structure currently defined in the preferences manager one should use: Preferences.getMenuStruct(pref_menu); where pref_menu is an object of class java.awt.Menu.

How to get the values?

To get the values for a particular field, you must first retrieve the group which contains the field you are looking for: group = Preferences.getGroup("G1");
Now group contains the group having the name "G1". Then you can get the the field with name "neg1" by doing: field = group.get("neg1");
The field value is then obtain by calling: val = field.getVal();
In that case, since that field is PrefFieldNegotiable field type the value returned by getVal() is a vector. Thus, val.size() is the size for that vector and val[i] contains the i^th string items in priority selected by the user.

Also available is the Test package where you can learn how to use the Preferences manager by examples.

Date: August, 1996 .