WklMap

Dim myWklMap As WklMap
Set myWklMap = Me!ControlName.Object

A data-bound world map of a form: one point per record at its latitude and longitude, with area and color from a value, following the current record like a subform.

None

The map is drawn from Natural Earth data built into the component, in the Equal Earth projection; no map service is contacted, so it works offline and in closed networks. Equal Earth keeps areas true, so points far north and near the equator compare fairly. Country borders follow Natural Earth's view of the de facto situation; ShowBorders = False draws only the land.

The area of a point is proportional to its value: four times the value gives twice the diameter. The largest value gets MaxPointSize; no point is drawn smaller than MinPointSize. The color blends from MinColor (smallest value) to MaxColor (largest), through MidColor when set. Large points are drawn first, so small points stay visible on top.

In Form view the map reads its data when the form opens, on Requery and when a value of LinkMasterFields changes (checked every 300 ms). Design view shows four sample points. A read error is shown in the map and in LastError, never raised. Pointing at a point shows its caption and value; a screen reader reads the points as a list, largest value first.

Extent sets the part of the world: the whole world, the points (auto) or a box in degrees. With AllowZoom the user zooms and pans in Form view; the zoom is not saved, survives Requery and a change of the master record, and ends when code sets Extent. ExtentChanged reports the user's zoom and pan. A report and Design view always show Extent. A region is drawn from Natural Earth at 1:50m, the world at 1:110m.

An ActiveX control: inserted into a form in design view (Form Design › Controls › ActiveX Controls); reports are not supported. VBA reaches it through the Object property of the control, where ControlName is the name of the control on the form.

Private Sub Form_Load()
    With Me!Map1.Object
        .RecordSource = "qrySignInsPerCity"
        .LatitudeField = "Latitude": .LongitudeField = "Longitude"
        .ValueField = "SignIns": .CaptionField = "City": .KeyField = "CityID"
    End With
End Sub
 
Private Sub Map1_PointClick(ByVal Key As Variant, ByVal Value As Variant)
    Me.Details.Form.Filter = "CityID = " & Key
    Me.Details.Form.FilterOn = True
End Sub

None

Property Get RecordSource() As String
Property Let RecordSource(RHS As String)

Gets or sets the table, query or SQL statement of the data.

None

Property value: String – A name or an SQL statement.

Read/write.

None

Declared by WklMap.

Property Get LatitudeField() As String
Property Let LatitudeField(RHS As String)

Gets or sets the field of the latitude.

None

Property value: String – A field name of RecordSource; degrees north, -90 to 90.

A row whose latitude is Null, not a number or outside -90 to 90 is not drawn and is counted in RowsWithoutPosition. Latitude 0 with longitude 0 is a valid position and is drawn; store Null for an unknown position.

Read/write.

None

Declared by WklMap.

Property Get LongitudeField() As String
Property Let LongitudeField(RHS As String)

Gets or sets the field of the longitude.

None

Property value: String – A field name of RecordSource; degrees east, -180 to 180.

Read/write.

None

Declared by WklMap.

Property Get ValueField() As String
Property Let ValueField(RHS As String)

Gets or sets the field whose value sets the area and color of a point.

None

Property value: String – A field name of RecordSource; empty for points of equal size.

A row without a value, with 0 or with a negative value is drawn at the smallest size in the color of the smallest value.

Read/write.

None

Declared by WklMap.

Property Get CaptionField() As String
Property Let CaptionField(RHS As String)

Gets or sets the field shown in the tooltip and read by screen readers.

None

Property value: String – A field name of RecordSource; empty for none.

Read/write.

None

Declared by WklMap.

Property Get KeyField() As String
Property Let KeyField(RHS As String)

Gets or sets the field that PointClick reports.

None

Property value: String – A field name of RecordSource; empty for the row number (1 for the first row).

Read/write.

None

Declared by WklMap.

Property Get Title() As String
Property Let Title(RHS As String)

Gets or sets the title above the map.

None

Property value: String – Any text; empty for none.

