Package generic.theme

# Class Gui

java.lang.Object
generic.theme.Gui

public class Gui extends Object
Provides a static set of methods for globally managing application themes and their values.

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 {name}.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 {name}.theme file.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `addThemeListener(ThemeListener listener)`
  Adds a `ThemeListener` to be notified of theme changes.
  `static Color`
  `brighter(Color color)`
  Returns a brighter version of the given color or darker if the current theme is dark.
  `static Color`
  `darker(Color color)`
  Returns a darker version of the given color or brighter if the current theme is dark.
  `static Color`
  `getColor(String id)`
  Returns the `Color` registered for the given id.
  `static Font`
  `getFont(String id)`
  Returns the current `Font` associated with the given id.
  `static Icon`
  `getIcon(String id)`
  Returns the Icon registered for the given id.
  `static boolean`
  `hasColor(String id)`
  Returns true if an color for the given Id has been defined
  `static boolean`
  `hasFont(String id)`
  Returns true if an font for the given Id has been defined
  `static boolean`
  `hasIcon(String id)`
  Returns true if an icon for the given Id has been defined
  `static boolean`
  `isBlinkingCursors()`
  Returns true if the application should allow blinking cursors, false otherwise.
  `static boolean`
  `isDarkTheme()`
  Returns true if the active theme is using dark defaults
  `static boolean`
  `isSystemId(String id)`
  Returns true if the given id is a system-defined id, such as those starting with `laf.color` or `system.color`.
  `static boolean`
  `isUpdatingTheme()`
  Returns true if the theme system is in the process of updating
  `static void`
  `registerFont(Component component, String fontId)`
  Binds the component to the font identified by the given font id.
  `static void`
  `registerFont(JComponent component, int fontStyle)`
  Registers the given component with the given font style.
  `static void`
  `removeThemeListener(ThemeListener listener)`
  Removes the given `ThemeListener` from the list of listeners to be notified of theme changes.
  `static void`
  `setBlinkingCursors(boolean b)`
  Sets application's blinking cursor state.
  `static void`
  `unRegisterFont(JComponent component, String fontId)`
  Removes the component and font id binding made in a previous call to `registerFont(Component, String)`.

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

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

- ## Method Details

  - ### getFont

    public static 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.

  - ### getColor

    public static 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.

  - ### addThemeListener

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

  - ### removeThemeListener

    public static 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

  - ### getIcon

    public static 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

  - ### hasColor

    public static 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 static 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 static 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

  - ### darker

    public static Color darker(Color color)
    Returns a darker version of the given color or brighter if the current theme is dark.
    Parameters:
      `color` - the color to get a darker version of
    Returns:
      a darker version of the given color or brighter if the current theme is dark

  - ### brighter

    public static Color brighter(Color color)
    Returns a brighter version of the given color or darker if the current theme is dark.
    Parameters:
      `color` - the color to get a brighter version of
    Returns:
      a brighter version of the given color or darker if the current theme is dark

  - ### registerFont

    public static 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.

    Calling this method will trigger a call to `JComponent.setFont(Font)`.

    Parameters:
      `component` - the component to set/update the font
      `fontId` - the id of the font to register with the given component

  - ### registerFont

    public static void registerFont(JComponent component, int fontStyle)
    Registers the given component with the given font style. This method allows clients to not define a font id in the theme system, but instead to signal that they want the default font for the given component, modified with the given style. As the underlying font is changed, the client will be updated with that new font with the given style applied.

    Most clients should not be using this method. Instead, use `registerFont(JComponent, int)`.

    The downside of using this method is that the end user cannot modify the style of the font. By using the standard theming mechanism for registering fonts, the end user has full control.

    Parameters:
      `component` - the component to set/update the font
      `fontStyle` - the font style, one of Font.BOLD, Font.ITALIC,

  - ### unRegisterFont

    public static void unRegisterFont(JComponent component, String fontId)
    Removes the component and font id binding made in a previous call to `registerFont(Component, String)`.

    Clients need to call this method if they decide to change the font id being used for a given component. Must clients do not need to use this method.

    Parameters:
      `component` - the component to remove
      `fontId` - the id of the font previously registered

  - ### isDarkTheme

    public static boolean isDarkTheme()
    Returns true if the active theme is using dark defaults
    Returns:
      true if the active theme is using dark defaults

  - ### isUpdatingTheme

    public static boolean isUpdatingTheme()
    Returns true if the theme system is in the process of updating
    Returns:
      true if the theme system is in the process of updating

  - ### isSystemId

    public static boolean isSystemId(String id)
    Returns true if the given id is a system-defined id, such as those starting with `laf.color` or `system.color`.
    Parameters:
      `id` - the id
    Returns:
      true if the given id is a system-defined id

  - ### setBlinkingCursors

    public static void setBlinkingCursors(boolean b)
    Sets application's blinking cursor state. This will affect all JTextFields, JTextAreas, JTextPanes via `UIDefaults`. Custom components can also respect this setting by either adding a `ThemeListener` or overriding `JComponent.updateUI()`

    NOTE: This method is a bit odd here as it doesn't really apply to a theme. But it requires manipulation of the look and feel which is managed by the theme. If other application level properties come along and also require changing the UIDefaults, perhaps a more general solution might be to add a way for clients to register a callback so that they get a chance to change the UIDefaults map as the look and feel is loaded.

    Parameters:
      `b` - true for blinking text cursors, false for non-blinking text cursors

  - ### isBlinkingCursors

    public static boolean isBlinkingCursors()
    Returns true if the application should allow blinking cursors, false otherwise. Custom components can use this method to determine if they should have a blinking cursor or not.
    Returns:
      true if the application should allow blinking cursors, false otherwise.