Spotfire.Dxp.Framework.Preferences Namespace TIBCO Spotfire 7.0 API Reference
The Spotfire.Dxp.Framework.Preferences namespace contains base classes and registries for extending TIBCO Spotfire with new preference types.
Classes

  Class Description
Public class PreferenceBase
Base class for Preference implementations.
Public class PreferenceManager
Provides functionality to retrieve and set preferences for the currently logged on user. There is only one object of this type available in the application. This instance is registered as a top-level service and can be accessed through one of the service provider methods. New instances of this type cannot be created.
Public class PreferenceObject T 
A preference object is a named value that can be stored on a user, group, and global level. Preference objects are managed through the PreferenceObjectService, using which new objects can be added, removed, and queried. The addition and removal of objects is, however, only available on a user (personal) level. Adding preference object to one or more groups is only available through the user interface of the application itself.

A preference object consists of a unique identification (a name) within its preference object class (see below), and the actual value. This means that two different users cannot create an object with the same name within the same preference object class.

The value type of a preference object is generic to reflect the type of the preference class it belongs to. To be able to persist preference objects, the value type must be serializable. In addition, it is also recommended for the type to be immutable, that is, it should not be possible to change the state of objects of that type through public property setters or methods.

Once added to the PreferenceObjectService, preference objects are fully managed by that service and synchronized with the server. If the Value of the preference object changes, the ValueChanged event is fired with a PreferenceObjectValueChangedEventArgs T  containing the previous and the new value. Through this event, the PreferenceObjectService can track changes and reflect them both locally and on the server. However, if the value type of the object is not immutable and its internal state changes, the event is not fired and the changes will not be detected by the manager. In such cases, it is absolutely necessary to explicitly requested for the changes to be persisted through a call to ApplyChanges T (PreferenceObject T ).

In some cases it is not possible to alter the value of a preference object. Whether or not the value of an object can be changed is reflected through the IsReadOnly property. Objects that are inherited from the group or those that are global are examples of read-only objects.

A group of (that is, one or more) preference objects belong to one preference class. One such class is globally identified through its name (a string), for example MyPreferenceObjects or Spotfire.Dxp.PreferenceObjects. Note that a preference class does not physically exist either locally or on the server. They are comparable to the concept of namespaces in .Net programming languages. All preference objects belonging to the same preference class must have the same value type T. This implies that classes should be logically named to hold preference objects for a well defined area.

It is possible to define default preference objects at group and application level. Such default objects are used as fallback objects, for example when searching a class (see Find T (String, T, PreferenceObjectIdentifier)).

Public class PreferenceObjectIdentifier
Public class PreferenceObjectService
Provides functionality to retrieve, add, and delete preference objects for the currently logged on user. There is only one object of this type available in the application. This instance is registered as a top-level service and can be accessed through one of the service provider methods. New instances of this type cannot be created.

A preference object defines a value that can be set as a preference. All preference objects are ordered in preference classes which defines categories of preference values.

Preference objects created through this service, are cached locally on the computer until synchronized with the server, at which point the settings are written to the server. The synchronization procedure is automatically managed, but doing so requires the application to be connected to the server.

When this service is initialized during application start-up, it will synchronize with the server to download new preference objects that may have been added for the currently logged on user. This, again, requires a connection to the server.

Public class PreferenceObjectValueChangedEventArgs T 
Event argument used when a preference objects value has changed.
Public class PreferenceProperty T 
One or more preference properties constitute a preference implemented as a type extending PreferenceBase. Each preference property is identified by a name and the Category and SubCategory of the preference that it is contained in.

The value of a preference property is decided through inheritance, where user values always have precedence before group values, that is, a user can override that value of a property inherited from a group. The same way, a group can override the value of a parent group. In addition, the preference property may have a default values which is returned when neither parent group(s) nor the user has defined a value for the property.

Each property is also associated with a version number. This version number must always be increased if the property is changed from the prior version such that the new version cannot be interpreted by older version through the default behavior of the .Net serialization framework. For instance, if the type T is changed from String to Int32, the version number should be increased. The version number should also be increased if properties are added to or removed from T.

Public class PreferencePropertyBase
Delegates

  Delegate Description
Public delegate PreferenceProperty T  DefaultValueCalculatorCallback
Delegate that calculates a default value for the preference property.
Enumerations

  Enumeration Description
Public enumeration PreferencePersistenceScope
Specifies identifiers to indicate the scope of preference persistence, that is, whether to store it locally or on the server.
Public enumeration PreferenceUsage
Specifies identifiers that define the usage of a preference.