This class can become quite complicated because we want the following behaviour from our keyboard manager.
The selected index should be able to move up past the top of the dataProvider and move to the bottom row and vice versa, in addition we should be able to go off the left hand side of the columns and appear on the right hand side and vice versa.

For example if the dataProvider has 25 items and each row contains 5 columns.

Up / Down Examples.
If we are at column 1 row 1 ( box 1 ) and we press up we should go to column 1 row 5( box 2 ) and then for every key press we should move up the column until we hit the row 1 column 1 index again. However if we press down then we should go to column 1 row 2 and so forth until we hit column 1 row 5 ( box 2 ). Then when we press down again we should move to the top of the column again row 1 column 1 ( box 1 ) and this should be the case for each column no matter how many rows it has.

Box 1          Box 2

Left / Right Examples
Again if we start in column 1 row 1 ( box 1 ) and we press left then we should end up in column 5 row 1 ( box 3 ) and each subsequent left keyboard event should decrement the column number until it reaches 1 again.
If we press the opposite right key then we should move right along the columns until we hit column 5 row 1 ( box 3 ) then we should loop back to column 1 row 1 ( box 1 ).

Box 1          Box 3

This is all quite simple however what should happen if we have an odd number in our dataProvider? For example a 5*5 grid with a 19 color dataprovider? like follows.

We need to make sure that pressing left and right still stay on the same row no matter how many items are in that row for example if we move from column 1 row 5 ( box 4 ) left we should end up in column 4 row 5 ( box 5 ) and vice versa if we press right from box 5 we should end up in box 4.

Box 4          Box 5

Also if we are in box 5 and we press down we should still go to the first item in the column. Furthermore if we are in position column 5 row 4 ( box 6 ) and we press down we should still go to position column 5 row 1 ( box 3 ). And if we press right then we should go to column 1 row 4 ( box 7 ) and vice versa.
Box 6 Box 7

Ok now we can actually get started writing some code. To begin we will need to know two things
1. The length of the dataProvider and 2. the number of columns to split it into. Next we need to know the current index and the keyboard input the user pressed. Knowing this lets create the following Interface.

 
package co.uk.betadesigns.components.colorpicker.interfaces
{
	import flash.events.KeyboardEvent;
 
	public interface ISparkColorPickerKeyboardManager
	{
		/**
		 * Set the number of columns that the ColorPicker has this
		 * is used in calculating the new index after keyboard events
		 * are pressed. The number of rows is also automatically calculated
		 * from dataProviderLength / numberOfColumns.
		 *
		 * @param value int representing the number of columns.
		 * @return int representing the number of columns.
		 *
		 */
		function set numberOfColumns( value : int ) : void;
		function get numberOfColumns() : int;
 
		/**
		 * Set the length that the ColorPicker dataProvider has.
		 * This is used in calculating the new index after keyboard events
		 * are pressed. The number of rows is also automatically calculated
		 * from dataProviderLength / numberOfColumns.
		 *
		 * @param value int representing the number of columns.
		 * @return int representing the number of columns.
		 *
		 */
		function set dataProviderLength( value : int ) : void;
		function get dataProviderLength() : int;
 
		/**
		 * The KeyDown method takes a keyboard event and the current
		 * index in the dataprovider it then calculates the new index
		 * based on the keyboard button pressed UP/DOWN/LEFT/RIGHT
		 * It uses the numberOfColumns and numberOfRows in order to
		 * calculate the the new index.
		 *
		 * @param event the keyboard event.
		 * @param index the current index in the dataProvider.
		 *
		 * @return returns the new index in the dataProvider.
		 *
		 */
		function keyDown( event : KeyboardEvent, index : int ) : int;
	}
}
 

