NAME

       Prima::Themes - object themes management

DESCRIPTION

       Provides layer for theme registration in Prima. Themes are loosely grouped alternations of default class
       properties and behavior, by default stored in "Prima/themes" subdirectory. The theme realization is
       implemented as interception of object profile during its creation, inside "::profile_add". Various themes
       apply various alterations, one way only - once an object is applied a theme, it cannot be neither changed
       nor revoked thereafter.

       Theme configuration can be stored in an rc file, ~/.prima/themes, and is loaded automatically, unless
       $Prima::Themes::load_rc_file explicitly set to 0 before loading the "Prima::Themes" module. In effect,
       any Prima application not aware of themes can be coupled with themes in the rc file by the following:

               perl -MPrima::Themes program

       "Prima::Themes" namespace provides registration and execution functionality.  "Prima::Themes::Proxy" is a
       class for overriding certain methods, for internal realization of a theme.

       For interactive theme selection use examples/theme.pl sample program.

SYNOPSIS

               # register a theme file
               use Prima::Themes qw(color);
               # or
               use Prima::Themes; load('color');
               # list registered themes
               print Prima::Themes::list;

               # install a theme
               Prima::Themes::install('cyan');
               # list installed themes
               print Prima::Themes::list_active;
               # create object with another theme while 'cyan' is active
               Class->create( theme => 'yellow');
               # remove a theme
               Prima::Themes::uninstall('cyan');

Prima::Themes

       load @THEME_MODULES
           Load  THEME_MODULES  from  files  via  "use"  clause, dies on error.  Can be used instead of explicit
           "use".

           A loaded theme file may register one or more themes.

       register $FILE, $THEME, $MATCH, $CALLBACK, $INSTALLER
           Registers a previously loaded theme. $THEME is a unique string identifier.  $MATCH  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 "isa" to each given class name, and if  matched,  the
           $CALLBACK  routine  is  called  with the following parameters: object, default profile, user profile,
           second item of the matched pair.

           If $CALLBACK is "undef", 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.

           The  theme  is  inactive  until "install" is called. If $INSTALLER 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.

           $FILE is used to indicate the file in which the theme is stored.

       deregister $THEME
           Un-registers $THEME.

       install @THEMES
           Installs  previosuly  loaded and registered loaded THEMES; the installed themes are now used to match
           new objects.

       uninstall @THEMES
           Uninstalls loaded THEMES.

       list
           Returns the list of registered themes.

       list_active
           Returns the list of installed themes.

       loaded $THEME
           Return 1 if $THEME is registered, 0 otherwise.

       active $THEME
           Return 1 if $THEME is installed, 0 otherwise.

       select @THEMES
           Uninstalls all currently installed themes, and installs THEMES instead.

       merger $OBJECT, $PROFILE_DEFAULT, $PROFILE_USER, $PROFILE_THEME
           Default  profile  merging  routine,  merges  $PROFILE_THEME   into   $PROFILE_USER   by   keys   from
           $PROFILE_DEFAULT.

       load_rc [ $INSTALL = 1 ]
           Reads  data  ~/.prima/themes and loads listed modules.  If $INSTALL = 1, installs the themes from the
           rc file.

       save_rc
           Writes configuration of currently installed themes into rc file, returns  success  flag.  If  success
           flag is 0, $! contains the error.

Prima::Themes::Proxy

       An instance of "Prima::Themes::Proxy", created as

       Prima::Themes::Proxy-> new( $OBJECT)

       is  a  non-functional  wrapper  for  any  Perl object $OBJECT. All methods of $OBJECT, except "AUTOLOAD",
       "DESTROY", and "new", are forwarded to $OBJECT itself transparently. The class can be used, for  example,
       to deny all changes to "lineWidth" inside object's painting routine:

               package ConstLineWidth;
               use vars qw(@ISA);
               @ISA = qw(Prima::Themes::Proxy);

               sub lineWidth { 1 } # line width is always 1 now!

               Prima::Themes::register( '~/lib/constlinewidth.pm', 'constlinewidth',
                       [ 'Prima::Widget' => {
                               onPaint => sub {
                                       my ( $object, $canvas) = @_;
                                       $object-> on_paint( ConstLineWidth-> new( $canvas));
                               },
                       } ]
               );

AUTHOR

       Dmitry Karasik, <dmitry@karasik.eu.org>.

FILES

       ~/.prima/themes

SEE ALSO

       Prima, Prima::Object, examples/themes.pl

perl v5.18.2                                       2009-02-24                                   Prima::Themes(3)