/ 
Tickit-0.52
River stage two • 35 direct dependents • 41 total dependents
/ Tickit::Pen

NAME

Tickit::Pen - store a collection of rendering attributes

DESCRIPTION

A pen instance stores a collection of rendering attributes for text to display. It comes in two forms, mutable and immutable. Both types of pen are subclasses of the base Tickit::Pen class.

An immutable pen is an instance of Tickit::Pen::Immutable. Its attributes are set by the constructor and are fixed thereafter. Methods are provided to query the presence or value of attributes, and to fetch the entire set as a hash.

A mutable pen is an instance of Tickit::Pen::Mutable. Its attributes may be set by the constructor, and can be changed at any time. As well as supporting the same query methods as immutable pens, more methods are provided to change or remove them. Mutable pens also currently support the concept of observers; other objects that will be informed when pen attributes are changed. However, these were only added to support an earlier version of what eventually became Tickit::Style, and are no longer required. They will be removed in a later version.

While mutable pens may initially seem more useful, they can complicate logic due to their shared referential nature. If the same mutable pen is shared across multiple places, care needs to be taken to redraw anything that depends on it if it is ever changed. If pens need sharing, especially if results are cached for performance, consider using immutable pens to simplify the logic.

Attributes

The following named pen attributes are supported:

fg => COL
bg => COL

Foreground or background colour. COL may be an integer or one of the eight colour names. A colour name may optionally be prefixed by hi- for the high-intensity version (may not be supported by all terminals). Some terminals may support a palette of 256 colours instead, some 16, and some only 8. The pen object will not check this as it cannot be reliably detected in all cases.

b => BOOL
u => BOOL
i => BOOL
rv => BOOL
strike => BOOL

Bold, underline, italics, reverse video, strikethrough, blink.

af => INT

Alternate font.

Note that not all terminals can render the italics, strikethrough, or alternate font attributes.

CONSTRUCTORS

$pen = Tickit::Pen->new( %attrs )

Returns a new pen, initialised from the given attributes.

Currently this method returns a Tickit::Pen::Mutable, though this may change in a future version. It is provided for backward-compatibility for code that expects to be able to construct a Tickit::Pen directly.

$pen = Tickit::Pen::Immutable->new( %attrs )

$pen = Tickit::Pen::Mutable->new( %attrs )

Return a new immutable, or mutable pen, initialised from the given attributes.

$pen = Tickit::Pen->new_from_attrs( $attrs )

Returns a new pen, initialised from keys in the given HASH reference. Used keys are deleted from the hash.

Currently this method returns a Tickit::Pen::Mutable, though this may change in a future version. It is provided for backward-compatibility for code that expects to be able to construct a Tickit::Pen directly.

$pen = Tickit::Pen::Immutable->new_from_attrs( $attrs )

$pen = Tickit::Pen::Mutable->new_from_attrs( $attrs )

Return a new immutable, or mutable pen, initialised from the given attributes.

$pen = $orig->as_mutable

$pen = $orig->clone

Returns a new mutable pen, initialised by copying the attributes of the original.

clone is provided as a legacy alias, but may be removed in a future version.

$pen = $orig->as_immutable

Returns an immutable pen, initialised by copying the attributes of the original. When called on an immutable pen, this method just returns the same pen instance.

$is_mutable = $pen->mutable

Returns true on mutable pens and false on immutable ones.

METHODS ON ALL PENS

The following query methods apply to both immutable and mutable pens.

$mutable = $pen->mutable

Returns true on Tickit::Pen::Mutable and false on Tickit::Pen::Immutable.

$exists = $pen->hasattr( $attr )

Returns true if the given attribute exists on this object

$value = $pen->getattr( $attr )

Returns the current value of the given attribute

%values = $pen->getattrs

Returns a key/value list of all the attributes

$equiv = $pen->equiv_attr( $other, $attr )

Returns true if the two pens have the equivalent values for the given attribute; that is, either both define it to the same value, or neither defines it.

$equiv = $pen->equiv( $other )

Returns true if the two pens have equivalent values for all attributes.

METHODS ON MUTABLE PENS

The following mutation methods exist on mutable pens.

$pen->chattr( $attr, $value )

Change the value of an attribute. Setting undef deletes the attribute entirely. See also delattr.

$pen->chattrs( \%attrs )

Change the values of all the attributes given in the hash. Recgonised attributes will be deleted from the hash.

$pen->delattr( $attr )

Delete an attribute from this pen. This attribute will no longer be modified by this pen.

$pen->copy_from( $other )

$pen->default_from( $other )

Copy attributes from the given pen. copy_from will override attributes already defined by $pen; default_from will only copy attributes that are not yet defined by $pen.

As a convenience both methods return $pen.

$pen->add_on_changed( $observer, $id )

Add an observer to the list of objects which will be informed when the pen attributes change. The observer will be informed by invoking a method on_pen_changed, passing in the pen reference and the opaque ID value given to this method.

$observer->on_pen_changed( $pen, $id )

The observer object is stored weakly, so it is safe to add the Tickit::Widget object that is using the pen as an observer. The ID value is not weakened.

The use of pen observers is now deprecated, and will be removed in a later version. This was a short-lived feature intended for adding mutable styles to widgets, which is now much better served by the Tickit::Style system instead.

$pen->remove_on_changed( $observer )

Remove an observer previously added by add_on_changed.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>