Introduction

In Current builds of Gumbo, we avoid all naming collisions in our classes by prefixing any duplicate named classes introduced by Gumbo with the Fx prefix.  THe community has spoken out loudly against this, and we need to drop the Fx prefix.  Dropping the prefix introduces some technical problems (duplicate classes in the same package, duplicate classes in the MXML namespace), and some usability problems (confusion between the 'old' Button and the 'new' Button).  Both of these problems will need to be solved via a reorganization and renaming of our classes and packages.

This document discusses proposed changes in three sections:

• Section 1:  new namespace organization
• Section 2:  Top Level Package Organization for the new Gumbo classes
• Section 3:  enumerate names and packages for all new Gumbo classes. Most changes will be due to removing the Fx Prefix, but some additional usability changes will be included as well.
• Appendix: Detailed list of classes in each namespace.

New Namespace Organization

In addition to reorganizing packages, the newly overlapping component and effect names will require us to split the 2009 MXML namespace to prevent conflicts.

Gumbo will now ship with the following distinct namespaces:

MXML 2006

URI: http://www.adobe.com/2006/mxml
Default Prefix: mx

The legacy mxml language namespace used in previous versions of Flex. This namespace contains:

• language tags
• top level (built-in) types
• halo
• rpc
• data services
• charts

As a language namespace, this namespace affects the way flex parses and compiles MXML. Only one language namespace can be used in an MXML document at a time.

MXML 2009

URI: http://ns.adobe.com/mxml/2009
Default Prefix: fx

The new mxml language namespace introduced as part of Gumbo. This namespace contains:

• language tags
• top level (built-in) types
• new Gumbo language tags

This is purely a language namespace, and does not contain component tags. As a language namespace, this namespace affects the way flex parses and compiles MXML. Only one language namespace can be used in an MXML document at a time.

Spark

URI: library://ns.adobe.com/flex/spark
Default Prefix: s

The new namespace for building spark based applications. This namespace contains:

• rpc
• data services
• spark
• TLF Text Framework

This namespace does not contain language tags, and must be used in conjunction with one of the mxml language namespaces.

Halo

URI: library://ns.adobe.com/flex/halo
Default Prefix: mx

The non-language-version-specific namespace for using halo components and classes in your application. This namespace contains:

• rpc
• data services
• halo
• halo air classes
• charts

This namespace can be used to bring halo components and classes into your spark based applications, or to build halo applications using the new 2009 version of mxml. This namespace does not contain language tags, and must be used in conjunction with one of the mxml language namespaces

Top Level Package Organization

As it stands today

The current packages in the flex 4 project list out like so:

mx.components
mx.core.
mx.effects
mx.events
mx.filters
mx.geom
mx.primitives
mx.layout
mx.skins
mx.states
mx.styles
mx.utils

Some specific notes:

• mx.states:  There is one class in this package, which does not rely on any classes from the flex 4 swc.  It should be moved into the framework project.
• mx.styles:   This folder only exists to hold style metadata.  THe metadata files should be moved to the spark.styles folder, and include files should be updated.
• mx.geom:   This folder is empty, and should be removed.
• mx.components: This is where the Fx components that need to be renamed live.  To date, we've grouped all of our new components into a single 'components' package under the mx namespace so they can be easily discovered.  We have considered splitting this into a separate controls and containers package, as we did in Halo. But in both the previous components ,and the new spark components, the line between controls and containers, esp. for data driven controls, becomes blurry, leaving the distinction meaningless.
• mx.effects:  Many of the new Fx effects introduced into this package will have duplicate names once the Fx prefix is removed, and will need to be moved into a separate package.  Moving them is complicated by the fact that developers will continue to use some of the effects in the mx package (Parallel, Sequence) but can't use all of them (most Halo effects won't work on GraphicElements, for example).
• mx.graphics:  The classes in this package are used heavily in the Gumbo model.  Some of them, however, are legacy classes in mx.graphics that were introduced in Flex 3.  If we choose to move these classes into a separate package, we will have to contend with the fact that core classes must remain in mx.graphics.

 Goals

our package structure should accomplish the following goals:

• avoid duplicate names in the same package between Halo and Gumbo classes.
• clearly lead developers towards the Gumbo classes. This is a complicated one, as there is no simple specific descriptive word that can be used in the package names. 'Skinnable', for example, describes the Spark components, but not the new effects, or layouts, or filters. The goal should not be for a developer to be able to identify these classes as 'better' or 'preferred' simply by looking at the package name, but rather that a developer, who knows they want to use spark, can easily identify the set of classes they should be paying attention to.

Branding (the usability kind, not the corporate kind)

