Prima::Themes(3)

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/theme" 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 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 explicit "use".

    A loaded theme file may register one or more themes.

register $FILE, $THEME, $MATCH, $CALLBACK, $INSTALLER
    Registers loaded theme. $THEME is unique string identifier. $MATCH is an array of pairs, where first item is class string, and second is a custom scalar parameter. When a new object is created, its class is matched via "isa" to each given class string, and if matched, $CALLBACK routine is called with parameters: object, default profile, user profile, second item of the matched pair.

    If $CALLBACK is "undef", default "merger" routine is called, which treats the second items of pairs as hashed of same format as 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, theme name and install 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 loaded THEMES; the installed themes are used to match new objects.

uninstall @THEMES
    Uninstalls loaded THEMES.

list
    Returns list of registered themes.

list_active
    Returns 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.

merger $OBJECT, $PROFILE_DEFAULT, $PROFILE_USER, $PROFILE_THEME
    Default profile merging routine, merges $PROFILE_THEME into $PROFILE_USER, based in keys found in $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. Any methods of $OBJECT class, 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