Friday, April 6, 2007

metadata.Exclude

From Gordon Smith of Adobe:
"Use [Exclude] metadata to exclude properties, methods, events, styles, or effects that don't apply to the subclass."

However, this seems to only apply to the MXML designer. If you look at the source code in the mx package, all excluded functions and properties are also overridden to do nothing so that actionscript code can't use them and the asdoc tags are marked as private so they don't show up in the docs.
The exclude tag only applies to what is inherited, so if an excluded function/variable is extended, then the exclude tag will not stop that newly redefined variable to be propagated to it's decedents. The exclude tag will need to be redeclared in a decedent to reinstate the exclusion. The "direction" property in Box, HBox and GridItem is a good example of this.

mx.containers.GridItem, which extends HBox, appears to have an example of each kind. Here's an example for each "kind" from GridItem.

[Exclude(name="direction", kind="property")]
[Exclude(name="setFocus", kind="method")]
[Exclude(name="focusIn", kind="event")] // notice this references the event type FocusEvent.FOCUS_IN
[Exclude(name="horizontalGap", kind="style")]
[Exclude(name="focusInEffect", kind="effect")]


Documentation relating to ASDocs can be found here.

2 comments:

Sid Maskit said...

Although everything said above seems correct, I found it a bit confusing. Based on some testing, here is my understanding of how the Exclude metadata tag works, at least for properties (I haven't tested anything else).

Let's say that we have a custom component in the file MyComponent.mxml, and within MyComponent.mxml, we have something like

<mx:Metadata>
[Exclude(name="alpha", kind="property")]
</mx:Metadata>

Then within another MXML component, we instantiate our custom component as follows:

<myNamespace:MyComponent id="myComponent" />

Because of the Exclude tag set for the alpha property, we will not be able to have an alpha attribute within the above tag declaring MyComponent.

However, that is the only thing limited by the exclude tag. We will still be able to access the alpha property of the myComponent object, both for setting and getting by ActionScript, and for binding within another MXML tag.

Sid Maskit said...

Quick follow-up. It turns out that the Exclude metadata tag does even less than I thought it does. All it does is make it so the excluded property will not show up in the code hinting list. You can still use the property, even within the tag declaring that component that it is a property of. So, continuing the example from my previous comments, it will work just fine to do the following:

<myNamespace:MyComponent id=”myComponent” alpha=“ 0.5” />

Gordon actually says this in his original post, but I did not understand what he meant.

"Flex", "ActionScript" and possibly "MXML" are probably trademarks of Adobe Systems Incorporated.
"Adobe" is a trademark of Adobe Systems Incorporated.
This site is in no way endorsed or sponsored by Adobe Systems Incorporated.
Content Copyright © 2007 Daniel Freiman.
Site Design Copyright by its copyright holder.
The Flex Non-Docs reserves the right to remove comments for any reason.
All ActionScript and MXML code (and ONLY ActionScript and MXML code) on this website is available under the MIT License.