Package ca.cgjennings.ui.theme

Class ThemedGlyphIcon

  • All Implemented Interfaces:
    ThemedIcon, javax.swing.Icon
    public class ThemedGlyphIcon
extends AbstractThemedIcon
    A resolution independent icon that is drawn using glyphs (symbols) taken from a font. A glyph icon can be created from a specific font, code point, and colour description, but more commonly it is created either from a label or descriptor. A label-based icon displays a letter chosen from automatically from a label string, optionally with a solid circular background. A descriptor is a compact string that describes how to compose the icon design. A descriptor can be as simple as the single code point of the symbol you want to display, or it can compose multiple glyphs using a combination of sizes, positions, orientations, and colours. Descriptors have the following syntax: 
    [gly:]CP[!][%][*][,FG[,BG]][@[Z][,+|-ADJ[,DX[,DY]]]][;...]
    gly:
    This character sequence is used to distinguish a glyph icon from a resource path, and is ignored here if present; it is followed by one or more layers separated by semicolons. Each layer consists of a single glyph and, optionally, colour and layout information.
    CP
    The hexadecimal code point of the glyph to show, or a single character such as A. The special characters ; ! % * , @ can only be indicated by hexadecimal code point. (By convention the code point uses upper case letters, while colours use lower case.)
    !
    If present after a code point, the glyph is mirrored from left-to-right.
    %
    If present after a code point, the glyph is mirrored from top-to-bottom.
    *
    If present after a code point, the glyph is rotated 45 degrees clockwise. (Any rotation that is a multiple of 90 degrees can be produced using a combination of !, %, and *.)
    ,FG
    The foreground (glyph) colour, see below (optional).
    ,BG
    The background colour, see below (optional). When a background colour is present, a filled circle (disc) is drawn behind the glyph.
    @
    This character indicates that a size and adjustment block will follow. It must be present for any of the size, font size, or offset components to occur. It is used to distinguish the adjustment block from a colour block (which is optional).
    Z
    The icon size (optional). This can be an integer number of points or one of the following characters: t tiny, s small, S medium small, m medium, M medium large, l large, L very large, g gigantic. The default is small, which is intended for menu items and most buttons and labels. If an icon size is set in more than one layer, the one closest to the end of the descriptor is used.
    +|-ADJ
    This adjusts the font size, relative to the icon's design grid (see below). It consists of either a plus sign (+) or minus sign (-), followed by a number indicating the relative amount to increase or decrease the font size for this glyph. The number may include a radix point (.) and fractional component.
    ,DX
    Adjusts the relative horizontal position of the glyph from center, in design grid units (see below).
    ,DY
    Adjusts the relative vertical position of the glyph from center, in design grid units (see below).
    ;...
    Glyphs may be stacked by listing multiple layers separated by semicolons (;). Layers are listed in order from bottom (drawn first) to top (drawn last).

    Icon colours
    A colour is either a Web-style hex string or a single character that describes a standard palette colour. The standard palette colours are: r (red), o (orange), y (yellow), g (green), b (blue), i (indigo), v (violet), p (pink), w (brown), t (teal) c (cyan), k (grey), 0 (black) or 1 (white). The actual colour obtained may vary depending on the installed theme. A Web-style colour can be 3 or 6 hex digits (4 or 8 if an alpha value is included) in ARGB order (not RGBA). They may start with #, which is ignored. Web colours may also be modified by the theme, although most themes do not do so. To explicitly forbid modifying a colour, append a !. For example, the following would produce pure red that cannot be modified: #f00!, as would ff0000!. A ! can be added to a palette colour, but it has no effect as palette colours are always determined by the theme.

    Palette colours have light and dark variants which are chosen based on whether the theme is light or dark. For example, a dark mode theme has dark backgrounds, so the light variant is typically chosen. Using a capital letter for the colour code will switch a light variant to dark or vice-versa. The default colour when none is specified is a "typical" colour taken from the theme designed to pair with standard label text.

    If a background colour is specified, the background is drawn as a filled circle (disc) behind the glyph. When a background colour is used, the background defaults to using a dark colour for the background and a light colour for the glyph, and the default foreground is white.

    The design grid and icon position adjustments
    The icon is composed against a hypothetical design grid that is 18 units by 18 units. All size adjustments and position offsets use these units. Hence, a DX value of 1 will shift the glyph 1/18 of the icon width to the right of the center.

    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Constructor Description
      ThemedGlyphIcon​(java.awt.Font font, int codePoint, java.awt.Color fg, java.awt.Color bg)
      Creates a new glyph icon that displays the specified code point using the supplied font and colours.
      ThemedGlyphIcon​(java.awt.Font font, java.lang.String descriptor)
      Creates a glyph icon from a descriptor that will draw glyphs from the specified font.
      ThemedGlyphIcon​(java.lang.String descriptor)
      Creates a glyph icon for a built-in icon from a compact string descriptor.
      ThemedGlyphIcon​(java.lang.String label, java.awt.Color fg, java.awt.Color bg)
      Creates a new glyph icon that displays a letter selected from a specified string.

    • Field Detail

      • GLYPH_RESOURCE_PREFIX

        public static final java.lang.String GLYPH_RESOURCE_PREFIX
        Prefix used to identify a glyph icon descriptor to {@link ResourceKit.getIcon()}. This is ignored, if present, at the start of a descriptor string.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ThemedGlyphIcon

        public ThemedGlyphIcon​(java.lang.String label,
                       java.awt.Color fg,
                       java.awt.Color bg)
        Creates a new glyph icon that displays a letter selected from a specified string. For example, given the string "The monkey is happy.", the icon might display the letter M (from monkey).

        Note: Tag strings and descriptors, while both strings, are interpreted completely differently.

        Parameters:
        label - a string containing text from which a letter should be chosen for the icon to display
        fg - an optional foreground colour, if null a default is selected
        bg - an optional background colour, if null then no background is included
        See Also:
        derive(java.lang.String), ThemedGlyphIcon(java.lang.String)

      • ThemedGlyphIcon

        public ThemedGlyphIcon​(java.awt.Font font,
                       int codePoint,
                       java.awt.Color fg,
                       java.awt.Color bg)
        Creates a new glyph icon that displays the specified code point using the supplied font and colours.
        Parameters:
        font - the font to use to draw the glyph symbol
        codePoint - the code point of the glyph to draw
        fg - the foreground (glyph) colour
        bg - the background; if non-null, a filled circle is drawn in this colour behind the glyph

      • ThemedGlyphIcon

        public ThemedGlyphIcon​(java.awt.Font font,
                       java.lang.String descriptor)
        Creates a glyph icon from a descriptor that will draw glyphs from the specified font. See the class description for descriptor syntax.
        Parameters:
        font - the font containing the desired glyphs
        descriptor - the non-null icon description

      • ThemedGlyphIcon

        public ThemedGlyphIcon​(java.lang.String descriptor)
        Creates a glyph icon for a built-in icon from a compact string descriptor. See the class description for descriptor syntax.
        Parameters:
        descriptor - the non-null icon description

    • Method Detail

      • derive

        public ThemedGlyphIcon derive​(int newWidth,
                              int newHeight)
        Description copied from interface: ThemedIcon
        Returns a new icon that renders the same image as this icon, but at a different size.
        Parameters:
        newWidth - the new width ≥ 1
        newHeight - the new height ≥ 1
        Returns:
        an icon with the revised dimensions

      • derive

        public ThemedGlyphIcon derive​(int newSize)
        Description copied from interface: ThemedIcon
        Returns a new icon that renders the same image as this icon, but at a different size.
        Parameters:
        newSize - the new width and height ≥ 1
        Returns:
        an icon with the revised dimensions

      • derive

        public ThemedGlyphIcon derive​(java.lang.String label)
        Returns a new icon with the same image as this icon, but "tagged" with a letter taken from a string. For example, given the string "The monkey is happy.", the icon might be tagged with the letter M (from monkey).

        Generally, for the tag to be legible this icon must either be blank, have a background, or use a glyph that has a solid filled area around the middle.

        Parameters:
        label - the string to choose a tag letter from
        Returns:
        the tagged icon

      • paintIcon

        protected void paintIcon​(java.awt.Component c,
                         java.awt.Graphics2D g,
                         int x,
                         int y)
        Specified by:
        paintIcon in class AbstractThemedIcon

      • paintGlyph

        protected void paintGlyph​(java.awt.Graphics2D g,
                          boolean darkMode)
        Called with a transformed and clipped graphics context to paint the icon's glyph. The context is scaled so that no matter the actual icon size, the method should paint the icon as if it were 18 pixels by 18 pixels in size.
        Parameters:
        g - the graphic context
        darkMode - true if the icon is being painted against a dark background, or if the background is unknown, in a dark theme

      • getIconWidth

        public int getIconWidth()
        Specified by:
        getIconWidth in interface javax.swing.Icon
        Overrides:
        getIconWidth in class AbstractThemedIcon

      • getIconHeight

        public int getIconHeight()
        Specified by:
        getIconHeight in interface javax.swing.Icon
        Overrides:
        getIconHeight in class AbstractThemedIcon

      • debugDump

        public static void debugDump()
        Injects built-in icons into the script console window for visual inspection.