Digital Primates» flex-actionscript

Making a custom datagrid scrollbar? I hope the width=16…

strict-inequality — Wed, 02 Feb 2011 22:29:16 +0000

Flex has a lot of great facilities for styling and skinning, including custom scrollbars. Unfortunately, I’ve discovered that Flex really wants your vertical scrollbars to be 16 pixels wide. When it isn’t, Flex can make some strange layout decisions when first putting it on screen. for example, check out this (very fancy) datagrid: I made an 8-pixel wide vertical scrollbar, complete with a lovely red and purple coloring, and used it in my datagrid. Obviously, there’s a couple things wrong. First, there’s an ugly white gap between my content and my fancy scrollbar. Second, it looks like the content in my 2nd column has a different left padding than the content in my 1st column. Finally, the header area above the scrollbar didn’t render correctly. To see what kind of scrolling behavior it had, I clicked on my “down arrow”: A couple things sorted themselves out: the 8-pixel white gap is gone, the header looks right, and the content in the last row (Roger McBob) looks proper. As a final test, I sorted the 2nd column and got this: Now all the content looks properly placed. So what the heck is going on here? This bad behavior can be traced back to ScrollControlBase.as, in setScrollBarProperties() and createVScrollBar(). setScrollBarProperties() is going to be invoked from DataGrid’s updateDisplayList(). What we’re really interested in is whether the content area (for the first and last names) has changed size, which is tracked in the class variable scrollAreaChanged. If that scroll area has changed, then setScrollBarProperties() is going to call updateDisplayList(). What’s that? Aren’t we already in a call to updateDisplayList(), and isn’t that call going to re-execute DataGrid.updateDisplayList() and get us right back in here? Yes. Yes it will. The other thing that setScrollBarProperties() is doing is deciding whether or not it needs to create or destroy scrollbars. For the situation I’ve created, it will need to create a vertical scrollbar. And it does so with a call to createVScrollBar(). That new scrollbar, before its measure() can get called, is going to report a width of 16, which is the default. And that value will be used to determine not only the overall content area (c.f. that ugly white gap), but also how the content therein is placed (c.f. the 2nd column content being off a few pixels). It’s going to do all this before we can actually measure the scrollbar, even when we re-enter the method. It’s not until we start interacting with the control (scrolling, sorting) that we get back into setScrollBarProperties() after the scrollbar has finally been measured. As we can see, it then starts laying out properly. It’s great that the framework handles getting us back into that method, but I can’t help thinking that it would be better served through an invalidation cycle, rather than a recursive call. If that happened, we’d go through a proper measure cycle and the content area would be sized correctly without having to touch the control. Funnily enough, in createVScrollBar() (I’m looking at the Flex SDK 3.5 here), there’s this code:

//need verticalScrollBar.validateNow()?

Given the way the code is written now, I’d say the answer is yes. That would force a measure and our datagrid would render correctly the first time. Maybe that should have been explored more before simply commenting it out.

Datagrid item editors and dynamic behavior (part 3/3)

strict-inequality — Wed, 12 Mar 2008 04:37:57 +0000

we’re ready to wrap up our functionality now. in part 1, we defined our problem (validated error reporting in a datagrid cell, plus dynamic validation characteristics) and made a first attempt at a solution. in part 2, we improved our error handling in the cells. now, in part 3, we’ll expand our validation logic beyond valid numbers to range checking based on other XML data in the row. this will fulfill our task of creating item editors with dynamic behavior. first, we’ll change our WeightEditor to define the ranges and accept a 2nd parameter in its validate() method. this parameter specifies the weight class against which we want to validate. its value will come from the row, and our custom ITEM_EDIT_END handler will be able to access it. here’s our new method signature:

public function validate(value:String,
weightClass:String) : String

in our handler, the old code looked like this:

var editor:WeightEditor2 = WeightEditor2
(weigh_in.itemEditorInstance);

var userEnteredValue:String = editor.text;

var errorMsg:String = editor.validate
(userEnteredValue);

and the new code is this:

var weightClass:String = event.itemRenderer.data.weightClass;
var editor:WeightEditor3 = WeightEditor3(weigh_in.itemEditorInstance);
var userEnteredValue:String = editor.text;
var errorMsg:String = editor.validate(userEnteredValue, weightClass);

note that our handler doesn’t do anything with the weightClass value except hand it to the validation method. our itemEditor and handler are fairly coupled to each other, but at least we’ve kept the validation logic in the editor and not spread it across both places. the handler logic is the same: if we fail our (now improved) validation, we’ll prevent the datagrid from moving out of the cell and allow the user to enter another value. here’s the code for the new item editor, WeightEditor3.mxml:


http://www.adobe.com/2006/mxml">

 // no need to validate here, since we don't act upon it. but if we did  // need to validate to make some kind of decision, then we'll end up  // validating twice.
return value;
}
/**
* This is our validation method. We pass validation if the user has
* entered a non-negative decimal. This is a public function so that we can
* re-use this validation outside of the editor.
*
* @param value         The user-entered value
* @param weightClass   From the XML, the weight class of this particular wrestler
*
* @return null if we pass validation, otherwise we return the error string
*/
public function validate(value:String, weightClass:String) : String
{
var validator:NumberValidator = new NumberValidator();
validator.allowNegative = false;
validator.required = false;
var result:ValidationResultEvent = validator.validate(value);
if (result.type != ValidationResultEvent.VALID)
return result.message;
var errorMsg:String = validateWeightClass(value, weightClass);
return errorMsg;
}
/**
* This is a validation helper method. It checks to ensure the entered weight
* is within range. The weight can be equal on the low end but must be lower than
* the high end.
*
* @param value         The user-entered value
* @param weightClass   From the XML, the weight class of this particular wrestler
*
* @return null if we pass validation, otherwise we return the error string
*/
protected function validateWeightClass(value:String, weightClass:String) : String
{
var lowWeight:Number = 0;
var highWeight:Number = 1000;
switch (weightClass)
{
case 'A' :
lowWeight = A_LOW;
highWeight = A_HIGH;
break;
case 'B' :
lowWeight = B_LOW;
highWeight = B_HIGH;
break;
case 'C' :
lowWeight = C_LOW;
highWeight = C_HIGH;
break;
case 'D' :
lowWeight = D_LOW;
highWeight = D_HIGH;
break;
default:
break;
}
var weight:Number = Number(value);
if ((weight >= lowWeight) && (weight < highWeight))
return null;
var errorMsg:String = "This wrestler's weight is out of his weight class. His weight must be between "
+ lowWeight + ' and ' + highWeight + ' pounds.';
return errorMsg;
}
]]>

click on the image to run the final app. test the new validation by entering valid numbers which are outside the weight range.

Datagrid item editors and dynamic behavior (part 2/3)

strict-inequality — Mon, 03 Mar 2008 19:09:52 +0000

