xml-based classes manual

docGen/doc.php

@@ -17,6 +17,8 @@
     'default' => DOC_BASE_URL.'#http://haxe.org/api/#type#'
 );
 
+$hide = array("ru.stablex.ui.ClassBuilder");
+
 file_put_contents(
     'doc/menu.html',
     "<ul>\n"
@@ -32,6 +34,8 @@
 
 
 function generate($srcPath, $dstPath = 'doc/', $imports = array()){
+    global $hide;
+
     if( !file_exists($dstPath) ){
         mkdir($dstPath, 0777, true);
     }
@@ -58,6 +62,10 @@ function generate($srcPath, $dstPath = 'doc/', $imports = array()){
         $import = preg_replace('/^([^a-zA-Z]*)/', '', $import);
         $import = preg_replace('/\.hx$/', '', $import);
 
+        if( in_array($import, $hide) ){
+            continue;
+        }
+
         $menu .= "<li class=\"class\"><a href=\"". url($import) ."\" class=\"class\">". basename($fname, '.hx') ."</a></li>\n";
 
         $doc = genDoc($fname, $imports);

docGen/src/manual/12_XML_based_classes.hx

@@ -0,0 +1,93 @@
+/**
+@manual Creating custom widget classes with xml markup.
+
+If you want to create your custom widget class, you have another option in addition to
+one described in <type>manual.05_Custom_widgets</type>.
+
+StablexUI provides data-driven way to create classes based on xml. You can convert
+any ui xml file to class definition with <type>ru.stablex.ui.UIBuilder</type>.createClass()
+
+Let's dig into example. Imagine, you need a square widget with button in the middle.
+And you need to use it in several places with different properties for button and different widget colors.
+Let's start with xml for such widget - custom.xml:
+
+<xml>
+<?xml version="1.0" encoding="UTF-8"?>
+
+<Widget w="100" h="100" skin:Paint-color="0xFF0000">
+    <HBox name="'box'" widthPt="100" heightPt="100" childPadding="4">
+        <Button name="'btn'" text="'Yeah!'" skin:Paint-color="0x00FF55" on-click="trace('it works!');"/>
+    </HBox>
+</Widget>
+</xml>
+
+Next step: create a class for this widget:
+
+<haxe>
+    /**
+    * Enrty point
+    *
+    */
+    static public function main () : Void{
+
+        //register classes for usage in xml.
+        // UIBuilder.regClass(...);
+        // ...
+
+        //create class for custom widget
+        ru.stablex.ui.UIBuilder.createClass("custom.xml", "com.example.Custom");
+
+        //initialize StablexUI
+        ru.stablex.ui.UIBuilder.init("defaults.xml");
+
+        //...
+    }//function main()
+</haxe>
+
+Now you can instantiate com.example.Custom or use 'Custom' tag in xml to create widgets!
+As a bonus this class also has fields 'box' and 'btn', which are <type>ru.stablex.ui.widgets.HBox</type> and <type>ru.stablex.ui.widgets.Button</type> instances.
+Take a look at source xml. You'll see <type>ru.stablex.ui.widgets.HBox</type> and <type>ru.stablex.ui.widgets.Button</type> widgets with constant `name` attributes.
+The rule is simple: all widgets with constant names in xml-based classes become class fields.
+To clarify what i mean (my english is really bad :) ), i'll show you an example usage of generated class:
+In haxe:
+
+<haxe>
+    //instantiate xml-based class
+    var w = ru.stablex.ui.UIBuilder.create(Custom);
+    trace( Type.typeof(w.box) ); //ru.stablex.ui.widgets.HBox
+    trace( Type.typeof(w.btn) ); //ru.stablex.ui.widgets.Button
+</haxe>
+
+Or in xml:
+
+<xml>
+<?xml version="1.0" encoding="UTF-8"?>
+
+<HBox w="800" h="600" childPadding="20">
+
+    <!-- use generated widget class as usual -->
+    <|Custom />
+    <|Custom skin:Paint-color="0x0000FF"/>
+
+    <!-- access widgets assigned to fields of generated class -->
+    <|Custom h="200" btn-text="'no-no!'" box-align="'bottom,right'" box-padding="10" />
+
+</HBox>
+</xml>
+
+Here is how it looks in <a href="http://stablex.ru/ui/demo/xmlClasses.swf" target="_blank">flash</a> and in <a href="http://stablex.ru/ui/demo/xmlClasses" target="_blank">html5</a>.
+Source code can be found in Github repository in <a href="https://github.com/RealyUniqueName/StablexUI/tree/master/samples/xmlClasses" target="_blank">samples/xmlClasses</a> directory.
+
+*/
+
+
+/**
+@manual Tips
+
+Since generated classes don't exist untill compiler find <type>ru.stablex.ui.UIBuilder</type>.createClass(...) calls, you
+can get errors like "Class not found: com.example.Custom" if you try to import this class somewhere or extend it.
+To avoid this problem it's recommended to dedicate main haxe file (one with static main() function) to StablexUI initialization.
+Take a look at <a href="https://github.com/RealyUniqueName/StablexUI/tree/master/samples/xmlClasses" target="_blank">sample project</a> for this technique
+and for example of extending generated class.
+
+*/

samples/xmlClasses/com/example/Init.hx

@@ -20,9 +20,6 @@ class Init{
         //create xml-based classes for custom widgets
         UIBuilder.createClass("ui/custom.xml", "com.example.Custom");
 
-        // //register classes, which rely on xml-based classes
-        // UIBuilder.regClass("com.example.CustomExtended");
-
         //initialize StablexUI
         UIBuilder.init("ui/defaults.xml");
 
@@ -32,6 +29,15 @@ class Init{
     }//function main()
 
 
+    /**
+    * constructor
+    *
+    */
+    public function new() : Void {
+    }//function new()
+
+
+
 }//class Init
 
 

src/ru/stablex/ui/UIBuilder.hx

@@ -685,7 +685,8 @@ class UIBuilder {
 
     /**
     * Create class for custom widget based on xml markup
-    *
+    * @param xmlFile - source markup file for new class
+    * @param cls - fully qualified class name for new class (E.g. 'com.example.MyFancyWidget')
     */
     #if haxe3 macro #else @:macro #end static public function createClass(xmlFile:String, cls:String) : Expr {
         if( !UIBuilder._initialized ){