JiuGongGe UI - A Simple Open Source UI Framework in HaXe

JiuGongGe (means 9-cell) UI is a UI framework written in HaXe with OpenFL for all platforms, including Flash, HTML5, Android/iOS and Windows. This UI framework is designed to be lightweight and mobile friendly.

The framework is actually a set of buttons (clickable cells) in a nested hierarchy, with each level containing at most 9 cells. The UI framework is firstly created for the BNote application.

Basic Usage
The framework contains two main classes, "JGGCell" represents a single cell and "JGG" is the whole set of cells. You can customize the look and feel for the cells by modifying and extending the first class. For the most time, you're working with the second class. Firstly, you need to create an instance of the "JGG" class, which is a subclass of "Sprite", so you can add it to the stage and set the positions:

var myJGG:JGG = new JGG();
addChild(myJGG);
myJGG.x = 300;
myJGG.y = 200;

But nothing happens until you initialize the UI:

  
myJGG.init(this,this,Assets.getText("assets/UILayout.txt"));

Where the first parameter is the UI host,usually the parent of the the UI object. All event handler function of the click event triggered by cells should be declared in the UI host as public functions. For example, if you use the stage as the UI host, the following function in your Main class can be used as on click event handler:

 
public function CallBack(event:Event)
 {   
  trace(event.target.name);
 }

The second parameter is the assets host, which will provide the UI framework with icons. The assets host must implement the function "getIcon(ID:String):DisplayObject" as a public method, which will be called by the JGG class to fetch icon resources. For example:

 
public function getIcon(ID:String)
 {   
  return new Bitmap(Assets.getBitmapData("assets/" + ID));
 }

The return value can be a Bitmap, Sprite, or any other display object.

The third parameter is the String of the config file. The cells' hierarchy is declared in the string. Usually, it's better to write the config file in a text file, then you can use "Assets.getText" to get the string and pass it to the JGG's init function, other than directly embed the string content in your code. For each line of the config file, you declare one cell and specify the cell's property. It's not necessary to give all the 9 cells for a level. Just declare used cells only. You should give the following things (with out the "[" and "]") in order and delimited by space:

 
[name_of_cell] [on_click_callback_function_name] [background_color] [icon] [text_label] [index][newline] 

Note strictly one row for one cell, and no spaces within [...] - use "_" or "-" instead. For example,

StartCell JGG_ChangeLevel 0xffffff null Start 0

You can use "#" at the beginning of the line to comment:

# This is a comment line.

Now about some details of each property declaration.
[name_of_cell]: Will be used as the name of the JGGCell class instance. [on_click_callback_function_name]: Use the same name of the public method in the UI host. When the cell is clicked by user, this function will be called. You can use the shortcut string "JGG_ChangeLevel" for folding (for non-center cell)or unfolding (if it is the center cell) levels, without implementing the function in the UI host.
[background_color]: Background color of the cell, e.g., 0xffffff.
[icon]: An ID string used as a parameter of Assets host's public function "getIcon". Use the shortcut string "null" if you want to simply use a text label instead.
[text_label]: This is usually used for debugging or quick prototyping purpose. It's recommended use an icon instead of a text label. You can use "_" for space, "/" for newline in the label string. The label text will shown only if the icon string is "null".
[index]: To give the level information of the cell. For example "0,1,0" - integer sequence separated by ','. It is an array of indices for different levels. "0,1,0" means the cell's index in the root level is "0", in the first level is "1" and in the second level is "0". For each level, there're at most 9 cells, so the indices are all staring from "0" to "8". The cell's position is determined by the index of its last level. Starting from center as "0", go left as "1" then up as "2", then along a clockwise circle to "8".
How to interpret the index: Take "0,2,4,3,5" as an example. Look at the last (5-th) integer "5", it means the cell is in the 4-th level with index "5", so it's position is the center one on the right panel. Now the second last (4-th) integer "3", it means the cell's parent's index (in the 3-rd level) is 3. And the integer "4" means the cells' parent' parent's index is 4... In short, you can think the indices as an index of a multidimensional array, which specifies the position of the the cell in the hierarchy.

For a complete example of the config file, please check: https://flaswf.googlecode.com/svn/trunk/JiuGongGeUI-v0.2/assets/UILayout.txt

Advanced Usage
To change cells' behavior, customize cell's look and feel etc.: You can use public functions foldLevel() and unfoldLevel(TargetCell:JGGCell) to change the levels manually, and getCell(name:String) to get a specific cell. The JGGCell class is a subclass of Sprite, so you can redraw the cell using its Graphics property. See the example's source code for more details: https://flaswf.googlecode.com/svn/trunk/JiuGongGeUI-v0.2/src/Main.hx

Although the UI framework is very simple, I believe it can satisfy the most needs for a simple application with some customization. For example, check the BNote app. However, if you're looking for a more feature complete UI framework in HaXe, try http://haxeui.org/ or http://ui.stablex.ru.

Links:
Flash demo: http://flaswf.googlecode.com/svn/trunk/JiuGongGeUI-v0.2/bin/flash/bin/JiuGongGe.swf
HTML5 demo: http://flaswf.googlecode.com/svn/trunk/JiuGongGeUI-v0.2/bin/html5/bin/index.html
Real Example (BNote): http://bruce-lab.blogspot.com/2014/10/bnote-free-online-taking-handwriting-notes.html
Source Code v0.2 (MIT): https://flaswf.googlecode.com/svn/trunk/JiuGongGeUI-v0.2
SWC for Flash/AS3: http://bruce-lab.blogspot.com/2014/11/jiugonggeswc-jiugongge-ui-for-flash-as3.html