Next we need to create two classes the first is our empty SparkColorPickerKeyboardManager and the second is the TestCase to go along with it.

 
package co.uk.betadesigns.components.colorpicker
{
	import co.uk.betadesigns.components.colorpicker.interfaces.ISparkColorPickerKeyboardManager;
 
	import flash.events.KeyboardEvent;
	import flash.ui.Keyboard;
 
	public class SparkColorPickerKeyboardManager
		implements ISparkColorPickerKeyboardManager
	{
		private var _numberOfColumns : int = 1;
 
		public function get numberOfColumns():int
		{
			return _numberOfColumns;
		}
 
		public function set numberOfColumns(value:int):void
		{
			if( value < 1 ) value = 1;
			_numberOfColumns = value;
		}
 
		private var _dataProviderLength : int = 0;
 
		public function get dataProviderLength():int
		{
			return _dataProviderLength;
		}
 
		public function set dataProviderLength(value:int):void
		{
			if( value < 1 ) value = 1;
			_dataProviderLength = value;
		}
 
		public function keyDown( event : KeyboardEvent, index : int ) : int
		{
			return index;
		}
	}
}
 

As you can see from the source above we have put in some simple checks on the setters to make sure the numberOfColumns and the dataProviderLength value can never be set to below 1 this will stop us from returning NaN and Infinity values.
For our TestCase we won't bother testing those two setters as they are quite simple so just setup your empty SparkColorPickerKeyboardMangerTests.as with 4 failing tests for our events Up/Down/Left/Right

 
package flexUnitTests.co.uk.betadesigns.components.colorpicker
{
	import co.uk.betadesigns.components.colorpicker.SparkColorPickerKeyboardManager;
 
	import flash.events.KeyboardEvent;
	import flash.ui.Keyboard;
 
	import flexunit.framework.Assert;
 
	public class SparkColorPickerKeyboardManagerTests
	{
		private var _class : SparkColorPickerKeyboardManager;
 
		[Before]
		public function setUp():void
		{
			_class = new SparkColorPickerKeyboardManager();
		}
 
		[After]
		public function tearDown():void
		{
			_class = null;
		}
 
		[Test]
		public function testKeyUp():void
		{
			Assert.fail( "Test Not implemented yet." );
		}
 
		[Test]
		public function testKeyDown():void
		{
			Assert.fail( "Test Not implemented yet." );
		}
 
		[Test]
		public function testKeyLeft():void
		{
			Assert.fail( "Test Not implemented yet." );
		}
 
		[Test]
		public function testKeyRight():void
		{
			Assert.fail( "Test Not implemented yet." );
		}
 
		private function up() : KeyboardEvent
		{
			return new KeyboardEvent( KeyboardEvent.KEY_DOWN, true, false, 0, Keyboard.UP );
		}
 
		private function down() : KeyboardEvent
		{
			return new KeyboardEvent( KeyboardEvent.KEY_DOWN, true, false, 0, Keyboard.DOWN );
		}
		private function left() : KeyboardEvent
		{
			return new KeyboardEvent( KeyboardEvent.KEY_DOWN, true, false, 0, Keyboard.LEFT );
		}
		private function right() : KeyboardEvent
		{
			return new KeyboardEvent( KeyboardEvent.KEY_DOWN, true, false, 0, Keyboard.RIGHT );
		}
	}
}
 

You will notice that I have also included four helper methods at the bottom of the class to simulate keypress' for our tests.
I have also added Assert.fail() to each test so that we can make sure they are working. I always do this just as a sanity check.
We need to test all the boundaries of our keyboard manager so we should test negative numbers as well as numbers that go beyond our dataProvider length to ensure they return expected values. In Addition we need to make sure our grids from above return the expected results.

We will begin fleshing out our tests in part 2-b

Below you can see the three components.

The Spark component does all the stuff the old MX one does like keyboard movement, selectedIndex, selectedColor, colorLabel, etc.. In addition I also added the ability to set/get the selectedItem and dispatching indexChange events.

To begin with lets look at what the current color picker does.

From the docs we can see that the color picker has the following properties and events. We are ignoring the Styles because these will be handled by the skins and not the components. I have also decided that the TextField is part of the Skin and not the responsibility of the component so we will be ignoring the showTextField property.

 
<mx:ColorPicker
    Properties
    colorField="color"
    labelField="label"
    selectedColor="0x000000"
    selectedIndex="0"
    showTextField="true|false"
 
    Styles...
 
    Events
    change="No default"
    close="No default"
    enter="No default"
    itemRollOut="No default"
    itemRollOver="No default"
    open="No default"
    />
 

Next if we look at the default MX ColorPicker we can see that there appears to only be 2 visual elements the preview panel and the drop down panel. So we know we need two classes one for each of them and one more to hold them together the actual SparkColorPicker Class. This classes skin will simply hold the other skin parts together and be used for managing the other two classes.
To begin with lets start by building the simplest item so that we can get something on the screen straight away.
We know it should should take a data item and that we should probably pass the colorField and labelField properties to it from the main class incase they are required.
So we have our simple ISparkColorPreviewPanel Interface ( comments omitted but are in the included files )

 
public interface ISparkColorPreviewPanel extends IEventDispatcher
{
	function get selectedColor() : uint;
	function set selectedColor( value : uint ) : void;
 
	function get colorField() : String;
	function set colorField( value : String ) : void;
 
	function get labelField() : String;
	function set labelField( value : String ) : void;
 
	function get data() : Object;
	function set data( value : Object ) : void;
}
 

I would normally start writing unit tests for this interface now but as this is a rather small class that consists of only getters and setters I won't bother for this example. Lets just write the concrete class.

 
public class SparkColorPickerPreviewPanel extends SkinnableComponent
		implements ISparkColorPreviewPanel
{
 
	public function SparkColorPickerPreviewPanel()
	{
		super();
		init();
	}
 
	private var _selectedColor : uint = 0x000000;
 
	[Bindable]
	/**
	 * @inheritDoc
	 */
	public function get selectedColor() : uint
	{
		return _selectedColor;
	}
 
	public function set selectedColor( value : uint ) : void
	{
		_selectedColor = value;
		invalidateProperties();
	}
 
	private var _colorField : String;
 
	/**
	 * @inheritDoc
	 */
	public function get colorField():String
	{
		return _colorField;
	}
 
	public function set colorField(value:String):void
	{
		_colorField = value;
		invalidateProperties();
	}
 
	private var _labelField : String;
 
	/**
	 * @inheritDoc
	 */
	public function get labelField():String
	{
		return _labelField;
	}
 
	public function set labelField(value:String):void
	{
		_labelField = value;
		invalidateProperties();
	}
 
	private var _data : Object;
 
	[Bindable]
	/**
	 * @inheritDoc
	 */
	public function get data():Object
	{
		return _data;
	}
 
	public function set data(value:Object):void
	{
		_data = value;
		invalidateProperties();
	}
 
	//-------------------------------------------------------
	// PRIVATE METHODS
	//-------------------------------------------------------
 
	private function init() : void
	{
		buttonMode = true;
		mouseEnabled = true;
		useHandCursor = true;
	}
}
 

This class doesn't really do anything except hold data and setup some default values so that it will act like a button it's all pretty self explanatory.

The next class we have to make is the default MX style preview panel as follows.

 
 
