NAME

       "Tickit::Style" - declare customisable style information on widgets

SYNOPSIS

          package My::Widget::Class
          use base qw( Tickit::Widget );
          use Tickit::Style;

          style_definition base =>
             fg => "red";

          style_definition ':active' =>
             b => 1;

          ...

          sub render_to_rb
          {
             my $self = shift;
             my ( $rb, $rect ) = @_;

             $rb->text_at( 0, 0, "Here is my text", $self->get_style_pen );
          }

          use My::Widget::Class;

          my $w = My::Widget::Class->new(
             class => "another-class",
          );

          ...

DESCRIPTION

       This module adds the ability to a Tickit::Widget class to declare a set of named keys that
       take values, and provides convenient accessors for the widget to determine what the values
       are at any given moment in time. The values currently in effect are determined by the
       widget class code, and any stylesheet files loaded by the application.

       The widget itself can store a set of tags; named entities that may be present or absent.
       The set of tags currently active on a widget helps to determine which definitions style
       are to be used.

       Finally, the widget itself stores a list of style class names. These classes also help
       determine which style definitions from a loaded stylesheet file are applied.

   Stylesheet Files
       A stylesheet file contains a list of definitions of styles. Each definition gives a
       "Tickit::Widget" class name, optionally a style class name prefixed by a period ("."),
       optionally a set of tags prefixed with colons (":"), and a body definition in a brace-
       delimited ("{}") block. Comments can appear anywhere that whitespace is allowed, starting
       with a hash symbol ("#") and continuing to the end of the line.

          WidgetClass {
            # basic style goes here
          }

          WidgetClass.styleclass {
            # style to apply for this class goes here
          }

          WidgetClass:tag {
            # style to apply when this tag is active goes here
          }

       Each style definition contains a set semicolon-delimited (";") assignments of values to
       keys. Each key is suffixed by a colon (":"), and the values may be integers, quoted
       strings ("..."), or the special identifiers "true" or "false".

          WidgetClass.styleclass {
            key1: "value 1";
            key2: 123;
            key3: true;
          }

       While it is more traditional for keys in stylesheet files to contain hyphens ("-"), it is
       more convenient in Perl code to use underscores ("_") instead.  The parser will convert
       hyphens in key names into underscores.

       As well as giving visual styling information, stylesheets can also associate behavioural
       actions with keypresses. These are given by a keypress key name in angle brackets
       ("<NAME>") and an action name, which is a bareword identifier.

        WidgetClass {
          <Enter>: activate;
        }

       A special widget type name of "*" can also be used to provide style blocks that will apply
       (at lower priority) to any type of widget. Typically these would be used along with
       classes or tags, to set application-wide styles.

        *:error {
          bg: "red";
          fg: "hi-white";
        }

   How Style is Determined
       The full set of style definitions applied to one named class of one widget type for all
       its style tags is called a "tagset". Each tagset consists of a partially-ordered list of
       entities called "keysets", which give a mapping from style keys to values for one
       particular set of active style tags. The widget may also have a special tagset containing
       the "direct-applied" style definition given to the constructor.

       The style at any given moment is determined by taking into account the style classes and
       tags that are in effect. The value of each key is determined by a first-match-wins search
       along the "direct applied" tagset (if present), then the tagset for each of the style
       classes, in order, followed finally by the base tagset for the widget type without class.

       Within each tagset, only the keysets that do not depend on a style tag that is inactive
       are considered. That is, a keyset that depends on no tags will always be considered, and
       any keyset that only depends on active keys will be considered, even if there are other
       active tags that the keyset does not consider. Tags are always additive, in this regard.

       While the order of the tagsets is exactly defined by the order of the style classes
       applied to the widget, the order of keysets within each tagset is not fully specified.
       Tagsets are stored partially ordered, sorted by the number of style tags that each keyset
       depends on. This ensures that more specific keysets are found before, and therefore
       override, less specific ones. However, it is not defined the ordering of keysets with
       equal numbers of (distinct) tags.

       For instance, if both "tag1" and "tag2" are active, the following stylesheet does not
       precisely determine the foreground colour:

          WidgetClass      { fg: "red"; }
          WidgetClass:tag1 { fg: "blue"; }
          WidgetClass:tag2 { fg: "green"; }

       While it is not specified which tagged definition takes precedence, and therefore whether
       it shall be blue or green, it is specified that both of the tagged definitions take
       precedence over the untagged definition, so the colour will not be red.

SUBCLASSING

       If a Widget class is subclassed and the subclass does not declare "use Tickit::Style"
       again, the subclass will be transparent from the point of view of style. Any style applied
       to the base class will apply equally to the subclass, and the name of the subclass does
       not take part in style decisions.

       If the subclass does "use Tickit::Style" again then the new subclass has a distinct widget
       type for style purposes. It can optionally copy the style information from its base class,
       but thereafter the stored information is distinct, and changes in the base class (such as
       loading style files) will not affect it.

       To copy the style information from the base, apply the "-copy" keyword:

          use Tickit::Style -copy;

       Alternatively, to start with a new blank state, use the "-blank" keyword:

          use Tickit::Style -blank;

       Currently, "-blank" is the default behaviour, but this may change in a future version,
       with a deprecation warning if no keyword is specified.

FUNCTIONS

   style_definition
          style_definition( $tags, %definition )

       In addition to any loaded stylesheets, the widget class itself can provide style
       information, via the "style_definition" function. It provides a definition equivalent to a
       stylesheet definition with no style class, optionally with a single set of tags. To supply
       no tags, use the special string "base".

          style_definition base =>
             key1 => "value",
             key2 => 123;

       To provide definitions with tags, use the colon-prefixed notation.

          style_definition ':active' =>
             key3 => "value";

   style_reshape_keys
          style_reshape_keys( @keys )

       Declares that the given list of keys are somehow responsible for determining the shape of
       the widget. If their values are changed, the "reshape" method is called.

   style_reshape_textwidth_keys
          style_reshape_textwidth_keys( @keys )

       Declares that the given list of keys contain text, the "textwidth()" of which is used to
       determine the shape of the widget. If their values are changed such that the "textwidth()"
       differs, the "reshape" method is called.

   style_redraw_keys
          style_redraw_keys( @keys )

       Declares that the given list of keys are somehow responsible for determining the look of
       the widget, but in a way that does not determine the size. If their values are changed,
       the "redraw" method is called.

       Between them these three methods may help avoid "Tickit::Widget" classes from needing to
       override the "on_style_changed_values" method.

ADDITIONAL FUNCTIONS/METHODS

       These functions are not exported, but may be called directly.

   load_style
          Tickit::Style->load_style( $string )

       Loads definitions from a stylesheet given in a string.

       Definitions will be merged with existing definitions in memory, with new values
       overwriting existing values.

   load_style_file
          Tickit::Style->load_style_file( $path )

       Loads definitions from a stylesheet file given by the path.

       Definitions will be merged the same way as "load_style".

   load_style_from_DATA
          Tickit::Style->load_style_from_DATA

       A convenient shortcut for loading style definitions from the caller's "DATA" filehandle.

   on_style_load
          Tickit::Style::on_style_load( \&code )

       Adds a CODE reference to be invoked after either "load_style" or "load_style_file" are
       called. This may be useful to flush any caches or invalidate any state that depends on
       style information.