By Ben Pritchard
 
Created
26 July 2010
 

Requirements

 
Prerequisite knowledge

This article is intended for Flash developers who have an intermediate understanding of ActionScript, ActionScript classes, and JSFL. Before you get started, install the Kuler panel for Flash CS3, available in the source code linked to above. You can familiarize yourself with the panel's functionality without installing it by watching a demo of the panel in action created by John Nack, senior product manager of Adobe Photoshop.
 
Familiarity with the Kuler API may be of additional benefit as well. You can familiarize yourself with the Kuler API by visiting the Kuler API page in the Adobe Developer Connection.
 

 
User Level

Intermediate
 

 
Sample files

A while ago I took the opportunity to brush up on my ActionScript 3.0 proficiency by creating a custom panel for Adobe Flash CS3 Professional. I have been a big fan of the Kuler web-hosted application, not to mention the different display incarnations to which it has been ported. I felt that I would try to make my contribution to the Flash community as well. This article provides you with an overview of how I created the Kuler panel for Flash CS3 Professional (see Figure 1) and highlights some of the great new features and methods it gives you in the Flash authoring environment—as well as the Kuler APIs.
 
kuler panel for Flash CS3 Professional
Figure 1. Kuler panel for Flash CS3 Professional
Flash CS4 Professional users enjoy the added benefit of having a native Kuler panel in the IDE (accessible from Window > Extensions), which allows them to create Kuler themes directly from Flash. For those of you who might not have had the opportunity to upgrade yet, this panel will provide you with the ability to use Kuler themes that you and others have created.
 

 
Kuler background

Kuler is a great color theme-sharing tool released by Adobe. It started out as a web-based application that enabled users to create, save, and download community-created color themes or harmonies. Downloaded themes are provided in the Adobe Swatch Exchange (ASE) format, enabling users to access the themes in their Creative Suite products. Users can create and rate themes, as well as filter them by most recent, popular, and highest rated. The Kuler website also provides search functionality and RSS feeds that list the different filtered theme lists.
 