In order to help a developer clearly identify classes in the 'new' framework, we will need to use a generic 'brand' identifier rather than a semantically meaningful name (see above).  Two obvious choices come to mind: fx and spark.  We chose fx as the prefix when we were prefixing class names because it was a good short option for something that customer were going to have to type over and over again.  But fx is part of the flex builder brand, rather than part of the open source flex framework.  Spark, on the other hand, is our 'official' name for the new component architecture and skinning model, so seems a more appropriate choice as the 'brand' used in the various package naming solutions proposed below.

Options

option 1, Minimal Solution:  move spark components and effects into specific sub-packages 

Take the position that spark is an extension of the existing framework, and should feel as much like first class citizens of the framework as any other component or class.  For the most part, we leave the new classes and packages of spark as second level elements of mx.  For the two areas that we have introduced replacement classes for existing parts of the framework -- components, and effects -- we push their packages down into a 'spark' sub-package.

mx.spark.components(...)
mx.core
mx.spark.effects(...)
mx.events
mx.filters
mx.primitives
mx.layout(...)
mx.skins.spark
mx.utils

 pros:  minimal disruption.  avoids most complications around the relationship between core mx framework classes and new spark classes.

cons:  relationship between spark components and the rest of the related classes -- graphics, layout, etc -- isn't clear.  no single package identifies all the 'new' classes.

option 2, grouped sub-package: move all the spark packages into a sub-package of mx, similar to how charts work.

 While spark is a first class part of the Flex framework, it is a constallation of classes meant to be used together.  layouts, graphics, components, and effects are all closely related to each other, and it should be clear to developers that these classes together comprise a library.  Clearly identify that by pushing all the new spark classes down into a second level 'spark' package.

mx.spark.components(...)
mx.spark.effects(...)
mx.spark.events
mx.spark.filters
mx.spark.primitives(...)
mx.spark.layout(...)
mx.spark.skins(...)
mx.spark.utils

 pros: single package (sort of) easily identifies the 'new' framework classes.  Keeps spark grouped under mx.

cons:  demotes 'spark' to a subpackage of the framework, giving mx.controls prominence over mx.spark.controls. Splits tightly coupled classes like graphics and effects classes across two packages. (mx.grpahics and mx.spark.graphics).

option 3, grouped-top level package:  move all the spark classes into a new top level package

Recognize that while spark is a first class part of the Flex framework, the eventual goal is for it to be a top level library that can live almost completely independent of the mx components.  move all of the spark classes into their own top level spark package.

spark.components(...)
spark.core
spark.effects(...)
spark.events
spark.filters
spark.primitives(...)
spark.layout(...)
spark.skins(...)
spark.utils

pros:  spark classes are clearly separated from classic halo components.  spark is given top level prominence on equal footing with mx.

cons:   some logical packages are split across mx. and spark. (i.e., mx.graphics and spark.graphics).

Graphics vs. Primitives

 Either option 2 or 3 gives us a graphics package split across mx.graphics and (mx.)spark.graphics.   Arguably, this will be confusing to developers.   While there are other places spark users will have to dip into the mx hierarchy (especially in this initial release), graphics feels like a coherent package fragmented in two. 

One possible solution would be to leave the stroke and fill classes (from both Flex 3 and Flex 4) in the mx.graphics package, and push all of the new graphic primitive classes into a new 'primitives' package (either mx.spark.primitives, or spark.primitives).

Proposal

Our current working proposal is a variation of Option 3, above. The general packages introduced by Spark will be:

spark.components
spark.core
spark.effects
spark.events
spark.filters
spark.layout
spark.primitives
spark.skins
spark.utils

The complete set of packages are:

spark.components
spark.components.supportClasses
spark.core
spark.effects
spark.effects.animation
spark.effects.easing
spark.effects.supportClasses
spark.effects.interpolation
spark.events
spark.filters
spark.layout
spark.layout.supportClasses
spark.primitives
spark.primitives.supportClasses
spark.skins.haloDefault
spark.skins.default
spark.utils

Class Renaming

Below is the complete table of classes in the Flex4 project, with their target package and class name after the renaming is complete.  Many classes went through unscathed. Where changes were made, they are for one of the following reasons:

• changing the name to remove the FxPrefix
• changing the package to avoid a collision with other classes after removing the FxPrefix.
• reorganizing 'bucket' packages that have aggregated too  many different types of functionality in one place.
• in one or two places, opportunistically fixing names no one likes
• moving base classes out of view when appropriate.

Version 8

Appendix A: detailed namespace contents

This section lists exactly what classes are included in each group used in the namespace descriptions above.

Built in Types

RPC

Data Services

Spark

TLF Text Framework

Halo AIR Classes

Charts

Halo