GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg.

1 / 13

GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1

2014-11-29

1. Introduction
All our management applications have tables and management forms, for companies, clients, customers,
suppliers, employees, etc.
For each one of these entities, we usually keep record of a large amount of information, including its location
(address, city, etc). And with current resources in terms of geolocation, its generally useful to record the
geographic coordinates of that location (latitude and longitude), sometimes a great accuracy is needed.
Thus we can see the locations on the map, note the details at ground level, and calculate routes, particularly
between our location and the location of these entities, and vice versa.

This Control helps us to implement a global solution for all these tasks.
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 2 / 13

The Control consists of a pair of files, both making use of the Google Maps API v3:

 GMaps.dll - Written in VB.NET, it can be incorporated in any WinForms application.

 GMaps.html – HTML with JavaScript code, is required for Maps display tasks, and should be placed in the
Application Startup Folder.

Requirements: The minimum screen resolution is 1360 x 768

2. Usage

Control Source and Test projects are provided in Visual Studio 2008 version, however upgradable by later
versions.
The component DLL is located at …\GMaps_All-in-1\GMaps\bin\Release\GMaps.dll
 Add it to your Toolbox, right-clicking the Toolbox area -> Choose Items… -> Browse -> select the DLL
 In the Solution Explorer, select your Project, open My Project -> References -> Add… -> Browse -> select
GMaps
 Drag the Control (GMaps) from the Toolbox to your Form. Give it a small size, it can be 0;0

The HTML file is located at …\GMaps_All-in-1\GMaps\ GMaps.html

 Copy it to the Application Startup Folder (either IDE project, either Real application).

3. How the Control works

3.1. Types
The Control works with 3 Types of Entities/Points/Markers:
• Type 1 – MyPlace – The owner’s location, company, office, etc. Can be the start or the end of a Route.
• Type 2 – Place2 – The kind of Entity being managed (company/client/customer/supplier/employee).
Can be the start or the end of a Route.
• Type 0 – WayPoint - Up to 8 locations where to pass by, from start to end of a Route operation.

3.2. Geocoding Results

Having one or more Address element(s), like Address, Postal Code, City, Region, Country, etc, and/or a
Latitude and a Longitude, we can perform some Geocoding operations, which returns the following Results
(a String Array):

 Array(0) : ErrorCode – If an error occurs, the Control displays a message. Codes returned:
“0” – Its OK, no errors
“1” – Illegal type
“2” – Name <name> already exist as <type>
“3” – Coordinates <lat>/<lng> already exist as <type>
“4” – MyPlace/Place2 must be defined (when adding a WayPoint)
“5” – Type Latitude
“6” – Type Longitude
“7” – Type any Address element(s)
“8” – Cannot define more than 8 WayPoints
“9” – Incorrect data. Verify Latitude/Longitude
“10” – Incorrect data. Verify Address/City/Country/etc
“11” – Verify Internet connection
“12” – Exception Error message...
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 3 / 13

 Array(1) : Status – Returned by the Geocoder. Possible values are:

• "OK" indicates that no errors occurred; the address was successfully parsed and at least one
geocode was returned.
• "ZERO_RESULTS" indicates that the geocode was successful but returned no results. This may
occur if the geocoder was passed a non-existent address.
• "OVER_QUERY_LIMIT" indicates that you are over your quota.
• "REQUEST_DENIED" indicates that your request was denied.
• "INVALID_REQUEST" generally indicates that the query (address, components or latlng) is
missing.
• "UNKNOWN_ERROR" indicates that the request could not be processed due to a server error.
The request may succeed if you try again.

 Array(2) : Accuracy - Returned by the Geocoder. Possible values are:

• "ROOFTOP" indicates that the returned result is a precise geocode for which we have location
information accurate down to street address precision.
• "RANGE_INTERPOLATED" indicates that the returned result reflects an approximation (usually on
a road) interpolated between two precise points (such as intersections).
Interpolated results are generally returned when rooftop geocodes are unavailable
for a street address.
• "GEOMETRIC_CENTER" indicates that the returned result is the geometric center of a result such
as a polyline (for example, a street) or polygon (region).
• "APPROXIMATE" indicates that the returned result is approximate.

 Array(3) : Formatted Address – Returned by the Geocoder. Human-readable address of the location.
This address is generally composed of one or more address components.

 Array(4) : Latitude - Returned by the Geocoder. A String containing a decimal number, representing