picking up from where we left off in part one, now we want to to improve our user notification when they enter a bad value in our datagrid. previously, we jumped out of the cell and left it blank. ideally, we want our cell, whose itemEditor is a derived class of TextInput, to behave like a TextInput with bad data. i.e. we would like a red border and an errortip.to get this behavior, we must have an understanding of how DataGrid works with regard to item editors and how to short-circuit its default behavior. by default, once you leave a datagrid cell, the DataGrid destroys the item editor and looks for the next cell to edit. this is why we got the “leave the cell” behavior in our first iteration. when a user leaves a datagrid cell, which dispatches the ITEM_EDIT_END event, the DataGrid invokes its handler method: itemEditorItemEditEndHandler. if the user has not canceled the edit, that method pulls the data out of the item editor (based on the value of editorDataField), puts the value in the cell, and under normal circumstances destroys the itemEditor. what we want to do is call our own handler when we get the ITEM_EDIT_END event. we do this by specifying a value for the itemEditEnd property on our DataGrid, like this: when our handler is called, we need to decide whether or not the value is good. if it is, we’ll simply exit and let the framework handle the rest (putting the value into the cell, destroying the item editor, and finding the next cell to edit). if the value is bad, however, we need to prevent that default behavior, by calling the preventDefault() method on the DataGridEvent passed to our handler: event.preventDefault(); though the DataGrid’s ITEM_EDIT_END handler is still invoked, this prevents the DataGrid from leaving the cell. however, it still destroys the item editor, so we need to be sure we’re done with the item editor before that happens. a moment ago, i said that we needed to take action if our value is no good. how do we know if it’s good or not? what would be ideal is if our item editor could somehow indicate that to the framework so that our event could tell us (a ‘valid’ flag, perhaps?), but there’s no framework support for that. so i did something rather ugly but necessary: i made the validate() method in our itemEditor public so that it could be invoked from our custom handler. and then i did something even uglier: i overloaded the return of that validation method to return the error string if it’s in error, and a null otherwise. in general, i’m not at all a fan of overloading a return type for such double meaning, but it seemed to be the most straightforward way of getting done what was needed without making multiple changes to the framework to support a more elegant solution. so our approach in the handler is to grab a reference to our itemEditor and invoke its validation method from there. that will give us the information we need to determine if we need to stay in our cell our move on to the next. here is our handler:

protected function processEditedItem(event:DataGridEvent) : void
{
if (event.reason == DataGridEventReason.CANCELLED)
return;
if (event.dataField != 'weight')
return;
 // we need a reference to our style of item editor so we can call  // its validation method.
var editor:WeightEditor2 = WeightEditor2(weigh_in.itemEditorInstance);
var userEnteredValue:String = editor.text;
var errorMsg:String = editor.validate(userEnteredValue);
 // if we didn't validate, we'll set our errorString and call preventDefault()  // so the datagrid knows to keep us in the same cell
if (errorMsg)
{
editor.errorString = errorMsg;
event.preventDefault();
}
}

we want to bug out straightaway if the user has canceled the edit (by hitting escape) or if our handler was called for a column in which we’re not interested. in both cases, the framework will handle the work. otherwise, we’ll grab a reference to our itemEditor, call its validation method with the data the user entered, and if we get back an error string from the validator, we’ll use that as the error tip and call preventDefault. here’s the code: wresting2.mxml


http://www.adobe.com/2006/mxml" layout="vertical" >

// we need a reference to our style of item editor so we can call  // its validation method.
var editor:WeightEditor2 = WeightEditor2(weigh_in.itemEditorInstance);
var userEnteredValue:String = editor.text;
var errorMsg:String = editor.validate(userEnteredValue);
// if we didn't validate, we'll set our errorString and call preventDefault()  // so the datagrid knows to keep us in the same cell
if (errorMsg)
{
editor.errorString = errorMsg;
event.preventDefault();
}
}
]]>



 Bob Smith 
 A 
 


 Tim McLarry 
 B 
 


 Joe Doug 
 C 
 


 Larry McTim 
 D

WeightEditor2.mxml:


http://www.adobe.com/2006/mxml">

 // no need to validate here, since we don't act upon it. but if we did  // need to validate to make some kind of decision, then we'll end up  // validating twice.
return value;
}
/**
* This is our validation method. We pass validation if the user has
* entered a non-negative decimal. This is a public function so that we can
* re-use this validation outside of the editor.
*
* @param value   The user-entered value
* @return null if we pass validation, otherwise we return the error string
*/
public function validate(value:String) : String
{
var validator:NumberValidator = new NumberValidator();
validator.allowNegative = false;
validator.required = false;
var result:ValidationResultEvent = validator.validate(value);
if (result.type != ValidationResultEvent.VALID)
return result.message;
return null;
}
]]>

you’ll notice that i introduced a label function on the weight column. that’s there to handle formatting numbers. for example, if the user entered 000122, we’ll display that as 122. for part 3, all we’ve got left is to change our validation so that we’ll flag an error if the entered weight is out-of-range of the weight class. click on the image to run the new app. to see the error behavior, enter a non-number such as 5.5.5. NOTE: there is a bug in flex2 DataGrid so that the behavior of the last cell is incorrect. if you enter a bad value in the last cell of the weight column and tab out, the value will disappear. if you hit enter, though, we’ll stay in the cell as expected. it seems this is fixed in flex 3.

Datagrid item editors and dynamic behavior (part 1/3)

strict-inequality — Wed, 27 Feb 2008 02:56:38 +0000

though a lot of validation functionality is available in mxml through validators, i’ve always found it curious that Datagrid seems to be a bit short-changed. for example, in mxml, i can create a TextInput and give it the ability to accept ranges of numbers, through both the restrict property and assigning it a NumberValidator, but how do we do the same in a Datagrid cell? further, what happens when we want to dynamically process cell contents based on other data in the same row? Adobe has a primer here: http://www.adobe.com/devnet/flex/quickstart/creating_item_editors/ … with help on creating different kinds of item editors. but whenever they give an example of a cell into which you’re meant to enter numbers, they use a NumericStepper. and that’s great, but maybe i don’t always want to use a NumericStepper in my interface. maybe i want to use a TextInput component, just like the rest of the cells. further, we still haven’t addressed the kinds of dynamic behavior i mentioned above. so what’s the solution? using the approach on that Adobe page called ‘Using a component as an item editor’, and by delving into a little bit of ActionScript, we can make ourselves a TextInput item editor that can do everything we need. i’m dividing this topic into 3 posts so we can build to our eventual solution. let’s take an example: say you’re building an app for your local high school’s wrestling team. you’ve already written the part of the app to pre-register wrestlers and now you’re working on the screen for weigh-in at the meet. when wrestlers pre-register, they enter their names and respective weight classes. on the day of the meet, you want your weigh-in screen to flag an error to the user that a wrestler is out of his weight class. let’s take a first stab at some prototype code. here’s the mxml you’ve written for the weigh-in app (called wrestling.mxml):





 Bob Smith 
 A 
 


 Tim McLarry 
 B 
 


 Joe Doug 
 C 
 


 Larry McTim 
 D

pretty straightfoward. we’ve got a Datagrid with 3 columns, some test XML to fill in the name and weight class, and a small form letting us know the weight class ranges (which i made up, and likely has no bearing on any realworld scenario). we’ve also referenced a WeightEditor.mxml, which is this code:


http://www.adobe.com/2006/mxml">

this code is more interesting. first, note that we’ve derived this item editor from TextInput, so it should behave more like the other cells than, say, a NumericStepper would. second, you’ll notice that we set the restrict property straightaway, so we see an immediate benefit that the user can enter only numbers, periods and commas in this field. we override the data method here to return what the user entered if it’s a number. if it’s not a number (e.g. 5.5.5..5), we’ll return nothing. why is the method called ‘data’? because that’s the value we specified in the editorDataField in the weight column in the wrestling.mxml file. it doesn’t have to be called ‘data’, you can call it whatever you’d like. but because ‘data’ exists and is considered the default, we have to specify that we’re overriding it. this is a decent first step, but doesn’t exhibit terribly useful behavior. first, if the user enters something that isn’t a number, the cell erases itself. good for avoiding keeping bad values around, not so good for the user experience. this is something we want to keep in mind for our next iteration. also note that we haven’t honored, at all, the weight class. we’ll also fix this in a later iteration, and it would be nice if we could provide some meaningful user feedback for what went wrong. we’ll address user notification in part 2. (click on the image to run the app)