Prima::Themes(3)					User Contributed Perl Documentation					  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/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

perl v5.14.2							    2009-02-24							  Prima::Themes(3)