Read/write.

None

Declared by WklMap.

Property Get ValueFormat() As String
Property Let ValueFormat(RHS As String)

Gets or sets the number format of the value in the tooltip.

None

Property value: String – A .NET number format such as 0.0 or #,##0; empty for automatic.

Read/write.

None

Declared by WklMap.

Property Get MinPointSize() As Long
Property Let MinPointSize(RHS As Long)

Gets or sets the diameter of the smallest point.

None

Property value: Long – Points (1/72 inch), 2 to 72; default 5.

Setting it above MaxPointSize raises MaxPointSize to the same value, so the two can be set in either order.

Read/write.

None

Declared by WklMap.

Property Get MaxPointSize() As Long
Property Let MaxPointSize(RHS As Long)

Gets or sets the diameter of the point with the largest value.

None

Property value: Long – Points (1/72 inch), 2 to 144; default 30.

Setting it below MinPointSize lowers MinPointSize to the same value.

Read/write.

None

Declared by WklMap.

Property Get MinColor() As OLE_COLOR
Property Let MinColor(RHS As OLE_COLOR)

Gets or sets the color of the smallest value.

None

Property value: OLE_COLOR – An RGB color; system colors are refused.

Read/write.

None

Declared by WklMap.

Property Get MidColor() As Long
Property Let MidColor(RHS As Long)

Gets or sets the color halfway between the smallest and the largest value.

None

Property value: Long – An RGB color, or -1 (the default) for a straight blend from MinColor to MaxColor.

Read/write.

None

Declared by WklMap.

Property Get MaxColor() As OLE_COLOR
Property Let MaxColor(RHS As OLE_COLOR)

Gets or sets the color of the largest value.

None

Property value: OLE_COLOR – An RGB color; the same as MinColor for points of one color.

Read/write.

None

Declared by WklMap.

Property Get ShowBorders() As Boolean
Property Let ShowBorders(RHS As Boolean)

Gets or sets whether country borders are drawn.

None

Property value: Boolean – True (default) draws the borders; False draws only the land.

A map with borders makes a statement about disputed areas, which an application may not want to make. In high contrast mode the borders are always drawn, so the land stays visible.

Read/write.

None

Declared by WklMap.

Property Get LinkMasterFields() As String
Property Let LinkMasterFields(RHS As String)

Gets or sets the fields or controls of the form whose values filter the data.

None

Property value: String – Names separated by semicolons.

Read/write.

None

Declared by WklMap.

Property Get LinkChildFields() As String
Property Let LinkChildFields(RHS As String)

Gets or sets the fields of RecordSource matched with LinkMasterFields.

None

Property value: String – Field names separated by semicolons, as many as in LinkMasterFields.

Read/write.

None

Declared by WklMap.

Sub Requery()

Reads the data again.

None

None

None

Declared by WklMap.

Property Get PointCount() As Long

Gets the number of points drawn.

None

Property value: Long

Read-only.

None

Declared by WklMap.

Property Get RowsWithoutPosition() As Long

Gets the number of rows skipped because their latitude or longitude was missing, not a number or out of range.

None

Property value: Long

Read-only.

None

Declared by WklMap.

Property Get LastError() As String

Gets the text of the last read error.

None

Property value: String – Empty when the data were read.

Read-only.

None

Declared by WklMap.

Property Get MapSource() As String

Gets the data set the map draws now and its version.

None

Property value: String – Natural Earth 5.1.2, ne_110m_admin_0_countries for the world, Natural Earth 5.1.2, ne_50m_admin_0_countries when the part shown is narrower than about four tenths of the world (a continent, a country or a region).

Read-only.

None

Declared by WklMap.

Property Get ColorScheme() As WklColorScheme
Property Let ColorScheme(RHS As WklColorScheme)

Gets or sets the color scheme.

None

Property value: `WklColorScheme` – As for the other components.

The sea takes the background of the scheme, the land and the borders shades between background and text. Points keep their colors from MinColor to MaxColor; in high contrast mode they take the highlight color.

