• PrefaceAndIntroduction
• MigratingFromAS3
• SimpleExamples
• MoreAdvancedExamples

Preface

HSL, pronounced "hustle", stands for haXe Signaling Library. It makes writing "event-driven" code in haXe hassle-free.

Every haXe developer should use it. Here's why:

• HSL is a standard

HSL is the standard haXe library for writing event-driven code. We need a standard way of writing event-driven code, because having standard ways makes it easier to reuse and share haXe code.

If Franco is using hxevents, and Justin is using Haxle, one would have to learn the former to work on a project with Franco and the latter to work on a project with Justin. Sounds like a bad idea: one should focus on writing awesome applications and games, rather than learning libraries. But that's not all: imagine writing an application that uses code written by both. Chances are the application will end up using, and depending on, both libraries.

And that's just two libraries. Imagine what happens when other developers start using Laurence' haXe port of as3-signals. Such situations can be avoided by having a standard.

HSL has been looked at by the judicial eyes of many haXe developers during its development. It has been crafted to fulfil the common needs. This makes the library a better standard than the aforesaid ones, which are mostly personal projects.

• HSL is cross-target

haXe is a cross-target language: haXe code can be compiled to multiple targets. However, some haXe developers depend on a target-specific event API for event-driven code, such as the AVM2-specific EventDispatcher class. This effectively restricts those developers from compiling their code to other targets, without using hacks.

HSL is as cross-target as haXe is. Therefore, the library does not prevent applications depending on it from being compiled to any target. You can use the library in flash games, CPP applications and Neko backends. The choice is yours.

• HSL has been tested sufficiently

As much as we philosophise about our designs before writing our APIs, there are always small design flaws. Those flaws surface when the APIs are used in big projects.

HSL has been used for two years now, in both small and big projects. In that period we have been improving the library. This makes the library very stable, today.

haXe developers should not be using the EventDispatcher class. This class is not cross-target, as explained above, thus restricts developers from compiling their code to targets other than AVM2 (swf9+/flash9+) and ActionScript 3. But the EventDispatcher has some serious design flaws, too:

• EventDispatcher requires inheritance

Events are usually dispatched by objects that extend the EventDispatcher class. That works in a lot of cases, but not all. If one wants to add event dispatching functionalities to an existing class by extending it, extending EventDispatcher as well isn't an option. In such cases one has to implement the IEventDispatcher interface and route all the methods to an EventDispatcher instance, which requires way too much code.

• EventDispatcher use often leads to extending the Event class

If one wants to include custom data in an event dispatched by an EventDispatcher, one must extend the Event class. This leads to more boilerplate code than necessary.

• EventDispatcher supports weakly referenced listeners

Because the addEventListener method has a useWeakReference argument, people are likely to use it at some point. Though such functionality could also be added to HSL, one will have to write that functionality oneself. Because of this, developers will be less tempted to use those oh-so terrible weakly referenced listeners.

Introduction

The library has been split into two parts: HSL-pico and HSL. HSL-pico consists of the core functionalities of the library, while HSL contains some additional extras as well. It is recommended that you install the full library if you are not sure which one to install.

Installation

Installing HSL is as easy as using it. Make sure you have haxelib installed (it comes with the haXe compiler). Open up a command-line interface, and use this command:

haxelib install hsl-1

Should you decide to install HSL-pico, use this command instead.

haxelib install hsl-pico-1

Small note here. Do you see the "-1" part of the commands above? That's the major version of the library. Should we ever make drastic changes to the API, we'll call the result "hsl-2". In effect, it is always safe to upgrade to the latest of "hsl-1". We will not break your code. We've got your back.

Using

You will have to tell the compiler that you're using the library. There are a couple of ways to do this.

• If you are using a HXML file to compile your project, just add the following line to that file:

-lib hsl-1

• If you are using FlashDevelop, just add an option to the "Project Properties". Go to Project > Properties... and open the "Compiler Options" tab. Click on the small button to the right of the "Libraries" row, and type in:

hsl-1

That's all, you're all set!

Proceed to the SimpleExamples page to check out some examples of HSL use. If you are familiar with the ActionScript 3 EventDispatcher class mentioned above, you can check out the MigratingFromAS3 page.