XiLib for Haxe

06.16.2008 7060 2

XiLib is a package of 2 classes, that can help in building modular Flash applications.
It facilites application's maintenance : There is no need to re-build the whole project to fix a specific bug, to upgrade an existing part or add a new part to an existing application.
Xilib works with Haxe Flash9 and gives help in loading and using ressources from external SWF libraries (as run-time downloaded classes, media assets, components, plugins or listeners*).
Let's see how does it work

What can XiLib do ?

XiLib contains XlibMananger class, that can be used to do:

  • Hard-coded loads of external libraries (once at once or several at the same time)
  • Soft-coded loads of external libraries (from an XML file)
  • Easilly use shared classes, components...

XlibManager also provides:

  • A plug-in system management, that allows you to download at run-time some parts of your project, like own skinned components for example.
  • An easy event system allowing a kind of inversion of control in the projects' building process

Maintainting modular applications can be sometimes quite difficult, especially when there is too many separated parts to manage, it gives headacke
So, a light framework was defined : XiLib uses Xlib & Xplug objects and you can use the workspace (folder structure joined to the library), to easilly work with XiLib.

What are Xlib & Xplug ?

They are SWFs files compiled with some specifications, and using a special extension (not requiered but prefered), in order to recongnize them.
A Xlib is an external downloadable library, as a shared library.
A Xplug can be used as a run-time downloaded plugin, or listener*.

Xlib specifications:

  • Media : .swfm : assets library : sounds, pictures, fonts...
  • Package : .swfp : packages, classes
  • Component : .swfc : [Package] + [Media]

XPlug specifications:

  • Plugin : .swfpl : swf + static function main() (compiled without "-main" option)
  • Listener : .swfl : swf + static function main() (compiled without "-main" option)

Objects requirements:

All the xlibs objects (Xlib or Xplug), must define a path that will be used to download the eXternal library and a name to locate ressources in the application.
If the eXternal library uses the stage of the root display object, so you have to add a stage param to the xlib. This param can be used 3 ways : hard-coded, it's a Sprite, soft coded in the .xlibs XML file* as child depths separated by comas or child names separated by comas too. To find the target, XlibManager uses the "root" given in arguments to its constructor.
A domain param comes next. If exist, it will define the domain where classes will be stored. If not, the defaut root domain will be used.
Then a Xplug (plugin or listener) must define a main function that is the class name containing the static function main (entry point of the plugin).
And at the end, only listener defines listen param that is a String that it will listen to through the XlibManager (pushEvent).

How does it work ?

In all cases, in order to use XiLib you need these 2 lines :

xlibm = new XlibManager( flash.Lib.current );
xlibm.addEventListener( XiLibEvent.COMPLETE, onComplete );

Manual managing (hard coded):

Here you have to build the Xlib or Xplug object(s) and give it (or them) to XlibManager to load.
It's an example of manual loading :

var xlib = new xilib.Xlib( "core", "../../../xlibs/release2006/packages/core.swfp" );
xlibm.loadXlib( xlib );

Automatic managing (soft coded):

Here you have to give to XlibManager the path to the .xlibs XML file, where it will find all the xlibs to download.
It's an example of automatic loading :

xlibm.loadXlibsFromXml( "example.xlibs" );

.xlibs XML file :

Here a sample of a xlibs list:

	<package name="core" path="../../../xlibs/release2006/packages/core.swfp" />

How to get my ressources ?

You can get your ressources easilly, here are some samples:

// To get the class definition:
Connection = xlibm.getClass( "core", "com.example.tools.Connection" );
// To get an instance of a class:
var proxy = xlibm.getInstance( "core", "com.example.tools.Proxy" );
trace( "Call to a static function : " + Connection.getData() );
trace( "Call to an object's instance function : " + proxy.getInstance() );
// To get the eXternal library's loader (if you want to add it to the DisplayList by yourself):
var sprite = xlibm.getLoaderInstance( "core" );

Then you can generate extrnal classes (using Haxe compiler option --gen-hx-classes), to get the right API of your external downloaded class or component, and use it as usual with type checking .

More examples:

You can find a set of samples of what actually, XiLib can do, by downloading the library.
There is a workspace folder, using an appropriate structure and containing examples, xlibs and libs (sources) separated.


You can download Xilib using haxelib:

haxelib install xilib

It will install automatically the library into the Haxe libraries path (usually C:\Program Files\Motion-Twin\haxe\lib\ on Windows).
XiLib contains also examples and the documentation (API).
To get the documentation and the examples run, go to the library path. They are in the workspace\projects\examples forlder. You can change the .xlibs to see the changes (as mentionned in README.txt)
Take a look at http://lib.haxe.org
You can download also from here.


Be careful when using stage in the XML file: The list of display objects' depths or their names, separated by comas, will try to be placed as is in the context. Especially adding or removing display objects, using trace function which adds a TextField instance to the root stage or swap it depths... a confusing might happen.
Be careful, when using same domain, classes with the same full qualified name will be "skipped", and the existing ones will be used. (You cannot override an existing function in the same domain...)
If you have any questions or suggestions, don't hesitate .


03.10.2009 at 03:32 Don-Duong Quach

Hi Michal,
Thanks for putting the lib together! I'm using it as a swc with mxmlc.
I was wondering what's the purpose of the xilib_on flag?
-Don Q.

03.10.2009 at 08:37 Michal

Hi !
xilib_on flag is here to set the project as using modules' external loading instead of building the modules inside the project.
I'm using it when I put the project on a server for example, for production.

Write a comment