Halo Style Metadata

Problem Description

The Halo components have a bunch of Style metadata that does not apply to the new Spark skins. For example, Button has metadata for cornerRadius, and fillColor styles, but setting them has no effect on the appearance of the button when using the new default Spark skins.

A related problem is that we currently have to put styles for visual information directly on components. So the problem we're having now with halo styles not being in spark skins will be revisited in a future release when we have a new theme for which the spark components' styles are not appropriate. Ideally, we will find a solution that allows us to separate visual styles from components, in the same way that skins separate the view of the component from the functionality of it.

Decision

Complete this section when a decision has been made and approved

Decision Criteria

Any new syntax should not affect use of Halo components
An ideal solution would be forward-compatible, so that changes in themes/skins/styles in the future would not affect our current spark components in the way that the halo components are now affected by this problem
Although the ideal solution should not be affected by scheduling issues, we need to realistically account for what could be done now to provide adequate functionality for Flex 4.

Proposed Solution(s):

0. Enhance ASDocs

Add verbiage to all style metadata asdocs to incidate which theme(s) pay attention to that style. Code-hinting would not help and hand-coders could still get into trouble (or mysterious situations that they didn't get any feedback on), but at least with tool support of showing ASDocs automatically for attributes on tags the developer would have a chance to see the theme information.

Example:
The following sentence would be the first sentence for every style that is unsupported in the Spark theme:
"This style only applies when the Halo theme is used."

0b. Enhance Style Metadata

Add 'theme' attribute to metadata tag, allowing the style to be tagged as theme-specific. This would cause our docs to issue a standard sentence at the top of the ASDocs, and would cause FB to do the same for its displayed ASDocs.

Example:
[Style(name="backgroundAlpha", type="Number", inherit="no", theme="halo")]

This would result in something like the following docs being displayed in the ASDocs and in the tool:
This style is specific to the halo theme.

1. Remove from ASDoc

Remove the ASDoc comments from the halo-specific styles so they are no longer documented. The styles will still be valid to set, and still appear in code hints.

1b. Remove from ASDoc and code hints

This adds on to solution 1 by having the tool look at metadata and/or ASDoc comments to determine whether or not to show code hints for the halo-specific styles. Details still need to be worked out.

2. Deprecate the styles

Does the deprecation mechanism work for styles?

3. New syntax for spark component styles

For example:

    <s:Button style="color:red"/>

Notes:

Meeting notes, 3/25/09:

Notes on each of items 1, 2, and 3 above:

1 and 1b) Remove from ASDocs and possibly from code hints
1 and 1b are considered too weak to be of real use. It would still be possible for developers to do the wrong thing. Also, it doesn't fix the problem of having theme-specific styles on components that we would have to live with for future generations of Spark components.
1b has the added problem that we do not currently have a mechanism for detecting theme-specific versioning information. That is, the tool could provide adequate hinting when the developer was programming Flex 3 versioned applications, but not when programming Flex4 but with the Halo theme selected.

2 Use deprecation
Question: Can deprecation work with styles? If not, how big is the work item?
2 may be adequate for now, but does not address the future-compatibility problem and continues to tie our visual styles into our components.
work items:

figure out whether deprecation would work with styles, or how much work it would be to make it do so
add deprecation metadata where needed (same places as ASDocs updates that would be needed for #3)
figure out whether deprecation could be theme-specific

Note: What about the plethora of deprecation warnings for those developers writing Flex 3 applications using Flex 4 SDK/compiler?

Pros:

simpler than the ideal solution (#3)
Deprecation warnings in inappropriate situations (Flex3 development using Flex4 sdk)

Cons:

doesn't remove the core problem of visual styles as part of core spark components

3) Use new syntax for setting styles on components
Leading contender: match HTML syntax
This is the 'ideal' solution because we could leave the styles there on Halo components but remove them for Spark components.
work items:

update spark components to use new 'style' property
update halo components to use new 'style' property (but would also leave old style metadata)
document which styles are used with which theme
supplement ASDocs to help developers figure out what's going to work
work to parse style string in either the compiler or the runtime
tools would need to provide code-hinting to help construct the style String

Notes:

Tools probably couldn't handle this work in Flex 4, so no code hinting. This means that anyone using the new mechanism is on their own for setting styles. Also, the design surface will most likely not reflect styles set
Since we have to handle the old Halo mode, it would still be possible for developers to set styles on Halo components that were not valid in the spark theme
Might need some deprecation mechanism also (#2) to avoid problems

Pros:

Better direction for the APIs: removes the visual styles from the new components before it's too late
styling more flexible in the future, better for theme developers

Cons:

Setting styles inline in MXML less obvious than it is today (especially without code hinting). On the other hand, it is more transparent what is happening ('color' is a style, not a property)
Developers on their own for inline styling in Flex 4

Meeting Notes from ARB, 3/27/09

New proposal 0 to just enhance ASDocs to indicate which theme(s) any particular style is appropriate for.

Without the code hinting support for the 'ideal' solution, it's a not-starter; we would be forcing users to use a non-obvious mechanism of setting styles until we actually made tooling work. This forced us to reconsider proposals 0 and 1 as the recommended solution.

Meeting Notes 4/2/09

We had already killed off 1 and 1b as being insufficient.

3 was killed in ARB because we do not have the time to do it right.

So we are down to 0 or 2.

2 seems inadequate because deprecation is a heavy hammer and doesn't convey the right meaning when the appropriateness of the style is specific to the theme in use. That is, the user may have a very valid reason for using Halo, and we will support that usage. But we will also say at the same time that the Halo styles are deprecated.
We decided that we should perhaps wait to deprecate these until we are ready to deprecate Halo overall.

0 seems like the right approach here. But a tweak was added to it: could/should we add a 'theme' tag to the style metadata and have docs and FB automatically generate the right ASDocs info? Or do we take the simpler approach of just copying and pasting the same sentence into all appropriate ASDocs in the framework. It's mostly a question of work: is it faster to just implement the tag code or to copy/paste everywhere?

Discuss the tradeoff above in ARB tomorrow.

Meeting Notes from ARB, 4/3/09

Since the extra metadata 'theme' attribute didn't seem like that much work for docs or FB to support (at least in the minimal way we intend for Flex4 - just being able to parse the attribute and emit standard docs based on the value), most people felt we should go with that solution.

Next step: lay out the work items and get management approval