NAME¶

Prima::Themes - object themes management

DESCRIPTION¶

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

Theme configuration can be stored in an RC file, ~/.prima/themes, and is loaded automatically unless $Prima::Themes::load_rc_file is 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

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

For the interactive theme selection see the 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 an object with another theme while 'cyan' is active
        Class->new( theme => 'yellow');
        # remove a theme
        Prima::Themes::uninstall('cyan');

Prima::Themes¶

load @THEME_MODULES

Loads THEME_MODULES from files via the "use" clause, dies on error. Can be used instead of the explicit "use" call.

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, and second item of the matched pair.

If the $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 the $INSTALLER subroutine is passed, it is called during install and uninstall with two parameters, the name of the theme and the boolean install/uninstall flag. When the install flag is 1, the theme is about to be installed; the subroutine is expected to return a boolean success flag. Otherwise, the subroutine's 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 previously loaded and registered THEMES; the installed themes will be applied 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 the keys from $PROFILE_DEFAULT.

load_rc [ $INSTALL = 1 ]

Reads the ~/.prima/themes file and loads the listed modules. If $INSTALL = 1, installs the themes from the RC file.

save_rc

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

Prima::Themes::Proxy¶

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

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

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

        package ConstLineWidth;
        use base '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