jmri
Interface UserPreferencesManager

Show UML class diagram

All Known Implementing Classes:

DefaultUserMessagePreferences

public interface UserPreferencesManager

Interface for the User Preferences Manager.

The User Message Preference Manager keeps track of the options that a user has selected in messages where they have selected "Remember this setting for next time"

See Also:

DefaultUserMessagePreferences

Method Summary

void	addComboBoxLastSelection(String comboBoxName, String lastValue) Adds the last selection of a combo box.
void	addPropertyChangeListener(PropertyChangeListener l)
void	allowSave()
void	disallowSave()
void	finishLoading()
String	getChoiceDescription(String strClass, String item) Returns the a meaningful description of a given item in a given class or group.
String	getChoiceName(String strClass, int n) Returns the nth item name in a given class
HashMap<Integer,String>	getChoiceOptions(String strClass, String item) Returns a map of the value against description of the different items in a given class.
String	getClassDescription(String strClass) Returns the description of a class/group registered with the preferences.
String	getComboBoxLastSelection(int n) returns the ComboBox Value at position n
String	getComboBoxLastSelection(String comboBoxName) returns the last selected value in a given combobox
String	getComboBoxName(int n) returns the ComboBox Name at position n
int	getComboBoxSelectionSize() returns the number of comboBox options saved
int	getMultipleChoiceDefaultOption(String strClass, String choice) Returns the default value of a given item in a given class
ArrayList<String>	getMultipleChoiceList(String strClass) Returns a list of all the multiple choice items registered with a given class.
int	getMultipleChoiceOption(String strClass, String item) Returns the current value of a given item in a given class
int	getMultipleChoiceSize(String strClass) Returns the number of Mulitple Choice items registered with a given class.
String	getPreferenceItemDescription(String strClass, String item) Returns the description of the given item preference in the given class
String	getPreferenceItemName(String strClass, int n) Returns the itemName of the n preference in the given class
ArrayList<String>	getPreferenceList(String strClass) Returns a list of preferences that are registered against a specific class.
ArrayList<String>	getPreferencesClasses() Returns a list of the classes registered with the preference manager.
int	getPreferencesSize(String strClass) returns the combined size of both types of items registered.
boolean	getPreferenceState(String strClass, String item) Returns the state of a given item registered against a specific class or item.
Object	getProperty(String strClass, Object key) Retrieve the value associated with a key in a given class If no value has been set for that key, returns null.
Set<Object>	getPropertyKeys(String strClass) Retrieve the complete current set of keys for a given class.
boolean	getSaveWindowLocation(String strClass)
boolean	getSaveWindowSize(String strClass)
Dimension	getScreen()
boolean	getSessionPreferenceState(String name) Enquire as to the state of a user preference for the current session.
boolean	getSimplePreferenceState(String name) Enquire as to the state of a user preference.
ArrayList<String>	getSimplePreferenceStateList() Returns an ArrayList of the checkbox states set as true.
String	getTableColumnAtNum(String table, int i) Get a name for a column at index i
boolean	getTableColumnHidden(String table, String column) Get the stored column hidden state for a given table
int	getTableColumnOrder(String table, String column) Get the stored position of the column for a given table
int	getTableColumnSort(String table, String column) Get the stored column sort order for a given table
int	getTableColumnWidth(String table, String column) Get the stored column width for a given table
List<String>	getTablesColumnList(String table) Get a list of all the column settings for a specific table
List<String>	getTablesList() Get a list of all the table preferences stored
ArrayList<String>	getWindowList()
Point	getWindowLocation(String strClass) Returns the x,y location of a given Window
Dimension	getWindowSize(String strClass) Returns the width, height size of a given Window
boolean	isWindowPositionSaved(String strClass) Do we have a saved window position for the class
void	messageItemDetails(String strClass, String item, String description, HashMap<Integer,String> options, int defaultOption) Add descriptive details about a specific message box, so that if it needs to be reset in the preferences, then it is easily identifiable.
void	messageItemDetails(String strClass, String item, String description, String[] msgOption, int[] msgNumber, int defaultOption) Add descriptive details about a specific message box, so that if it needs to be reset in the preferences, then it is easily identifiable.
void	preferenceItemDetails(String strClass, String item, String description) Register details about a perticular preference, so that it can be displayed in the GUI and provide a meaning full description when presented to the user.
void	removePropertyChangeListener(PropertyChangeListener l)
void	resetChangeMade()
void	setClassDescription(String strClass) Given that we know the class as a string, we will try and attempt to gather details about the preferences that has been added, so that we can make better sense of the details in the preferences window.
void	setComboBoxLastSelection(String comboBoxName, String lastValue) sets the last selected value in a given combobox
void	setLoading()
void	setMultipleChoiceOption(String strClass, String choice, int value) Sets the value of a given item in a given class, by its integer value
void	setMultipleChoiceOption(String strClass, String choice, String value) Sets the value of a given item in a given class, by its string description
void	setPreferenceState(String strClass, String item, boolean state) Used to save the state of checkboxes which can suppress messages from being displayed.
void	setProperty(String strClass, Object key, Object value) Attach a key/value pair to the given class, which can be retrieved later.
void	setSaveWindowLocation(String strClass, boolean b)
void	setSaveWindowSize(String strClass, boolean b)
void	setSessionPreferenceState(String name, boolean state) Used to surpress messages for the current session, the information is not stored, can not be changed via the GUI.
void	setSimplePreferenceState(String name, boolean state) This is used to remember the last selected state of a checkBox and thus allow that checkBox to be set to a true state when it is next initialised.
void	setTableColumnPreferences(String table, String column, int order, int width, int sort, boolean hidden) Stores the details of a tables column, so that it can be saved and re-applied when jmri is re-started
void	setWindowLocation(String strClass, Point location) Saves the last location of a given component on the screen.
void	setWindowSize(String strClass, Dimension dim) Saves the last size of a given component on the screen The jmri.util.JmriJFrame, will automatically use the class name of the frame if the class name returned is equal to jmri.util.JmriJFrame, the size is not stored
void	showErrorMessage(String title, String message, String classString, String item, boolean sessionOnly, boolean alwaysRemember) Show an error message ("don't forget ...") with a given dialog title and user message.
void	showInfoMessage(String title, String message, String classString, String item) Show an info message ("don't forget ...")
void	showInfoMessage(String title, String message, String classString, String item, boolean sessionOnly, boolean alwaysRemember) Show an info message ("don't forget ...") with a given dialog title and user message.
void	showWarningMessage(String title, String message, String classString, String item, boolean sessionOnly, boolean alwaysRemember) Show a warning message ("don't forget ...") with a given dialog title and user message.

