IMPORTANT: Updates to Prism are on indefinite hold – more details can be found in the README in the within the Prism source. I have decided to continue publishing this short series because it documents how to use Prism in its current form and so still may be useful.
I am extremely excited to announce the release of Prism – an all-new dynamic theming library for Android. This is an initial release to get the basic functionality out there, but it is already pretty powerful. However there are some exciting additions in the pipeline which will make it more powerful still. In this series of articles we’ll cover the various aspects of prism to enable you to make use of it and even extend it yourself to meet the requirements of your project.
One small note about spelling: As you may have guessed from the spelling of the word ‘colour’ throughout this series of posts I am English and prefer to use the English spelling of ‘colour’. I am fully aware that there are many people who spell it ‘color’. In order to give people the freedom to use whichever spelling they prefer, Prism will accept both spellings. So you can call setColor(int color) in place of setColour(int colour) if you prefer. However, using the English spelling of ‘colour’ will result in slightly better performance because there will be one less method call as internally setColor(int color) simply calls setColour(int colour). So if you choose to spell ‘colour’ incorrectly you will suffer a very minor performance hit!
For now Prism is divided in to three separate libraries:
- prism – the core Prism library
- prism-viewpager – an extension which hooks up ViewPager with the core Prism library
- prism-palette – an extension which hooks up Palette with the core Prism library
The reasoning behind splitting them up was that the core Prism library has no external dependencies and is small and cheap to add to your project. However both the ViewPager and Palette extensions have external dependencies on the relevant support libraries. So if, for example, your project needs neither of these extensions you do not incur any unnecessary dependencies. However, if you do need ViewPager then you’re project will already have a dependency on the ViewPager support library so the overhead of adding the Prism ViewPager extension lib will be negligible.
Prism is published to both jCenter and Maven Central so, assuming that you already have one or both of these configured as repos for your project it is simply a case of adding the dependencies to your build.grade:
apply plugin: 'com.android.application'
android {
compileSdkVersion 22
buildToolsVersion "23.0.0 rc3"
defaultConfig {
applicationId "com.stylingandroid.prism.sample.palette"
minSdkVersion 7
targetSdkVersion 22
versionCode 1
versionName "1.0"
}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
}
dependencies {
compile 'com.android.support:appcompat-v7:22.2.0'
compile 'com.android.support:design:22.2.0'
compile 'com.android.support:support-v4:22.2.0'
compile 'com.stylingandroid.prism:prism:1.0.1'
compile 'com.stylingandroid.prism:prism-viewpager:1.0.1'
}
At the time of writing version 1.0.1 is the released version, but for future compatibility the current released version is 
.
Once you have added the necessary dependencies you can start using Prism.
The basic concept of Prism is based around three distinct object types: Setters, Filters, & Triggers.
A Setter allows us to set the colour of a UI object – typically a View but not always, as we shall see. The basic function of a Setter is to map a generic setColour(int colour) (or setColor(int color)) call to a specific method call on the View that it wraps. For example, the built in ViewBackgroundSetter will map to setBackgroundCOLOR(int color). In some cases the Setter can provide different behaviour on different versions of Android – for example StatusBarSetter will have no effect on pre-Lollipop devices because status bar colouring is not supported prior to Lollipop. However it will degrade gracefully (no crashing!) so you can safely use it and allow the Setter implementation to worry about how to apply the colour at runtime.
The standard Setters built in to Prism are:
FabSetter(FloatingActionButton fab)– sets the background tint colour on the design support library implementation of FloatingActionButtonStatusBarSetter(Window window)– sets the status bar colour on the supplied Window. Note that this does not take a View.TextSetter(TextView textView)– sets the text colour on the supplied TextView.ViewBackgroundSetter(View view)– sets the background colour of the supplied View.
Of course you can create your own Setters for custom Views which may require have additional components which can be coloured, and you can create multiple Setters for a single View to sett different attributes and add them all to the Prism to colour multiple components simultaneously.
A Filter allows us to modify a colour. Prism is generally called with a single colour value and sometimes we may want to apply different variants of that colour to different UI components – Filters enable us to do just that. In its most basic form a Filter takes a colour value as in input, performs some colour transformation upon that colour, and returns the transformed colour value. The basic built-in colour filters are:
IdentityFilter()– returns the colour which was input.ShadeFilter(float amount)– darkens the colour by effectively mixing in black. The value is a float from 0.0-1.0 which determines how much black to add. A value of 0 makes no change, and a value of 1.0 will produce pure blackTintFilter(float amount)– lightens the colour by effectively mixing in white. The value is a float from 0.0-1.0 which determines how much white to add. A value of 0 makes no change, and a value of 1.0 will produce pure white.
A Trigger is what triggers colour change events. Typically it will call setColour(in colour) on a Prism instance to propagate a colour change to all of the Setters which have been registered with that instance.
There are no Triggers currently built in to the core Prism library because that would require some library dependencies. However these are provided in the optional ViewPager and Palette extensions.
Now that we have our three types of components, we need to wire them up and that is what the Prism instance does. Each Prism instance has zero or more Triggers (which will cause a colour change), and one or more Setters (which will be called in response to a colour change). Each Setter can have a Filter attached which will transform the trigger colour before applying it to the Setter.
As well as this basic wiring, Prism also contains some intelligent factories which will construct appropriate Setter implementations automatically for you. For example, if you pass in a design library FloatingActionButton to Prism#background() it will automatically create a FabColourSetter for you.
A Prism instance is constructed using a builder pattern which constructs the components, wires them up, and then attaches to the Trigger and then responds to trigger events.
Lets look at how we can create a simple Prism instance:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
TextView textView = (TextView) findViewById(R.id.text_view);
AppBarLayout appBar = (AppBarLayout) findViewById(R.id.app_bar);
Toolbar toolbar = (Toolbar) findViewById(R.id.toolbar);
FloatingActionButton fab = (FloatingActionButton) findViewById(R.id.fab);
setSupportActionBar(toolbar);
Filter tint = new TintFilter(TINT_FACTOR_50_PERCENT);
prism = Prism.Builder.newInstance()
.background(appBar)
.background(getWindow())
.text(textView)
.background(fab, tint)
.build();
fab.setOnClickListener(this);
setColour(currentColour);
}
@Override
protected void onDestroy() {
if (prism != null) {
prism.destroy();
}
super.onDestroy();
}
Most of this code doesn’t require any explanation – it’s standard Android stuff. The highlighted section shows the creation of the Prism instance. We first create a 50% tit filter (which will lighten the colour wherever it is applied.
Next we create a Prism.Builder instance, and add the AppBar instance (which will create a Setter for the AppBar background colour), the Window (which will create a Setter for our StatusBarColour), a TextView (which will set the text colour because of using the text(TextView) method on the Builder), and a FloatingActionButton which will set the background colour of our FAB with the tint applied.
Finally we call build() to construct the Prism instance;
Now that we have everything wired up, we can change the colour of all of these components simultaneously by simply calling setColour(int colour) on the Prism instance:
prism.setColour(0xFF0000);
We also explicitly destroy the Prism instance in onDestroy(). While this isn’t strictly necessary because nothing will hold a reference to Prism instance after the Activity is destroyed leaving it free to be garbage collected, it never hurst the clean up when we no longer need it.
So there we have the fundamentals of Prism: By adding an additional 6 lines of code to our onCreate() we can do this if we hook up our FAB to toggle colours:
So that’s pretty powerful stuff but we haven’t even looked at incorporating Triggers in to the equation yet. In the next article we’ll do just that.
The full source for this sample is available as one of the sample apps within the Prism source.
© 2015, Mark Allison. All rights reserved.
Copyright © 2015 Styling Android. All Rights Reserved.
Information about how to reuse or republish this work may be available at http://blog.stylingandroid.com/license-information.
