Class FillInPreferenceCategory
- java.lang.Object
-
- ca.cgjennings.apps.arkham.dialog.prefs.FillInPreferenceCategory
-
- All Implemented Interfaces:
PreferenceCategory
- Direct Known Subclasses:
CatDesignSupport
public class FillInPreferenceCategory extends java.lang.Object implements PreferenceCategory
A preference category allows the user to manage a set of user preferences linked to user settings. Commonly used controls can be added easily using the provided methods, or you can add custom panels and override the appropriate methods to manage loading and changing settings keys.- Author:
- Chris Jennings
-
-
Constructor Summary
Constructors Constructor Description FillInPreferenceCategory(PluginContext context, java.lang.String title, java.awt.image.BufferedImage iconImage)
Create a new preferences panel that will use decorated settings keys that are unique to a given plug-in.FillInPreferenceCategory(PluginContext context, java.lang.String title, java.lang.String iconResource)
Create a new preferences panel that will use decorated settings keys that are unique to a given plug-in.FillInPreferenceCategory(PluginContext context, java.lang.String title, javax.swing.Icon icon)
Create a new preferences panel that will use decorated settings keys that are unique to a given plug-in.FillInPreferenceCategory(java.lang.String title, java.awt.image.BufferedImage iconImage)
Create a new preferences category that will use plain settings keys (that is, the exact keys that are specified).FillInPreferenceCategory(java.lang.String title, java.lang.String iconResource)
Create a new preferences category that will use plain settings keys (that is, the exact keys that are specified).FillInPreferenceCategory(java.lang.String title, javax.swing.Icon icon)
Create a new preferences category that will use plain settings keys (that is, the exact keys that are specified).
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description SettingBackedControl
add(java.lang.String key, SettingBackedControl control)
Adds any setting backed control, mapped to key.javax.swing.JButton
addButton(java.lang.String label, java.awt.event.ActionListener pressHandler)
Adds a button to the panel that will call the supplied action listener when pressed.SBCheckBox
addCheckBox(java.lang.String key, java.lang.String text, boolean invert)
Adds a checkbox at the current indent level that is mapped to key.SBDropDown<java.lang.String>
addDropDown(java.lang.String key, java.lang.String[] labels, java.lang.String[] values)
Adds a dropdown menu button at the current indent level that is mapped to key.javax.swing.JTextField
addField(java.lang.String key, java.lang.String label, int cols)
Adds a text field with an optional label.void
addHelp(java.lang.String helpPage, java.lang.String label)
Adds a help icon that links to a help page.void
addHelp(java.lang.String helpPage, java.lang.String label, boolean isDocPage)
Deprecated.javax.swing.JRadioButton
addRadioButton(java.lang.String label, java.awt.event.ActionListener pressHandler)
Adds a new radio button that will be a member of the current button group.SBIntSpinner
addRange(java.lang.String key, java.lang.String label, int min, int max, int stepSize)
Adds a ranged integer control at the current indent level that is mapped to key.void
addResetKey(java.lang.String key)
Register a settings key.void
addResetKeys(java.lang.String... keys)
A convenience method for adding multiple keys at once.void
addTip(java.lang.String popupText)
Adds an icon that displays pop-up help text when hovered over.javax.swing.JComponent
addUnmanagedControl(javax.swing.JComponent uc)
Adds a custom control that will be managed by the caller.javax.swing.Icon
getIcon()
Returns the icon used to represent this category visually.javax.swing.JPanel
getPanel()
Returns the panel of controls that allows the user to edit the settings for this category.Settings
getSettings()
java.lang.String
getTitle()
Returns the localized name of this preference category.javax.swing.JLabel
heading(java.lang.String text)
Adds a heading label to the panel.void
indent()
Indent subsequent controls one additional level.boolean
isRestartRequired()
If the user applies the settings changes, this will be called after the settings are updated to check if a restart is required.void
join()
Causes the next control to be added to be placed on the same line as the previous control, instead of on a new line.javax.swing.JLabel
label(java.lang.String text)
Adds a plain label to the panel.void
loadSettings()
This method is called when the preferences dialog is about to be displayed in order to initialize the controls with the current settings.javax.swing.JLabel
note(java.lang.String text)
Adds a small note label to the panel.void
startNewButtonGroup()
Starts a new button group.void
storeSettings()
This method is called when the user accepts the changes in the preferences dialog.javax.swing.JLabel
subheading(java.lang.String text)
Adds a subheading label to the panel.JTip
tip(java.lang.String tipText)
Adds a pop-up tip with the specified text to the panel.java.lang.String
toString()
void
unindent()
Reduce indentation of subsequent controls one level.
-
-
-
Constructor Detail
-
FillInPreferenceCategory
public FillInPreferenceCategory(java.lang.String title, java.awt.image.BufferedImage iconImage)
Create a new preferences category that will use plain settings keys (that is, the exact keys that are specified).- Parameters:
title
- the localized name of the categoryiconImage
- an optional image for the category; should be themed- See Also:
ResourceKit.getThemedImage(java.lang.String)
-
FillInPreferenceCategory
public FillInPreferenceCategory(java.lang.String title, java.lang.String iconResource)
Create a new preferences category that will use plain settings keys (that is, the exact keys that are specified).- Parameters:
title
- the localized name of the categoryiconResource
- a resource file that represents the icon
-
FillInPreferenceCategory
public FillInPreferenceCategory(java.lang.String title, javax.swing.Icon icon)
Create a new preferences category that will use plain settings keys (that is, the exact keys that are specified).- Parameters:
title
- the localized name of the categoryicon
- the category icon
-
FillInPreferenceCategory
public FillInPreferenceCategory(PluginContext context, java.lang.String title, java.awt.image.BufferedImage iconImage)
Create a new preferences panel that will use decorated settings keys that are unique to a given plug-in.- Parameters:
context
- a plug-in context for the plug-in for which decorated settings keys should be usedtitle
- the localized name of the categoryiconImage
- an optional image for the category; should be themed- See Also:
ResourceKit.getThemedImage(java.lang.String)
-
FillInPreferenceCategory
public FillInPreferenceCategory(PluginContext context, java.lang.String title, java.lang.String iconResource)
Create a new preferences panel that will use decorated settings keys that are unique to a given plug-in.- Parameters:
context
- a plug-in context for the plug-in for which decorated settings keys should be usedtitle
- the localized name of the categoryiconResource
- a resource file that represents the icon
-
FillInPreferenceCategory
public FillInPreferenceCategory(PluginContext context, java.lang.String title, javax.swing.Icon icon)
Create a new preferences panel that will use decorated settings keys that are unique to a given plug-in.- Parameters:
context
- a plug-in context for the plug-in for which decorated settings keys should be usedtitle
- the localized name of the categoryicon
- the category icon
-
-
Method Detail
-
getTitle
public java.lang.String getTitle()
Description copied from interface:PreferenceCategory
Returns the localized name of this preference category.- Specified by:
getTitle
in interfacePreferenceCategory
- Returns:
- the category name, in the interface locale
-
getIcon
public javax.swing.Icon getIcon()
Description copied from interface:PreferenceCategory
Returns the icon used to represent this category visually. The returned icon should be 48x48 pixels in size. Ifnull
is returned, a default icon will be used.- Specified by:
getIcon
in interfacePreferenceCategory
- Returns:
- an icon representing this category
-
addResetKey
public void addResetKey(java.lang.String key)
Register a settings key. If the value of the key changes, the user will be informed that they must restart Strange Eons for changes to take effect.- Parameters:
key
- the name of the settings key to track
-
addResetKeys
public void addResetKeys(java.lang.String... keys)
A convenience method for adding multiple keys at once.- Parameters:
keys
-
-
isRestartRequired
public boolean isRestartRequired()
If the user applies the settings changes, this will be called after the settings are updated to check if a restart is required. The base implementation checks to see if any of the keys registered withaddResetKey(java.lang.String)
have changed value, and returnstrue
if they have.- Specified by:
isRestartRequired
in interfacePreferenceCategory
- Returns:
true
if the application must be restarted for changes to take effect
-
loadSettings
public void loadSettings()
This method is called when the preferences dialog is about to be displayed in order to initialize the controls with the current settings. The base class will initialize any of the standard controls that have been added with a non-null
key. It also records the initial value of any reset keys that have been added so that they can be compared to their new value later on to determine if a reset is required. Subclasses may override this to handle loading of custom controls.- Specified by:
loadSettings
in interfacePreferenceCategory
-
storeSettings
public void storeSettings()
This method is called when the user accepts the changes in the preferences dialog. It updates the settings values with the new values set in the category panel. The base class implementation handles processing of any built-in controls that were added.- Specified by:
storeSettings
in interfacePreferenceCategory
-
getSettings
public final Settings getSettings()
-
heading
public javax.swing.JLabel heading(java.lang.String text)
Adds a heading label to the panel.
-
subheading
public javax.swing.JLabel subheading(java.lang.String text)
Adds a subheading label to the panel.
-
label
public javax.swing.JLabel label(java.lang.String text)
Adds a plain label to the panel.
-
note
public javax.swing.JLabel note(java.lang.String text)
Adds a small note label to the panel.
-
tip
public JTip tip(java.lang.String tipText)
Adds a pop-up tip with the specified text to the panel.- Parameters:
tipText
- the help text to display- Returns:
- the component that was added
-
addCheckBox
public SBCheckBox addCheckBox(java.lang.String key, java.lang.String text, boolean invert)
Adds a checkbox at the current indent level that is mapped to key. If invert istrue
, then the box will be checked when the setting is false instead of true.- Parameters:
key
- the setting key nametext
- the text for the checkboxinvert
- whether to invert the relationship with the setting value- Returns:
- the checkbox that was added
-
addDropDown
public SBDropDown<java.lang.String> addDropDown(java.lang.String key, java.lang.String[] labels, java.lang.String[] values)
Adds a dropdown menu button at the current indent level that is mapped to key.- Parameters:
key
- the setting key namelabels
- the list of labels to show in the drop downvalues
- the values to assign to the key for each label- Returns:
- the dropdown menu that was added
-
addRange
public SBIntSpinner addRange(java.lang.String key, java.lang.String label, int min, int max, int stepSize)
Adds a ranged integer control at the current indent level that is mapped to key.- Parameters:
key
- the setting key namemin
- the minimum valuemax
- the maximum valuestepSize
- the adjustment step size- Returns:
- the control that was added
-
addField
public javax.swing.JTextField addField(java.lang.String key, java.lang.String label, int cols)
Adds a text field with an optional label.- Parameters:
key
- the settings key to uselabel
- the label text to use, ornull
cols
- the number of columns for the field- Returns:
- the text field
-
addButton
public javax.swing.JButton addButton(java.lang.String label, java.awt.event.ActionListener pressHandler)
Adds a button to the panel that will call the supplied action listener when pressed.- Parameters:
label
- the label text for the buttonpressHandler
- a listener to call when the button is pressed- Returns:
- returns the button that was added
-
startNewButtonGroup
public void startNewButtonGroup()
Starts a new button group. Any radio buttons that are added are automatically placed in the last-started group. Only one button in a given group can be selected at any one time.
-
addRadioButton
public javax.swing.JRadioButton addRadioButton(java.lang.String label, java.awt.event.ActionListener pressHandler)
Adds a new radio button that will be a member of the current button group.- Parameters:
label
- the label text for the buttonpressHandler
- an optional listener to call when the button is pressed; generally every button in the group would share a single listener- Returns:
- the new radio button
- See Also:
startNewButtonGroup()
-
add
public SettingBackedControl add(java.lang.String key, SettingBackedControl control)
Adds any setting backed control, mapped to key.- Parameters:
key
- the setting key namecontrol
- the control to add- Returns:
- the control
-
addUnmanagedControl
public javax.swing.JComponent addUnmanagedControl(javax.swing.JComponent uc)
Adds a custom control that will be managed by the caller. It is up to the subclass to map preference settings to and from the control.- Parameters:
uc
- the unmanaged control to add- Returns:
- the unmanaged control
-
addHelp
public void addHelp(java.lang.String helpPage, java.lang.String label)
Adds a help icon that links to a help page. If the help page looks like ahttp[s]
URL, the button will link to that page. Otherwise it is assumed to the base name of documentation page.- Parameters:
helpPage
- the page to open when the icon is clickedlabel
- an optional label for the help button- See Also:
StrangeEons.getUrlForDocPage(java.lang.String)
-
addHelp
@Deprecated public void addHelp(java.lang.String helpPage, java.lang.String label, boolean isDocPage)
Deprecated.
-
addTip
public void addTip(java.lang.String popupText)
Adds an icon that displays pop-up help text when hovered over.- Parameters:
popupText
- the text to display
-
join
public void join()
Causes the next control to be added to be placed on the same line as the previous control, instead of on a new line.
-
indent
public void indent()
Indent subsequent controls one additional level. Indentation is reset automatically when a heading or subheading is added.
-
unindent
public void unindent()
Reduce indentation of subsequent controls one level.
-
getPanel
public javax.swing.JPanel getPanel()
Description copied from interface:PreferenceCategory
Returns the panel of controls that allows the user to edit the settings for this category. The returned panel should match the design of standard panels, such as the use of a white background and gold headings.- Specified by:
getPanel
in interfacePreferenceCategory
- Returns:
- a panel of user interface controls
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-