__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>