Determining a Flex event's default behavior

Question

How can I tell what the default behavior for a cancelable event is?

For example, I read somewhere that the TextEvent.TEXT_INPUT has a default behavior and that default behavior includes adding a text character associated with the key that was pressed to a TextInput. That makes perfect sense.

But if I hadn't read that, how would I know what the default behavior is? Other than guessing. In this case, it's probably obvious. But in other situations, it might not be.

For example, in the docs, look at DataGridEvent.HEADER_RELEASE's cancelable property. It says:

cancelable: true

so, there appears to be a "default behavior" associated with a DataGridEvent.HEADER_RELEASE event. But what is it? And why would I cancel it if I'm not really sure what it is? :)

thanks.

Answer 1

It's all in the documentation, which says: "The DataGrid control has a default handler for this event that implements a single-column sort."

The live docs a pretty thorough. If you keep following the links you'll usually find what you are looking for.

Answer 2

Here's what I think to be true -

To cancel the default behavior associated with an event, 2 things must be true:

1. The event must be marked as cancelable (you can check the event's cancelable property to determine this). If you are dispatching the event yourself, set the 3rd parameter to true to mark the event as cancelable. If the event is marked as cancelable, calling event.preventDefault() will set the event to "cancelled" and a query of event.isDefaultPrevented() will return true. If the event is NOT marked as cancelable, calling event.preventDefault() will do nothing at all. A query of event.isDefaultPrevented() will always return false no matter how many times you call event.preventDefault().

2. The event handler registered for the event must actually have the ability to do nothing (i.e. prevent the default behavior associated with the event). So the handler must have something like this in it:

   if (!event.isDefaultPrevented()) { doSomething(); }

So, that still leaves me with the question - "For a cancelable event of type X, what is the default behavior?"

I guess that depends on the target of the event. For example, the target of a DataGridEvent.HEADER_RELEASE event is a DataGrid and inside the DataGrid class you'll find this in the constructor:

addEventListener(DataGridEvent.HEADER_RELEASE,
                     headerReleaseHandler,
                     false, EventPriority.DEFAULT_HANDLER);

and the handler looks like this:

private function headerReleaseHandler(event:DataGridEvent):void
{
    if (!event.isDefaultPrevented())
    {
        manualSort = true;
        sortByColumn(event.columnIndex);
        manualSort = false;
    }
}

Or, you can poke around aimlessly in the docs forever and maybe stumble on the answer like this:

http://livedocs.adobe.com/flex/3/langref/mx/controls/DataGrid.html#event%3aheaderRelease

"The DataGrid control has a default handler for this event that implements a single-column sort"

Hopefully, this answer helps reduce the aimlessness of your doc search.

Jeremy