MadButterfly Application Framework

The application framework can simplify the design of UI application. The following code provide a minimal MadButterfly application.

char *svg;
if (argc > 2) svg = argv[1];
else svg = "worksapce";
MBAPP *myApp = MBApp_Init(svg);
MBApp_loop();
MBApp_done();

The workspaces.svg is a SVG file with multiple scene. It can contains tens of pages for a complex application. These 6 lines can be used to load any MB SVG file which can be edited by the inkscape.

Comparing to the traditional GUI application framework, the MadButterfly does not provide too much widgets. In a rich-format user interface, the widgets does not too useful. Every application will provide their own "widgets" or we call components in the MadButterfly. Each component is a set of SVG files and callback functions. A component looks like a traditional widget with flexible skin support. The looks and feels of the widget in different application can be very different. This solves the difficult of the traditional GUI framework.

For example, the MadButterfly provide the button component internally. It contains three frames. We make each frame very complex easily. We can even put another application in a button since they are nothing but another multiscene SVG file. The components have the benefit of the traditional widget, but without their limitations.

Although MadButterfly does not has traditional widgets, a couple of "widgets" is still available. Those widgets does not define the outlook at all. Instead, they provide a convenient way to create visual components in the screen. Their outlook can be customized by a SVG file. These widgets will become traditional widgets if programmers choice to use the builtin SVG files. Please refer to MadButterfly widgets for the details.

Use MB symbol

The inkscape MadButterfly extention can convert a SVG group into a MB symbol. These symbols can be access via

mb_sprite_t *mui =  MBApp_getUI(myApp);
mb_obj_t *obj = MB_SPRITE_GET_OBJ(mui,"btn");
coord_t *button = MBO_COORD(obj);

The MBApp_getUI will return the root sprite of the worksapce.svg. This sprite is actually a big collection of objects. It contains all objects in all scenes. We can use the MBS_PRITE_GET_OBJ to get a MB symbol object, which is an instance of coord_t.

In the MadButterfly, the observer pattern is used to define the interaction between the presentation layer, controller and the model layer. Usually, the model data can be saved in the MBApp or any mb_obj_t.

MBApp_setModel(myApp, (void *) mydata);
mb_prop_set(mb_obj_prop_store(button),"data",(void *) mydata);

The subject can be acquired by using the mb_obj_get_mouse(), mb_obj_get_key() or mb_obj_get_timer() and then we can use the subject API to add an observer.

subject_add_observer(mb_obj_get_mouse(button), mouseHandler, (void *) button);
subject_add_event_observer(mb_obj_get_mouse(button), EVT_MOUSE_MOVE, mouseHandler, (void *) button);

The mouseHandler can use the button to get its associated 'mydata' and then do whatever we want. We can create a very complex application by using only these primitives.

MadButterfly Application Framework events

The MAF will generate some events by using the MAF subject, which can be returned by MBApp_getSubject(). The following events are defined. * EVT_APP_START: This is called before we enter the mainloop. We can load extra SVG files or construct extra UI elements at runtime here. * EVT_APP_EXIT: This is called before twe leave the mainloop.

Display Object - mb_obj_t

The display object is the basic display unit of the MadButterfly.

DIsplay Object events

EVT_OBJ_ADDED: This is sent when a sprite is added into the display list. We can add observer for this event to refresh itself before it is shown.
EVT_OBJ_CLICK: This sprite is clicked. This is sent when users press and release the left mouse button inside the sprite.
EVT_OBJ_DOUBLECLICK: This sprite is double-clicked.
EVT_OBJ__REMOVED: This is sent when a sprite is removed from the display list.
EVT_OBJ_RENDERED: This is sent when the sprite is visible and need to be rendered. We can use this event to update the content of the sprite. It will be called only when we need to draw the sprite again. If the sprite is not visible, it will not be sent so that we can save some unnecessary updates.
EVT_OBJ_RIGHT_CLICK: This is sent when users click the right mouse button inside the sprite. It is usually used to show the content menu.

Display Object properties

[TBD]

Sprite

The sprite is a set of display objects which is divided into multiple scene. Please remember that the sprite itself is not a Display Object. If you want to move or resize a sprite, you need to get the "_root" object of it and operate on the root object instead. For example,

coord_t *root = MB_SPRITE_GET_OBJ(sprite,"_root");
coord_move(root,100,100);

Sprite events

Each sprite will generate some events related to the scene and focus change. The sprite subject can be get by using mb_sprite_getSubject.

EVT_SPRITE_ENTERFRAME: This event is sent when we enter a new scene. It is sent initially before this first scene is displayed or when we call gotoScene to jump to a new scene.
EVT_SPRITE_LEAVEFRAME: This event is sent when we about to leave the current scene.

Sprite properties

currentscene: An string which stands for the id of the current scene.
scenes: An string array contains all scenes in this sprite.

Script support

The MadButterfly framework provide multiple scripting langauges binding natively. You can choice the default scripting engine in the application wizard. The scripting engien can be changed latter. We can also mix two language as well. We can use C as main program and call mouse observer in python. Or we can use a component which is designed by forth from a python script.

The Madbutterfly will load the script binding dynamically in the runtime if it detect a new language is requested. Every language binding is implemented in a shared library. For example, if a components contains a python script, we can load the python.so when the button is created.

The script can be put inside the scene group so that it will be evaluated when we enter this scene. This is equivalent to the onEnterScene event of the scene subject.