.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Prima::Themes 3"
.TH Prima::Themes 3 "2009-02-24" "perl v5.14.2" "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"
Prima::Themes \- object themes management
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides layer for theme registration in Prima. Themes are loosely grouped
alternations of default class properties and behavior, by default stored in 
\&\f(CW\*(C`Prima/themes\*(C'\fR subdirectory. The theme realization is implemented as interception
of object profile during its creation, inside \f(CW\*(C`::profile_add\*(C'\fR. Various themes
apply various alterations, one way only \- once an object is applied a theme,
it cannot be neither changed nor revoked thereafter.
.PP
Theme configuration can be stored in an rc file, \fI~/.prima/themes\fR, and is
loaded automatically, unless \f(CW$Prima::Themes::load_rc_file\fR explicitly set to \f(CW0\fR
before loading the \f(CW\*(C`Prima::Themes\*(C'\fR module. In effect, any Prima application 
not aware of themes can be coupled with themes in the rc file by the following:
.PP
.Vb 1
\&        perl \-MPrima::Themes program
.Ve
.PP
\&\f(CW\*(C`Prima::Themes\*(C'\fR namespace provides registration and execution functionality.
\&\f(CW\*(C`Prima::Themes::Proxy\*(C'\fR is a class for overriding certain methods, for internal
realization of a theme.
.PP
For interactive theme selection use \fIexamples/theme.pl\fR sample program.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&        # register a theme file
\&        use Prima::Themes qw(color);
\&        # or
\&        use Prima::Themes; load(\*(Aqcolor\*(Aq);
\&        # list registered themes
\&        print Prima::Themes::list;
\&
\&        # install a theme
\&        Prima::Themes::install(\*(Aqcyan\*(Aq);
\&        # list installed themes
\&        print Prima::Themes::list_active;
\&        # create object with another theme while \*(Aqcyan\*(Aq is active
\&        Class\->create( theme => \*(Aqyellow\*(Aq);
\&        # remove a theme
\&        Prima::Themes::uninstall(\*(Aqcyan\*(Aq);
.Ve
.SH "Prima::Themes"
.IX Header "Prima::Themes"
.ie n .IP "load @THEME_MODULES" 4
.el .IP "load \f(CW@THEME_MODULES\fR" 4
.IX Item "load @THEME_MODULES"
Load \s-1THEME_MODULES\s0 from files via \f(CW\*(C`use\*(C'\fR clause, dies on error.
Can be used instead of explicit \f(CW\*(C`use\*(C'\fR.
.Sp
A loaded theme file may register one or more themes.
.ie n .IP "register $FILE, $THEME, $MATCH, $CALLBACK, $INSTALLER" 4
.el .IP "register \f(CW$FILE\fR, \f(CW$THEME\fR, \f(CW$MATCH\fR, \f(CW$CALLBACK\fR, \f(CW$INSTALLER\fR" 4
.IX Item "register $FILE, $THEME, $MATCH, $CALLBACK, $INSTALLER"
Registers a previously loaded theme. \f(CW$THEME\fR is a unique string identifier.
\&\f(CW$MATCH\fR is an array of pairs, where the first item is a class name,
and the second is an arbitrary scalar parameter. When a new object is created,
its class is matched via \f(CW\*(C`isa\*(C'\fR to each given class name,
and if matched, the \f(CW$CALLBACK\fR routine is called with the following parameters:
object, default profile, user profile, second item of the matched pair.
.Sp
If \f(CW$CALLBACK\fR is \f(CW\*(C`undef\*(C'\fR, the default merger routine is called,
which treats the second items of the pairs as hashes of the same format as
the default and user profiles.
.Sp
The theme is inactive until \f(CW\*(C`install\*(C'\fR is called. If \f(CW$INSTALLER\fR subroutine is
passed, it is called during install and uninstall, with two parameters, the
name of the theme and boolean install/uninstall flag. When install flag is 1,
the theme is about to be installed; the subroutine is expected to return a
boolean success flag. Otherwise, subroutine return value is not used.
.Sp
\&\f(CW$FILE\fR is used to indicate the file in which the theme is stored.
.ie n .IP "deregister $THEME" 4
.el .IP "deregister \f(CW$THEME\fR" 4
.IX Item "deregister $THEME"
Un-registers \f(CW$THEME\fR.
.ie n .IP "install @THEMES" 4
.el .IP "install \f(CW@THEMES\fR" 4
.IX Item "install @THEMES"
Installs previosuly loaded and registered loaded \s-1THEMES\s0; the installed themes
are now used to match new objects.
.ie n .IP "uninstall @THEMES" 4
.el .IP "uninstall \f(CW@THEMES\fR" 4
.IX Item "uninstall @THEMES"
Uninstalls loaded \s-1THEMES\s0.
.IP "list" 4
.IX Item "list"
Returns the list of registered themes.
.IP "list_active" 4
.IX Item "list_active"
Returns the list of installed themes.
.ie n .IP "loaded $THEME" 4
.el .IP "loaded \f(CW$THEME\fR" 4
.IX Item "loaded $THEME"
Return 1 if \f(CW$THEME\fR is registered, 0 otherwise.
.ie n .IP "active $THEME" 4
.el .IP "active \f(CW$THEME\fR" 4
.IX Item "active $THEME"
Return 1 if \f(CW$THEME\fR is installed, 0 otherwise.
.ie n .IP "select @THEMES" 4
.el .IP "select \f(CW@THEMES\fR" 4
.IX Item "select @THEMES"
Uninstalls all currently installed themes, and installs \s-1THEMES\s0 instead.
.ie n .IP "merger $OBJECT, $PROFILE_DEFAULT, $PROFILE_USER, $PROFILE_THEME" 4
.el .IP "merger \f(CW$OBJECT\fR, \f(CW$PROFILE_DEFAULT\fR, \f(CW$PROFILE_USER\fR, \f(CW$PROFILE_THEME\fR" 4
.IX Item "merger $OBJECT, $PROFILE_DEFAULT, $PROFILE_USER, $PROFILE_THEME"
Default profile merging routine, merges \f(CW$PROFILE_THEME\fR into \f(CW$PROFILE_USER\fR
by keys from \f(CW$PROFILE_DEFAULT\fR.
.ie n .IP "load_rc [ $INSTALL = 1 ]" 4
.el .IP "load_rc [ \f(CW$INSTALL\fR = 1 ]" 4
.IX Item "load_rc [ $INSTALL = 1 ]"
Reads data \fI~/.prima/themes\fR and loads listed modules.
If \f(CW$INSTALL\fR = 1, installs the themes from the rc file.
.IP "save_rc" 4
.IX Item "save_rc"
Writes configuration of currently installed themes into rc file,
returns success flag. If success flag is 0, \f(CW$!\fR contains the error.
.SH "Prima::Themes::Proxy"
.IX Header "Prima::Themes::Proxy"
An instance of \f(CW\*(C`Prima::Themes::Proxy\*(C'\fR, created as
.PP
Prima::Themes::Proxy\-> new( \f(CW$OBJECT\fR)
.PP
is a non-functional wrapper for any Perl object \f(CW$OBJECT\fR. All methods of \f(CW$OBJECT\fR,
except \f(CW\*(C`AUTOLOAD\*(C'\fR, \f(CW\*(C`DESTROY\*(C'\fR, and \f(CW\*(C`new\*(C'\fR, are forwarded to \f(CW$OBJECT\fR
itself transparently. The class can be used, for example, to deny all
changes to \f(CW\*(C`lineWidth\*(C'\fR inside object's painting routine:
.PP
.Vb 3
\&        package ConstLineWidth;
\&        use vars qw(@ISA);
\&        @ISA = qw(Prima::Themes::Proxy);
\&
\&        sub lineWidth { 1 } # line width is always 1 now!
\&
\&        Prima::Themes::register( \*(Aq~/lib/constlinewidth.pm\*(Aq, \*(Aqconstlinewidth\*(Aq, 
\&                [ \*(AqPrima::Widget\*(Aq => {
\&                        onPaint => sub {
\&                                my ( $object, $canvas) = @_;
\&                                $object\-> on_paint( ConstLineWidth\-> new( $canvas));
\&                        },
\&                } ]
\&        );
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "FILES"
.IX Header "FILES"
\&\fI~/.prima/themes\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Object, \fIexamples/themes.pl\fR