Read/write.

None

Declared by WklMap.

Property Get Extent() As String
Property Let Extent(RHS As String)

Gets or sets the part of the world the map shows.

None

Property value: String – world (the default; also for an empty text), auto (the points with a margin of a tenth of their span on every side, at least 2 degrees, the world without points), or west,south,east,north in degrees with a decimal point, for example 5.5,45,17.5,55.5 for Central Europe.

The text uses a decimal point whatever the regional settings, so a value stored in a table reads the same on every computer. West must be less than east and south less than north: the map has longitude 180 at its left and right edge, so an extent across it is refused with wkeInvalidValue; show such a region up to 180 on one side. The map keeps the aspect of the extent and shows a little more in the direction where the control is wider or taller; VisibleExtent tells what is shown. Setting Extent ends a zoom of the user, also when the text is the same.

Read/write.

' Show the region of the selected customer, and let the user look around.
Me!Map1.Object.Extent = Me!RegionExtent   ' for example "13.3,45.4,16.6,46.9"
Me!Map1.Object.AllowZoom = True

Declared by WklMap.

Property Get VisibleExtent() As String

Gets the part of the world shown now.

None

Property value: String – west,south,east,north in degrees with a decimal point and at most four decimals.

In Form view it is the part on the screen, after the user's zoom and including what the aspect of the control adds to Extent; without a window (a report) it is the part Extent names. Setting it as Extent shows the same part again, so an application can store the user's view and restore it.

Read-only.

None

Declared by WklMap.

Property Get AllowZoom() As Boolean
Property Let AllowZoom(RHS As Boolean)

Gets or sets whether the user zooms and pans the map in Form view.

None

Property value: Boolean – False (the default): the map is a picture. True: the mouse wheel zooms around the mouse pointer, Ctrl+Plus and Ctrl+Minus around the middle, dragging and the arrow keys pan, Home goes back to Extent; the map takes the focus with Tab.

The map never zooms out beyond the world and not closer than about one degree. Setting AllowZoom to False ends a zoom.

Read/write.

None

Declared by WklMap.

Property Get ColorField() As String
Property Let ColorField(RHS As String)

Gets or sets the field whose value sets the color of a point.

None

Property value: String – A field name of RecordSource; empty (the default) to color by ValueField.

With a color field, size and color show two different values, for example the number of sign-ins as the area and the share of failed sign-ins as the color. A row without a color value takes MinColor. The tooltip shows both values, the color value after a middle dot in ColorFormat.

Read/write.

None

Declared by WklMap.

Property Get ColorRange() As String
Property Let ColorRange(RHS As String)

Gets or sets the values that get MinColor and MaxColor.

None

Property value: String – Empty (the default) for the smallest and the largest loaded value, or low,high with a decimal point, for example 0,1 for a share.

A fixed range keeps a color meaning the same value from one load to the next. A value outside the range takes the color of the nearer end. Low must be less than high; another text is refused with wkeInvalidValue.

Read/write.

None

Declared by WklMap.

Property Get ColorFormat() As String
Property Let ColorFormat(RHS As String)

Gets or sets the number format of the color value in the tooltip.

None

Property value: String – A .NET number format such as 0.0%; empty for automatic.

Read/write.

None

Declared by WklMap.

Event PointClick(ByVal Key As Variant, ByVal Value As Variant)

Occurs on a click on a point.

In a form module: Private Sub <ControlName>_PointClick(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklMap.

Event DataLoaded(ByVal Points As Long)

Occurs when the data were read, also after an error.

In a form module: Private Sub <ControlName>_DataLoaded(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklMap.

Event ExtentChanged(ByVal Extent As String)

Occurs after the user zoomed or panned the map, once the new part is drawn.

A drag raises the event once, when the mouse button is released. Setting Extent or AllowZoom by code does not raise it, so the event procedure may set them without starting a loop.

In a form module: Private Sub <ControlName>_ExtentChanged(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklMap.