PreferenceModel (docking-frames-core 1.1.2p20b.fix-1 API)

All Known Implementing Classes:

AbstractPreferenceModel, BubbleThemePreferenceModel, ButtonContentPreferenceModel, DefaultPreferenceModel, DockingFramesPreference, EclipseThemePreferenceModel, KeyStrokePreferenceModel, LayoutPreferenceModel, MergedPreferenceModel, PreferenceTreeModel
```
public interface PreferenceModel
```
A preference model is a layer between the framework and its properties, and the dialog, table or tree with which the user can modify these properties. A model consists of "preferences", each preference is a wrapper around a single property. A preference also serves as buffer: modifying a preference does not immediately change the property. Clients have to call read() to fill the preference-buffers, and have to call write() to write changes back.
The framework stores and loads some properties automatically, the preferences for these properties are called "natural". If on the other hand the framework assumes that a property is managed by the client, its preference is called "artificial". Clients have to use a PreferenceStorage to persistently store and load the artificial preferences.
A preference model also offers information of how to present its preferences to the user.
The typical lifecycle of a PreferenceModel looks as follows:
1. A PreferenceStorage is created and its content loaded using one of its read-methods.
2. The new, empty model is created.
3. With a call to PreferenceStorage.load(PreferenceModel, boolean) the artificial and natural preferences are loaded.
4. With a call to write() all preferences are made available to the entire framework.
5. At any time a call to read() will update the contents of the model.
6. At any time a call to write() will make modified preferences available to the entire framework.
7. With a call to PreferenceStorage.store(PreferenceModel) the preferences are stored.
8. Using one of the write-methods of the PreferenceStorage the client can store the preferences persistently
Note that many PreferenceModels can share the same PreferenceStorage. In such a case its best to re-create and refill the models before using them.
Author:

Benjamin Sigg

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addPreferenceModelListener(PreferenceModelListener listener)` Adds a listener to this model.
`void`	`doOperation(int index, PreferenceOperation operation)` Executes the enabled operation `operation`.
`DockController`	`getController()` Gets the `DockController` in whose realm this model is used.
`String`	`getDescription(int index)` Gets a description of the `index`'th object.
`String`	`getLabel(int index)` Gets a short label that can be presented to the user for the `index`'th object.
`PreferenceOperation[]`	`getOperations(int index)` Gets all operations for which this model has a definition for the preference at location `index`.
`Path`	`getPath(int index)` Gets the unique identifier of the `index`'th preference of this model.
`int`	`getSize()` Gets the number of preferences stored in this model.
`Path`	`getTypePath(int index)` Tells what kind of type the `index`'th value is.
`Object`	`getValue(int index)` Gets the `index`'th preference.
`Object`	`getValueInfo(int index)` Gets information about how the `index`'th value can be modified.
`boolean`	`isEnabled(int index, PreferenceOperation operation)` Tells whether the operation `operation` is enabled for the preference at location `index`.
`boolean`	`isNatural(int index)` Tells whether the `index`'th preference is natural or artificial.
`void`	`read()` Uses an unknown source to update this model and load all the preferences that are currently available.
`void`	`removePreferenceModelListener(PreferenceModelListener listener)` Removes a listener from this model.
`void`	`setValue(int index, Object value)` Sets the value of the `index`'th preference.
`void`	`setValueNatural(int index)` Like `setValue(int, Object)` this method changes the value of the `index`'th preference.
`void`	`write()` Writes the current preferences to the location where they are used.

- Method Detail
  - getController
```
DockController getController()
```
    Gets the DockController in whose realm this model is used. The controller is mainly necessary to load icons and text.
    
    Returns:
    
    the controller in whose realm this model is used
  - read
```
void read()
```
    Uses an unknown source to update this model and load all the preferences that are currently available. If the underlying resource cannot be read, or returns invalid data, then this model should not change its content.
  - write
```
void write()
```
    Writes the current preferences to the location where they are used.
  - addPreferenceModelListener
```
void addPreferenceModelListener(PreferenceModelListener listener)
```
    Adds a listener to this model.
    
    Parameters:
    
    listener - the new listener
  - removePreferenceModelListener
```
void removePreferenceModelListener(PreferenceModelListener listener)
```
    Removes a listener from this model.
    
    Parameters:
    
    listener - the listener to remove.
  - getSize
```
int getSize()
```
    Gets the number of preferences stored in this model.
    
    Returns:
    
    the number of preferences
  - getLabel
```
String getLabel(int index)
```
    Gets a short label that can be presented to the user for the index'th object.
    
    Parameters:
    
    index - the number the preference
    
    Returns:
    
    a short human readable description
  - getDescription
```
String getDescription(int index)
```
    Gets a description of the index'th object. The description is a longer text that will be presented to the user.
    
    Parameters:
    
    index - the number of the preference
    
    Returns:
    
    the description, might be null, might be formated in HTML
  - isEnabled
```
boolean isEnabled(int index,
                  PreferenceOperation operation)
```
    Tells whether the operation operation is enabled for the preference at location index.
    
    Parameters:
    
    index - some location
    
    operation - an operation from getOperations(int)
    
    Returns:
    
    true if the operation is enabled, false if not
  - getOperations
```
PreferenceOperation[] getOperations(int index)
```
    Gets all operations for which this model has a definition for the preference at location index. Note: a PreferenceEditor has operations as well, if the editor and the model share an operation, then the operation is considered to belong to the editor.
    
    Parameters:
    
    index - the location of a preference
    
    Returns:
    
    the list of available operations (enabled and disabled operations), can be null
  - doOperation
```
void doOperation(int index,
                 PreferenceOperation operation)
```
    Executes the enabled operation operation.
    
    Parameters:
    
    index - the location of the affected preference
    
    operation - the operation to execute
  - getValueInfo
```
Object getValueInfo(int index)
```
    Gets information about how the index'th value can be modified. For an integer that might be its upper and lower boundaries. The type of this objects depends on getTypePath(int).
    
    Parameters:
    
    index - the index of the info
    
    Returns:
    
    the information or null if no information is available
  - getValue
```
Object getValue(int index)
```
    Gets the index'th preference. The type path determines how the value is to be presented on the screen.
    
    Parameters:
    
    index - the number of the preference
    
    Returns:
    
    the value or maybe null, has to be immutable
  - setValue
```
void setValue(int index,
              Object value)
```
    Sets the value of the index'th preference.
    
    Parameters:
    
    index - the number of the preference
    
    value - the new value, may be null
  - isNatural
```
boolean isNatural(int index)
```
    Tells whether the index'th preference is natural or artificial.
    - A natural preference is just available, it does not need to be stored anywhere and will maintain its value even if the application is restarted. Natural preferences may be views of other models which already have persistent storage or represent values that are calculated from other values.
    - An artificial preference needs to be stored. It represents some setting that is not available in the wild. It cannot maintain its state during application restarts.
    Parameters:
    
    index - the index of the preference
    
    Returns:
    
    true if the preference is natural, false if it is artificial
  - setValueNatural
```
void setValueNatural(int index)
```
    Like setValue(int, Object) this method changes the value of the index'th preference. But this time the natural preference has to extract the value from its underlying property.
    
    Parameters:
    
    index - the index of the preference to update
  - getTypePath
```
Path getTypePath(int index)
```
    Tells what kind of type the index'th value is. The type is represented as a path. Most times the path would equal the name of some class. Note: there is a set of standard paths defined in Path.
    
    Parameters:
    
    index - the number of the value
    
    Returns:
    
    a unique path for the type of this value
  - getPath
```
Path getPath(int index)
```
    Gets the unique identifier of the index'th preference of this model.
    
    Parameters:
    
    index - the index of the preference
    
    Returns:
    
    the unique path, compared to the other paths of this model

Interface PreferenceModel

Method Summary

Method Detail

getController

read

write

addPreferenceModelListener

removePreferenceModelListener

getSize

getLabel

getDescription

isEnabled

getOperations

doOperation

getValueInfo

getValue

setValue

isNatural

setValueNatural

getTypePath

getPath