Merge pull request #21 from cheekiatng/timob-20602

[TIMOB-20602] Hyperloop: Build doesn't work with 5.4.0

modules/android/hyperloop/1.1.2/documentation/android.html

@@ -0,0 +1,100 @@
+<h1>Hyperloop for Android Programming Guide</h1>
+<blockquote>
+<p>This documentation is made available before final release and is subject to change without notice and comes with no warranty express or implied.</p>
+</blockquote>
+<h2>Requirements</h2>
+<p>You'll need to have the following minimum requirements to use Hyperloop for Android:</p>
+<ul>
+<li>Titanium 5.4.0</li>
+<li>Android 2.3.3+ SDK</li>
+</ul>
+<h2>Pre-release Installation</h2>
+<p>For pre-release, you'll need to update to the latest unreleased version of Titanium 5.4.0 by running <code>ti sdk install -b master -d</code>.  Make sure you set the version of your application to use this version in your <code>tiapp.xml</code> <code>&lt;sdk-version&gt;</code>.</p>
+<h2>Classes</h2>
+<h3>Overview</h3>
+<p>Classes in Hyperloop map to the underlying classes defined in Java.  For example, if you have a class such as <code>android.view.View</code> defined, you would reference it using a standard require such as:</p>
+<p><code>javascript
+var View = require('android.view.View');</code></p>
+<p>This will return the <code>View</code> class object.  Meaning, it's not an instance of a <code>View</code>, but the <code>View</code> class itself.</p>
+<p>Once you have a the Class reference returned from <code>require</code>, you can call normal JavaScript property and functions against it. Remember, at this point calling functions or properties against the class object above will be accessing Class level (static) Java methods (not instance level).</p>
+<p>For example, you could get the generated view id of the <code>View</code> using the example:</p>
+<p><code>javascript
+var generatedId = View.generateViewId();</code></p>
+<p>This is because <a href="http://developer.android.com/reference/android/view/View.html#generateViewId()"><code>generateViewId</code></a> is defined as a static method.</p>
+<h3>Instantiation</h3>
+<p>To instantiate a native Class and create an instance, you can use <code>new</code> just as you normally do in Javascript or Java:</p>
+<p><code>javascript
+var view = new View(activity);</code></p>
+<h3>Methods and Fields</h3>
+<p>Methods in Java are mapped to JavaScript functions. Fields in Java are mapped to JavaScript property accessors. static methods or fields (such as constants) will be attached to the class type.</p>
+<p>For example:</p>
+<p><code>java
+public class Example {
+    public int field;
+    public static final String staticString = "";
+    public void method(int argument);
+    public static boolean staticMethod();
+}</code></p>
+<p>Would map to the following in JavaScript:</p>
+<p><code>javascript
+example.field = 123;
+Example.staticString;
+example.method(567);
+var result = Example.staticMethod();</code></p>
+<h4>Method resolution</h4>
+<p>If a class has overloads for a method (multiple forms of the method with different signatures, but the same name), we will attempt to match the correct method to invoke on the Java side by matching the passed in arguments to the closest match. Typically, this involves matching the name, number of arguments and the ability to convert the passed in arguments (in-order) to the method's parameter types. We are slightly more liberal in accepting numeric primitives than typical method resolution due to the conversion of JS Numbers.</p>
+<h3>Casting</h3>
+<p>Sometimes interfaces and classes define generic return types such as <code>Object</code>, or declare they return or accept a super type but you know the actual received/passed type will be a subclass of it - and you will need to cast them to a different type to then reference methods and properties of the more specific subclass.</p>
+<p>For example, suppose the result of the function returned an <code>android.view.ViewGroup.LayoutParams</code> but you know the implementation is actually a <code>android.widget.FrameLayout.LayoutParams</code>. You could use the following:</p>
+<p><code>javascript
+var params = view.getLayoutParams();
+params = FrameLayoutParams.cast(params);
+params.leftMargin = 100;
+params.topMargin = 50;</code></p>
+<p><strong>Be careful with casting:</strong>  If you cast an object which is actually something different, you will experience an error and likely a crash.</p>
+<h4>Converting Titanium proxies</h4>
+<p>You can also convert a Titanium UI Component into its equivalent by passing the titanium proxy into the equivalent UI class' constructor.  For example, this would work:</p>
+<p><code>javascript
+var tiView = Ti.UI.createView( { backgroundColor : "red" } );
+var nativeView = new View(tiView);
+console.log('X (relative to parent): ', nativeView.getLeft());</code></p>
+<h3>Interfaces</h3>
+<p>Interfaces may be implemented using a Javascript syntax similar to an anonymous Java class. Call the constructor of the interface type with a JS object that contains the overriding method implementations with properties that match the interface method names, and corresponding values as the function that implements that method.</p>
+<p>For example, to create an instance that implements <code>android.view.View.OnTouchListener</code>:</p>
+<p><code>javascript
+var OnTouchListener = require('android.view.View.OnTouchListener'),
+    listener = new OnTouchListener({
+        onTouch: function(v, event) {
+            // Do some work here
+            return true;
+        }
+    });</code></p>
+<h3>Creating your own classes</h3>
+<p>Hyperloop provides you the ability to dynamically create your own Java classes at runtime.  Once created, these classes can be used as normal in either Hyperloop or passed to native calls. We generate the custom subclass using the "extend" function of the type we want to extend, which takes a single JS Object as an argument containing the overriding method implementations (same as we did for interface implementations). The returned value is a new class type that subclasses the extended type. We can then use the constructor to generate instances of that subclass.</p>
+<p>It's easiest to understand with an example - let's create a simple custom subclass of <code>android.view.View</code>, and instantiate an instance of it:</p>
+<p><code>javascript
+var Activity = require('android.app.Activity'),
+    activity = new Activity(Ti.Android.currentActivity),
+    View = require('android.view.View'),
+    MyView = android.view.View.extend({
+        onDraw: function(canvas) {
+            // implementation here
+        }
+    }),
+    view = new MyView(activity);
+// Add your custom view to the content...</code></p>
+<p>This will create a new class in the Java runtime which will extend <code>android.view.View</code> which is equivalent to the following code (though please note that we do <em>not</em> generate Java source, but instead generate Dalvik bytecode that gets loaded into the runtime as a class):</p>
+<p>```java
+class MyView extends android.view.View {</p>
+<pre><code>protected void onDraw(Canvas canvas) {
+    // implementation here
+}
+</code></pre>
+<p>}
+```</p>
+<h2>Using Third-party libraries</h2>
+<p>You can use Third-party libraries in Hyperloop.</p>
+<h3>JARs</h3>
+<p>Simply place the JAR files into the <code>platform/android</code> folder of your app. Hyperloop will pick up the JAR files and will generate necessary bindings and include the JARs in your app.</p>
+<h3>AARs</h3>
+<p>Simply place the AAR files into the <code>platform/android</code> folder of your app. Hyperloop will pick up the AAR files and will generate necessary bindings, extract resources, extract and use the classes.jar, *.so file, etc.</p>