Kuler was then released as a Dashboard widget for Mac OS X (see Figure 2; download (ZIP, 164K). This brought to the user's desktop the ability to browse through color themes. Colors can be selected and copied to the Clipboard for use.
 
kuler Dashboard widget for Mac OS X
Figure 2. Kuler Dashboard widget for Mac OS X
Adobe has released an AIR version of Kuler (see Figure 3; download (AIR, 627K). This cross-platform version of Kuler can be used right on the user's desktop.
 
Adobe AIR version of kuler
Figure 3. Adobe AIR version of Kuler

 
The Kuler API

Porting the Kuler application is quite easy because Adobe provides an API to return RSS feeds for each of the Kuler filters. You can easily consume the Kuler API feeds and display the results in your own custom user interface. This is what led me to the development of the Kuler panel for Flash CS3 Professional.
 
The Kuler API provides a set of URLs that return RSS feeds. These APIs give additional functionality over the current kuler.adobe.com interface and RSS feeds by providing such features as returning images of the swatches in a color theme.
 
Additional information on the usage of the Kuler API can be found on the Kuler API page in the Adobe Developer Connection.
 

 
Designing the user interface

One of the most important things to take into account when developing a custom panel for Flash CS3 Professional is ease of use. Adobe provided a great UI style for Kuler, so I decided to follow their lead and style the panel UI after the web-based, Dashboard widget, and Adobe AIR versions of the application. In Figure 4 you can see what I started off with. The UI primarily consists of a V3 Flash Scroll Pane component, an input text area, and controls to select the feed the user wants to view.
 
Original kuler panel UI
Figure 4. Original Kuler panel UI

 
Constructing the user interface and complementing code

Skinning the Version 3 (V3) components (see Figure 5) is an extremely easy task compared to modifying earlier versions of the UI components. You can modify the appearance of the component simply by double-clicking it and editing it in Flash as you would any other movie clip.
 
Skinning scrollbar components
Figure 5. Skinning scroll bar components
The main Timeline of your Flash panel is responsible for tying the code from your ActionScript classes together. The primary classes that I created for the panel were JSFLKuler and KulerItem. I will show you how these classes are implemented on the main Timeline of the panel:
 
import com.pixelfumes.kuler.*; import flash.events.Event;
Grant Skinner recently released several classes that enable you to modify properties such as the scroll bars' width of the V3 components easily. I imported these classes as well, because I really wanted to tweak the way the scroll bars look on the default scroll pane:
 
import fl.managers.StyleManager; StyleManager.setStyle("scrollBarWidth",11);
I instantiate an instance of the JSFLKuler class here and give it a variable name of kuler. I then tell it to load the RSS feed for the most recent color combinations in Kuler using the Adobe Kuler API. Notice the use of my developer key in the URL for the feed. The Adobe Kuler API requires the use of a valid developer key in order to return a feed. You can sign up for your own developer key on the Kuler API page.
 
Once we have a valid developer key we are able to instantiate the instance of the JSFLKuler class using the following code:
 
var devKey:String = "29CE344635AB36DB7F2A50B3C8AC7E55"; kuler.loadFeed("http://kuler-api.adobe.com/rss/get.cfm?listtype=recent&key="+devKey);
In order to tell when the RSS feed has loaded or failed, I set up listeners that will listen for the JSFLKuler class to dispatch the FEED_LOADED or FEED_FAILED event:
 
kuler.addEventListener(com.pixelfumes.kuler.JSFLKuler.FEED_LOADED,onFeedReady); kuler.addEventListener(com.pixelfumes.kuler.JSFLKuler.FEED_FAILED,onFeedFailed);
There are several different ways to populate the new V3 ScollPane component with content. In this case I create a new, blank movie clip named stubMC. I set stubMC as the source for the scroll pane, which has an instance name of sp. Now any items that I add to stubMC will appear within the scroll pane:
 
var stubMC:MovieClip = new MovieClip(); sp.source = stubMC;
When the feed is loaded, I can loop through the results and create instances of the KulerItem class, the class that handles the display of each swatch group. Using the getItemCount method from the JSFLKuler class, I can get the number of swatch groups I am working with.
 
As I loop through the items, I assign the name, swatch colors, and rating that I parse from the RSS feed. In the code below, you will notice that I am instantiating instances of the KulerItem class. This works a little like the attachMovie method from ActionScript 2.0 in this case. I will cover the KulerItem class in detail later in this article:
 
function onFeedReady(e:Event):void{ if(kuler.getItemCount() < 1){ feedControl_mc.status_txt.text = "No Results"; }else{ for(var i:uint=0;i<kuler.getItemCount();i++){ var ki = new KulerItem(); stubMC.addChild(ki); ki.y = i*60; ki.setLabel(kuler.getItem(i).title); ki.setSwatchColors(kuler.getItem(i).hexColor) ki.setRating(kuler.getItem(i).rating); } sp.refreshPane(); } hidePreloader() }
In the event that the RSS feed load should fail, you need to display a notification to the user:
 
function onFeedFailed(e:Event):void{ feedControl_mc.status_txt.text = "Feed Load Failed"; hidePreloader(); }
In order to remove items from the stubMC with the scroll pane, I simply set the stubMC to null and recreate it as a fresh, empty movie clip. I use this function primarily to wipe the previous swatch groups from the panel display each time a new RSS feed is loaded:
 
function removeKulerItems():void{ stubMC = null; stubMC = new MovieClip(); sp.source = stubMC; }
Listening for the click on an instance of KulerItem is easy: I simply add an event listener for the ITEM_SELECTED event to be broadcast. This fires the onItemSelected function on the main Timeline:
 
this.addEventListener(com.pixelfumes.kuler.KulerItem.ITEM_SELECTED, onItemSelected);
The onItemSelected function gathers arguments such as the swatch colors, swatch group name, and rating from the event that is broadcast and uses them as arguments being passed to the JSFL function:
 
function onItemSelected(e:Event):void{ var args:Array = e.target.swatchColors; args.push(escape(e.target.schemeName)); trace(e.target.swatchColors); executeJSFL(["kuler/kuler.jsfl","addSwatches",args]); }

 
JSFL file and general panel creation notes

The JSFL file for the Kuler panel handles the click of a color theme within your panel. Its job is to accept the arguments passed to it and use them to display the color swatches on the Stage. As you saw previously, the onItemSelected event function calls a function within a JSFL file named kuler.jsfl. This file should be located in your Commands folder and inside of a folder named kuler.
 
If you are unfamiliar with the creation of a custom panel for Flash, this procedure may be new for you. Your JSFL file will be called from the Kuler panel SWF file, which I named kuler.swf. This is really just a SWF file that resides within a folder on your system called WindowSWF. After your panel files have been created, they will need to be located in the following directories on your system:
 
  • kuler.swf (primary panel file)
    Windows Vista:[boot drive]\Users\username\Local Settings\Application Data\Adobe\Flash CS3\language\Configuration\WindowSWF
    Windows XP: [boot drive]\Documents and Settings\user\Local Settings\Application Data\Adobe\Flash CS3\language\Configuration\WindowSWF
    Mac OS X:[hard drive]/Users/userName/Library/Application Support/Adobe/Flash CS3/language/Configuration/WindowSWF
    Windows XP:[boot drive]\Documents and Settings\user\Local Settings\Application Data\Adobe\Flash CS3\language\Configuration\WindowSWF
    Mac OS X:[hard drive]/Users/userName/Library/Application Support/Adobe/Flash CS3/language/Configuration/WindowSWF
  • kuler.jsfl
    Windows Vista:[boot] drive\Users\username\Local Settings\Application Data\Adobe\Flash CS3\language\Configuration\Commands\kuler
    Windows XP:[boot] drive\Documents and Settings\user\Local Settings\Application Data\Adobe\Flash CS3\language\Configuration\Commands\kuler
    Mac OS X:[hard drive]/Users/userName/Library/Application Support/Adobe/Flash CS3/language/Configuration/Commands/kuler
As you are testing and creating these files, it is a good idea to place them in their proper locations. Having your Kuler FLA file publish to the WindowsSWF directory enables you to test the panel each time you publish it. You can access the panel by selecting Window > Other Panels > [Your SWF] from the main Flash menu. To see updates to the SWF file, you must close the panel and reopen it each time you republish the SWF file.
 

 
Examining the JSFL functions

The JSFL file itself contains only two functions: one to add the selected swatches to the Stage that the user has selected and one to display an alert box when the user clicks the info button at the bottom of the panel.
 
Take a look at the first function, called addSwatches. This function is passed a single argument containing six items. Items one through five contain the hex codes for the swatch group that was clicked, and the sixth item passes in the name of the color theme: