This is an automated email from the ASF dual-hosted git repository.
aharui pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-asjs.wiki.git
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 <[email protected]>
AuthorDate: Tue May 29 22:25:27 2018 -0700
Updated Emulation Components (markdown)
---
Emulation-Components.md | 36 +++++++++++++++++++++++++++++++++++-
1 file changed, 35 insertions(+), 1 deletion(-)
diff --git a/Emulation-Components.md b/Emulation-Components.md
index b91d21b..616d637 100644
--- a/Emulation-Components.md
+++ b/Emulation-Components.md
@@ -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 work.
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
[email protected].
