Map Module

The Map Module is a demo model,  MapDemo, available to registered users on idBase in the Planimate / Developer Tools region. It demonstrates use of the Map_Paint_Object,  a sophisticated and high performance zoomable/scrollable tiled map display. The Map Paint Object works with the support of a number of Planimate routine operations, system broadcasts, object properties, table structures and system attributes. This model is a working example of how to tie it all together.

Local Portal Attributes

DragX,DragY,DragLong,DragLat	Private attributes used to store the starting point (in panel pixels and in map co-ordinates) during a drag. The drag handler maintains the given map co-ordinate under the cursor.
Longitude,Latitude	The co-ordinate at the center of the map's visible area. This is kept up-to-date with map interactions. This can be set and a broadcast added to trigger the reposition_map change object.
Zoom	Zoom level of the map. This can be set and a broadcast added to trigger the reposition_map change object.

Broadcasts Received

_run_start	When the model starts this triggers an update of object positions. The map is centred at (p.Longitude,p.Latitude). This is needed if the visible panel is the map panel when the model starts since it wont get the _panel_visible broadcast.
_panel_resized	This triggers an update of object positions when the main window is resized, which can cause a shift in the map with use of the "Resize Panel To Window" panel option. The map is kept centred.
_panel_visible	This triggers an update of object positions when the map becomes visible during the run, whether its because its in the main window or a viewport. The map will be centred on (p.Longitude,p.Latitude).
_panel_drag	This triggers the drag handler when a user mouses down and drags the map. During the drag the map and object positions are updated to track the mouse.
_panel_scroll	This implements mouse wheel zoom. If zoom to mouse co-ordinate is enabled, it will reposition the map so the last co-ordinate is at the mouse cursor, otherwise it will keep the map centred..

Broadcasts Sent

None

Configuration Table: t.MapOptions

This table has a single row with settings that configure the map behaviour.

mapObject	This needs to be set to a _paint_objects label which points to the map paint object.
FixedZoom	Boolean, if false the map works in variable zoom mode where the model specifies the longitude range and the map calculates the appropriate zoom. If true, the map works in fixed zoom mode where the model specifies a co-ordinate and zoom level and the map calculates the longitude range. Fixed zoom is generally best and required if you wish the map to track the mouse cursor position as you zoom in and out.
TileSet	A text cell (can be a label if required) which names the tileset. The map will look for tiles in a folder of this name or a DB file of that name, depending on the Map Paint Object's "Fetch Tiles From DB File" option. DB files are the recommended format for tilesets as it avoids the filesystem overheads of many thousands of individual tile files.
MinZoom	The minimum zoom level (most zoomed out level) that the user can zoom out to. 0 is the "world" level where one 256x256 tile is the whole world, but since a map view is typically bigger than a tile, it would very likely be more like 2 or 3 for the whole world. In a model focussed on a region you want the minimum zoom level set so the whole region is covered and not much more.
MaxZoom	The maximum zoom level (most zoomed in level) that the user can zoom in to. This depends on how many zoom levels of tiles you supply which will in turn depend on the level of geographic detail the model requires. Planimate will upscale tiles if the map option is enabled. This means you can have detailed tiles at multiple specific regions and coarser tiles at other, the platform combines the best it can get at any particular location.
ZoomToCursor	If this boolean is false then the map zooms in and out based on keeping the last clicked location centred in the view. If true then the map zooms in and out in a way that keeps the location the cursor at under the cursor. Be aware that if the user zooms out too far, the map will clip to the edges and the position under the cursor will change. As long as the mouse isn't moved (much), when the user zooms back in it will go back to the location it was at. Setting a MinZoom pertinent to the model is recommended to minimise this.
MinIconScale, MaxIconScale	Values which should be set as percentages. The demo includes basic scaling of item and portal icons so their size grows and shrinks in proportion to the level of zoom of the map. In detailed models this can keep objects such as berths and ships in proportion with their surrounding geography. These values set the minimum and maximum scale factor ranges, defaults being 25% for minimum and 400% for maximum. In a complex model you may have different scales for different features (eg: berths vs. ships) and you will need to extend the handler code for this.
MinIconLevel	This sets the minimum zoom level which icons (object and item) are displayed. If the map zoom level is less than this value, the icons are hidden, something you may want when zooming out. As with the scaling, in a complex model you might customise this to have various levels of minimum zoom for different features.
UnityScaleLevel	A value which sets the zoom level at which the object/item icons in this demo are at a proportion of 1 object/item pixel to 1 map tile pixel. In a model where the object and item items are to line up accurately with map features, this value may well need to differ for the different locations and items and you would need to extend the map code to handle each case separately. Such an extention could also incorporate loading different icons at different levels of zoom as scaling the one icon up or down too much does not give the best results.