royale-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [] branch master updated: Updated Emulation Components (markdown)
Date Wed, 30 May 2018 05:25:30 GMT
This is an automated email from the ASF dual-hosted git repository.

aharui pushed a commit to branch master
in repository

The following commit(s) were added to refs/heads/master by this push:
     new d23843d  Updated Emulation Components (markdown)
d23843d is described below

commit d23843d79a8bc0ef4d77cd4264be45fd75483ad5
Author: aharui <>
AuthorDate: Tue May 29 22:25:27 2018 -0700

    Updated Emulation Components (markdown)
--- | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/ b/
index b91d21b..616d637 100644
--- a/
+++ b/
@@ -1,5 +1,12 @@
 The Emulation Components are components designed to emulate, but not guarantee 100% backward-compatibility
with Flex components.  There are two sets right now:  MXRoyale contains emulations of UIComponent
and other MX components.  SparkRoyale will contain emulation of Spark components
+This document has the following sections:
+[Creating An Emulation Component](#creating-an-emulation-component)
+[Getting An Emulation Component to Run](#getting-an-emulation-component-to-run)
+[Finishing An Emulation Component](#finishing-an-emulation-component)
+## Creating An Emulation Component
 The plan is to quickly create classes with stubs for APIs we know our migrating users are
using based on -api-reports sent in by these users.  The current list is at the end of this
page.  The goal is not to try to get every line of code in an existing MX or Spark component
to work in Royale.  Instead, we just want to get the public APIs that are actually used to
 But first, we want to try to get the migrating user's app to compile.  So the process is
to quickly create a class of the same package name and class name as the Flex component and
either copy in Royale APIs (renaming if necessary), copying in the API from the flex-sdk repo
(if it will work as is) or copying in the API from the flex-sdk repo and removing all of the
code and leaving a TODO.
@@ -2203,4 +2210,31 @@ spark.skins.SparkSkin:mxmlContent 	28
 spark.skins.SparkSkin:states 	13
 spark.skins.SparkSkin:updateDisplayList 	45
 spark.skins.SparkSkin:useChromeColor 	18
\ No newline at end of file
+## Getting An Emulation Component To Run
+Once you have finished the stubs for an emulation component, that component should allow
the migration application to compile without errors about that component.  But to get the
component to actually work, you have to implement code for those stubs.  The key principle
for doing that is the use of Composition instead of Inheritance.
+Royale's Basic and Express component sets are comprised of "Top Level Components" hereafter
abbreviated as TLCs.  These are the components that most folks reference in their applications,
such as Label, TextInput, ComboBox, HBox, VBox, Group, etc.  Even Application.  But unlike
Flex TLCs of the same or similar name which are subclasses of UIComponent or something else
and the method bodies are full of code that you commented out to create the Emulation Component,
Royale TLCs are composed [...]
+It is important for Emulation Components that are UI components to subclass mx.core.UIComponent
or one of its subclasses because we need to emulate the class hierarchy of the Flex components.
 That is more important than trying to re-use code by subclassing a Basic or Express component,
so Emulation Components that are UI TLCs should not subclass an Basic or Express component.
+But, if there is little code in the Basic or Express version of a component, then getting
the Emulation Component to run should be as simple as:
+1) copying the little bits of code from the Basic or Express version into the right stub
in the Emulation Component
+2) copying the CSS from Basic or Express defaults.css into the MXRoyale or SparkRoyale defaults.css
+Those two steps should "re-compose" the Basic/Express beads onto the Emulation strand and
it should "just work".  If you are lucky it will but odds are that it won't.  There are often
unexpected assumptions made in the beads about what kind of strand they are on.  These are
bugs and should be fixed in the Basic/Express beads.  But sometimes you will be better off
subclassing the Basic/Express bead in the MXRoyale or MXSpark package and overriding or adding
something, especially if you ha [...]
+So far, the mx:Button, mx:CheckBox, mx:RadioButton, mx:TextInput, mx:TextArea, mx:ComboBox
and s:Button have been made to put something up on the screen in both SWF and JS output. 
You can look at the GitHub history and see what changes were needed to get them to run.
+## Finishing An Emulation Component
+The current set of running components are not finished.  They do not appear on the screen
at roughly the same size and appearance as the Flex components.  We may not bother matching
the appearance pixel-for-pixel and we may not match sizes exactly, but we do want the UI controls
to be in the same places such that scrollbars aren't forced to appear.
+We haven't finished any component yet.  As we do so and better understand good practices
for doing so, we will update this section.  But first, we want to see if we can get a migrated
app to launch and put something up on the screen without any exceptions being thrown.

To stop receiving notification emails like this one, please contact

View raw message