Container widget relationship

Components

Container

A container is an instance of a HemlockContainer, and is the heart of any Hemlock app. The container maintains a collection of widgets in its _widgets:Object private member variable. This can be in two simple steps: create the _widgets object, then add widgets to the stage; see below.

Create the container’s _widgets object

The following example shows how to build the container’s _widgets member variable with two basic widgets:

// Within the container's constructor
widgets = {
    chatroom: new ChatroomWidget(this, {
        x:690, y:10,          // position
        width:300, height:650 // dimensions
    }),
    game: new GameWidget(this, {
        x:10, y:10,
        width:650, height:680
    })
};

Add widgets to the stage

The addWidgets() function lets you add widgets to the stage in a specific order. Widgets added last overlap widgets added first, like a stack.

// Within the container's constructor
addWidgets([
    widgets.game,
    widgets.chatroom
]);

Widget

A widget is an instance of a HemlockWidget. Each widget consists of a package of files, e.g., com.mintdigital.hemlock.widgets.chatroom. Within this package are three files:

• The widget class: This should be named according to the package. For instance, the widget in com.mintdigital.hemlock.widgets.chatroom should be named ChatroomWidget.as. This file needs to include handlers.as and views.as.
• events.as: This contains listener registration and event handlers, which are attached to the widget’s various views and controls via event listeners. To attach event handlers, override registerListeners() using the registerListener() function.
• views.as: This is responsible for creating the widget’s views and controls. This code should override createViews() and destroyViews().

You can also nest widgets within widgets using addWidgets(), which behaves similarly to the function in HemlockContainer.

Event handling

Incoming data goes from the socket to the widgets via events:

1. The client (XMPPClient) dispatches an event on itself, such as a MessageEvent or PresenceEvent.
2. The container (HemlockContainer subclass) listens for these events on the client. When the container hears these, it redispatches the events on itself.
3. The container’s widgets (HemlockWidget subclasses) listen for these events on the container. When the widgets, hear these, they act upon them.

This structure allows the container to dispatch an event on itself once containing data that originated at the socket, and all widgets within that container can handle it accordingly. For instance, if the incoming event contains game data, a custom GameWidget could reflect the game data by moving a player’s piece on a game board, while ChatroomWidget observes the same game data and logs the move in the chatroom in a human-readable sentence.