<s:Skin xmlns:fx="http://ns.adobe.com/mxml/2009"
		xmlns:s="library://ns.adobe.com/flex/spark"
		>
	<!-- host component -->
	<fx:Metadata>
		[HostComponent("co.uk.betadesigns.components.colorpicker.SparkColorPickerPreviewPanel")]
	</fx:Metadata>
 
	<fx:Script>
		<![CDATA[
 
			[Bindable]
			public var borderWidth : Number = 3;
 
			[Bindable]
			public var arrowBorderWidth : Number = 2;
 
			[Bindable]
			public var panelWidth : Number = 22;
 
			[Bindable]
			public var panelHeight : Number = 22;
 
		]]>
	</fx:Script>
 
	<s:Group>
		<s:Graphic x="0" y="0">
			<!--BORDER-->
			<s:Rect height="{ panelWidth }" width="{ panelHeight }">
				<s:stroke>
					<s:SolidColorStroke color="0x000000" weight="1"/>
				</s:stroke>
				<s:fill>
					<s:LinearGradient rotation="90">
						<s:entries>
							<s:GradientEntry color="0xFFFFFF" ratio="0.00" alpha="1"/>
							<s:GradientEntry color="0xCCCCCC" ratio="0.33" alpha="1"/>
							<s:GradientEntry color="0x8E8E8E" ratio="0.66" alpha="1"/>
						</s:entries>
					</s:LinearGradient>
				</s:fill>
			</s:Rect>
			<!--INNER COLOR-->
			<s:Rect
				id="innerColor"
				x="{ borderWidth }" y="{ borderWidth }"
				height="{ panelHeight - ( borderWidth * 2 ) }"
				width="{ panelWidth - ( borderWidth * 2 ) }">
				<s:fill>
					<s:SolidColor color="{ hostComponent.selectedColor }"/>
				</s:fill>
			</s:Rect>
			<!--BOTTOM RIGHT ARROW BOX-->
			<s:Rect
				id="arrowBox"
				x="{ panelWidth - ( borderWidth * 3 ) }" y="{ panelHeight - ( borderWidth * 3 ) }"
				height="{ borderWidth * 3 }" width="{ borderWidth * 3 }">
				<s:fill>
					<s:LinearGradient rotation="90">
						<s:entries>
							<s:GradientEntry color="0xCCCCCC" ratio="0.33" alpha="1"/>
							<s:GradientEntry color="0x8E8E8E" ratio="0.66" alpha="1"/>
						</s:entries>
					</s:LinearGradient>
				</s:fill>
			</s:Rect>
			<!--ARROW -->
			<s:Path data="M { arrowBox.x + arrowBorderWidth } { arrowBox.y + arrowBorderWidth }
					L { arrowBox.x + arrowBox.width - arrowBorderWidth } { arrowBox.y + arrowBorderWidth }
					L { arrowBox.x + ( arrowBox.width / 2 ) } { arrowBox.y + ( arrowBox.height - ( arrowBorderWidth * 1.5 ) ) }
					L { arrowBox.x + arrowBorderWidth } { arrowBox.y + arrowBorderWidth }
					">
				<s:stroke>
					<s:SolidColorStroke id="arrowStroke" color="0x000000" weight="1"/>
				</s:stroke>
				<s:fill>
					<s:SolidColor color="0x000000"/>
				</s:fill>
			</s:Path>
			<!--INNER BORDER-->
			<s:Path data="M { innerColor.x } { innerColor.y }
					L { innerColor.x + innerColor.width } { innerColor.y }
					L { innerColor.x + innerColor.width } { arrowBox.y - arrowStroke.weight }
					L { arrowBox.x - arrowStroke.weight } { arrowBox.y - arrowStroke.weight }
					L { arrowBox.x - arrowStroke.weight } { innerColor.y + innerColor.height }
					L { innerColor.x } { innerColor.y + innerColor.height }
					L { innerColor.x } { innerColor.y }
					">
				<s:stroke>
					<s:SolidColorStroke color="0x000000" weight="1" alpha="0.5"/>
				</s:stroke>
			</s:Path>
 
		</s:Graphic>
		<s:filters>
			<s:DropShadowFilter
				distance="1"
				/>
		</s:filters>
	</s:Group>
</s:Skin>
 

In this class we are simply setting up the way in which the preview should look using the new Group and Graphic elements. The important things here are that we set the HostComponent to our custom SparkColorPickerPreview class. And that we link our Fill to our host component on the following line.

 
<s:fill>
    <s:SolidColor color="{ hostComponent.selectedColor }"/>
</s:fill>
 

That allows our color to be updated everytime the color is set on the hostComponent.

We can test this by simply putting the following code in an example project.

 
<colorpicker:SparkColorPickerPreviewPanel selectedColor="0xFF0000" />
 

I have set my version up with a default.css file and skin so I don't need to reference one here if you want to know how to do that then see this post on Default Skin for custom FlashBuilder components. otherwise simply add the skin file as the skinClass like follows.

 
<colorpicker:SparkColorPickerPreviewPanel selectedColor="0xFF0000"
skinClass="co.uk.betadesigns.components.colorpicker.skins.mx.MXPreviewSkin"/>
 

