Efficient, reusable (and centered) CheckBox renderers for DataGrids
As it turns out, truly reusable CheckBox renderers are much simpler to create than I previously reported. This post will provide and discuss what I think are the last CheckBox renderers you will ever need.
Did you know that CheckBox has a built-in click handler? I didn't until recently, despite its not-so-sneaky name of clickHandler. It is a protected function, so its only accessible if you subclass CheckBox, but that's OK since our renderers will do just that. clickHandler is key to creating these reusable renderers and keeping them super simple.
Before I start in on my inevitably wordy and detailed description lets take a look at our end result. CheckBoxRenderers in action and the source.
Edit: I initially forgot to mention that these renderers are heavily based on and influenced by the information provided by Flex Jedi Alex Harui on his blog. Thanks to Alex for illustrating "the right way" to do things.
This time around we will start with the item renderer since it is the simpler of the two. (Both of these classes center the CheckBox as that is the most common request, but if you don't need them centered simply remove the updateDisplayList() functions.)
CenteredCheckBoxItemRenderer.as:
{
import flash.display.DisplayObject;
import flash.events.MouseEvent;
import flash.text.TextField;
import mx.controls.CheckBox;
import mx.controls.dataGridClasses.DataGridListData;
public class CenteredCheckBoxItemRenderer extends CheckBox
{
// update data item on click
override protected function clickHandler(event:MouseEvent):void
{
super.clickHandler(event);
data[DataGridListData(listData).dataField] = selected;
}
// center the checkbox icon
override protected function updateDisplayList(w:Number, h:Number):void
{
super.updateDisplayList(w, h);
var n:int = numChildren;
for (var i:int = 0; i <n; i++)
{
var c:DisplayObject = getChildAt(i);
// CheckBox component is made up of box skin and label TextField
if (!(c is TextField))
{
c.x = (w - c.width) / 2;
c.y = (h - c.height) / 2;
}
}
}
}
}
There are 2 major differences between this class and our previous version. First, it doesn't implement ClassFactory, which means we can simply type its fully qualified class name into the itemRenderer attribute of a DataGrid and it will work (just like with mx.controls.CheckBox), requiring one less bindable variable in our file. The reason we can do this is that CheckBox, and by extension CenteredCheckBoxItemRenderer implement IDropInListItemRenderer. I won't go into the full details (if anyone would like me to dedicate a post to describing this more fully let me know) but in the case of CheckBox, that basically means that it knows how to set its selected state based on a piece of data that is passed to it. The second major difference is closely related to this fact, which is that we no longer have to override the data setter- we get that functionality for free.
The most important line in the item renderer class is essentially the other half of the equation. Whereas we get data retrieval and rendering for free, we have to provide the data setting functionality. That is really the only thing that separates it from a regular CheckBox other than the centering code, and its accomplished with this single line of code:
data[DataGridListData(listData).dataField] = selected;
This line uses the listData property (defined by IDropInListItemRenderer) to locate and update the specific piece of data this CheckBox is rendering in our DataGrid.
The CenteredCheckBoxHeaderRender class is pretty similar to my previous version in that it still implements IFactory and has to be implemented as a ClassFactory instance. For details on using ClassFactory see the previous post referenced above. The main differences this time around are that the class is defined in ActionScript rather than MXML and streamlines things by using the built-in clickHandler function. Below is the portion of the class we will discuss further.
public var stateHost:Object;
public var stateProperty:String;
// set selected state based on external property
override public function set data(value:Object):void
{
selected = stateHost[stateProperty];
}
// toggle external property on click
override protected function clickHandler(event:MouseEvent):void
{
super.clickHandler(event);
stateHost[stateProperty] = selected;
}
As discussed in the previous post, headerRenderers get initialized repeatedly during their existence. This means that we are unable to store any kind of state for them inside themselves because it will get reset over and over again. To work around this we define the stateHost and stateProperty variables which will be assigned via the properties property of ClassFactory. (Again, see previous post for a more thorough explanation of ClassFactory.) In our example application we point these to a selectAllFlag variable (the stateProperty) defined in the main application (the stateHost property). The overridden data setter shown above then uses this external value to set the selected state of our component. Correspondingly, clickHandler sets this value when our CheckBox is clicked, saving our state out to a safe, external location.
Two minor things to mention about our application are a couple of attributes set on the DataGridColumn that our renderers live in. First, notice that we set a dataField attribute like usual. This is required for our new itemRenderer class to work properly, whereas it was not needed when using ClassFactory for both the headerRenderer and itemRenderer. The second important point is that we have set the column's sortable attribute to false. This is necessary in order to ensure clicks in the header are processed as CheckBox clicks and not sorting actions. Also note that we process the header click and set the item values in the main file. While it would be possible to do this inside the header renderer class leaving it outside makes the renderer that much more flexible.
Hopefully this all makes sense, is not too long winded and provides renderers that others can and will use in future projects. Please post questions, complaints and comments in the... well... comments.
CellularDataGrid for Flex 2
A DataGrid that supports highlighting and selection on a cellular level (as opposed to row level like the default) is a fairly common request/topic. While I realize people have done this before and this is supported out of the box by Flex 3 (sort of, see first comment below) I decided to give it a shot during some down time yesterday. I was pretty amazed at how easy it was. Even in my newline-happy code format the component is only 55 lines. The results of about 2 hours of fiddling can been seen and downloaded by following the link below.
View CellularDataGrid (Right click for source)
Hopefully someone finds this useful and/or interesting. If nothing else it should serve as an example of why diving into the framework and getting your tweak on is a worthwhile activity.
Update: Thanks to Tom's suggestion, the problem with the selection indicator not disappearing correctly when selecting a cell in the same row is now fixed. The example and source have been updated.