---
name: "Prima::Themes"
section: "3"
platform: "linux"
package: "libprima-perl"
version: "1.28-1.3+b3"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/Prima::Themes"
---

# Prima::Themes(3)

object themes management

## 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*