Method Detail

setLoading

void setLoading()

finishLoading

void finishLoading()

getSimplePreferenceState

boolean getSimplePreferenceState(String name)

Enquire as to the state of a user preference.

Preferences that have not been set will be considered to be false.

The name is free-form, but to avoid ambiguity it should start with the package name (package.Class) for the primary using class.

setSimplePreferenceState

void setSimplePreferenceState(String name,
                              boolean state)

This is used to remember the last selected state of a checkBox and thus allow that checkBox to be set to a true state when it is next initialised. This can also be used anywhere else that a simple yes/no, true/false type preference needs to be stored. It should not be used for remembering if a user wants to suppress a message as there is no means in the GUI for the user to reset the flag. setPreferenceState() should be used in this instance The name is free-form, but to avoid ambiguity it should start with the package name (package.Class) for the primary using class.

Parameters:

name - A unique name to identify the state being stored

state - simple boolean.

getSimplePreferenceStateList

ArrayList<String> getSimplePreferenceStateList()

Returns an ArrayList of the checkbox states set as true.

setPreferenceState

void setPreferenceState(String strClass,
                        String item,
                        boolean state)

Used to save the state of checkboxes which can suppress messages from being displayed. This method should be used by the initiating code in conjunction with the preferenceItemDetails. Here the items are stored against a specific class and access to change them is made available via the GUI, in the preference manager.

The strClass parameter does not have to be the exact class name of the initiating code, but can be one where the information is related and therefore can be grouped together with.

Both the strClass and item although free form, should make up a unique reference.

Parameters:

strClass - The class that this preference should be stored or grouped with.

item - The specific item that is to be stored

state - Boolean state of the item.

getPreferenceState

boolean getPreferenceState(String strClass,
                           String item)

Returns the state of a given item registered against a specific class or item.

preferenceItemDetails

void preferenceItemDetails(String strClass,
                           String item,
                           String description)

Register details about a perticular preference, so that it can be displayed in the GUI and provide a meaning full description when presented to the user.

Parameters:

strClass - A string form of the class that the preference is stored or grouped with

item - The specific item that is being stored.

description - A meaningful decription of the item that the user will understand.

getPreferenceList

ArrayList<String> getPreferenceList(String strClass)

Returns a list of preferences that are registered against a specific class.

getPreferenceItemName

String getPreferenceItemName(String strClass,
                             int n)

Returns the itemName of the n preference in the given class

getPreferenceItemDescription

String getPreferenceItemDescription(String strClass,
                                    String item)

Returns the description of the given item preference in the given class

getSessionPreferenceState

boolean getSessionPreferenceState(String name)

Enquire as to the state of a user preference for the current session.

Preferences that have not been set will be considered to be false.

The name is free-form, but to avoid ambiguity it should start with the package name (package.Class) for the primary using class.

setSessionPreferenceState

void setSessionPreferenceState(String name,
                               boolean state)

Used to surpress messages for the current session, the information is not stored, can not be changed via the GUI.

This can be used to help prevent over loading the user with repetitive error messages such as turnout not found while loading a panel file due to a connection failing. The name is free-form, but to avoid ambiguity it should start with the package name (package.Class) for the primary using class.

Parameters:

name - A unique identifer for preference.

state -

resetChangeMade

void resetChangeMade()

showInfoMessage

void showInfoMessage(String title,
                     String message,
                     String classString,
                     String item)

Show an info message ("don't forget ...") with a given dialog title and user message. Use a given preference name to determine whether to show it in the future. The classString & item parameters should form a unique value

Parameters:

title - Message Box title

message - Message to be displayed

classString - String value of the calling class

item - String value of the specific item this is used for

showErrorMessage

void showErrorMessage(String title,
                      String message,
                      String classString,
                      String item,
                      boolean sessionOnly,
                      boolean alwaysRemember)

Show an error message ("don't forget ...") with a given dialog title and user message. Use a given preference name to determine whether to show it in the future. added flag to indicate that the message should be suppressed JMRI session only. The classString & item parameters should form a unique value

Parameters:

title - Message Box title

message - Message to be displayed

classString - String value of the calling class

item - String value of the specific item this is used for

sessionOnly - Means this message will be suppressed in this JMRI session and not be remembered

alwaysRemember - Means that the suppression of the message will be saved

showInfoMessage

void showInfoMessage(String title,
                     String message,
                     String classString,
                     String item,
                     boolean sessionOnly,
                     boolean alwaysRemember)

Show an info message ("don't forget ...") with a given dialog title and user message. Use a given preference name to determine whether to show it in the future. added flag to indicate that the message should be suppressed JMRI session only. The classString & item parameters should form a unique value

Parameters:

title - Message Box title

message - Message to be displayed

classString - String value of the calling class

item - String value of the specific item this is used for

sessionOnly - Means this message will be suppressed in this JMRI session and not be remembered

alwaysRemember - Means that the suppression of the message will be saved

showWarningMessage

void showWarningMessage(String title,
                        String message,
                        String classString,
                        String item,
                        boolean sessionOnly,
                        boolean alwaysRemember)

Show a warning message ("don't forget ...") with a given dialog title and user message. Use a given preference name to determine whether to show it in the future. added flag to indicate that the message should be suppressed JMRI session only. The classString & item parameters should form a unique value

Parameters:

title - Message Box title

message - Message to be displayed

classString - String value of the calling class

item - String value of the specific item this is used for

sessionOnly - Means this message will be suppressed in this JMRI session and not be remembered

alwaysRemember - Means that the suppression of the message will be saved

addComboBoxLastSelection

void addComboBoxLastSelection(String comboBoxName,
                              String lastValue)

Adds the last selection of a combo box.

The name is free-form, but to avoid ambiguity it should start with the package name (package.Class) for the primary using class, followed by an identifier for the combobox

getComboBoxLastSelection

String getComboBoxLastSelection(String comboBoxName)

returns the last selected value in a given combobox

setComboBoxLastSelection

void setComboBoxLastSelection(String comboBoxName,
                              String lastValue)

sets the last selected value in a given combobox

getComboBoxSelectionSize

int getComboBoxSelectionSize()

returns the number of comboBox options saved

getComboBoxName

String getComboBoxName(int n)

returns the ComboBox Name at position n

getComboBoxLastSelection

String getComboBoxLastSelection(int n)

returns the ComboBox Value at position n

getScreen

Dimension getScreen()

allowSave

void allowSave()

disallowSave

void disallowSave()

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener l)

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener l)

getClassDescription

String getClassDescription(String strClass)

Returns the description of a class/group registered with the preferences.

getPreferencesClasses

ArrayList<String> getPreferencesClasses()

Returns a list of the classes registered with the preference manager.

setClassDescription

void setClassDescription(String strClass)

Given that we know the class as a string, we will try and attempt to gather details about the preferences that has been added, so that we can make better sense of the details in the preferences window.

This looks for specific methods within the class called "getClassDescription" and "setMessagePreferenceDetails". If found it will invoke the methods, this will then trigger the class to send details about its preferences back to this code.

messageItemDetails

void messageItemDetails(String strClass,
                        String item,
                        String description,
                        String[] msgOption,
                        int[] msgNumber,
                        int defaultOption)

Add descriptive details about a specific message box, so that if it needs to be reset in the preferences, then it is easily identifiable. displayed to the user in the preferences GUI.

Parameters:

strClass - String value of the calling class/group

item - String value of the specific item this is used for.

description - A meaningful description that can be used in a label to describe the item

msgOption - Description of each option valid option.

msgNumber - The references number against which the Description is refering too.

defaultOption - The default option for the given item.

messageItemDetails

void messageItemDetails(String strClass,
                        String item,
                        String description,
                        HashMap<Integer,String> options,
                        int defaultOption)

Add descriptive details about a specific message box, so that if it needs to be reset in the preferences, then it is easily identifiable. displayed to the user in the preferences GUI.

Parameters:

strClass - String value of the calling class/group

item - String value of the specific item this is used for.

description - A meaningful description that can be used in a label to describe the item

options - A map of the integer value of the option against a meaningful description.

defaultOption - The default option for the given item.

getChoiceOptions

HashMap<Integer,String> getChoiceOptions(String strClass,
                                         String item)

Returns a map of the value against description of the different items in a given class. This information can then be used to build a Combo box.

Parameters:

strClass - Class or group of the given item

item - the item which we wish to return the details about.

getMultipleChoiceSize

int getMultipleChoiceSize(String strClass)

Returns the number of Mulitple Choice items registered with a given class.

getMultipleChoiceList

ArrayList<String> getMultipleChoiceList(String strClass)

Returns a list of all the multiple choice items registered with a given class.

getChoiceName

String getChoiceName(String strClass,
                     int n)

Returns the nth item name in a given class

getChoiceDescription

String getChoiceDescription(String strClass,
                            String item)

Returns the a meaningful description of a given item in a given class or group.

getMultipleChoiceOption

int getMultipleChoiceOption(String strClass,
                            String item)

Returns the current value of a given item in a given class

getMultipleChoiceDefaultOption

int getMultipleChoiceDefaultOption(String strClass,
                                   String choice)

Returns the default value of a given item in a given class

setMultipleChoiceOption

void setMultipleChoiceOption(String strClass,
                             String choice,
                             String value)