In the next post I will walk through testing and creating a SparkColorPickerDropDownPanel, after that we will look at creating the MxDropDownPanelSkin and a keyboardManager for handling input from the user to move around the dataprovider. Once we have our PreviewPanel and DropDownPanel complete we will then move onto creating the SparkColorPicker class to pull it all together with the skins. Or you can just download the source files here and work your way through them.
I hope this post was useful and I appreciate any comments, suggestions or criticism.

To begin you need to move your custom component into a FlexLibrary.

Adding an Icon to your custom component

Once inside the library if you want to include a custom Icon with your component to accompany it in the Component Explorer simply place an icon in the same folder as the Component. For example my component is in the following package structure.

Next add the following metaData to your component file.

ActionScript

 
[IconFile("Icon.png")]
public class ExampleComponent
{
   ...
}
 

or if it is an MXML component

 
<fx:Metadata>
 
[IconFile("Icon.png")]
 
</fx:Metadata>
 

The next step is to create a design.xml file.
Design.xml

 
<?xml version="1.0" ?>
<design>
 
</design>
 

First we add the namespace we would like to appear for our custom component when it is imported into mxml views.

 
	<namespaces>
 
		<namespace
			prefix="betadesigns"
			uri="http://www.betadesigns.co.uk/Blog"
			/>
 
	</namespaces>
 

The prefix value is what will appear before your component name so for example a spark button has

<s:button>

so our custom component would be

<betadesigns:button>

Next we need to add the folder category we would like to create in the Component view.

 
 
	<categories>
		<category
			id="beta"
			label="BetaDesigns Components"
			defaultExpand="true" />
	</categories>
 

I have chosen to give my folder the name BetaDesigns Components, the id value will be used as a reference so that we can tell each component which Category folder we want to place it into.

Finally for the design.xml file we need to add one more node the components node.

<components>
		<component
			name="loginComponent"
			namespace="betadesigns"
			category="beta"
			displayName="Login Component" />
	</components>

Inside the components node we add our custom component giving it an identifying name ( this doesn't have to be the same as the mxml file name ) tell it which namespace to use here i am using my betadesigns namespace provided above. we then set which category we wish to include it in and give it a display name.
That is all that is needed for our design.xml file.

We then need one more file the *-manifest.xml this file can be called anything you like but it tends to be appended with the suffix -manifest so that it can be easily identified.

 
<?xml version="1.0"?>
<componentpackage>
    <component
    	id="loginComponent"
    	class="co.uk.betadesigns.components.example.ExampleComponent"
    	/>
</componentpackage>
 

This manifest file contains the id to the item in the design.xml file as well as the absolute path to the file to map to that component id. As you can see from the above i have a component in my library called ExampleComponent however i want this component to appear in the Components viewer as my login component so i give it the id=loginComponent in the manifest file which points to the name=loginComponent in the design.xml file.
The final piece of the puzzle is to open up the library preferences>Flex Library Compiler

 

under the namespace url place the same namespace your defined in your design.xml file.
under manifrest file choose your *-manifest.xml file.

Next choose>Flex Library Build Path>Assets

Make sure your design.xml file and icon file if you are including one are selected.
There is no need to include the -manifest.xml file as it is automatically compiled into the swc by adding it to our Compiler prefs.

Now if you reference your swc in a new project you should see your components appear under your custom folder with your custom icons.

[Icons not appearing issue]
If this happens then try restarting Eclipse/FlashBuilder as it doesn't seem to pick up the changes everytime.

Project FIles

However it does have lots of other cool features like::

Color grouping

Nice shiny 3D balls for the color swatches.

Kuler Lookup facility ( optional just set Kuler = true/false );

Can be used exactly the same as the Flex Color picker so you can just swap it into existing projects.

OK Just right click to view the source

This is mostly based on the Flex Color Picker so feel free to use it in your own projects improve it and just give me a shout as I would love to see it implemented in real life projects personal or otherwise.