Package ca.cgjennings.apps.arkham.dialog.prefs

Class 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()
      Returns the settings instance used by this category to load and store settings.
      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.

      • Methods inherited from class java.lang.Object

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

    • 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 category
        iconImage - 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 category
        iconResource - 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 category
        icon - 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 used
        title - the localized name of the category
        iconImage - 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 used
        title - the localized name of the category
        iconResource - 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 used
        title - the localized name of the category
        icon - 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 interface PreferenceCategory
        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. If null is returned, a default icon will be used.
        Specified by:
        getIcon in interface PreferenceCategory
        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 with addResetKey(java.lang.String) have changed value, and returns true if they have.
        Specified by:
        isRestartRequired in interface PreferenceCategory
        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 interface PreferenceCategory

      • 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 interface PreferenceCategory

      • getSettings

        public final Settings getSettings()
        Returns the settings instance used by this category to load and store settings.

      • 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 is true, then the box will be checked when the setting is false instead of true.
        Parameters:
        key - the setting key name
        text - the text for the checkbox
        invert - 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 name
        labels - the list of labels to show in the drop down
        values - 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 name
        min - the minimum value
        max - the maximum value
        stepSize - 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 use
        label - the label text to use, or null
        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 button
        pressHandler - 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 button
        pressHandler - 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 name
        control - 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 a http[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 clicked
        label - 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 interface PreferenceCategory
        Returns:
        a panel of user interface controls

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object