Prima::Themes(3pm)

1Prima::Themes(3)      User Contributed Perl Documentation     Prima::Themes(3)
2
3
4

NAME

6       Prima::Themes - object themes management
7

DESCRIPTION

9       Provides layer for theme registration in Prima. Themes are loosely
10       grouped alternations of default class properties and behavior, by
11       default stored in "Prima/themes" subdirectory. The theme realization is
12       implemented as interception of object profile during its creation,
13       inside "::profile_add". Various themes apply various alterations, one
14       way only - once an object is applied a theme, it cannot be neither
15       changed nor revoked thereafter.
16
17       Theme configuration can be stored in an rc file, ~/.prima/themes, and
18       is loaded automatically, unless $Prima::Themes::load_rc_file explicitly
19       set to 0 before loading the "Prima::Themes" module. In effect, any
20       Prima application not aware of themes can be coupled with themes in the
21       rc file by the following:
22
23               perl -MPrima::Themes program
24
25       "Prima::Themes" namespace provides registration and execution
26       functionality.  "Prima::Themes::Proxy" is a class for overriding
27       certain methods, for internal realization of a theme.
28
29       For interactive theme selection use examples/theme.pl sample program.
30

SYNOPSIS

32               # register a theme file
33               use Prima::Themes qw(color);
34               # or
35               use Prima::Themes; load('color');
36               # list registered themes
37               print Prima::Themes::list;
38
39               # install a theme
40               Prima::Themes::install('cyan');
41               # list installed themes
42               print Prima::Themes::list_active;
43               # create object with another theme while 'cyan' is active
44               Class->create( theme => 'yellow');
45               # remove a theme
46               Prima::Themes::uninstall('cyan');
47

Prima::Themes

49       load @THEME_MODULES
50           Load THEME_MODULES from files via "use" clause, dies on error.  Can
51           be used instead of explicit "use".
52
53           A loaded theme file may register one or more themes.
54
55       register $FILE, $THEME, $MATCH, $CALLBACK, $INSTALLER
56           Registers a previously loaded theme. $THEME is a unique string
57           identifier.  $MATCH is an array of pairs, where the first item is a
58           class name, and the second is an arbitrary scalar parameter. When a
59           new object is created, its class is matched via "isa" to each given
60           class name, and if matched, the $CALLBACK routine is called with
61           the following parameters: object, default profile, user profile,
62           second item of the matched pair.
63
64           If $CALLBACK is "undef", the default merger routine is called,
65           which treats the second items of the pairs as hashes of the same
66           format as the default and user profiles.
67
68           The theme is inactive until "install" is called. If $INSTALLER
69           subroutine is passed, it is called during install and uninstall,
70           with two parameters, the name of the theme and boolean
71           install/uninstall flag. When install flag is 1, the theme is about
72           to be installed; the subroutine is expected to return a boolean
73           success flag. Otherwise, subroutine return value is not used.
74
75           $FILE is used to indicate the file in which the theme is stored.
76
77       deregister $THEME
78           Un-registers $THEME.
79
80       install @THEMES
81           Installs previosuly loaded and registered loaded THEMES; the
82           installed themes are now used to match new objects.
83
84       uninstall @THEMES
85           Uninstalls loaded THEMES.
86
87       list
88           Returns the list of registered themes.
89
90       list_active
91           Returns the list of installed themes.
92
93       loaded $THEME
94           Return 1 if $THEME is registered, 0 otherwise.
95
96       active $THEME
97           Return 1 if $THEME is installed, 0 otherwise.
98
99       select @THEMES
100           Uninstalls all currently installed themes, and installs THEMES
101           instead.
102
103       merger $OBJECT, $PROFILE_DEFAULT, $PROFILE_USER, $PROFILE_THEME
104           Default profile merging routine, merges $PROFILE_THEME into
105           $PROFILE_USER by keys from $PROFILE_DEFAULT.
106
107       load_rc [ $INSTALL = 1 ]
108           Reads data ~/.prima/themes and loads listed modules.  If $INSTALL =
109           1, installs the themes from the rc file.
110
111       save_rc
112           Writes configuration of currently installed themes into rc file,
113           returns success flag. If success flag is 0, $! contains the error.
114

Prima::Themes::Proxy

116       An instance of "Prima::Themes::Proxy", created as
117
118       Prima::Themes::Proxy-> new( $OBJECT)
119
120       is a non-functional wrapper for any Perl object $OBJECT. All methods of
121       $OBJECT, except "AUTOLOAD", "DESTROY", and "new", are forwarded to
122       $OBJECT itself transparently. The class can be used, for example, to
123       deny all changes to "lineWidth" inside object's painting routine:
124
125               package ConstLineWidth;
126               use vars qw(@ISA);
127               @ISA = qw(Prima::Themes::Proxy);
128
129               sub lineWidth { 1 } # line width is always 1 now!
130
131               Prima::Themes::register( '~/lib/constlinewidth.pm', 'constlinewidth',
132                       [ 'Prima::Widget' => {
133                               onPaint => sub {
134                                       my ( $object, $canvas) = @_;
135                                       $object-> on_paint( ConstLineWidth-> new( $canvas));
136                               },
137                       } ]
138               );
139

AUTHOR

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

FILES

144       ~/.prima/themes
145