/*
This file is part of leafdigital leafChat.
leafChat is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
leafChat 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 General Public License for more details.
You should have received a copy of the GNU General Public License
along with leafChat. If not, see <http://www.gnu.org/licenses/>.
Copyright 2011 Samuel Marshall.
*/
package com.leafdigital.prefs.api;
import java.awt.Font;
import leafchat.core.api.*;
/**
* Singleton to provide preferences.
* <p>
* Preferences are currently stored in an XML file. Owner names and preference
* names must meet the following restrictions:
* <p>
* The first character must be a letter (not digit). Future characters
* must be letters, digits, _ or -; no spaces or other special characters.
* <p>
* To ensure uniqueness, if you create a new category of PreferencesOwner,
* begin the string with a word and an underline;
* <code>Plugin_com.leafdigital.whatever</code> is how the system plugin
* ones are generated.
*/
public interface Preferences extends Singleton
{
/**
* Returns a preference group.
* @param owner Owner of preference (if in doubt, use getPluginOwner)
* @return Group that can be used to check preferences
* @throws BugException If owner name is invalid
*/
public PreferencesGroup getGroup(String owner);
/**
* Returns a preference group. Shortcut for calling getPluginOwner and getGroup.
* @param p Plugin owning preference
* @return Group that can be used to check preferences
*/
public PreferencesGroup getGroup(Plugin p);
// Because all preferences are strings, these to/from methods are provided
// so that you can store other things in preferences. Obviously you can do
// it manually if you need to store something more complicated.
/**
* @param value Retrieved preference
* @return Value as int
* @throws BugException If conversion fails
*/
public int toInt(String value) throws BugException;
/**
* @param value Integer
* @return String equivalent
*/
public String fromInt(int value);
/**
* @param value Retrieved preference
* @return Value as font
* @throws BugException If conversion fails
*/
public Font toFont(String value) throws BugException;
/**
* @param value Font to represent as string
* @return String equivalent of font
*/
public String fromFont(Font value);
/**
* @param value Retrieved preference
* @return Value as boolean
* @throws BugException If conversion fails
*/
public boolean toBoolean(String value) throws BugException;
/**
* @param value Boolean to represent as string
* @return String equivalent of boolean
*/
public String fromBoolean(boolean value);
/**
* Given an arbitrary string, returns a token safe to use in preferences names.
* @param name String
* @return Safed string
*/
public String getSafeToken(String name);
// These methods obtain PreferencesOwner objects representing particular things
/**
* @param p Plugin
* @return Owner string representing a particular plugin
*/
public String getPluginOwner(Plugin p);
/**
* @param className Plugin class name
* @return owner string representing a particular plugin given full class name
*/
public String getPluginOwner(String className);
}