.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Tickit::Pen 3pm" .TH Tickit::Pen 3pm "2023-02-06" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Tickit::Pen" \- store a collection of rendering attributes .SH "DESCRIPTION" .IX Header "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 \f(CW\*(C`Tickit::Pen\*(C'\fR class. .PP An immutable pen is an instance of \f(CW\*(C`Tickit::Pen::Immutable\*(C'\fR. 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. .PP A mutable pen is an instance of \f(CW\*(C`Tickit::Pen::Mutable\*(C'\fR. 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. .PP 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. .SS "Attributes" .IX Subsection "Attributes" The following named pen attributes are supported: .IP "fg => \s-1COL\s0" 8 .IX Item "fg => COL" .PD 0 .IP "bg => \s-1COL\s0" 8 .IX Item "bg => COL" .PD Foreground or background colour. \f(CW\*(C`COL\*(C'\fR may be an integer or one of the eight colour names. A colour name may optionally be prefixed by \f(CW\*(C`hi\-\*(C'\fR 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. .IP "fg:rgb8 => \s-1STRING\s0" 8 .IX Item "fg:rgb8 => STRING" .PD 0 .IP "bg:rgb8 => \s-1STRING\s0" 8 .IX Item "bg:rgb8 => STRING" .PD Foreground or background colour secondary \s-1RGB8\s0 specification. The value is a string encoding the three 8\-bit values in hexadecimal notation, prefixed by a hash (\f(CW\*(C`#\*(C'\fR) symbol; for example .Sp .Vb 1 \& #13579B .Ve .Sp On input, either lower\- or upper-case is accepted; on output the letters will be upper-case. .Sp These attribute can only be set if the corresponding regular index attribute is also set. Changing or clearing the regular index will also clear the \s-1RGB8\s0 version. .Sp Applications wishing to use this attribute should be aware that the majority of terminal drivers will not be able to support it, and so should make sure to set an appropriate regular colour index as well. Some terminals using the \&\fIxterm\fR driver may make use of it, however, and therefore ignore the index version. .IP "b => \s-1BOOL\s0" 8 .IX Item "b => BOOL" .PD 0 .IP "u => \s-1BOOL\s0" 8 .IX Item "u => BOOL" .IP "i => \s-1BOOL\s0" 8 .IX Item "i => BOOL" .IP "rv => \s-1BOOL\s0" 8 .IX Item "rv => BOOL" .IP "strike => \s-1BOOL\s0" 8 .IX Item "strike => BOOL" .IP "blink => \s-1BOOL\s0" 8 .IX Item "blink => BOOL" .PD Bold, underline, italics, reverse video, strikethrough, blink. .IP "af => \s-1INT\s0" 8 .IX Item "af => INT" Alternate font. .PP Note that not all terminals can render the italics, strikethrough, or alternate font attributes. .SH "CONSTRUCTORS" .IX Header "CONSTRUCTORS" .SS "new" .IX Subsection "new" .Vb 1 \& $pen = Tickit::Pen\->new( %attrs ) .Ve .PP Returns a new pen, initialised from the given attributes. .PP Currently this method returns a \f(CW\*(C`Tickit::Pen::Mutable\*(C'\fR, though this may change in a future version. It is provided for backward-compatibility for code that expects to be able to construct a \f(CW\*(C`Tickit::Pen\*(C'\fR directly. .PP .Vb 1 \& $pen = Tickit::Pen::Immutable\->new( %attrs ) \& \& $pen = Tickit::Pen::Mutable\->new( %attrs ) .Ve .PP Return a new immutable, or mutable pen, initialised from the given attributes. .SS "new_from_attrs" .IX Subsection "new_from_attrs" .Vb 1 \& $pen = Tickit::Pen\->new_from_attrs( $attrs ) .Ve .PP Returns a new pen, initialised from keys in the given \s-1HASH\s0 reference. Used keys are deleted from the hash. .PP Currently this method returns a \f(CW\*(C`Tickit::Pen::Mutable\*(C'\fR, though this may change in a future version. It is provided for backward-compatibility for code that expects to be able to construct a \f(CW\*(C`Tickit::Pen\*(C'\fR directly. .PP .Vb 1 \& $pen = Tickit::Pen::Immutable\->new_from_attrs( $attrs ) \& \& $pen = Tickit::Pen::Mutable\->new_from_attrs( $attrs ) .Ve .PP Return a new immutable, or mutable pen, initialised from the given attributes. .SS "as_mutable" .IX Subsection "as_mutable" .SS "clone" .IX Subsection "clone" .Vb 1 \& $pen = $orig\->as_mutable \& \& $pen = $orig\->clone .Ve .PP Returns a new mutable pen, initialised by copying the attributes of the original. .PP \&\f(CW\*(C`clone\*(C'\fR is provided as a legacy alias, but may be removed in a future version. .SS "as_immutable" .IX Subsection "as_immutable" .Vb 1 \& $pen = $orig\->as_immutable .Ve .PP 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. .SS "mutable" .IX Subsection "mutable" .Vb 1 \& $is_mutable = $pen\->mutable .Ve .PP Returns true on mutable pens and false on immutable ones. .SH "METHODS ON ALL PENS" .IX Header "METHODS ON ALL PENS" The following query methods apply to both immutable and mutable pens. .SS "hasattr" .IX Subsection "hasattr" .Vb 1 \& $exists = $pen\->hasattr( $attr ) .Ve .PP Returns true if the given attribute exists on this object .SS "getattr" .IX Subsection "getattr" .Vb 1 \& $value = $pen\->getattr( $attr ) .Ve .PP Returns the current value of the given attribute .SS "getattrs" .IX Subsection "getattrs" .Vb 1 \& %values = $pen\->getattrs .Ve .PP Returns a key/value list of all the attributes .SS "equiv_attr" .IX Subsection "equiv_attr" .Vb 1 \& $equiv = $pen\->equiv_attr( $other, $attr ) .Ve .PP 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. .SS "equiv" .IX Subsection "equiv" .Vb 1 \& $equiv = $pen\->equiv( $other ) .Ve .PP Returns true if the two pens have equivalent values for all attributes. .SH "METHODS ON MUTABLE PENS" .IX Header "METHODS ON MUTABLE PENS" The following mutation methods exist on mutable pens. .SS "chattr" .IX Subsection "chattr" .Vb 1 \& $pen\->chattr( $attr, $value ) .Ve .PP Change the value of an attribute. Setting \f(CW\*(C`undef\*(C'\fR deletes the attribute entirely. See also \f(CW\*(C`delattr\*(C'\fR. .SS "chattrs" .IX Subsection "chattrs" .Vb 1 \& $pen\->chattrs( \e%attrs ) .Ve .PP Change the values of all the attributes given in the hash. Recgonised attributes will be deleted from the hash. .SS "delattr" .IX Subsection "delattr" .Vb 1 \& $pen\->delattr( $attr ) .Ve .PP Delete an attribute from this pen. This attribute will no longer be modified by this pen. .SS "copy_from" .IX Subsection "copy_from" .SS "default_from" .IX Subsection "default_from" .Vb 1 \& $pen\->copy_from( $other ) \& \& $pen\->default_from( $other ) .Ve .PP Copy attributes from the given pen. \f(CW\*(C`copy_from\*(C'\fR will override attributes already defined by \f(CW$pen\fR; \f(CW\*(C`default_from\*(C'\fR will only copy attributes that are not yet defined by \f(CW$pen\fR. .PP As a convenience both methods return \f(CW$pen\fR. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans