Class Theme

  • Direct Known Subclasses:
    DagonTheme, HydraTheme, PluginTestTheme, TchoTchoTheme, UltharTheme

    public abstract class Theme
    extends java.lang.Object
    A Theme encapsulates a UI design theme. Themes are applied while installing a look and feel and given an opportunity to modify its design parameters (typically by changing values in either the default or look and feel UIDefaults).
    Since:
    2.00RC1
    Author:
    Chris Jennings
    • Constructor Summary

      Constructors 
      Constructor Description
      Theme()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      Settings.Colour applyThemeToColor​(int argb)
      Gives the theme the opportunity to modify a colour to refelct the theme.
      Settings.Colour applyThemeToColor​(java.awt.Color source)
      Gives the theme the opportunity to modify a colour to reflect the theme.
      java.awt.image.BufferedImage applyThemeToImage​(java.awt.image.BufferedImage source)
      Gives the theme the opportunity to modify a image to reflect the theme.
      javax.swing.LookAndFeel createLookAndFeelInstance()
      Returns an instance of the look and feel for the theme.
      static java.lang.String findAvailableFontFamily​(java.lang.String families)
      Returns the first font family in a list of comma-separated font families that is available on this system.
      static java.lang.String findAvailableFontFamily​(java.lang.String[] families)
      Given an array of font family names, returns the first font family that is available on this system.
      static javax.swing.Icon getDisabledIcon​(javax.swing.JComponent component, javax.swing.Icon icon)
      A helper that returns a disabled version of any icon.
      java.lang.String getLookAndFeelClassName()
      Returns the look and feel class name.
      java.net.URL getSyntaxThemeUrl()
      Returns a URL for a file that describes this theme's preferred syntax highlighting theme, or null to use a default.
      java.lang.String getThemeDescription()
      An optional sentence (without final punctuation) that briefly describes the theme.
      java.lang.String getThemeGroup()
      Returns a string that names a group to which the theme belongs.
      ThemedIcon getThemeIcon()
      Returns an icon for the theme.
      java.lang.String getThemeName()
      Returns the name of this theme, as it should be presented to the user.
      boolean isDark()
      Returns whether the theme is, on the whole, light-on-dark, similar to OS "dark modes".
      void modifyLookAndFeel​(javax.swing.LookAndFeel laf)
      This method is called just before the look and feel is installed and just after modifyLookAndFeelDefaults(javax.swing.UIDefaults).
      abstract void modifyLookAndFeelDefaults​(javax.swing.UIDefaults defaults)
      This method is called after the look and feel has been instantiated but before it has been installed and allows you to modify the look and feel's default properties.
      abstract void modifyManagerDefaults​(javax.swing.UIDefaults defaults)
      This method is called prior to instantiating the look and feel and allows you to modify the UI manager's default properties.
      void themeInstalled()
      Called just after the look and feel has been installed.
      java.lang.String toString()
      Returns the name of the theme, as given by getThemeName().
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • ALTERNATE_DOCUMENT_TAB_ORIENTATION

        public static final java.lang.String ALTERNATE_DOCUMENT_TAB_ORIENTATION
        A UI key that controls a boolean property that affects whether document tabs should switch their orientation. Set if tabs look wrong for a given L&F.
        See Also:
        Constant Field Values
      • HEADING_BORDER

        public static final java.lang.String HEADING_BORDER
        A UI key that contains the Border used for headings and subheadings. If null, a default algorithm is used to create a suitably themed border. The font for headings is based on the font used for titled borders, at a larger size. (If that font is not available, the default font for labels is used.)
        See Also:
        JHeading, Constant Field Values
      • EDITOR_TAB_BACKGROUND

        public static final java.lang.String EDITOR_TAB_BACKGROUND
        A UI key that contains the Color used for the background of the editor tabs.
        See Also:
        Constant Field Values
      • SIDEPANEL_TITLE_BACKGROUND

        public static final java.lang.String SIDEPANEL_TITLE_BACKGROUND
        A UI key that contains the Color used for the background of sidepanel title bars, like at the top of project views.
        See Also:
        Constant Field Values
      • SIDEPANEL_TITLE_FOREGROUND

        public static final java.lang.String SIDEPANEL_TITLE_FOREGROUND
        A UI key that contains the Color used for the foreground of sidepanel title bars, like at the top of project views.
        See Also:
        Constant Field Values
      • FILE_DROP_BORDER

        public static final java.lang.String FILE_DROP_BORDER
        A UI key that contains the Color used for the border drawn around fields that accept a file drop when files are dragged over them.
        See Also:
        Constant Field Values
      • CONTEXT_BAR_BACKGROUND

        public static final java.lang.String CONTEXT_BAR_BACKGROUND
        UI key for context bar background colour.
        See Also:
        Constant Field Values
      • CONTEXT_BAR_FOREGROUND

        public static final java.lang.String CONTEXT_BAR_FOREGROUND
        UI key for context bar foreground colour.
        See Also:
        Constant Field Values
      • CONTEXT_BAR_BUTTON_BACKGROUND

        public static final java.lang.String CONTEXT_BAR_BUTTON_BACKGROUND
        UI key for context bar button background colour.
        See Also:
        Constant Field Values
      • CONTEXT_BAR_BUTTON_ROLLOVER_BACKGROUND

        public static final java.lang.String CONTEXT_BAR_BUTTON_ROLLOVER_BACKGROUND
        UI key for context bar button background colour when under pointer.
        See Also:
        Constant Field Values
      • CONTEXT_BAR_BUTTON_ROLLOVER_OUTLINE_FOREGROUND

        public static final java.lang.String CONTEXT_BAR_BUTTON_ROLLOVER_OUTLINE_FOREGROUND
        UI key for context bar button outline colour when under pointer.
        See Also:
        Constant Field Values
      • CONTEXT_BAR_BUTTON_ARMED_OUTLINE_FOREGROUND

        public static final java.lang.String CONTEXT_BAR_BUTTON_ARMED_OUTLINE_FOREGROUND
        UI key for context bar button outline colour when held down.
        See Also:
        Constant Field Values
      • CYCLE_BUTTON_ICON_MARGIN_ADJUSTMENT

        public static final java.lang.String CYCLE_BUTTON_ICON_MARGIN_ADJUSTMENT
        A UI key for an adjustment applied to the margin of cycle buttons to move the cycle icon close to the button edge.
        See Also:
        Constant Field Values
      • CONSOLE_BACKROUND

        public static final java.lang.String CONSOLE_BACKROUND
        UI key for console background colour; used if painter is null.
        See Also:
        Constant Field Values
      • CONSOLE_BACKGROUND_PAINTER

        public static final java.lang.String CONSOLE_BACKGROUND_PAINTER
        UI key for console background colour.
        See Also:
        Constant Field Values
      • CONSOLE_OUTPUT

        public static final java.lang.String CONSOLE_OUTPUT
        UI key for console output text colour.
        See Also:
        Constant Field Values
      • CONSOLE_ERROR

        public static final java.lang.String CONSOLE_ERROR
        UI key for console error text colour.
        See Also:
        Constant Field Values
      • CONSOLE_WARNING

        public static final java.lang.String CONSOLE_WARNING
        UI key for console warning text colour.
        See Also:
        Constant Field Values
      • CONSOLE_INFO

        public static final java.lang.String CONSOLE_INFO
        UI key for console information text colour.
        See Also:
        Constant Field Values
      • CONSOLE_SELECTION_BACKGROUND

        public static final java.lang.String CONSOLE_SELECTION_BACKGROUND
        UI key for console text selection background colour.
        See Also:
        Constant Field Values
      • CONSOLE_SELECTION_FOREGROUND

        public static final java.lang.String CONSOLE_SELECTION_FOREGROUND
        UI key for console text selection foreground colour.
        See Also:
        Constant Field Values
      • CONSOLE_FONT

        public static final java.lang.String CONSOLE_FONT
        UI key for console font.
        See Also:
        Constant Field Values
      • NOTES_BACKGROUND

        public static final java.lang.String NOTES_BACKGROUND
        UI key for text notes panels (e.g., project notes) background colour.
        See Also:
        Constant Field Values
      • NOTES_FOREGROUND

        public static final java.lang.String NOTES_FOREGROUND
        UI key for text notes panels (e.g., project notes) foreground colour.
        See Also:
        Constant Field Values
      • LINK_LABEL_FOREGROUND

        public static final java.lang.String LINK_LABEL_FOREGROUND
        UI key for the foreground colour of JLinkLabels.
        See Also:
        Constant Field Values
      • MESSAGE_BORDER_EXTERIOR

        public static final java.lang.String MESSAGE_BORDER_EXTERIOR
        Exterior border colour of mesage pop-ups.
        See Also:
        Constant Field Values
      • MESSAGE_BORDER_EDGE

        public static final java.lang.String MESSAGE_BORDER_EDGE
        Interior border colour of mesage pop-ups.
        See Also:
        Constant Field Values
      • MESSAGE_BORDER_MAIN

        public static final java.lang.String MESSAGE_BORDER_MAIN
        Primary border colour of mesage pop-ups.
        See Also:
        Constant Field Values
      • MESSAGE_BACKGROUND

        public static final java.lang.String MESSAGE_BACKGROUND
        Background colour of mesage pop-ups.
        See Also:
        Constant Field Values
      • MESSAGE_FOREGROUND

        public static final java.lang.String MESSAGE_FOREGROUND
        Foreground (text) colour of mesage pop-ups.
        See Also:
        Constant Field Values
      • MESSAGE_BORDER_INFORMATION

        public static final java.lang.String MESSAGE_BORDER_INFORMATION
        Message pop-up border for informational messages.
        See Also:
        Constant Field Values
      • MESSAGE_BORDER_DIALOG

        public static final java.lang.String MESSAGE_BORDER_DIALOG
        Message pop-up border for dialog messages.
        See Also:
        Constant Field Values
      • PROJECT_FIND_BACKGROUND

        public static final java.lang.String PROJECT_FIND_BACKGROUND
        UI key for project search field background colour.
        See Also:
        Constant Field Values
      • PROJECT_FIND_FOREGROUND

        public static final java.lang.String PROJECT_FIND_FOREGROUND
        UI key for project search field foreground colour.
        See Also:
        Constant Field Values
      • PLUGIN_README_BACKGROUND

        public static final java.lang.String PLUGIN_README_BACKGROUND
        UI key for plug-in installation notes and catalog info background colour.
        See Also:
        Constant Field Values
      • PLUGIN_README_FOREGROUND

        public static final java.lang.String PLUGIN_README_FOREGROUND
        UI key for plug-in installation notes and catalog info foreground colour.
        See Also:
        Constant Field Values
      • PROJECT_NOTES_TAB_BACKGROUND

        public static final java.lang.String PROJECT_NOTES_TAB_BACKGROUND
        UI key for the project area properties/notes tabs background color.
        See Also:
        Constant Field Values
      • PROJECT_HEADER_BACKGROUND

        public static final java.lang.String PROJECT_HEADER_BACKGROUND
        UI key for the background colour used for project view headers (Project Files, Add New Task..., Properties/Notes, etc.)
        See Also:
        Constant Field Values
      • PROJECT_HEADER_FOREGROUND

        public static final java.lang.String PROJECT_HEADER_FOREGROUND
        UI key for the background colour used for project view headers (Project Files, Add New Task..., Properties/Notes, etc.)
        See Also:
        Constant Field Values
      • PREFS_BACKGROUND

        public static final java.lang.String PREFS_BACKGROUND
        UI key for project search field background colour.
        See Also:
        Constant Field Values
      • PREFS_FOREGROUND

        public static final java.lang.String PREFS_FOREGROUND
        UI key for project search field foreground colour.
        See Also:
        Constant Field Values
      • PREFS_HEADING

        public static final java.lang.String PREFS_HEADING
        UI key for project search field foreground colour.
        See Also:
        Constant Field Values
      • HEAD_BANNER_FOREGROUND

        public static final java.lang.String HEAD_BANNER_FOREGROUND
        UI key for the "head banner" foreground colour. This is a rectangular banner with higher contrast than a standard label-on-panel. The most prominent example is the MultiCloseDialog.
        See Also:
        Constant Field Values
      • HEAD_BANNER_BACKGROUND

        public static final java.lang.String HEAD_BANNER_BACKGROUND
        UI key for the "head banner" backround colour. This is a rectangular banner with higher contrast than a standard label-on-panel.
        See Also:
        Constant Field Values
      • DISABLED_ICON_FILTER

        public static final java.lang.String DISABLED_ICON_FILTER
        An image filter used to create a disabled icon from a regular icon when no disabled icon is explicitly set. If set, the value must be a subclass of BufferedImageOp. (This includes any filter in the ca.cgjennings.graphics.filters package.)
        See Also:
        Constant Field Values
    • Constructor Detail

      • Theme

        public Theme()
    • Method Detail

      • getThemeName

        public java.lang.String getThemeName()
        Returns the name of this theme, as it should be presented to the user. Theme names are typically short, one or two words. A localized theme name should use the UI locale (Language.getInterfaceLocale()).

        The base class generates a name from the class name by removing "Theme" from the end (if present) and inserting a space whenever an upper case letter follows a lower case letter. So, for example, "TchoTchoTheme" would become "Tcho Tcho".

        Returns:
        the human-friendly name of this theme
      • getThemeDescription

        public java.lang.String getThemeDescription()
        An optional sentence (without final punctuation) that briefly describes the theme. The base class returns null to indicate that no description is provided.
        Returns:
        a theme description
      • getThemeGroup

        public java.lang.String getThemeGroup()
        Returns a string that names a group to which the theme belongs. Themes that have the same group will be placed together in the list of selectable themes. The base class returns the theme name. Themes that complement each other, such as light and dark variants of the same theme, should return the same group name. It is recommended to use the name of the light theme as the group name for both.
        Returns:
        a non-null string naming the theme's group
      • isDark

        public boolean isDark()
        Returns whether the theme is, on the whole, light-on-dark, similar to OS "dark modes". The base class returns false.
        Returns:
        true if the theme is a "dark mode" style theme
        Since:
        3.2
      • getThemeIcon

        public ThemedIcon getThemeIcon()
        Returns an icon for the theme. The base class attempts to find an image in the same package as the theme's class, with the same name, but with a file extension of either ".png" or ".jp2" (in that order). Multiple versions of the image can be provided using "@Nx" file name suffixes, as in MyTheme.png, MyTheme@2x.png.
        Returns:
        the theme's representative image
      • toString

        public final java.lang.String toString()
        Returns the name of the theme, as given by getThemeName().
        Overrides:
        toString in class java.lang.Object
        Returns:
        the name of this theme
      • findAvailableFontFamily

        public static java.lang.String findAvailableFontFamily​(java.lang.String families)
        Returns the first font family in a list of comma-separated font families that is available on this system. If none of the families is available, a standard sans-serif family is returned.
        Parameters:
        families - a list of comma-separated font family names
        Returns:
        the first available entry in the list, or the standard sans-serif family name
      • findAvailableFontFamily

        public static java.lang.String findAvailableFontFamily​(java.lang.String[] families)
        Given an array of font family names, returns the first font family that is available on this system. If none of the font families in the array are available, this method returns Font.SANS_SERIF.
        Parameters:
        families - an array of candidate family names
        Returns:
        the available candidate with the lowest index in families, or the standard sans-serif family name
      • getLookAndFeelClassName

        public java.lang.String getLookAndFeelClassName()
        Returns the look and feel class name. Subclasses may override this to use a custom look and feel.
        Returns:
        the name of a LookAndFeel subclass
      • createLookAndFeelInstance

        public javax.swing.LookAndFeel createLookAndFeelInstance()
        Returns an instance of the look and feel for the theme. If getLookAndFeelClassName() returns null, then the theme installer will call this instead. The base class throws an UnsupportedOperationException. If the class name is null and this returns null, the app will refuse to start.
        Returns:
        a non-null look-and-feel instance for the theme
      • modifyManagerDefaults

        public abstract void modifyManagerDefaults​(javax.swing.UIDefaults defaults)
        This method is called prior to instantiating the look and feel and allows you to modify the UI manager's default properties.
        Parameters:
        defaults - the UIManager defaults
      • modifyLookAndFeelDefaults

        public abstract void modifyLookAndFeelDefaults​(javax.swing.UIDefaults defaults)
        This method is called after the look and feel has been instantiated but before it has been installed and allows you to modify the look and feel's default properties.
        Parameters:
        defaults - the Look and Feel UI defaults
      • modifyLookAndFeel

        public void modifyLookAndFeel​(javax.swing.LookAndFeel laf)
        This method is called just before the look and feel is installed and just after modifyLookAndFeelDefaults(javax.swing.UIDefaults). It allows you to make any final changes to the look and feel before it is installed.

        The base class implementation does nothing.

        Parameters:
        laf - the look and feel to be installed
      • themeInstalled

        public void themeInstalled()
        Called just after the look and feel has been installed. This is the final step of theme installation and provides the theme with a chance to clean up any resources that are no longer required.

        The base class implementation does nothing.

      • applyThemeToImage

        public java.awt.image.BufferedImage applyThemeToImage​(java.awt.image.BufferedImage source)
        Gives the theme the opportunity to modify a image to reflect the theme. The base class returns source unmodified.

        Important: Themes that wish to override this to modify images must be sure to return a copy of the original image and leave the source unmodified to avoid corrupting the image cache.

        Parameters:
        source - the image to apply themeing to
        Returns:
        a themed copy of the image, or the original image if it is not modified by the theme
        See Also:
        #applyThemeToImage(java.lang.String)
      • applyThemeToColor

        public Settings.Colour applyThemeToColor​(java.awt.Color source)
        Gives the theme the opportunity to modify a colour to reflect the theme. The base class returns the input without changes, other than ensuring it is a Colour.
        Parameters:
        source - the colour to theme
        Returns:
        a modified colour, or the original colour
      • applyThemeToColor

        public final Settings.Colour applyThemeToColor​(int argb)
        Gives the theme the opportunity to modify a colour to refelct the theme. This is a convenience that passes the ARGB value through applyThemeToColor(java.awt.Color).
        Parameters:
        argb - the colour to theme, as an int in ARGB format
        Returns:
        a modified colour, or the original colour
      • getSyntaxThemeUrl

        public java.net.URL getSyntaxThemeUrl()
        Returns a URL for a file that describes this theme's preferred syntax highlighting theme, or null to use a default.
        Returns:
        URL of a document describing the syntax theme, or null
      • getDisabledIcon

        public static javax.swing.Icon getDisabledIcon​(javax.swing.JComponent component,
                                                       javax.swing.Icon icon)
        A helper that returns a disabled version of any icon. Used by look-and-feel implementations to provide default disabled icons.
        Parameters:
        component - the component that the icon is for; may be null
        icon - the icon to convert
        Returns:
        a version of the icon that will render in a disabled state