Package generic.theme

# Class ThemeManager

java.lang.Object
generic.theme.ThemeManager

Direct Known Subclasses:
  `ApplicationThemeManager`, `HeadlessThemeManager`, `StubThemeManager`

public abstract class ThemeManager extends Object
This class manages application themes and their values. The ThemeManager is an abstract base class that has two concrete subclasses (and others for testing purposes) - StubThemeManager and ApplicationThememManager. The StubThemeManager exists as a placeholder until the ApplicationThemeManager is installed via `ApplicationThemeManager.initialize()`.

The basic idea is that all the colors, fonts, and icons used in an application should be accessed indirectly via an "id" string. Then the actual color, font, or icon can be changed without changing the source code. The default mapping of the id strings to a value is defined in .theme.properties files which are dynamically discovered by searching the module's data directory. Also, these files can optionally define a dark default value for an id which would replace the standard default value in the event that the current theme specifies that it is a dark theme. Themes are used to specify the application's `LookAndFeel`, whether or not it is dark, and any customized values for colors, fonts, or icons. There are several "built-in" themes, one for each supported `LookAndFeel`, but additional themes can be defined and stored in the users application home directory as a .theme file.

Clients that just need to access the colors, fonts, and icons from the theme can use the convenience methods in the `Gui` class. Clients that need to directly manipulate the themes and values will need to directly use the ThemeManager which and be retrieved using the static `getInstance()` method.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected LafType`
  `activeLafType`
  `protected GTheme`
  `activeTheme`
  `protected ApplicationThemeDefaults`
  `applicationDefaults`
  `protected GThemeValueMap`
  `currentValues`
  `protected static ThemeManager`
  `INSTANCE`
  `protected GThemeValueMap`
  `javaDefaults`
  `static final String`
  `THEME_DIR`
  `protected boolean`
  `useDarkDefaults`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ThemeManager()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addTheme(GTheme newTheme)`
  Adds the given theme to set of all themes.
  `void`
  `addThemeListener(ThemeListener listener)`
  Adds a `ThemeListener` to be notified of theme changes.
  `void`
  `adjustFonts(int amount)`
  Adjust the size of all fonts by the given amount.
  `protected void`
  `buildCurrentValues()`
  This method is called to create the internal set of theme value used by the application.
  `void`
  `deleteTheme(GTheme theme)`
  Removes the theme from the set of all themes.
  `protected void`
  `error(String message)`
  `GTheme`
  `getActiveTheme()`
  Returns the active theme.
  `Set<GTheme>`
  `getAllThemes()`
  Returns a set of all known themes.
  `GThemeValueMap`
  `getApplicationDarkDefaults()`
  Returns the `GThemeValueMap` containing all the dark default values defined in theme.properties files.
  `GThemeValueMap`
  `getApplicationLightDefaults()`
  Returns the `GThemeValueMap` containing all the standard default values defined in theme.properties files.
  `Color`
  `getColor(String id)`
  Returns the `Color` registered for the given id.
  `GThemeValueMap`
  `getCurrentValues()`
  Returns a `GThemeValueMap` of all current theme values including unsaved changes to the theme.
  `GThemeValueMap`
  `getDefaults()`
  Returns a `GThemeValueMap` containing all default values for the current theme.
  `static GTheme`
  `getDefaultTheme()`
  Returns the default theme for the current platform.
  `Font`
  `getFont(String id)`
  Returns the current `Font` associated with the given id.
  `Icon`
  `getIcon(String id)`
  Returns the Icon registered for the given id.
  `static ThemeManager`
  `getInstance()`
  `GThemeValueMap`
  `getJavaDefaults()`
  Returns the `GThemeValueMap` containing all the default theme values defined by the current `LookAndFeel`.
  `LafType`
  `getLookAndFeelType()`
  Returns the `LafType` for the currently active `LookAndFeel`
  `GThemeValueMap`
  `getNonDefaultValues()`
  Returns a `GThemeValueMap` contains all values that differ from the default values (values defined by the `LookAndFeel` or in the theme.properties files.
  `List<GTheme>`
  `getSupportedThemes()`
  Returns a set of all known themes that are supported on the current platform.
  `GTheme`
  `getTheme(String themeName)`
  Returns the known theme that has the given name.
  `GThemeValueMap`
  `getThemeValues()`
  Returns the theme values as defined by the current theme, ignoring any unsaved changes that are currently applied to the application.
  `boolean`
  `hasColor(String id)`
  Returns true if an color for the given Id has been defined
  `boolean`
  `hasFont(String id)`
  Returns true if an font for the given Id has been defined
  `boolean`
  `hasIcon(String id)`
  Returns true if an icon for the given Id has been defined
  `boolean`
  `hasThemeChanges()`
  Returns true if there are any unsaved changes to the current theme.
  `boolean`
  `hasThemeValueChanges()`
  Returns true if any theme values have changed.
  `protected void`
  `installInGui()`
  `boolean`
  `isChangedColor(String id)`
  Returns true if the color associated with the given id has been changed from the current theme value for that id.
  `boolean`
  `isChangedFont(String id)`
  Returns true if the font associated with the given id has been changed from the current theme value for that id.
  `boolean`
  `isChangedIcon(String id)`
  Returns true if the Icon associated with the given id has been changed from the current theme value for that id.
  `boolean`
  `isDarkTheme()`
  Returns true if the current theme use dark default values.
  `boolean`
  `isUsingAquaUI(ComponentUI UI)`
  Returns true if the given UI object is using the Aqua Look and Feel.
  `boolean`
  `isUsingNimbusUI()`
  Returns true if 'Nimbus' is the current Look and Feel
  `protected ApplicationThemeDefaults`
  `loadApplicationDefaults()`
  `protected void`
  `notifyThemeChanged(ThemeEvent event)`
  `void`
  `registerFont(Component component, String fontId)`
  Binds the component to the font identified by the given font id.
  `void`
  `removeThemeListener(ThemeListener listener)`
  Removes the given `ThemeListener` from the list of listeners to be notified of theme changes.
  `void`
  `restoreColor(String id)`
  Restores the current color value for the given color id to the value established by the current theme.
  `void`
  `restoreFont(String id)`
  Restores the current font value for the given font id to the value established by the current theme.
  `void`
  `restoreIcon(String id)`
  Restores the current icon value for the given icon id to the value established by the current theme.
  `void`
  `restoreThemeValues()`
  Restores all the current application back to the values as specified by the active theme.
  `void`
  `setColor(ColorValue newValue)`
  Updates the current value for the color id in the newValue
  `void`
  `setColor(String id, Color color)`
  Updates the current color for the given id.
  `void`
  `setFont(FontValue newValue)`
  Updates the current value for the font id in the newValue
  `void`
  `setFont(String id, Font font)`
  Updates the current font for the given id.
  `void`
  `setIcon(IconValue newValue)`
  Updates the current value for the `Icon` id in the newValue
  `void`
  `setIcon(String id, Icon icon)`
  Updates the current `Icon` for the given id.
  `void`
  `setLookAndFeel(LafType lafType, boolean useDarkDefaults)`
  Sets the current `LookAndFeel`.
  `void`
  `setTheme(GTheme theme)`
  Sets the application's active theme to the given theme.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### THEME_DIR

    public static final String THEME_DIR
    See Also:
      - Constant Field Values

  - ### INSTANCE

    protected static ThemeManager INSTANCE

  - ### activeTheme

    protected GTheme activeTheme

  - ### activeLafType

    protected LafType activeLafType

  - ### useDarkDefaults

    protected boolean useDarkDefaults

  - ### javaDefaults

    protected GThemeValueMap javaDefaults

  - ### currentValues

    protected GThemeValueMap currentValues

  - ### applicationDefaults

    protected ApplicationThemeDefaults applicationDefaults

- ## Constructor Details

  - ### ThemeManager

    public ThemeManager()

- ## Method Details

  - ### getInstance

    public static ThemeManager getInstance()

  - ### loadApplicationDefaults

    protected ApplicationThemeDefaults loadApplicationDefaults()

  - ### installInGui

    protected void installInGui()

  - ### buildCurrentValues

    protected void buildCurrentValues()
    This method is called to create the internal set of theme value used by the application. To do this, we use a layered approach to install values, with the last values added overwriting any pre-existing values with the same key. The values are added in the following order:

         java defaults -> light values -> dark values -> look and feel values -> property file values -> theme values

    At the point this method is called, this is the state of these various values:

    - The 'javaValues' are normalized in the form of 'laf.font.TextArea'
    - The 'applicationDefaults' contains values loaded from the `theme.properties` files:

               font.listing.base
               font.monospaced
               [color]Viewport.background = color.bg
               [laf.font]TextArea.font = font.monospaced
               [laf.boolean]Button.rollover = true

    - The 'activeTheme' values are those loaded by the current theme, which has any changes made to the default values

  - ### restoreThemeValues

    public void restoreThemeValues()
    Restores all the current application back to the values as specified by the active theme. In other words, reverts any changes to the active theme that haven't been saved.

  - ### restoreColor

    public void restoreColor(String id)
    Restores the current color value for the given color id to the value established by the current theme.
    Parameters:
      `id` - the color id to restore back to the original theme value

  - ### restoreFont

    public void restoreFont(String id)
    Restores the current font value for the given font id to the value established by the current theme.
    Parameters:
      `id` - the font id to restore back to the original theme value

  - ### restoreIcon

    public void restoreIcon(String id)
    Restores the current icon value for the given icon id to the value established by the current theme.
    Parameters:
      `id` - the icon id to restore back to the original theme value

  - ### isChangedColor

    public boolean isChangedColor(String id)
    Returns true if the color associated with the given id has been changed from the current theme value for that id.
    Parameters:
      `id` - the color id to check if it has been changed
    Returns:
      true if the color associated with the given id has been changed from the current theme value for that id.

  - ### isChangedFont

    public boolean isChangedFont(String id)
    Returns true if the font associated with the given id has been changed from the current theme value for that id.
    Parameters:
      `id` - the font id to check if it has been changed
    Returns:
      true if the font associated with the given id has been changed from the current theme value for that id.

  - ### isChangedIcon

    public boolean isChangedIcon(String id)
    Returns true if the Icon associated with the given id has been changed from the current theme value for that id.
    Parameters:
      `id` - the Icon id to check if it has been changed
    Returns:
      true if the Icon associated with the given id has been changed from the current theme value for that id.

  - ### setTheme

    public void setTheme(GTheme theme)
    Sets the application's active theme to the given theme.
    Parameters:
      `theme` - the theme to make active

  - ### setLookAndFeel

    public void setLookAndFeel(LafType lafType, boolean useDarkDefaults)
    Sets the current `LookAndFeel`. This is used by theme editors to allow users to see the effects of changing LookAndFeels when configuring a theme. Setting this different from the activeTheme's LookAndFeel setting means the the current theme is in an unsaved state and causes the `hasThemeChanges()` method to return true.
    Parameters:
      `lafType` - the `LafType` to set the LookAndFeel to
      `useDarkDefaults` - true if the application should used dark defaults with this LookAndFeel

  - ### addTheme

    public void addTheme(GTheme newTheme)
    Adds the given theme to set of all themes.
    Parameters:
      `newTheme` - the theme to add

  - ### deleteTheme

    public void deleteTheme(GTheme theme)
    Removes the theme from the set of all themes. Also, if the theme has an associated file, the file will be deleted.
    Parameters:
      `theme` - the theme to delete

  - ### getAllThemes

    public Set<GTheme> getAllThemes()
    Returns a set of all known themes.
    Returns:
      a set of all known themes.

  - ### getSupportedThemes

    public List<GTheme> getSupportedThemes()
    Returns a set of all known themes that are supported on the current platform.
    Returns:
      a set of all known themes that are supported on the current platform.

  - ### getActiveTheme

    public GTheme getActiveTheme()
    Returns the active theme.
    Returns:
      the active theme.

  - ### getLookAndFeelType

    public LafType getLookAndFeelType()
    Returns the `LafType` for the currently active `LookAndFeel`
    Returns:
      the `LafType` for the currently active `LookAndFeel`

  - ### getTheme

    public GTheme getTheme(String themeName)
    Returns the known theme that has the given name.
    Parameters:
      `themeName` - the name of the theme to retrieve
    Returns:
      the known theme that has the given name

  - ### getCurrentValues

    public GThemeValueMap getCurrentValues()
    Returns a `GThemeValueMap` of all current theme values including unsaved changes to the theme.
    Returns:
      a `GThemeValueMap` of all current theme values

  - ### getThemeValues

    public GThemeValueMap getThemeValues()
    Returns the theme values as defined by the current theme, ignoring any unsaved changes that are currently applied to the application.
    Returns:
      the theme values as defined by the current theme, ignoring any unsaved changes that are currently applied to the application

  - ### getNonDefaultValues

    public GThemeValueMap getNonDefaultValues()
    Returns a `GThemeValueMap` contains all values that differ from the default values (values defined by the `LookAndFeel` or in the theme.properties files.
    Returns:
      a `GThemeValueMap` contains all values that differ from the defaults.

  - ### getColor

    public Color getColor(String id)
    Returns the `Color` registered for the given id. Will output an error message if the id can't be resolved.
    Parameters:
      `id` - the id to get the direct color for
    Returns:
      the `Color` registered for the given id.

  - ### getFont

    public Font getFont(String id)
    Returns the current `Font` associated with the given id. A default font will be returned if the font can't be resolved and an error message will be printed to the console.
    Parameters:
      `id` - the id for the desired font
    Returns:
      the current `Font` associated with the given id.

  - ### getIcon

    public Icon getIcon(String id)
    Returns the Icon registered for the given id. If no icon is registered for the id, the default icon will be returned and an error message will be dumped to the console
    Parameters:
      `id` - the id to get the registered icon for
    Returns:
      the actual icon registered for the given id

  - ### setFont

    public void setFont(String id, Font font)
    Updates the current font for the given id.
    Parameters:
      `id` - the font id to update to the new color
      `font` - the new font for the id

  - ### setFont

    public void setFont(FontValue newValue)
    Updates the current value for the font id in the newValue
    Parameters:
      `newValue` - the new `FontValue` to install in the current values.

  - ### setColor

    public void setColor(String id, Color color)
    Updates the current color for the given id.
    Parameters:
      `id` - the color id to update to the new color
      `color` - the new color for the id

  - ### setColor

    public void setColor(ColorValue newValue)
    Updates the current value for the color id in the newValue
    Parameters:
      `newValue` - the new `ColorValue` to install in the current values.

  - ### setIcon

    public void setIcon(String id, Icon icon)
    Updates the current `Icon` for the given id.
    Parameters:
      `id` - the icon id to update to the new icon
      `icon` - the new `Icon` for the id

  - ### setIcon

    public void setIcon(IconValue newValue)
    Updates the current value for the `Icon` id in the newValue
    Parameters:
      `newValue` - the new `IconValue` to install in the current values.

  - ### getJavaDefaults

    public GThemeValueMap getJavaDefaults()
    Returns the `GThemeValueMap` containing all the default theme values defined by the current `LookAndFeel`.
    Returns:
      the `GThemeValueMap` containing all the default theme values defined by the current `LookAndFeel`

  - ### getApplicationDarkDefaults

    public GThemeValueMap getApplicationDarkDefaults()
    Returns the `GThemeValueMap` containing all the dark default values defined in theme.properties files. Note that dark defaults includes light defaults that haven't been overridden by a dark default with the same id.
    Returns:
      the `GThemeValueMap` containing all the dark values defined in theme.properties files

  - ### getApplicationLightDefaults

    public GThemeValueMap getApplicationLightDefaults()
    Returns the `GThemeValueMap` containing all the standard default values defined in theme.properties files.
    Returns:
      the `GThemeValueMap` containing all the standard values defined in theme.properties files

  - ### getDefaults

    public GThemeValueMap getDefaults()
    Returns a `GThemeValueMap` containing all default values for the current theme. It is a combination of application defined defaults and java `LookAndFeel` defaults.
    Returns:
      the current set of defaults.

  - ### isUsingAquaUI

    public boolean isUsingAquaUI(ComponentUI UI)
    Returns true if the given UI object is using the Aqua Look and Feel.
    Parameters:
      `UI` - the UI to examine.
    Returns:
      true if the UI is using Aqua

  - ### isUsingNimbusUI

    public boolean isUsingNimbusUI()
    Returns true if 'Nimbus' is the current Look and Feel
    Returns:
      true if 'Nimbus' is the current Look and Feel

  - ### addThemeListener

    public void addThemeListener(ThemeListener listener)
    Adds a `ThemeListener` to be notified of theme changes.
    Parameters:
      `listener` - the listener to be notified

  - ### removeThemeListener

    public void removeThemeListener(ThemeListener listener)
    Removes the given `ThemeListener` from the list of listeners to be notified of theme changes.
    Parameters:
      `listener` - the listener to be removed

  - ### hasThemeChanges

    public boolean hasThemeChanges()
    Returns true if there are any unsaved changes to the current theme.
    Returns:
      true if there are any unsaved changes to the current theme.

  - ### hasThemeValueChanges

    public boolean hasThemeValueChanges()
    Returns true if any theme values have changed. This does not take into account the current Look and Feel. Use `hasThemeChanges()` to also account for changes to the Look and Feel.
    Returns:
      true if any theme values have changed

  - ### hasColor

    public boolean hasColor(String id)
    Returns true if an color for the given Id has been defined
    Parameters:
      `id` - the id to check for an existing color.
    Returns:
      true if an color for the given Id has been defined

  - ### hasFont

    public boolean hasFont(String id)
    Returns true if an font for the given Id has been defined
    Parameters:
      `id` - the id to check for an existing font.
    Returns:
      true if an font for the given Id has been defined

  - ### hasIcon

    public boolean hasIcon(String id)
    Returns true if an icon for the given Id has been defined
    Parameters:
      `id` - the id to check for an existing icon.
    Returns:
      true if an icon for the given Id has been defined

  - ### registerFont

    public void registerFont(Component component, String fontId)
    Binds the component to the font identified by the given font id. Whenever the font for the font id changes, the component will updated with the new font.
    Parameters:
      `component` - the component to set/update the font
      `fontId` - the id of the font to register with the given component

  - ### isDarkTheme

    public boolean isDarkTheme()
    Returns true if the current theme use dark default values.
    Returns:
      true if the current theme use dark default values.

  - ### getDefaultTheme

    public static GTheme getDefaultTheme()
    Returns the default theme for the current platform.
    Returns:
      the default theme for the current platform.

  - ### notifyThemeChanged

    protected void notifyThemeChanged(ThemeEvent event)

  - ### error

    protected void error(String message)

  - ### adjustFonts

    public void adjustFonts(int amount)
    Adjust the size of all fonts by the given amount.
    Parameters:
      `amount` - the number to add to the current font size;