the Latitude of the location. Decimal Separator can be Dot or Comma, depending on Local Culture.

 Array(5) : Longitude - Returned by the Geocoder. A String containing a decimal number,

representing the Longitude of the location. Decimal Separator can be Dot or Comma, depending on
Local Culture.

3.3. Using the Control

 Basically, the Control is used to convert the Address element(s) of the Entity being treated into
Coordinates. This can be achieved without loading the Control, simply by calling a Method (see 3.3.1.).
 But if you want:
• View location(s) on a map (Map or Satellite views)
• Visually adjust any location(s)
• Calculate a Route between two locations, optionally with waypoints
• View the Entity’s location at ground level (StreetView)
• Enter Address element(s) and define location(s) outside your Application Forms
Then the Control must be loaded (see 3.3.2.).

3.3.1. Without Types and Maps

 Having one or more Address element(s), like Address, Postal Code, City, Region, Country, etc, we
can perform a simple Geocoding operation and get the Results. See Method GeoCoding
 Having a Latitude and a Longitude, in decimal format, we can perform a simple Reverse Geocoding
operation and get the Results. See Method GeoReverse
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 4 / 13

3.3.2. With Types and Maps

The Control holds an internal table of 10 possible locations:
 MyPlace
 Place2
 Up to 8 WayPoints
These locations can be loaded into the Control (before calling it – see Method LoadGMaps), or
defined/added inside the Control, through a panel called Details.

Before loading the Control, you can:

 Through Properties MyPlace and Place2, specify alternative tags for those location types
 Through Method SetCenter, override the predefined Initial Map Center
 Clear all Locations previously stored into the Control. See Method Clear
 Store Location(s) of any type (listed above) in the Control. See Method LoadPlace

Within your Form, you can also:

 Call any support Function: PrepFullAddr, Str2DSDot, Str2DSCulture and Coord2DMS
 Take control of any Location change (Load or Adjust operations). See Event GeoResults

4. Dealing with the Control

MyPlace and Place2 tags will be changed to any other previously redefined tags.

 – Shows “Place2” location with maximum zoom, allowing a precise Adjustment of

the location, simply by dragging the icon. Only allowed in Google Maps view.

 – Only allowed within previous operation. Returns to the Google Maps view, showing all
defined and adjusted points.
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 5 / 13

 – Only allowed within other views (Routes/StreetView). Shows a Map (Map or Satellite) with
all defined locations. Dragging Markers will update the Internal Location Table. Locations can be Added or
Updated through the Details panel , which is open in the next example:

 – Shows a Route from “MyPlace” to “Place2”, including all eventually

defined WayPoint(s), and the corresponding Text (driving) itinerary (Directions).
 “MyPlace”, “Place2” and the WayPoints are loaded from the Control’s internal table, which can be updated in
Google Maps view. Dragging start point, end point or waypoints will not update the Internal Location Table.
Route options can be modified through the Route options panel, which is open in the next example:
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 6 / 13

 – Same as above, but from “Place2” to “MyPlace”.

Notice that the routes can be quite different, due to traffic directions.

 – Shows “Place2” location at ground level (StreetView mode).

StreetView options can be modified through the Point of view options panel, which is open in the next
example:
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 7 / 13

 – Shows the Control’s internal table of Locations.

 /
In Google Maps view – – Opens the Details panel, where we can Define or Update
“MyPlace” / “Place2”, or Add / Remove WayPoints, and see all the related information returned by the
Geocoder.
In Route views – – Opens the Route options panel, where we can change some Route
parameters.
In StreetView view – – Opens the Point of view options panel, where we can change the
Camera position options.

 – Closes the Control and returns to your Form, restoring its original size and location
(WindowState) and ControlBox.
Note: The Control is just Closed, not Disposed. So, its internal table of Locations is preserved, and all the
locations defined at your Form’s level will remain active if you call the Control again.
To clear the Control’s table of Locations, you can use the Clear Method, before calling the Control (see
LoadGMaps Method).
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 8 / 13

5. Details panel

In Google Maps view, open this panel ( ) to Define or Update “MyPlace” / “Place2”, or Add /
Remove WayPoints, and see all the related information returned by the Geocoder.
Note: If you type Latitude/Longitude, a Reverse GeoCoding operation is performed, even if Address box(es) are
filled. If Latitude/Longitude are empty, a regular GeoCoding operation is performed.

 – Clears and Enables the input boxes, allowing data typing.

 – When pressed, shows Latitude and Longitude in the format Degreeso Minutes’ Seconds’’.

 – Using the data typed in the input boxes, performs a GeoCoding operation, which, if
