bibliothek.extension.gui.dock.preference.PreferenceModel Maven / Gradle / Ivy

Go to download
/*
 * Bibliothek - DockingFrames
 * Library built on Java/Swing, allows the user to "drag and drop"
 * panels containing any Swing-Component the developer likes to add.
 * 
 * Copyright (C) 2008 Benjamin Sigg
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 * Benjamin Sigg
 * [email protected]
 * CH - Switzerland
 */
package bibliothek.extension.gui.dock.preference;

import bibliothek.gui.DockController;
import bibliothek.util.Path;

/**
 * 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 {@link #read()} to fill the preference-buffers, and have to call {@link #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 {@link 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 {@link PreferenceModel} looks as follows:

 * 
 *  A {@link PreferenceStorage} is created and its content loaded using one of its read-methods.	
 *  The new, empty model is created.
 *  With a call to {@link PreferenceStorage#load(PreferenceModel, boolean)} the artificial and natural preferences are loaded.
 *  With a call to {@link #write()} all preferences are made available to the entire framework.
 *  At any time a call to {@link #read()} will update the contents of the model.
 *  At any time a call to {@link #write()} will make modified preferences available to the entire framework. 
 *  With a call to {@link PreferenceStorage#store(PreferenceModel)} the preferences are stored.
 *  Using one of the write-methods of the {@link PreferenceStorage} the client can store the preferences persistently
 * 
 * Note that many {@link PreferenceModel}s can share the same {@link PreferenceStorage}. In such a case its best to re-create and refill the
 * models before using them.
 * @author Benjamin Sigg
 */
public interface PreferenceModel {
	/**
	 * Gets the {@link DockController} in whose realm this model is used. The controller
	 * is mainly necessary to load icons and text.
	 * @return the controller in whose realm this model is used
	 */
	public DockController getController();
	
    /**
     * 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.
     */
    public void read();
    
    /**
     * Writes the current preferences to the location where they are used.
     */
    public void write();
    
    /**
     * Adds a listener to this model.
     * @param listener the new listener
     */
    public void addPreferenceModelListener( PreferenceModelListener listener );
    
    /**
     * Removes a listener from this model.
     * @param listener the listener to remove.
     */
    public void removePreferenceModelListener( PreferenceModelListener listener );
    
    /**
     * Gets the number of preferences stored in this model.
     * @return the number of preferences
     */
    public int getSize();
    
    /**
     * Gets a short label that can be presented to the user for the 
     * index'th object.
     * @param index the number the preference
     * @return a short human readable description
     */
    public String getLabel( int index );
    
    /**
     * Gets a description of the index'th object. The description
     * is a longer text that will be presented to the user.
     * @param index the number of the preference
     * @return the description, might be null, might be formated
     * in HTML
     */
    public String getDescription( int index );
    
    /**
     * Tells whether the operation operation is enabled for
     * the preference at location index.
     * @param index some location
     * @param operation an operation from {@link #getOperations(int)}
     * @return true if the operation is enabled, false
     * if not
     */
    public boolean isEnabled( int index, PreferenceOperation operation );
    
    /**
     * Gets all operations for which this model has a definition for
     * the preference at location index. Note: a {@link PreferenceEditor}
     * has operations as well, if the editor and the model share an operation,
     * then the operation is considered to belong to the editor.
     * @param index the location of a preference
     * @return the list of available operations (enabled and disabled operations),
     * can be null
     */
    public PreferenceOperation[] getOperations( int index );
    
    /**
     * Executes the enabled operation operation.
     * @param index the location of the affected preference
     * @param operation the operation to execute
     */
    public void doOperation( int index, PreferenceOperation operation );
    
    /**
     * 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 {@link #getTypePath(int)}.
     * @param index the index of the info
     * @return the information or null if no information is
     * available
     */
    public Object getValueInfo( int index );
    
    /**
     * Gets the index'th preference. The {@link #getTypePath(int) type path}
     * determines how the value is to be presented on the screen.
     * @param index the number of the preference
     * @return the value or maybe null, has to be immutable
     */
    public Object getValue( int index );
    
    /**
     * Sets the value of the index'th preference.
     * @param index the number of the preference
     * @param value the new value, may be null
     */
    public void setValue( int index, Object value );
    
    /**
     * 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.
     * 
     * @param index the index of the preference
     * @return true if the preference is natural, false
     * if it is artificial
     */
    public boolean isNatural( int index );
    
    /**
     * Like {@link #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.
     * @param index the index of the preference to update
     */
    public void setValueNatural( 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 {@link Path}.
     * @param index the number of the value
     * @return a unique path for the type of this value
     */
    public Path getTypePath( int index );
    
    /**
     * Gets the unique identifier of the index'th preference of
     * this model.
     * @param index the index of the preference
     * @return the unique path, compared to the other paths of this model
     */
    public Path getPath( int index );
}