Package ca.corbett.extras.logging

Class LogConsoleTheme

java.lang.Object
ca.corbett.extras.properties.AbstractProperty
ca.corbett.extras.logging.LogConsoleTheme
All Implemented Interfaces:
EventListener, ChangeListener
public final class LogConsoleTheme extends AbstractProperty implements ChangeListener
A LogConsoleTheme represents a set of LogConsoleStyle objects that can be applied within the LogConsole.

Styles

Every LogConsoleTheme contains at minimum one LogConsoleStyle - the "Default" style can be customized but cannot be removed. If no other styles are specified, then all log messages in the LogConsole will be displayed in that default style when used with this theme.

You can specify additional styles either by selecting one of the pre-built themes via the create...() factory methods in this class, or by specifying them manually by creating and configuring one or more LogConsoleStyle instances and handing them to this theme via the setStyle() method. There is no limit to the number of styles a theme can have, but note the matching rules below.

Matching styles to log messages

The LogConsole will ask the current theme for a matching LogConsoleStyle to use for each log message that comes in. Style matching is done either by matching a log Level, or by matching a string token that appears in a log message, or both.
  • If a log message matches a style's log token and its log level, that style is considered a strong match for that log message.
  • If a log message matches a style's log token, but the style doesn't specify a log level, it is still considered a strong match.
  • If a log message matches a style's log level, but the style doesn't specify a log token, then this is considered a weak match. That means that this style will match only if no other style matches the log message.
  • If no style matches, either by log token or by log level, then the default style will be used for that log message.

Persisting a custom style

LogConsoleTheme (and also LogConsoleStyle) extend ConfigObject, so they can be easily persisted to disk using a FileBasedProperties instance. It is recommended to use a prefix when doing so to differentiate different styles in the same properties file.

Listening for style changes