Sets the value of a given item in a given class, by its string description

setMultipleChoiceOption

void setMultipleChoiceOption(String strClass,
                             String choice,
                             int value)

Sets the value of a given item in a given class, by its integer value

getPreferencesSize

int getPreferencesSize(String strClass)

returns the combined size of both types of items registered.

setWindowLocation

void setWindowLocation(String strClass,
                       Point location)

Saves the last location of a given component on the screen.

The jmri.util.JmriJFrame, will automatically use the class name of the frame if the class name returned is equal to jmri.util.JmriJFrame, the location is not stored

Parameters:

strClass - This is a unique identifier for window location being saved

location - The x,y location of the window given in a Point

setWindowSize

void setWindowSize(String strClass,
                   Dimension dim)

Saves the last size of a given component on the screen

The jmri.util.JmriJFrame, will automatically use the class name of the frame if the class name returned is equal to jmri.util.JmriJFrame, the size is not stored

Parameters:

strClass - This is a unique identifier for window size being saved

dim - The width, height size of the window given in a Dimension

getWindowLocation

Point getWindowLocation(String strClass)

Returns the x,y location of a given Window

getWindowSize

Dimension getWindowSize(String strClass)

Returns the width, height size of a given Window

getWindowList

ArrayList<String> getWindowList()

isWindowPositionSaved

boolean isWindowPositionSaved(String strClass)

Do we have a saved window position for the class

Parameters:

strClass -

Returns:

true if the window position details are stored, false if not.

getSaveWindowSize

boolean getSaveWindowSize(String strClass)

getSaveWindowLocation

boolean getSaveWindowLocation(String strClass)

setSaveWindowSize

void setSaveWindowSize(String strClass,
                       boolean b)

setSaveWindowLocation

void setSaveWindowLocation(String strClass,
                           boolean b)

setProperty

void setProperty(String strClass,
                 Object key,
                 Object value)

Attach a key/value pair to the given class, which can be retrieved later. These are not bound properties as yet, and don't throw events on modification. Key must not be null.

getProperty

Object getProperty(String strClass,
                   Object key)

Retrieve the value associated with a key in a given class If no value has been set for that key, returns null.

getPropertyKeys

Set<Object> getPropertyKeys(String strClass)

Retrieve the complete current set of keys for a given class.

setTableColumnPreferences

void setTableColumnPreferences(String table,
                               String column,
                               int order,
                               int width,
                               int sort,
                               boolean hidden)

Stores the details of a tables column, so that it can be saved and re-applied when jmri is re-started

Parameters:

table - The reference for the table

column - The column name

order - The position that the column appears in the header

width - The width of the column

sort - The sort order of the column

hidden - Should the column be hidden

getTableColumnOrder

int getTableColumnOrder(String table,
                        String column)

Get the stored position of the column for a given table

Parameters:

table - The reference for the table

column - The column name

Returns:

-1 if not found

getTableColumnWidth

int getTableColumnWidth(String table,
                        String column)

Get the stored column width for a given table

Parameters:

table - The reference for the table

column - The column name

Returns:

-1 if not found

getTableColumnSort

int getTableColumnSort(String table,
                       String column)

Get the stored column sort order for a given table

Parameters:

table - The reference for the table

column - The column name

Returns:

0 if not found

getTableColumnHidden

boolean getTableColumnHidden(String table,
                             String column)

Get the stored column hidden state for a given table

Parameters:

table - The reference for the table

column - The column name

Returns:

0 if not found

getTableColumnAtNum

String getTableColumnAtNum(String table,
                           int i)

Get a name for a column at index i

Parameters:

table - The reference for the table

i - The column index returns null if not found, otherwise the column name

getTablesList

List<String> getTablesList()

Get a list of all the table preferences stored

Returns:

a List of all the tables, if no tables exist then an empty list is returned

getTablesColumnList

List<String> getTablesColumnList(String table)

Get a list of all the column settings for a specific table

Parameters:

table -

Returns:

a List of all the columns in a table, if the table is not valid an empty list is returned