Adding hints to Flex 3 MXML tags

ColdFusion tags can be annotated with the hint attribute, effectively creating a surrogate for single line comments. This is something I’ve wanted to be able to do in MXML for a while, and I’m glad to see the Gumbo specs include this feature in the form of private attributes.  If you can’t wait for Flex 4, you can apply this monkey patch to add hints in your Flex 3 MXML.

For those new to monkey patching, the technique allows you to rewrite classes from the framework or from swcs by defining your own class with the same fully-qualified name. Through the magic of inheritance, any changes to a class will cascade down to its subclasses. To create hints we just need to add a do-nothing public setter method called “hint” somewhere where it will be inherited by the entire SDK.  If we could change the source for Object we’d be done, but we can’t so we’re going to have to patch a couple of files.  Practically every file in the SDK has the line

include "../core/Version.as";

so that’s our best starting point. Create a directory structure for the mx.core package in your main source directory and copy the SDK’s Version.as into that directory. Add the line

public function set hint(value:String):void {}

to the copy. This isn’t going to change anything immediately because the compiled classes are still using the old Version.as, but this step makes the rest of the patch completely painless. To get the change to go through we have to grab a copy of each of the classes we want to add hints to and place them along side the patched Version.as.

Most MXML tags describe components, so grab FlexSprite.as from the SDK source and place it in the same directory as the new Version.as. Without editing FlexSprite.as you can now say

<mx:Panel hint="The compiler is cool with this." />

Sadly, FlexSprite isn’t the base class for everything that can be declared in MXML, so there are a couple of other classes you’ll need to grab if you want hints for them too. A few good candidates for this patch are mx.styles.CSSSytleDeclaration, mx.effects.Effect, and the entire mx.states package. I’m not going to try and patch everything, so if you use this technique and the compiler complains about the absence of the hint property, just grab the source for whatever class needs patching and put it in the patched mx package.

This entry was posted in Flex and tagged , . Bookmark the permalink. Both comments and trackbacks are currently closed.

2 Comments

  1. Posted November 6, 2008 at 2:12 pm | Permalink

    Why can’t you use ASDOC comments for this ?

  2. Posted November 7, 2008 at 12:53 am | Permalink

    ASDOC can only be used within the Script tag in MXML documents. My goal was to document the component/effect/state tags directly since they make up the meat of most MXML files (at least for me).