Purpose
Returns coordinate or distance information about a Map window. You can call this function from the MapBasic window in MapInfo Pro.
Syntax
MapperInfo( window_id, attribute )window_id is an integer window identifier.
attribute is an integer code, indicating which type of information should be returned. See table below for values.
Return Value
Float, logical, or string, depending on the attribute parameter.
Description
The MapperInfo() function returns information about a Map window.
The window_id parameter specifies which Map window to query. To obtain a window identifier, call the FrontWindow() function immediately after opening a window, or call the WindowID() function at any time after the window's creation.
There are several numeric attributes that MapperInfo() can return about any given Map window. The attribute parameter tells the MapperInfo() function which Map window statistic to return. The attribute parameter should be one of the codes from the following table; codes are defined in MAPBASIC.DEF.
| attribute setting | ID | MapperInfo() Return Value |
|---|---|---|
| MAPPER_INFO_ZOOM | 1 | The Map window's current zoom value (for example, the East-West distance currently displayed in the Map window), specified in MapBasic's current distance units; see Set Distance Units statement. |
| MAPPER_INFO_SCALE | 2 | The Map window's current scale, defined in terms of the number of map distance units (for example, Miles) per paper unit (for example, Inches) displayed in the window. This returns a value in MapBasic's current distance units. |
| MAPPER_INFO_CENTERX | 3 | The x-coordinate of the Map window's center. |
| MAPPER_INFO_CENTERY | 4 | The y-coordinate of the Map window's center. |
| MAPPER_INFO_MINX | 5 | The smallest x-coordinate shown in the window. |
| MAPPER_INFO_MINY | 6 | The smallest y-coordinate shown in the window. |
| MAPPER_INFO_MAXX | 7 | The largest x-coordinate shown in the window. |
| MAPPER_INFO_MAXY | 8 | The largest y-coordinate shown in the window. |
| MAPPER_INFO_LAYERS | 9 | Returns number of layers in the Map window as a SmallInt (excludes the cosmetic layer and group layers). |
| MAPPER_INFO_EDIT_LAYER | 10 | A SmallInt indicating the number of the currently-editable layer. A value of zero means that the Cosmetic layer is editable. A value of -1 means that no layer is editable. |
| MAPPER_INFO_XYUNITS | 11 | String representing the map's abbreviated coordinate unit name, for example, "degree". |
| MAPPER_INFO_DISTUNITS | 12 | String representing the map's abbreviated distance unit name, for example, "mi" for miles. |
| MAPPER_INFO_AREAUNITS | 13 | String representing the map's abbreviated area unit name, for example, "sq mi" for square miles. |
| MAPPER_INFO_SCROLLBARS | 14 | Logical value indicating whether the Map window shows scrollbars. |
| MAPPER_INFO_DISPLAY | 15 | Small integer, indicating what aspect of the map is displayed on the status bar. Corresponds to Set Map Display. Return value will be one of these:
|
| MAPPER_INFO_NUM_THEMATIC | 16 | Small integer, indicating the number of thematic layers in this Map window. |
| MAPPER_INFO_COORDSYS_CLAUSE | 17 | string result, indicating the window's CoordSys clause. |
| MAPPER_INFO_COORDSYS_NAME | 18 | String result, representing the name of the map's CoordSys as listed in MAPINFOW.PRJ (but without the optional "\p..." suffix that appears in MAPINFOW.PRJ). Returns empty string if CoordSys is not found in MAPINFOW.PRJ. |
| MAPPER_INFO_MOVE_DUPLICATE_NODES | 19 | Small integer, indicating whether duplicate nodes should be moved when reshaping objects in this Map window. If the value is 0, duplicate nodes are not moved. If the value is 1, any duplicate nodes within the same layer will be moved. To return to using the default from the map preferences, call Set Map Move Nodes Default. |
| MAPPER_INFO_DIST_CALC_TYPE | 20 | Small integer, indicating type of calculation to use for distance, length, perimeter, and area calculations for mapper. Corresponds to Set Map Distance Type. Return values include:
|
| MAPPER_INFO_DISPLAY_DMS | 21 | Small integer, indicating whether the map displays coordinates in decimal degrees, DMS (degrees, minutes, seconds), or Military Grid Reference System or USNG (US National Grid) format. Return value is one of the following:
|
| MAPPER_INFO_COORDSYS_CLAUSE_WITH_BOUNDS | 22 | String result, indicating the window's CoordSys clause including the bounds. |
| MAPPER_INFO_CLIP_TYPE | 23 | The type of clipping being implemented. Choices include:
|
| MAPPER_INFO_CLIP_REGION | 24 | Returns a string to indicate if a clip region is enabled. Returns the string "on" if a clip region is enabled in the Mapper window. Otherwise, it returns the string "off". |
| MAPPER_INFO_REPROJECTION | 25 | String value indicating the current value of the reprojection mode. The value can be either:
|
| MAPPER_INFO_RESAMPLING | 26 | String value indicating the method for calculating the pixel values of the source image being reprojected. The value can be either:
|
| MAPPER_INFO_MERGE_MAP | 27 | String value: the string of MapBasic statements that a user needs to merge one map window into the current map window. |
| MAPPER_INFO_ALL_LAYERS | 28 | This will return the count of layers and group layers (includes all nested layers and group layers) |
| MAPPER_INFO_GROUPLAYERS | 29 | This will return the count of all group layers (includes nested group layers) |
| MAPPER_INFO_LABELS_SELECTABLE | 30 | Logical value indicating whether labels can be selected in the Map window. |
| MAPPER_INFO_HAS_CUSTOM_LABELS | 31 | Logical value, representing whether the map has custom labels or not. |
| MAPPER_INFO_CARTO_SCALE | 32 | Float value of the cartographic scale value calculate by MapInfo Pro before it is rounded for display. |
| MAPPER_INFO_CARTO_SCALE_EXPR | 33 | String expression of the cartographic scale similar to how it is displayed in the Map window's status bar, e.g., if the cartographic scale is 945,000, the string expression returned is "1:945,000". The string is formatted using the Regional settings for number formatting. |
| MAPPER_INFO_TIME_ENABLED | 35 | Logical – is time |
| MAPPER_INFO_TIME_START | 36 |
DateTime – starting time or first time period Note: the date or time portion may not be used depending on the layer time settings |
| MAPPER_INFO_TIME_END | 37 |
DateTime – ending time of last time period Note: the date or time portion may not be used depending on the layer time settings |
| MAPPER_INFO_TIME_INTERVAL | 38 | Integer - How long each time period should be |
| MAPPER_INFO_TIME_INTERVAL_UNIT | 39 | String - Units of the interval |
| MAPPER_INFO_TIME_STEP | 40 | Integer - number of units the start of the next time period will be from the previous one |
| MAPPER_INFO_TIME_STEP_UNIT | 41 | String - Units of the step |
| MAPPER_INFO_TIME_SNAP | 42 | Logical – should the start and end exent be snapped to nearest time unit |
| MAPPER_INFO_TIME_SNAP_UNIT | 43 | String - Units to Snap to |
| MAPPER_INFO_TIME_START_INCLUDE | 44 | Logical – when constructing a layer time query, should there be a start condition against the time period. If False, all date from the extent start will be included |
| MAPPER_INFO_TIME_START_INCLUSIVE | 45 | Logical - when constructing a layer time query, should the start condition include the time period start (>=), or not (>) |
| MAPPER_INFO_TIME_END_INCLUDE | 46 |
Logical – when constructing a layer time query, should there be an end condition against the time period. If False, all date up to the extent end will be included
|
| MAPPER_INFO_TIME_END_INCLUSIVE | 47 | Logical - when constructing a layer time query, should the end condition include the time period end (<=), or not (<) |
| MAPPER_INFO_TIME_PLAYBACK_SPEED | 48 | Float – number of milliseconds delay when playing time periods |
| MAPPER_INFO_TIME_PLAYBACK_DIRECTION | 49 | Integer – forward (1), backward (-1) used |
| MAPPER_INFO_TIME_PLAYBACK_REVERSE | 50 | Logical – when playing time periods and the end is reached, reverse the direction and keep playing. Applies when Repeat is true |
| MAPPER_INFO_TIME_PLAYBACK_REPEAT | 51 | Logical – continually repeat playback |
| MAPPER_INFO_TIME_PERIOD_COUNT | 52 | Integer - number of time periods |
| MAPPER_INFO_TIME_CURRENT_PERIOD | 53 | Integer – current time period being shown on map |
| MAPPER_INFO_TIME_PERIOD_START | 54 | DateTime - the start time of the specified time period. Note: this integer property requires a third parameter to specify which time period. This third parameter is an integer time period from 1 to MAPPER_INFO_TIME_PERIOD_COUNT |
| MAPPER_INFO_TIME_PERIOD_END | 55 |
DateTime - the end time of the specified time period. Note: this integer property requires a third parameter to specify which time period. This third parameter is an integer time period from 1 to MAPPER_INFO_TIME_PERIOD_COUNT |
| MAPPER_INFO_TIME_FORMAT | 56 |
DateTime format string eg “g” or “yyyymmdd” Can be used in MapBasic FormatDateTime$() function. Calculated based on Map Time interval and snapping. |
| MAPPER_INFO_TIME_FORMAT_TYPE | 57 |
Set Map window {_windowId} time format type [begin|end|both
|
| MAPPER_INFO_TIME_EXTENT_HAS_DATE | 58 | Logical - Returns True if any of the time enabled layers have a time start type of date or datetime or date plus time |
| MAPPER_INFO_TIME_EXTENT_HAS_TIME | 59 | Logical - Returns True if any of the time enabled layers have a time start type of time or datetime or date plus time |
| MAPPER_INFO_TIME_EXTENT_FROM | 60 |
Integer – Returns from where the extents should be taken. -1 = Auto (all layers), 0 (custom), and 1-n (time layer index, not layer ID. Example if map has 3 layers and 2 are time layers then user need to provide the index of time layer out of 2.) |
| MAPPER_INFO_TIME_CURRENT_START_EXTENT | 61 | DateTime – Returns current time period start extent. |
| MAPPER_INFO_TIME_CURRENT_END_EXTENT | 62 |
DateTime – Returns current time period end extent.
|
| MAPPER_INFO_TIME_CUSTOM_TIMEPERIOD | 63 | Logical – Returns if current time period is custom or not. |
| MAPPER_INFO_TIME_LAYER_N | 64 |
Integer – Returns the layer id of the Nth time layer. This needs a 3rd argument which is 1 based time layer index (not layer id). Example: MapperInfo(frontwindow(), 64, 1) ‘This will return layer id of 1st time layer in map. |
| MAPPER_INFO_NUM_ADORNMENTS | 200 | This will return an integer representing the number of adornments associated with a mapper. Use some value suitably outside the normal range for MapperInfo, such as 100. |
| MAPPER_INFO_ADORNMENT+n | 201 | This will return the WindowID of a given adornment associated with the Mapper. |
When you call MapperInfo() to obtain coordinate values (for example, by specifying MAPPER_INFO_CENTERX as the attribute), the value returned represents a coordinate in MapBasic's current coordinate system, which may be different from the coordinate system of the Map window. Use the Set CoordSys statement to specify a different coordinate system.
A setting for each Map window and providing MapBasic support to set and get the current setting for each mapper. During Reshape, the move duplicate nodes can be set to none or move all duplicates within the same layer.
Whenever a new Map window is created, the initial move duplicate nodes setting will be retrieved from the mapper preference (Options / Preference / Map Window / Move Duplicate Nodes in).
An existing Map window can be queried for its current Move Duplicate Nodes setting using a new attribute in MapperInfo() function.
The current state can be changed for a mapper window using the Set Map statement.
Coordinate Value Returns
MapperInfo() does not return coordinates (for example MINX, MAXX, MINY, MAXY) in the units set for the map window. Instead, the coordinate values are returned in the units of the internal coordinate system of the MapInfo Pro session or the MapBasic application that calls the function (if the coordinate system was changed within the application). Also, the MAPPER_INFO_XYUNITS attribute returns the units that are used to display the cursor location in the Status Bar (set by using Set Map Window Frontwindow() XY Units).
Clip Region Information
Beginning with MapInfo Pro 6.0, there are three methods that are used for Clip Region functionality. The MAPPER_INFO_CLIP_OVERLAY (2) method is the method that has been the only option until MapInfo Pro 6.0. Using this method, the Overlap() function (Erase Outside Target command) is used internally. Since the Overlap() function cannot produce result with Text objects, text objects are never clipped. For Point objects, a simple point in region test is performed to either include or exclude the Point. Label objects are treated similar to Point objects and are either completely displayed (is the label point is inside the clip region object) or ignored. Since the clipping is done at the spatial object level, styles (wide lines, symbols, text) are never clipped.
The MAPPER_INFO_CLIP_DISPLAY_ALL (0) method uses the Windows Display to perform the clipping. All object types are clipped. Thematics, rasters, and grids are also clipped. Styles (wide lines, symbols, text) are always clipped. This is the default clipping type.
The MAPPER_INFO_CLIP_DISPLAY_POLYOBJ (1) uses the Windows Display to selectively perform clipping which mimics the functionality produced by MAPPER_INFO_CLIP_OVERLAY (2). Windows Display Clipping is used to clip all Poly Objects (Regions and Polylines) and objects than can be converted to Poly Objects (rectangles, rounded rectangles, ellipses, and arcs). These objects will always have their symbology clipped. Points, Labels, and Text are treated as they would be in the MAPPER_INFO_CLIP_OVERLAY (2) method. In general, this method should provide better performance that the MAPPER_INFO_CLIP_OVERLAY (2) method.
Error Conditions
ERR_BAD_WINDOW (590) error generated if parameter is not a valid window number.
ERR_FCN_ARG_RANGE (644) error generated if an argument is outside of the valid range.
ERR_WANT_MAPPER_WIN (313) error generated if window id is not a Map window.
See Also:
LayerInfo() function, Set Distance Units statement, Set Map statement