sucessful, fills the returned values boxes and Defines or Updates “MyPlace” location.

 – Same as above, for “Place2” location.

 – Using the data typed in the input boxes, performs a GeoCoding operation, which, if
sucessful, fills the returned values boxes , Adds a new WayPoint location and updates the counter on the
right, which shows always the total number of loaded WayPoints.
Note: WayPoints cannot be Updated. Just Added or Deleted.

 – Removes the last defined WayPoint.

 – Removes ALL defined WayPoints.

 – Closes this Details panel.

6. Route options panel

In Route views, open this panel ( ) to modify some Route parameters:

 Travel Mode: Driving, Bicycling or Walking.
 Avoid: HighWays, Trolls, Ferries.
 WayPoints: Optimize and StopOver.
 Provide Route Alternatives (if possible).
Note: In all cases, when you Check/Uncheck a button/box, the Directions Service is called and the the Map and
Directions display are redrawn.

 – Closes this Route options panel.

GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 9 / 13

7. Point of view options panel

In StreetView view, open this panel ( ) to modify the Camera position options:
 Camera heading – The camera heading (horizontal angle) in degrees. North is 0o, East is 90o, South is 180o,
West is 270o.
 Camera pitch – The camera pitch (vertical angle), in degrees from the horizon (0o). Range from -90o (down)
to 90o (up) , although it is possible that not the full range is supported.
Note: In both cases, after sliding the cursor, when you release the mouse, the view is redrawn.

 – Closes the Point of view options panel.

8. Control’s Properties

 MyPlace Default = “MyPlace” WriteOnly Property

Redefines the Tag which shortly describes the owner’s Location/Company/Office, etc.
Don’t exceed +- 14 characters.
Example:
GMaps1.MyPlace = “PortWine Inc.”

 Place2 Default = “Place2” WriteOnly Property

Redefines the Tag which shortly describes the kind of Entity being managed (company/ client/ customer/
supplier/ employee).
Don’t exceed +- 14 characters.
Example:
GMaps1. Place2 = “Customer”

9. Control’s Methods/Functions
 Clear Clears all Location information stored in the Control
Syntax: Clear()
Example:
GMaps1. Clear()

 Coord2DMS Converts a Coordinate from Decimal Degrees format to Degreeso Minutes’

Seconds’’ format
Syntax: Coord2DMS(Coord As String, vLat As Boolean) As String
• Coord - Value to be converted
• vLat - Type of the value. True for Latitude (N/S), False for Longitude (E/W)
Example:
GMaps1. Coord2DMS(“-9.1367298”, False) result: “09o 08’ 12.23’’ W”
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 10 / 13

 GeoCoding Given one or more text Address element(s), returns a String Array containing the
Geocoding Results – see 3.2. Geocoding Results
Syntax: GeoCoding(FullAddr As String) As Array
• FullAddr - The text Address element(s) must be “prepared” into a unique String – see PrepFullAddr
Function
Example – Calling the Method with constants (variables can also be specified):
Dim Res(5) As String
Res = GMaps1.GeoCoding(GMaps1.PrepFullAddr(New String() {“rua augusta, nº 2”, “lisboa”, “portugal”}))
result:
Res(0) : “0” - No errors occurred
Res(1) : “OK” - Status
Res(2) : “ROOFTOP” - Accuracy
Res(3) : “Rua Augusta 2, 1100-053 Lisbon, Portugal” - Formatted Address
Res(4) : “38.7085440” - Latitude
Res(5) : “-9.1367298” - Longitude

Remarks: See PrepFullAddr Function – Note that an input Array can also be used.

 GeoReverse Given a Latitude and a Longitude, returns a String Array containing the Geocoding
Results – see 3.2. Geocoding Results
Syntax: GeoReverse(Latitude As String, Longitude As String) As Array
• Latitude - A String containing a numeric decimal value
• Longitude - A String containing a numeric decimal value
Example:
Dim Res(5) As String
Res = GMaps1.GeoReverse(“38.7085440”, “-9.1367298”)
result: Same as above (GeoCoding)

 LoadGMaps The control is passed to a specific instance of GMaps

