1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
__END__
=head1 NAME
Irssi::UI::Theme
=head1 FIELDS
=head1 METHODS
=head2 C<format_expand $theme, $format, $flags>
C<$flags> is an optional bitmask of any of the following flags:
=over
=item C<EXPAND_FLAG_IGNORE_REPLACES>
Any replacements specified in the theme are not applied to this expansion.
=item C<EXPAND_FLAG_RECURSIVE_MASK>
B<TODO: dunno>
=item C<EXPAND_FLAG_IGNORE_EMPTY>
If the format contains variables and no values are specified, an empty string is
returned instead of a partially filled template.
=back
B<TODO: What?>
Example:
my $formatted_str = Irssi::current_theme()->format_expand('{hilight Hello}');
B<NOTE: it seems that this only operates on abstract templates, not those
accessible with C</FORMAT>. Weird>
=head2 C<get_format $theme, $module, $tag>
Returns the unexpanded format template for the format name supplied in C<$tag>.
Valid values for C<$module> are:
=over
=item C<fe-common/perl>
=item C<fe-common/irc/dcc>
=item C<fe-common/irc>
=item C<fe-common/core>
=item C<fe-common/irc/notifylist>
=item C<fe-text>
=back
Example:
my $pubmsg_format = Irssi::current_theme()->get_format('fe-common/core', 'pubmsg');
=head1 THEME DETAILS
=head2 Loading and Testing
You can change themes by issuing a C</SET theme F<theme-name>> command from Irssi.
Reloading is slightly harder, since Irssi will only reload and process a new theme
if the C<theme> variable I<changes>.
You can force a reload of the theme (and everything else) with C</RELOAD>. This
reloads the configuration file too, so if you did any changes remember to C</SAVE>
first.
B<Remember also that C</SAVE> overwrites the theme file with old data so keep
backups C<:)>>
Better alternatives are the following aliases:
/ALIAS THEMERELOAD SCRIPT EXEC Irssi::themes_reload();
or
/ALIAS THEMERELOAD SET theme default; EVAL SET theme $theme
The former is preferred if you have scripting support, whereas the latter will
work without scripting (Perl) support loaded, but requires that you are editing
a custom theme, rather than modifying F<default.theme>.
=head2 TEMPLATES
The actual mechanism used by Irssi to print text into the client involves a
certain amount of indirection, which allows themes to reformat messages in
various ways before they are displayed.
The overall structure of these templates is based around 3 basic ideas:
=over
=item Nested Templates
=item Colour Codes
=item Variable Expansion
=item Special Variables
=back
The real text formats that irssi uses are the ones you can find with
/FORMAT command. Back in the old days all the colors and texts were mixed
up in those formats, and it was really hard to change the colors since you
might have had to change them in tens of different places. So, then came
this templating system.
Now the C</FORMAT>s don't have any colors in them, and they also have very
little other styling. Most of the stuff you need to change is in this
theme file. If you can't change something here, you can always go back
to change the /FORMATs directly, they're also saved in the F<*.theme> files.
So, the templates. They're those C<{blahblah}> parts you see all over the
/FORMATs and here. Their usage is simply C<{name parameter1 parameter2}>.
When irssi sees this kind of text, it goes to find C<name> from the abstracts
block below and sets C<parameter1> into C<$0> and C<parameter2> into C<$1> (you
can have more parameters of course). Templates can have sub-templates. Here's a
small example:
/FORMAT format hello {colorify {underline world}}
abstracts = { colorify = "%G$0-%n"; underline = "%U$0-%U"; }
When irssi expands the templates in C<"format">, the final string would be:
hello %G%Uworld%U%n
ie. underlined bright green "world" text. and why C<$0->, why not C<$0>? C<$0>
would only mean the first parameter, C<$0-> means all the parameters. With
C<{underline hello world}> you'd really want to underline both of the words, not
just the hello (and world would actually be removed entirely).
See also L<Formats#arguments|Formats/ALIAS AND FORMAT TEMPLATE ARGUMENTS> for
details on the variable to argument mapping.
=head2 COLOURS
You can find definitions for the colour format codes in L<Formats/COLOURS>.
There's one difference here though. C<%n> format. Normally it means the default
color of the terminal (white mostly), but here it means the "reset color back to
the one it was in higher template". For example if there was C</FORMAT test
%g{foo}bar>, and C<foo = "%Y$0%n">, irssi would print yellow C<"foo"> (as set
with C<%Y>) but C<"bar"> would be green, which was set at the beginning before
the C<{foo}> template. If there wasn't the C<%g> at start, the normal behaviour
of C<%n> would occur. If you I<really> want to use the terminal's default color,
use C<%N>.
=head1 AUTHOR
Based on the original content found as comments in the F<default.theme> file.
Copyright E<copy> 2000-2010 L<The Irssi project|http://irssi.org>.
Formatting and additional content by Tom Feist
L<shabble+irssi@metavore.org|mailto:shabble+irssi@metavore.org>
|
