ilog.views.appframe.settings
Class IlvObjectSettingsHandler

java.lang.Object
  ilog.views.appframe.settings.IlvObjectSettingsHandler

public class IlvObjectSettingsHandler
extends Object

Defines objects that ease the initialization of objects from the settings of an application.
An IlvObjectSettingsHandler is in charge of selecting the settings element that initializes its associated object and of calling a settings serializer that asks the object to read and write its settings data.

As an example, let's consider a CustomizedLabel class that reads its data from the settings. Using an IlvObjectSettingsHandler, it will read its data from the settings as follows:

 public class CustomizedLabel extends JLabel {
   private IlvObjectSettingsHandler settingsHandler;

   public CustomizedLabel(String name) {
     settingsHandler = new IlvObjectSettingsHandler(this, "label");
     settingsHandler.setSettingsName(name);
     settingsHandler.addSettingsSerializer(new IlvSettingsSerializer() {
       public void readSettings(IlvSettingsElement element, Object object) {
         CustomizedLabel.this.readSettings(element);
       }

       public void writeSettings(IlvSettingsElement element, Object object) {
         CustomizedLabel.this.writeSettings(element);
       }
     });
   }

   public void setApplication(IlvApplication application) {
     settingsHandler.setApplication(application);
   }

   protected void readSettings(IlvSettingsElement element) {
     setText(element.getString("text", getText()));
     setForeground(element.getColor("foreground", getForeground()));
     validate();
   }

   protected void writeSettings(IlvSettingsElement element) {
     element.setString("text", getText());
     element.setColor("foreground", getForeground());
   }
 }
 

In the settings, the label can be defined as follows:

 <appframe>
     <settings>
         <label name="default" background="#ff0000" text="Customized label"/>
     </settings>
 </appframe>
 

Finally, the CustomizedLabel can be instantiated and initialized:

 CustomizedLabel label = new CustomizedLabel("default");
 label.setApplication(application);
 

The label will be displayed with a red "Customized label" text. If settings change after the application has been initialized - as for new plugins installed by the application - and have an impact on the definition of the label settings, the readSettings method of the label will be invoked again, so that the label can display the new settings changes.

Constructor Summary

IlvObjectSettingsHandler(Object object, String settingsType)
Constructs a new IlvObjectSettingsHandler for the specified object.

Method Summary

void	addSettingsSerializer(IlvSettingsSerializer serializer) Adds a serializer responsible for reading and writing the settings of the associated object.
boolean	areSettingsCustomizable() Determines whether the settings accessed by this settings handler can be customized.
IlvApplication	getApplication() Returns the application of the object.
IlvSettings	getSettings() Returns the settings that initialize the associated object.
IlvSettingsElement	getSettingsElement() Returns the settings element that provides the settings for the associated object.
protected IlvSettingsElement	getSettingsElement(IlvSettings settings) Returns the settings element that provides the settings for the associated object.
String	getSettingsName() Returns the name that identifies the associated object within the settings.
IlvSettingsQuery	getSettingsQuery() Returns the query that selects the settings element that provides the settings of the associated object.
String	getSettingsType() Returns the type of the settings element that provides the settings for the associated object.
boolean	isAutomaticReading() Determines whether this object settings handler automatically reads the settings when enough settings parameters have been set for getting a settings element.
void	readSettings() Reads the settings of the object associated with this handler instance.
protected void	readSettings(IlvSettings settings) Reads the settings of the object associated with this handler instance.
boolean	removeSettingsSerializer(IlvSettingsSerializer serializer) Removes the specified serializer.
void	setApplication(IlvApplication application) Sets the application of the object.
void	setAutomaticReading(boolean automatic) Sets the automatic reading mode to the specified value.
void	setSettings(IlvSettings settings) Sets the settings that initialize the associated object.
void	setSettingsCustomizable(boolean customizable) Declares the settings accessed by this settings handler as customizable, depending on the value of the customizable parameter.
void	setSettingsElement(IlvSettingsElement element) Forces the settings to be read and written from the specified settings element.
void	setSettingsName(String name) Sets the name that identifies the associated object within the settings.
void	setSettingsQuery(IlvSettingsQuery query) Sets the query that selects the settings element that provides the settings for the associated object.
void	setSettingsType(String type) Sets the type of the settings element that provides the settings for the associated object.
void	writeSettings(IlvSettings settings) Writes the settings of the object associated with this handler instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IlvObjectSettingsHandler

public IlvObjectSettingsHandler(Object object,
                                String settingsType)

Constructs a new IlvObjectSettingsHandler for the specified object.

Parameters:

object - The object to configure from settings using this handler.

settingsType - The type of settings elements that this handler will read and write.

Method Detail

getApplication

public IlvApplication getApplication()

Returns the application of the object.

See Also:

setApplication(ilog.views.appframe.IlvApplication)

setApplication

public void setApplication(IlvApplication application)

Sets the application of the object.
If the settings this handler listens for have not been specified, the method setSettings(ilog.views.appframe.settings.IlvSettings) is called with the settings of the application, given by the application method IlvApplication.getSettingsManager(). In this case, this handler instance is added as a settings listener to the settings manager of the application.

Parameters:

application - The application of the object.

See Also:

getApplication(), setSettings(ilog.views.appframe.settings.IlvSettings)

getSettings

public IlvSettings getSettings()

Returns the settings that initialize the associated object.

Returns:

The settings of the object.

See Also:

setSettings(ilog.views.appframe.settings.IlvSettings)

setSettings

public void setSettings(IlvSettings settings)

Sets the settings that initialize the associated object.

Parameters:

settings - The new settings of the object.

See Also:

getSettings()

getSettingsName

public String getSettingsName()

Returns the name that identifies the associated object within the settings. It corresponds to the value of the name attribute of the settings element that provides the settings for the associated object. If no name has been specified using the method setSettingsName(java.lang.String), null will be returned.

Returns:

The settings name.

See Also:

setSettingsName(java.lang.String), getSettingsElement(), getSettingsQuery()

setSettingsName

public void setSettingsName(String name)

Sets the name that identifies the associated object within the settings.

Parameters:

name - The new settings name.

getSettingsType

public String getSettingsType()

Returns the type of the settings element that provides the settings for the associated object.

Returns:

The settings type or null if no settings type has been specified.

See Also:

setSettingsType(java.lang.String), getSettingsElement()

setSettingsType

public void setSettingsType(String type)

Sets the type of the settings element that provides the settings for the associated object.

Parameters:

type - The type of the settings element.

See Also:

getSettingsType()

setSettingsQuery

public void setSettingsQuery(IlvSettingsQuery query)

Sets the query that selects the settings element that provides the settings for the associated object.

Parameters:

query - The new settings query.

See Also:

getSettingsQuery()

getSettingsQuery

public IlvSettingsQuery getSettingsQuery()

Returns the query that selects the settings element that provides the settings of the associated object.

If a query has been specified with the method setSettingsQuery(ilog.views.appframe.settings.IlvSettingsQuery), it will be returned. Otherwise, a query is built for selecting a settings root element of the type returned by getSettingsType() and the value of the name attribute equal to the name returned by getSettingsName(). If getSettingsName() returns null, the query will select the first root element it finds with the settings type given by the method getSettingsType().

Returns:

The settings query.

See Also:

setSettingsQuery(ilog.views.appframe.settings.IlvSettingsQuery), #see #getSettingsType

getSettingsElement

public IlvSettingsElement getSettingsElement()

Returns the settings element that provides the settings for the associated object. If a settings element has been specified with the setSettingsElement(ilog.views.appframe.settings.IlvSettingsElement) method, it will be returned. Otherwise, the settings element is selected from the settings given by the getSettings() method with the query returned by getSettingsQuery().

Returns:

The settings element or null if no settings element could be found.

See Also:

setSettingsElement(ilog.views.appframe.settings.IlvSettingsElement), readSettings(), getSettingsQuery(), getSettingsElement(IlvSettings)

getSettingsElement

protected IlvSettingsElement getSettingsElement(IlvSettings settings)

Returns the settings element that provides the settings for the associated object. If a settings element has been specified with the setSettingsElement(ilog.views.appframe.settings.IlvSettingsElement) method, it will be returned. Otherwise, the settings element is selected from the settings given by the getSettings() method with the query returned by getSettingsQuery().

Parameters:

settings - The settings to select the settings element in. If null, it will be set to settings given by the method getSettings().

Returns:

The settings element or null if no settings element could be found.

See Also:

setSettingsElement(ilog.views.appframe.settings.IlvSettingsElement), readSettings(), getSettingsQuery(), getSettingsElement()

setSettingsElement

public void setSettingsElement(IlvSettingsElement element)

Forces the settings to be read and written from the specified settings element.
This method overrides the settings element that is selected by default within the settings given by the method getSettings() with the query getSettingsQuery().

Parameters:

element - The settings element that provides the settings for the object associated with this handler instance.

See Also:

getSettingsElement()

addSettingsSerializer

public void addSettingsSerializer(IlvSettingsSerializer serializer)

Adds a serializer responsible for reading and writing the settings of the associated object.

Parameters:

serializer - The settings serializer.

See Also:

removeSettingsSerializer(ilog.views.appframe.settings.IlvSettingsSerializer)

removeSettingsSerializer

public boolean removeSettingsSerializer(IlvSettingsSerializer serializer)

Removes the specified serializer.

Parameters:

serializer - The settings serializer to remove.

Returns:

true if the serializer was previously added to the handler instance; false otherwise.

See Also:

addSettingsSerializer(ilog.views.appframe.settings.IlvSettingsSerializer)

readSettings

public void readSettings()

Reads the settings of the object associated with this handler instance. This method should only be called if the automatic reading mode has been set to false. It makes the associated object read its settings.
The settings element that provides the settings is first selected and is given to the settings serializer for initializing the associated object.

See Also:

setAutomaticReading(boolean)

readSettings

protected void readSettings(IlvSettings settings)

Reads the settings of the object associated with this handler instance.
This method is called after this handler object has been added to the settings manager of the application and the settings of the application have been initialized.

The settings element that provides the settings is first selected and is given to the settings serializer for initializing the associated object.

Parameters:

settings - The settings to read the settings of the associated object from.

writeSettings

public void writeSettings(IlvSettings settings)

Writes the settings of the object associated with this handler instance.
This method is called after the settings listener of this handler instance has been notified to save the settings changes. For example, this can happen when the application prepares to close.

The settings element that provides the settings is first selected with the method getSettingsElement(). If this method returns null, a new settings element of the type given by getSettingsType() will be created and added to the settings given by getSettings(), so that it is selectable from the query given by getSettingsQuery(). If such a settings element could not be created or added to the settings the write processing stops. Otherwise, all the settings serializers are asked to save the modifications.

Parameters:

settings - The settings to write the settings of the associated object into. If null, the settings given by getSettings() will be used.

isAutomaticReading

public boolean isAutomaticReading()

Determines whether this object settings handler automatically reads the settings when enough settings parameters have been set for getting a settings element. By default, true is returned.

Returns:

true if settings are read automatically; false if settings are read when invoking the readSettings() method explicitly.

See Also:

setAutomaticReading(boolean), setSettings(ilog.views.appframe.settings.IlvSettings), setSettingsQuery(ilog.views.appframe.settings.IlvSettingsQuery), setSettingsName(java.lang.String), setSettingsElement(ilog.views.appframe.settings.IlvSettingsElement)

setAutomaticReading

public void setAutomaticReading(boolean automatic)

Sets the automatic reading mode to the specified value.

Parameters:

automatic - The automatic reading mode.

See Also:

isAutomaticReading()

areSettingsCustomizable

public boolean areSettingsCustomizable()

Determines whether the settings accessed by this settings handler can be customized. If the settings are customizable, the writeSettings(ilog.views.appframe.settings.IlvSettings) method is called to save the modifications. Otherwise, the writeSettings(ilog.views.appframe.settings.IlvSettings) method is not called.

See Also:

setSettingsCustomizable(boolean), writeSettings(ilog.views.appframe.settings.IlvSettings)

setSettingsCustomizable

public void setSettingsCustomizable(boolean customizable)

Declares the settings accessed by this settings handler as customizable, depending on the value of the customizable parameter. By default, the settings accessed by the settings handler are customizable.

Parameters:

customizable - if true, the settings will be declared customizable and the writeSettings(ilog.views.appframe.settings.IlvSettings) method will be called to save the changes that have occurred in the associated object in the settings.

See Also:

areSettingsCustomizable(), writeSettings(ilog.views.appframe.settings.IlvSettings)