Syntax: LoadGMaps()
Example:
GMaps1. LoadGMaps()
Remarks: When the Control’s instance is loaded, the Control becomes Visible, the window is Maximized and
the Form’s ControlBox is Hidden. See also Close Control’s button.

 LoadPlace Loads a Location (MyPlace, Place2 or a WayPoint) into the Control

Syntax: LoadPlace(Type As Byte, [Name As String = “”], [FullAddr As String = “”], _
[Lat As String = “”], [Lng As String = “”] ) As Array
• Type - Type of Location to be loaded: 1 = MyPlace, 2 = Place2, 0 = WayPoint
• Name - Optional. A Name to be associated with the Location
• FullAddr - Optional. A String “prepared” with text Address element(s). See PrepFullAddr Function
• Lat - Optional. A String containing a numeric decimal value for Latitude
• Lng - Optional. A String containing a numeric decimal value for Longitude
Remarks: If Lat/Lng are specified, a Reverse GeoCoding is performed, otherwise, FullAddr will be used for a
regular GeoCoding operation.
Example 1 – Sending a FullAddr for “Place2” (Type = 2):
Dim Res(5) As String
Res = GMaps1.LoadPlace(2, GMaps1.PrepFullAddr(New String() {“rua augusta, nº 2”, “lisboa”, “portugal”}))
result:
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 11 / 13

Res(0) : “0” - No errors occurred

Res(1) : “OK” - Status
Res(2) : “ROOFTOP” - Accuracy
Res(3) : “Rua Augusta 2, 1100-053 Lisbon, Portugal” - Formatted Address
Res(4) : “38.7085440” - Latitude
Res(5) : “-9.1367298” - Longitude
Example 2 – Sending Latitude and Longitude for a WayPoint (Type = 0):
Dim Res(5) As String
Res = GMaps1.LoadPlace(0, , “38.7085440”, “-9.1367298”)
result: Same as above (Example 1)

Note: Creating an Array to put the results, it is only necessary if you want to control, programmatically, the
occurrence of errors.
If there are no errors, the results of all operations of Defining or Adjusting can be controlled through the
GeoResults Event. So, the Method can be simply called this way:
Call GMaps1.LoadPlace(0, , “38.7085440”, “-9.1367298”)

 PrepFullAddr Prepares a String for GeoCoding purpose

Syntax: PrepFullAddr(Addrs As Array) As String
• Addrs - A String Array (of any size) containing the Address element(s)
This Function picks one or more Address element(s) from a String Array, removes some problematic
characters and diacritics, and builds an unique String, separating the elements with a comma
Example 1 – Calling the Function with an inline Array:
GMaps1. PrepFullAddr(New String() {“Rua Fernão de Magalhães, nº 20-5ºDº+”, _
“8365-148”, “Armação de Pêra”, “Algarve”, “Portugal”}))
result:
“RUA FERNAO DE MAGALHAES N 20 5 D , 8365 148, ARMACAO DE PERA, ALGARVE, PORTUGAL”
Example 2 – Calling the Function with an external Array:
Dim MyArray(2) As String
MyArray(0) = “rua tomás anunciação, 44”
MyArray(0) = “Lisboa”
MyArray(0) = “Portugal”
GMaps1. PrepFullAddr(MyArray)
result:
“RUA TOMAS ANUNCIACAO 44, LISBOA, PORTUGAL”
Remarks: Even if the address is just one string, it will have to be declared as Array.
Example: consider an input TextBox1:
GMaps1. PrepFullAddr(New String() {TextBox1.Text})
Note: New String() is not necessary in Visual Studio versions 2010 and later. Above example can be:
GMaps1. PrepFullAddr({TextBox1.Text})

 SetCenter Overrides the predefined Initial Map Center

Syntax: SetCenter( [FullAddr As String = “”], [Lat As String = “”], [Lng As String = “”]
• FullAddr - Required if Lat/Lng are not specified. A String “prepared” with text Address element(s)
(see PrepFullAddr Function) or a simple string, with elements separated by commas,
but with no diacritics
• Lat - Required if FullAddr is not specified. A String containing a numeric decimal value for
Latitude
• Lng - Required if FullAddr is not specified. A String containing a numeric decimal value for
Longitude
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 12 / 13

Examples:
GMaps1. SetCenter(New String() {“Rua Fernão de Magalhães, nº 20-5ºDº+”, _
“8365-148”, “Armação de Pêra”, “Algarve”, “Portugal”}))
GMaps1. SetCenter("Eiffel Tower, Avenue Anatole France, Paris, France")
GMaps1. SetCenter( , “41.148087”, “-8.664355”)
GMaps1. SetCenter( , 41.148087, -8.664355)
Remarks: Initial Map CenterMap becomes visible only when you call the Control without any previous
Location definition

 Str2DSCulture Given a Coordinate, replaces it Decimal Separator (Dot or Comma) with the
Current Culture Decimal Separator
Syntax: Str2DSCulture(Str As String) As String
• Str - A String containing a numeric decimal value
Example 1 – Assume Current Culture Decimal Separator is Comma:
GMaps1.Str2DSCulture(“-9.1367298”) result: “-9,1367298”
GMaps1.Str2DSCulture(“-9,1367298”) result: “-9,1367298”
Example 2 – Assume Current Culture Decimal Separator is Dot:
GMaps1.Str2DSCulture(“-9.1367298”) result: “-9.1367298”
GMaps1.Str2DSCulture(“-9,1367298”) result: “-9.1367298”
Remarks: No need to worry about this. Regardless of what you send, the Control always send Dot to the
Geocoder and returns Current Culture Decimal Separator

 Str2DSDot Given a Coordinate, replaces it Decimal Separator (Dot or Comma) with Dot
Syntax: Str2DSDot(Str As String) As String
• Str - A String containing a numeric decimal value
Example:
GMaps1.Str2DSCulture(“-9.1367298”) result: “-9.1367298”
GMaps1.Str2DSCulture(“-9,1367298”) result: “-9.1367298”
Remarks: No need to worry about this. Regardless of what you send, the Control always send Dot to the
Goecoder and returns Current Culture Decimal Separator

10.Control’s Event
 GeoResults Occurs whenever a Location is Defined or Adjusted (in Google Maps view), and the
Geocoding result Status is “OK”
Syntax: GeoResults(Adjusted As Boolean, Type As Byte, IndexWP As Integer, _
Address As String, Latitude As String, Longitude As String, _
Accuracy As String)
• Adjusted - False – A Location has been Defined
True – A Location has been Adjusted (by dragging the marker)
• Type - 1 – Location type is “MyPlace”
2 – Location type is “Place2”
0 – Location type is WayPoint
• IndexWP - If Location is a WayPoint, its Index ( 0 to 7 ). Otherwise, -1
• Address - The Formatted Address returned by the Geocoder
• Latitude - The Latitude returned by the Geocoder ()
• Longitude - The Longitude returned by the Geocoder ()
• Accuracy - Location's Accuracy returned by the Geocoder
() String containing a decimal number, Decimal Separator is Current Culture format
GMaps v1.1.12 – Google Maps/Routing/StreetView All-in-1 2014©Avelino Ferreira Pg. 13 / 13

Example:
Private Sub GMaps1_GeoResults(ByVal Adjusted As Boolean, ByVal Type As Byte, _
ByVal IndexWP As Integer, ByVal Address As String, ByVal Latitude As String, _
ByVal Longitude As String, ByVal Accuracy As String) Handles GMaps1.GeoResults

‘ Assume you want to update variables Client_Lat, Client_Lng and Client_Addr,

‘ but only when “Place2” is Adjusted with maximum precision (Accuracy). So:

If Type = 2 And Adjusted And Accuracy = "ROOFTOP" Then

Client_Lat = Latitude
Client_Lng = Longitude
Client_Addr = Address
End If

End Sub

11.The HTML/Javascript file

Is required for Maps display tasks, and should be placed in the Application Startup Folder (either IDE project,
either Real application).
4 google.maps classes are used:
 Geocoder – In Google Maps view. Function AddMarker receives data from the Control’s internal Locations
table and creates Markers, which, when Adjusted/dragged, will send feedback to the Control.
Related resources: var Map1, div mapPanel – 100%
 DirectionsService / DirectionsRenderer – In Route views. Function calcRoute picks the Marker’s positions,
sets the start and end of the route and eventual waypoints, draws the appropriate Route (var
Map2, div routePanel – 69.7%) and writes textual instructions (div dirPanel – 30%), according to
the parameters received from the Control
 StreetViewPanorama – In StreetView view. Function initStView picks the Marker’s position of “Place2” and
draws the Map (var Map3, div sviewPanel – 49.8%) and Panorama (div panorPanel – 50%),
according to the parameters received from the Control

< end of document >