HMMS Documentation - Module Development

Introduction

The Hugin battlemap management system is designed in an extremely modular fashion. The miniatures, the drawing tools, and even the grid lines are implemented as modules in Hugin. Adding new features and functionality is as simple as creating a feature module and installing it into the core Hugin system. Do you want to develop a Hugin module? Great! The general module design workflow is as follows:

The module interface allows a module to register user interface elements, such as a view, menu items, or pallette tools.
The MapView class provides utiltity functions for modules and instantiates the modules. At present, each module's instantiation is hardcoded into the - loadDefaultModules method.
Cross-client state is stored in a shared hierarchical javascript object, something like a filesystem. The structure of this object is relatively freeform: Although there are standardized paths used by the core modules (e.g., minis), you can add your own paths without changing any configuration. Note that unlike a normal filesystem, "directories" are created and destroyed automatically as needed.
Access to the shared javascript object is mediated by ICON. All modifications to the object must go through ICON, and ICON can be used to register callbacks for when the object is changed.

Module Interface

- (id)initWithMapView:(MapView)in_mv

Default module initializer used by MapView.

- (void)mapViewUpdatedPosition:(MapView)in_mv

Called by MapView when the user drags the view, changes the scale factor, resizes the window, or otherwise changed the view rectangle. If your module includes a view, it should ensure that the view is sized properly (using MapView's - displayFrame), scaled properly (using MapView's - gridSize), and positioned properly (MapView's - pixelForPosition) can help here. Note that all points and sizes in MapView are typically stored with respect to grid dimensions rather than pixels (1 square = 50x50 pixels in the default scale). This also helps make them agnostic to how the user has scrollled the view.

- (CPString)description

Returns a short one-word module name.

- (void)mvSetICONHub:(ICON)in_icon_hub

Called when the login process completes and ICON is ready to mediate access to the shared object. The module should use this opportunity to register its interest in any of the object's subtrees and to record the ICON hub object if it will need to modify the object at any point during its lifetime. Note that this method may get called multiple times if the user logs out and back in again.

- (id)mvModuleInfo

Returns a javascript object describing the module's user interface elements:

view

A CPView to be included as a subview of the battlemap.

tools

[Tool Pallette Name (default: "General")]

[Tool Name]

image: A CPImage to display as the tool's icon
mouseDownSel: A SELECTOR referencing a method of the module to invoke when the tool is selected and the user mouseDowns on the battlemap. The method is passed a CPPoint containing the relevant position on the battlemap
mouseDragSel: A SELECTOR referencing a method of the module to invoke when the tool is selected and the user mouseDrags on the battlemap. The method is passed a CPPoint containing the relevant position on the battlemap
mouseUpSel: A SELECTOR referencing a method of the module to invoke when the tool is selected and the user mouseUps on the battlemap. The method is passed a CPPoint containing the relevant position on the battlemap

menu

[Menu Name (e.g.: File, Edit... )]

[Menu Item Name]

target: The object to send the menu item's action to
action: A SELECTOR referecing a method of the target to invoke when the menu item is selected. The method is passed the menu item being selected

drags

A javascript array containing a list of drag types that the battlemap should accept. When an item with one of the specified types is dragged onto the battlemap, the module's - mvModuleDragOperation:position: method will be invoked with the CPDraggingInfo of the drag operation, and the position where the drag occurred.

MapView Documentation

- (int)gridSize: Returns the ratio of pixels to position (i.e., the height/width of a grid square). Defaults to 50.
- (CPRect)viewableRegion: Returns the viewable rectangle (in grid square position) currently being displayed on the map view.
- (CPRect)displayFrame: Returns the viewable rectangle (in pixels) currently being displayed on the map view.
- (CPPoint)pixelForPosition:(CPPoint)pos: Transform the specified position on the battlemap grid to the corresponding pixel on the battlemap frame. The returned pixel is translated based on the viewable area -- the upper left hand corner of the viewable area (whatever its position) will be transformed to the pixel (0,0).
- (CPPoint)globalPixelForPosition:(CPPoint)pos: Transform the specified position on the battlemap grid to the corresponding pixel in the viewable area without translating with respect to the viewable area.
- (CPPoint)positionForPixel:(CPPoint)pix: Transform the specified pixel on the battlemap frame to the corresponding position on the battlemap.
- (CPSize)sizeFromPixelSize:(CPSize)pSize;: Transform the provided size in pixels to the corresponding size in grid square position.
- (CPSize)pixelSizeFromSize:(CPSize)size;: Transform the provided size in grid square position to the corresponding size in pixels
- (CPRect)pixelRectFromRect:(CPRect)frame: Transform the provided rectangle in pixels to the corresponding rectangle in grid square position
- (CPRect)rectFromPixelRect:(CPRect)frame: Transform the provided rectangle in grid square position to the corresponding rectangle in pixels
- (CPPoint)positionForEvent:(CPEvent)evt: Transform the specified event's location to the corresponding grid square position.
- (void)setViewableOriginToPosition:(CPPoint)pos: Set the upper left hand corner of the viewable area to the specified position.
- (void)offsetViewableByPosition:(CPPoint)delta: Move the viewable area by the specified amount (in terms of grid square position)
- (void)offsetViewableByPixels:(CPPoint)delta: Move the viewable area by the specified amount (in terms of pixels)

Shared Object Hierarchy

instances

[Short Instance Name]

prototypes: Prototype definitions of miniatures (MVMiniModule).
minis: Miniatures currently on the battlemap (MVMiniModule).
shapes: Whiteboard content (MVWhiteboardModule).
zones: Shared Measurements (MVZoneModule).

ICON Documentation

- (void)registerForUpdatesToPath:(CPString)path target:(CPString)target selector:(SEL)selector: Register interest in changes to the shared object at the specified path, or any of its subnodes. Changes will result in a callback to the specified method selector invoked on target. The callback method must accept one parameter: the new value of the recently-changed javascript object. The callback method will be invoked immediately with the current value of the object.
- (void)deleteAtPath:(CPString)path: Delete the node (and its subtree) of the indicated path into the shared object. Path components are separated by forward slashes ('/'). This method returns immediately. Callbacks will be invoked once the change is propagated through the server.
- (void)appendToPath:(CPString)path data:(id)data: Create a new subnode of the node at the indicated path into the shared object and set its value to the javascript object data. The subnode will be assigned a randomly selected name guaranteed not to conflict with any existant subnodes. Path components are separated by forward slashes ('/'). This method returns immediately. Callbacks will be invoked once the change is propagated through the server.
- (int)immediateAppendToPath:(CPString)path data:(id)data: Create a new subnode of the node at the indicated path into the shared object and set its value to the javascript object data. The subnode will be assigned a randomly selected name guaranteed not to conflict with any existant subnodes. Path components are separated by forward slashes ('/'). This method blocks until the change is registered with the server, and returns the timestamp of the registered change. Note that the change will not be reflected in the local copy of the shared object until - timestamp returns a value greater than or equal to the timestamp returned by this method.
- (void)appendToPath:(CPString)path data:(id)data target:(id)target success:(SEL)successSelector fail:(SEL)failSelector: Create a new subnode of the node at the indicated path into the shared object and set its value to the javascript object data. The subnode will be assigned a randomly selected name guaranteed not to conflict with any existant subnodes. Path components are separated by forward slashes ('/'). This method returns immediately. The provided callback methods successSelector or failSelector will be invoked on target upon the success or failure of the operation. You should not need to invoke this method directly.
- (void)writeToPath:(CPString)path data:(id)data: Replace the node at the indicated path into the shared object with the javascript object data. Path components are separated by forward slashes ('/'). This method returns immediately. Callbacks will be invoked once the change is propagated through the server.
- (int)immediateWriteToPath:(CPString)path data:(id)data: Replace the node at the indicated path into the shared object with the javascript object data. Path components are separated by forward slashes ('/'). This method blocks until the change is registered with the server, and returns the timestamp of the registered change. Note that the change will not be reflected in the local copy of the shared object until - timestamp returns a value greater than or equal to the timestamp returned by this method.
- (void)writeToPath:(CPString)path data:(id)data safe:(BOOL)safe target:(id)target success:(SEL)successSelector fail:(SEL)failSelector: Replace the node at the indicated path into the shared object with the javascript object data. Path components are separated by forward slashes ('/'). This method returns immediately. By setting safe to false, the write operation will fail if there is already content present at the indicated path or one of its subnodes. The provided callback methods successSelector or failSelector will be invoked on target upon the success or failure of the operation. You should not need to invoke this method directly.
- (id)getPath:(CPString)path: Return the node at the indicated path into the shared object.
- (CPString)username: Return the username of the user currently logged into ICON.
- (CPString)path: Return ICON's current default path. For the purposes of module development, this is typically /instances/[active instance name]. (i.e. your module should always prefix reads and writes with this path.
- (int)timestamp: Return the timestamp of the latest update to the shared object that ICON is currently aware of. This is used primarilly to determine when the immediate* operations have completed.