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.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>