MapMarkerHandle

Handle for fluent configuration of marker positioning, screen sizing, zoom scaling, pivot, and visibility on MapCanvas.

Overview

MapMarkerHandle provides a fluent configuration handle for widgets added as markers to a MapCanvas.

Key features: - Repositioning in map coordinates (position) or projected external world coordinates (projectedPosition). - Fixed screen-space sizing with min/max zoom clamping (screenSize, minScreenSize, maxScreenSize). - Dynamic zoom scaling relative to a reference zoom factor (zoomScaling). - Normalized pivot point adjustment (pivot) and viewport culling (cullOutsideViewport). - Zoom-level LOD visibility ranges (visibleZoom).

Fluent Marker Configuration with Handle

MapMarkerHandle<MapMarker> handle = map.addMarker("home", 128.0f, 256.0f, "Base")
    .screenSize(32.0f, 32.0f)
    .pivot(0.5f, 1.0f);

Related links

• AnchorWidget: Spatial anchor pinning a screen-space UI widget to 3D/2D world coordinates with zoom scaling, pivot, and viewport culling.
• MapCanvas: Interactive 2D map widget extending WorldCanvas with map sizing, texture and grid layers, coordinate projection, and marker handles.
• MapMarker: Neutral base marker shell for MapCanvas supporting custom content, text labels, selection, and highlighting.

API

MapMarkerHandle::anchor()

Returns the underlying low-level AnchorWidget managing this marker.

Returns AnchorWidget: The managing AnchorWidget..

MapMarkerHandle::cullOutsideViewport(boolean)

Enables or disables automatic culling when the marker is outside the visible viewport.

Parameter	Type	Description
cullOutsideViewport	boolean	Whether to automatically hide the marker when outside the viewport.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::id()

Returns the unique string identifier of this marker within the map.

Returns String: The string identifier or text..

MapMarkerHandle::mapX()

Returns the X coordinate of the marker in map coordinate space.

Returns float: The floating-point coordinate or dimension value..

MapMarkerHandle::mapY()

Returns the Y coordinate of the marker in map coordinate space.

Returns float: The floating-point coordinate or dimension value..

MapMarkerHandle::maxScreenSize(float, float)

Sets maximum screen dimensions to prevent marker over-expanding at high zoom.

Parameter	Type	Description
width	float	Width dimension.
height	float	Height dimension.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::minScreenSize(float, float)

Sets minimum screen dimensions to prevent marker over-shrinking at low zoom.

Parameter	Type	Description
width	float	Width dimension.
height	float	Height dimension.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::pivot(float, float)

Sets the normalized anchor pivot point (0.0 to 1.0) inside the marker bounds.

Parameter	Type	Description
x	float	Horizontal X coordinate.
y	float	Vertical Y coordinate.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::position(float, float)

Positions the marker in map coordinate space.

Parameter	Type	Description
mapX	float	Target X coordinate in map coordinate units.
mapY	float	Target Y coordinate in map coordinate units.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::priority()

Returns the user-defined priority value of this marker.

Returns int: The integer count value..

MapMarkerHandle::priority(int)

Sets the marker sorting priority value.

Parameter	Type	Description
priority	int	Marker sorting and clustering priority value.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::projectedPosition(float, float)

Positions the marker in external world coordinates projected via MapCanvas projection.

Parameter	Type	Description
worldX	float	Target X coordinate in external world units.
worldY	float	Target Y coordinate in external world units.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::screenSize(float, float)

Sets the base fixed screen dimensions of this marker in UI pixels.

Parameter	Type	Description
width	float	Width dimension.
height	float	Height dimension.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::visible(boolean)

Sets the manual visibility flag of this marker.

Parameter	Type	Description
visible	boolean	Visibility flag.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::visibleZoom(float, float)

Restricts marker visibility to the specified zoom range.

Parameter	Type	Description
minZoom	float	Minimum allowed zoom scale factor.
maxZoom	float	Maximum allowed zoom scale factor.

Returns MapMarkerHandle: This instance for chaining..

MapMarkerHandle::widget()

Returns the UI widget rendered as this marker.

Returns Widget: The T value..

MapMarkerHandle::zoomScaling(boolean, float)

Configures dynamic scaling of the marker size relative to map zoom.

Parameter	Type	Description
zoomScaling	boolean	True to scale marker size dynamically with zoom.
referenceZoom	float	Zoom level at which marker displays at base screen dimensions.

Returns MapMarkerHandle: This instance for chaining..