Map.h header

#include <ew/core/Map.h>

Namespace ew::core

Map class

class ew::core::Map

A map content object: a raster base image with labelled vector regions drawn over it, plus travel routes between locations and pinned markers. Regions link to location entities and can drill down into sub-maps, so a project's spaces form a navigable hierarchy; routes and a travel speed let the timeline validator check that journeys are physically possible. A first-class content object like anything else in the graph.

Members

ew::core::Map::Map(ContentId id, QString title)

Creates a map with identity id and title, with no base image or regions.

const QString & ew::core::Map::title() const

The map's title.

void ew::core::Map::setTitle(QString title)

Sets the map's title.

const QString & ew::core::Map::imageAssetPath() const

The path (relative to the project's assets folder) of the raster base image; empty if none has been set.

void ew::core::Map::setImageAssetPath(QString imageAssetPath)

Sets the base image asset path (relative to the project's assets folder).

const std::vector< MapRegion > & ew::core::Map::regions() const

The regions drawn over the map, in order.

void ew::core::Map::setRegions(std::vector< MapRegion > regions)

Sets the regions drawn over the map.

void ew::core::Map::addRegion(MapRegion region)

Appends region to the map.

const std::vector< MapRoute > & ew::core::Map::routes() const

The travel routes between locations on the map.

void ew::core::Map::setRoutes(std::vector< MapRoute > routes)

Sets the map's travel routes.

void ew::core::Map::addRoute(MapRoute route)

Appends route to the map.

double ew::core::Map::travelSpeedPerHour() const

The overland travel speed, in distance units per hour, used to turn route distances into travel times. Always positive.

void ew::core::Map::setTravelSpeedPerHour(double speedPerHour)

Sets the travel speed; non-positive values are ignored so the speed stays usable.

const QString & ew::core::Map::distanceUnit() const

The label for the map's distance units (e.g. "km", "miles", "leagues"), for display.

void ew::core::Map::setDistanceUnit(QString distanceUnit)

Sets the label for the map's distance units.

double ew::core::Map::widthDistance() const

The real-world distance (in distance units) spanning the full width of the base image, giving the map a scale for the measurement tool. 0 means the scale is unset. Never negative.

void ew::core::Map::setWidthDistance(double widthDistance)

Sets the map's width distance; negative values are clamped to 0 (unset).

const std::vector< MapPin > & ew::core::Map::pins() const

The pinned markers on the map.

void ew::core::Map::setPins(std::vector< MapPin > pins)

Sets the map's pinned markers.

void ew::core::Map::addPin(MapPin pin)

Appends pin to the map.

MapGridKind ew::core::Map::gridKind() const

The kind of grid overlaid on the map (default: none).

void ew::core::Map::setGridKind(MapGridKind gridKind)

Sets the kind of grid overlaid on the map.

int ew::core::Map::gridColumns() const

The number of grid cells spanning the base image's width, at least one. The row count follows from the image's aspect ratio when the grid is drawn.

void ew::core::Map::setGridColumns(int gridColumns)

Sets the grid column count; values below one are clamped to one.

const std::vector< MapToken > & ew::core::Map::tokens() const

The tokens placed on the map's grid overlay.

void ew::core::Map::setTokens(std::vector< MapToken > tokens)

Sets the tokens placed on the map's grid overlay.

void ew::core::Map::addToken(MapToken token)

Appends token to the map.

MapPin struct

struct ew::core::MapPin

A pin dropped on a map: a labelled marker at a point, carrying a free-text note. Pins mark points of interest that are not full regions – a landmark, a battle site, a story beat.

Members

MapPoint ew::core::MapPin::position

The pin's position in normalized map coordinates.

QString ew::core::MapPin::label

The pin's short label, shown next to the marker.

QString ew::core::MapPin::note

A longer free-text note for the pin.

bool operator==(const MapPin &, const MapPin &)=default

Pins compare equal when position, label, and note all match.

MapPoint struct

struct ew::core::MapPoint

A point on a map in normalized [0,1] coordinates relative to the base image, so regions stay correct at any display size.

Members

double ew::core::MapPoint::x = 0.0

The x coordinate, normalized to [0,1] across the base image's width.

double ew::core::MapPoint::y = 0.0

The y coordinate, normalized to [0,1] across the base image's height.

bool operator==(const MapPoint &, const MapPoint &)=default

Points compare equal when both coordinates match.

MapRegion struct

struct ew::core::MapRegion

A labelled region drawn over a map: a polygon (its vertices, at least three for an area), an optional link to the location entity it depicts (bridging the map to the codex), and an optional link to a sub-map to drill into (world -> country -> city).

Members

QString ew::core::MapRegion::label

The region's display label.

std::vector<MapPoint> ew::core::MapRegion::points

The polygon vertices, in order, in normalized map coordinates.

ContentId ew::core::MapRegion::linkedEntityId

The location entity this region depicts; a null id means none.

ContentId ew::core::MapRegion::linkedMapId

The sub-map this region drills into; a null id means none.

QString ew::core::MapRegion::layer

The layer this region belongs to (e.g. "Political", "Geographic", "Climate"); empty for the default layer. Layers can be toggled visible or hidden.

bool ew::core::MapRegion::revealed = true

Whether this region is revealed to players/readers. Regions default to revealed; hiding one keeps it in the author's view (dimmed) but drops it from the map's Player View, so locations can be revealed progressively as the story unfolds.

MapRoute struct

struct ew::core::MapRoute

A travel route between two location entities, carrying the distance between them (in the map's distance units). Combined with the map's travel speed this yields a travel time, which the timeline validator uses to flag journeys that are physically too fast.

Members

ContentId ew::core::MapRoute::fromEntityId

The location entity at one end of the route.

ContentId ew::core::MapRoute::toEntityId

The location entity at the other end of the route.

double ew::core::MapRoute::distance = 0.0

The distance between the two locations, in the map's distance units (never negative).

bool operator==(const MapRoute &, const MapRoute &)=default

Routes compare equal when both endpoints and the distance match.

MapToken struct

struct ew::core::MapToken

A movable token on a map's battle-map/grid overlay: a labelled counter at a point, an optional colour for quick identification, and an optional link to the codex entity (a character or creature) it represents. Tokens are the pieces moved around during a scene, distinct from the static pins that mark fixed points of interest.

Members

MapPoint ew::core::MapToken::position

The token's position in normalized map coordinates.

QString ew::core::MapToken::label

The token's short label, shown on the counter.

QString ew::core::MapToken::color

The token's colour as a hex string (e.g. "#c04040"); empty selects a default colour.

ContentId ew::core::MapToken::linkedEntityId

The codex entity this token represents; a null id means none.

bool operator==(const MapToken &, const MapToken &)=default

Tokens compare equal when position, label, colour, and linked entity all match.

Enumerations

enum class MapGridKind { None, Square, Hex }

The kind of grid overlaid on a battle map: none, a square grid, or a hex grid. Square and hex grids turn the map into a tactical playing surface for moving tokens across.