[royale-asjs.wiki] branch master updated: Updated Emulation Components (markdown)

[ah...@apache.org]

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 <ah...@apache.org>
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
aharui@apache.org.