Prima::Themes(3)

🌸 NAME 🌸

Prima::Themes — object themes management, and this is its manual, bestie. 🎀

---

✨ DESCRIPTION ✨

Okay so Prima::Themes provides a layer for theme registration in Prima. Themes are loosely grouped alternations of the default class properties and behaviors, and by default they’re stored in the Prima/themes subdirectory. ✨

Under the hood, 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. 💅

⚠️ No take-backs: 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 it’s 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 💅

This namespace is where the theme-registration API lives, bestie — here’s every method. 🫶

🫶 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. Byeee 👋

🔥 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 — the RC file, bestie. 📁

---

👀 SEE ALSO 👀

Prima, Prima::Object, examples/themes.pl. Go peek, iykyk. 👀

---

Okay that’s the whole page, mwah 💖 — source perl v5.42.0, dated 2024-08-20. periodt. 💅