LogConsoleTheme accepts ChangeListeners, and will send out a change message whenever any style properties are changed, or when styles are added or removed.
Since:
2023-03-17
Author:
scorbo2

  • Field Details

  • Constructor Details

    • LogConsoleTheme

      public LogConsoleTheme(String fullyQualifiedName)
      Creates a plain theme with black text on a white background, and no styled matchers for any particular log messages. This is equivalent to calling LogConsoleTheme.createPlainTheme(), but you may also want to look at the static factory methods in this class to create something with some preset styling options already set.

  • Method Details

    • clear

      public void clear()
      Clears all log styles except for the Default style, and resets the default background color to white.

    • createPlainTheme

      public static LogConsoleTheme createPlainTheme()
      Creates and returns a plain theme with black text and no matchers. This is equivalent to just doing a new LogConsoleTheme() but is provided for consistency with other static creator methods.
      Returns:
      A new, default, rather boringly unstyled LogConsoleTheme.

    • createDefaultStyledTheme

      public static LogConsoleTheme createDefaultStyledTheme()
      Creates and returns a LogConsoleTheme with some basic log matchers. Most log messages will be written in plain black text, but messages of level WARNING will be written in bold orange text, and messages of level SEVERE will be written in bold red text.
      Returns:
      A LogConsoleTheme with a default styling (black on white).

    • createMatrixStyledTheme

      public static LogConsoleTheme createMatrixStyledTheme()
      Creates and returns a "matrix"-style LogConsoleTheme, with a black background and green text. Also includes highlighting of errors and warnings.
      Returns:
      A LogConsoleTheme with a "matrix" styling (green on black).

    • createPaperStyledTheme

      public static LogConsoleTheme createPaperStyledTheme()
      Creates and returns a "paper" style LogConsoleTheme, with mostly black text on a grey background. Also includes highlighting of errors and warnings.
      Returns:
      A LogConsoleTheme with a "paper" styling (black on grey).

    • addChangeListener

      public void addChangeListener(ChangeListener listener)
      Register to receive notifications when any style properties are changed, added, or removed from this theme.
      Parameters:
      listener - The listener to add.

    • removeChangeListener

      public void removeChangeListener(ChangeListener listener)
      Unregister from receiving notifications when style properties are changed, added, or removed from this theme.
      Parameters:
      listener - The listener to add.

    • setDefaultBgColor

      public void setDefaultBgColor(Color color)
      Sets the default background color - this is the background that will be used unless specifically overridden by some style matcher.
      Parameters:
      color - The new default background color. Ignored if null.

    • getDefaultBgColor

      public Color getDefaultBgColor()
      Returns the default background color - this is the background that will be used unless specifically overridden by some style matcher.
      Returns:
      The default background color.

    • setFontPointSize

      public void setFontPointSize(int size)
      As a shortcut, it's possible to set the font point size of all style matchers with one call, instead of one by one.
      Parameters:
      size - The new font point size to apply to all styles in this theme.

    • setStyle

      public void setStyle(String name, LogConsoleStyle style)
      Sets or replaces the style with the given name. If the given style is null, then this method will defer to removeStyle(name).
      Parameters:
      style - The style object to set. If null, will invoke removeStyle(name).

    • getStyle

      public LogConsoleStyle getStyle(String name)
      Returns the LogConsoleStyle of the given name, if it exists.
      Parameters:
      name - The name of the style in question.
      Returns:
      A LogConsolStyle object, or null if name not found.

    • getStyleNames

      public List<String> getStyleNames()
      Returns a list of all style names contained in this theme. This list is guaranteed to always contain at least one name ("Default"). The "Default" entry is always returned in position 0 in the list. The remainder of the list is sorted alphabetically.
      Returns:
      A list of all style names contained in this theme.

    • getStyleName

      public String getStyleName(LogConsoleStyle style)
      Returns the name of the given style, if it exists within this theme.
      Parameters:
      style - A LogConsoleStyle instance.
      Returns:
      The name of the given LogConsoleStyle if it is present, else null.

    • removeStyle

      public void removeStyle(String name) throws IllegalArgumentException
      Removes the style with the given name, if it exists. If the given name is null, or if you try to remove the "Default" style, an IllegalArgumentException will be thrown.
      Parameters:
      name - The name of the style to remove.
      Throws:
      IllegalArgumentException - If name is null or "Default"

    • getMatchingStyle

      public LogConsoleStyle getMatchingStyle(String logMsg, Level logLevel)
      Returns the appropriate LogConsoleStyle within this theme for the given log message and log level. If no style within this theme is a match, then the default theme is returned.
      Parameters:
      logMsg - The log message in question.
      logLevel - The Level at which this message was logged.
      Returns:
      A LogConsoleStyle from this theme that matches the given parameters.

    • stateChanged

      public void stateChanged(ChangeEvent e)
      Triggered when one of our style objects is changed. We simply pass this on to whoever is listening to this theme.
      Specified by:
      stateChanged in interface ChangeListener
      Parameters:
      e - A ChangeEvent

    • saveToProps

      public void saveToProps(Properties props)
      Description copied from class: AbstractProperty
      Saves the current value(s) of this property to the given Properties instance.
      Specified by:
      saveToProps in class AbstractProperty
      Parameters:
      props - Any Properties instance which will receive the value(s) of this property.

    • loadFromProps

      public void loadFromProps(Properties props)
      Description copied from class: AbstractProperty
      Loads the value(s) for this property from the given Properties instance, overwriting any current value. The current value of this property will be used as a default value in the event that this property does not exist in the given Properties instance.
      Specified by:
      loadFromProps in class AbstractProperty
      Parameters:
      props - Any Properties instance which contains value(s) for this property.

    • generateFormFieldImpl

      protected FormField generateFormFieldImpl()
      Description copied from class: AbstractProperty
      Descendant classes must implement this method to generate a FormField associated with this property. The generateFormField() method in this class will call this abstract method to create the FormField, which will then be augmented with our fully qualified name, read-only state, help text, and extra attributes.
      Specified by:
      generateFormFieldImpl in class AbstractProperty
      Returns:
      A FormField associated with this property.

    • loadFromFormField

      public void loadFromFormField(FormField field)
      Description copied from class: AbstractProperty
      Populates this Property's value(s) from the given form field, assuming the field is of the correct type.
      Specified by:
      loadFromFormField in class AbstractProperty
      Parameters:
      field - The FormField containing a value for this property.