1Tickit::Pen(3)        User Contributed Perl Documentation       Tickit::Pen(3)
2
3
4

NAME

6       "Tickit::Pen" - store a collection of rendering attributes
7

DESCRIPTION

9       A pen instance stores a collection of rendering attributes for text to
10       display. It comes in two forms, mutable and immutable. Both types of
11       pen are subclasses of the base "Tickit::Pen" class.
12
13       An immutable pen is an instance of "Tickit::Pen::Immutable". Its
14       attributes are set by the constructor and are fixed thereafter. Methods
15       are provided to query the presence or value of attributes, and to fetch
16       the entire set as a hash.
17
18       A mutable pen is an instance of "Tickit::Pen::Mutable". Its attributes
19       may be set by the constructor, and can be changed at any time. As well
20       as supporting the same query methods as immutable pens, more methods
21       are provided to change or remove them.
22
23       While mutable pens may initially seem more useful, they can complicate
24       logic due to their shared referential nature. If the same mutable pen
25       is shared across multiple places, care needs to be taken to redraw
26       anything that depends on it if it is ever changed. If pens need
27       sharing, especially if results are cached for performance, consider
28       using immutable pens to simplify the logic.
29
30   Attributes
31       The following named pen attributes are supported:
32
33       fg => COL
34       bg => COL
35               Foreground or background colour. "COL" may be an integer or one
36               of the eight colour names. A colour name may optionally be
37               prefixed by "hi-" for the high-intensity version (may not be
38               supported by all terminals). Some terminals may support a
39               palette of 256 colours instead, some 16, and some only 8. The
40               pen object will not check this as it cannot be reliably
41               detected in all cases.
42
43       fg:rgb8 => STRING
44       bg:rgb8 => STRING
45               Foreground or background colour secondary RGB8 specification.
46               The value is a string encoding the three 8-bit values in
47               hexadecimal notation, prefixed by a hash ("#") symbol; for
48               example
49
50                  #13579B
51
52               On input, either lower- or upper-case is accepted; on output
53               the letters will be upper-case.
54
55               These attribute can only be set if the corresponding regular
56               index attribute is also set. Changing or clearing the regular
57               index will also clear the RGB8 version.
58
59               Applications wishing to use this attribute should be aware that
60               the majority of terminal drivers will not be able to support
61               it, and so should make sure to set an appropriate regular
62               colour index as well. Some terminals using the xterm driver may
63               make use of it, however, and therefore ignore the index
64               version.
65
66       b => BOOL
67       u => BOOL
68       i => BOOL
69       rv => BOOL
70       strike => BOOL
71       blink => BOOL
72               Bold, underline, italics, reverse video, strikethrough, blink.
73
74       af => INT
75               Alternate font.
76
77       Note that not all terminals can render the italics, strikethrough, or
78       alternate font attributes.
79

CONSTRUCTORS

81   new
82          $pen = Tickit::Pen->new( %attrs )
83
84       Returns a new pen, initialised from the given attributes.
85
86       Currently this method returns a "Tickit::Pen::Mutable", though this may
87       change in a future version. It is provided for backward-compatibility
88       for code that expects to be able to construct a "Tickit::Pen" directly.
89
90          $pen = Tickit::Pen::Immutable->new( %attrs )
91
92          $pen = Tickit::Pen::Mutable->new( %attrs )
93
94       Return a new immutable, or mutable pen, initialised from the given
95       attributes.
96
97   new_from_attrs
98          $pen = Tickit::Pen->new_from_attrs( $attrs )
99
100       Returns a new pen, initialised from keys in the given HASH reference.
101       Used keys are deleted from the hash.
102
103       Currently this method returns a "Tickit::Pen::Mutable", though this may
104       change in a future version. It is provided for backward-compatibility
105       for code that expects to be able to construct a "Tickit::Pen" directly.
106
107          $pen = Tickit::Pen::Immutable->new_from_attrs( $attrs )
108
109          $pen = Tickit::Pen::Mutable->new_from_attrs( $attrs )
110
111       Return a new immutable, or mutable pen, initialised from the given
112       attributes.
113
114   as_mutable
115   clone
116          $pen = $orig->as_mutable
117
118          $pen = $orig->clone
119
120       Returns a new mutable pen, initialised by copying the attributes of the
121       original.
122
123       "clone" is provided as a legacy alias, but may be removed in a future
124       version.
125
126   as_immutable
127          $pen = $orig->as_immutable
128
129       Returns an immutable pen, initialised by copying the attributes of the
130       original. When called on an immutable pen, this method just returns the
131       same pen instance.
132
133   mutable
134          $is_mutable = $pen->mutable
135
136       Returns true on mutable pens and false on immutable ones.
137

METHODS ON ALL PENS

139       The following query methods apply to both immutable and mutable pens.
140
141   hasattr
142          $exists = $pen->hasattr( $attr )
143
144       Returns true if the given attribute exists on this object
145
146   getattr
147          $value = $pen->getattr( $attr )
148
149       Returns the current value of the given attribute
150
151   getattrs
152          %values = $pen->getattrs
153
154       Returns a key/value list of all the attributes
155
156   equiv_attr
157          $equiv = $pen->equiv_attr( $other, $attr )
158
159       Returns true if the two pens have the equivalent values for the given
160       attribute; that is, either both define it to the same value, or neither
161       defines it.
162
163   equiv
164          $equiv = $pen->equiv( $other )
165
166       Returns true if the two pens have equivalent values for all attributes.
167

METHODS ON MUTABLE PENS

169       The following mutation methods exist on mutable pens.
170
171   chattr
172          $pen->chattr( $attr, $value )
173
174       Change the value of an attribute. Setting "undef" deletes the attribute
175       entirely. See also "delattr".
176
177   chattrs
178          $pen->chattrs( \%attrs )
179
180       Change the values of all the attributes given in the hash. Recgonised
181       attributes will be deleted from the hash.
182
183   delattr
184          $pen->delattr( $attr )
185
186       Delete an attribute from this pen. This attribute will no longer be
187       modified by this pen.
188
189   copy_from
190   default_from
191          $pen->copy_from( $other )
192
193          $pen->default_from( $other )
194
195       Copy attributes from the given pen. "copy_from" will override
196       attributes already defined by $pen; "default_from" will only copy
197       attributes that are not yet defined by $pen.
198
199       As a convenience both methods return $pen.
200

AUTHOR

202       Paul Evans <leonerd@leonerd.org.uk>
203
204
205
206perl v5.36.0                      2023-01-20                    Tickit::Pen(3)