UnitMap

The central class of the API — it is used to create a unitmap instance on a page and manipulate it.

// Initialize a `unitmap` instance on the `<div id="map">` element of the page:
var map = unitmap("map", "YOUR_API_KEY");

// Or you may pass an element reference directly:
var mapElement = document.getElementByid("map");
var map = unitmap(mapElement, "YOUR_API_KEY");

Creation

Options

UnitMap.load(mapId, [callback])

Loads a Unit Map by a given ID.

// Load the Unit Map with an ID of `1`:
map.load("1", function () {
  console.log("Unit Map ready.");
});

// You can also listen for the `ready` event along with / instead of 
// the load() callback:
map.on("ready", function (map) {
	console.log("Unit Map ready (event).");  
});

Arguments

UnitMap.units()

Returns a UnitSelection object containing all Unit objects.

// Get a unit selection object from the map:
var units = map.units();

// Color units with the ID's of `1`, `2`, and `3`. Review 
// the UnitSelection documentation for futher explanation:
units.find(["1", "2", "3"]).color("#000");

UnitMap.levels()

Returns a LevelSelection object containing all Level objects.

// Get a level selection object from the map:
var levels = map.levels();

// Hide all levels with a `floor` tag except levels with a value of `1`:
levels.has({floor: true}).show().expect({floor: "1"}).hide();

UnitMap.translate([point])

Performs a 2D transform to the given position if provided. Otherwise returns the current position value.

Arguments

Returns

Either an [x, y] coordinates Array of the current position or the object chain.

UnitMap.scale([scale])

Performs a 2D transform scaling to the given value when provided. Otherwise returns the current scale value.

// Set the scale to a factor of 1, representing the maps intrinsic size:
map.scale(1);

// Set the scale to a factor of 0.5, representing half of the maps intrinsic size:
map.scale(0.5);

// Set the scale to a factor of 2, representing double the maps intrinic size:
map.scale(2);

// Console log the map's current scale value.
console.log(map.scale());

Arguments

Returns

Either the current scale value or the object chain.

UnitMap.minScale([minScale])

Sets the minimum scale factor to the given value when provided. Otherwise returns the current minimum scale factor value.

Arguments

Returns

Either the current minimum scale factor value or the object chain.

UnitMap.maxScale([maxScale])

Sets the maximum scale factor to the given value when provided. Otherwise returns the current maximum scale factor value.

Arguments

Returns

Either the current minimum scale factor value or the object chain.

UnitMap.zoom([factor])

Increase or decrease the zoom level by a given factor.

Arguments

Returns

The object chain

UnitMap.zoomTo(point, [factor])

Increase or decrease the zoom level by a given factor while Interpolating a 2D translation of the map to a given position.

Arguments

UnitMap.panTo(point)

Interpolates a 2D translation of the map to a given position.

Arguments

Returns

The object chain.

UnitMap.panZoom([enabled])

Determines if pan and zoom gestures are enabled.

Arguments

Returns

The object chain.

UnitMap.autoScale(autoScale)

Sets the auto-scaling strategy the Unit Map will employ. Supported values are width, geo, clientRect, and none

Returns

The object chain.

UnitMap.toLocal(point)

Translate the given position from the viewport (screen space) into map space.

var mapElement = document.getElementById("map");

// Output the [x, y] of the current mouse position to the console.

mapElement.addEventListener("mousemove", function(event) {
  var point = map.toLocal([event.clientX, event.clientY]);
  console.log(point);
});

Arguments

Returns

An [x, y] coordinates Array.

UnitMap.fromLocal(point)

Translate the given position from map space into screen space.

// Output the top left position of the unit map in screen space.

var point = map.fromLocal([0, 0]);

Arguments

Returns

An [x, y] coordinates Array.

Events

UnitMap.on(event, callback, [context])

Binds a given callback function to a given event. The callback will be invoked in the given context whenever the event is triggered. Reference the above Events section for support events.

// Create a named function to handle the event.
// These are commonly referred to as handler or listener functions.

function handleUnitClick (unit) {
  console.log('Unit Clicked:', unit.id);
}

// Bind the handler function to the `unit:click` event:
map.on('unit:click', handleUnitClick);

Arguments

UnitMap.off([event], [callback], [context])

Remove a previously-bound callback function. If no context is specified, all versions of the callback with different contexts will be removed. If no callback is specified, all callbacks for the event will be removed. If no event is specified, callbacks for all events will be removed.

// Create a named function to handle the event.
// These are commonly referred to as handler or listener functions.

function handleUnitClick (unit) {
  console.log("Unit Clicked:", unit.id);
}

// Bind the handler function to the `unit:click` event:
map.on("unit:click", handleUnitClick);

// Unbind the handler function from the `unit:click` event:
map.off("unit:click", handleUnitClick);

Arguments