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 hypens (-), it is more convenient in Perl code to use underscores (_) instead. The parser will convert hypens 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;
 }

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( $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( @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( @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( @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.

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.

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.

Tickit::Style->load_style_from_DATA

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

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.

cpanm Tickit::Widgets

perl -MCPAN -e shell
install Tickit::Widgets