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:

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.