Class # MobileMapViewer

forsearch

Maps

forsearch

Map --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description A control for viewing maps loaded via a map provider like Google.

Warning

On Android, this control cannot be accessed until its `Opening` event executes. Accessing it before that will result in an `UnsupportedOperationException`.

## Properties

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |----------------------------------------------------------|---------------------------------------------------------------|-----------|--------| | `AccessibilityHint` | `String` | | | | `AccessibilityLabel` | `String` | | | | `ControlCount` | `Integer` | ✓ | | | `Enabled` | `Boolean` | | | | `HasScaleIndicator` | `Boolean` | | | | `Height` | `Integer` | ✓ | | | `Latitude` | `Double` | ✓ | | | `Left` | `Integer` | ✓ | | | `LockBottom` | `Boolean` | | | | `LockLeft` | `Boolean` | | | | `LockRight` | `Boolean` | | | | `LockTop` | `Boolean` | | | | `Longitude` | `Double` | ✓ | | | `MapType` | `MapTypes` | | | | `Name` | `String` | ✓ | | | `Parent` | `MobileUIControl` | ✓ | | | `TintColor` | `ColorGroup` | | | | `Top` | `Integer` | ✓ | | | `TrackMode` | `TrackModes` | | | | `Visible` | `Boolean` | | | | `Width` | `Integer` | ✓ | | | `ZoomRadius` | `Double` | | | ## Methods

table-centered_column_4

| Name | Parameters | Returns | Shared | |----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|--------| | `AddConstraint` | constraint As `iOSLayoutConstraint`, name As `String` = "" | | | | `AddControl` | child As `MobileUIControl`, isBeingAdded As `Boolean` = `False` | | | | `AddLocation` | locations() As `MapLocation` | | | | | `ParamArray` locations() As `MapLocation` | | | | `ClearFocus` | | | | | `Constraint` | name As `String` | `iOSLayoutConstraint` | | | `ControlAt` | index As `Integer` | `MobileUIControl` | | | `Controls` | | `Iterable` | | | `GoToLocation` | latitude As `Double`, longitude As `Double` | | | | `GoToLocation` | location As `MapLocation` | | | | `Handle` | | `Ptr` | | | | type As `HandlesTypes` | `Ptr` | | | `LocationsFromQuery` | query As `String` | `MapLocation()` | | | `Refresh` | | | | | `RemoveConstraint` | constraint As `iOSLayoutConstraint` | | | | | name As `String` | | | | `RemoveControl` | child As `MobileUIControl` | | | | `RemoveLocation` | locations() As `MapLocation` | | | | | `ParamArray` locations() As `MapLocation` | | | | `SetFocus` | | | | | `ToPicture` | | | | | | | `Picture` | | ## Events

table-centered_column_4

| Name | Parameters | Returns | |------------------------------------------------------------|---------------------------------------------------------------------------------------------|---------| | `Closing` | | | | `LocationSelected` | location As `MapLocation` | | | `Opening` | | | | `Pressed` | latitude As `Double`, longitude As `Double` | | | `RequestedPicture` | map As `Picture` | | | `UserLocationChanged` | latitude As `Double`, longitude As `Double` | | ## Enumerations

forsearch

MobileMapViewer.HandleTypes ### HandleTypes > Specifies the type of OS handle you wish to receive for use with the Handle property. > > | Enum | Description | > |-----------|-----------------------------------------------| > | MapView | Provides access to the underlying Map View | > | GoogleMap | Provides access to the underlying Google Map. |

forsearch

MobileMapViewer.MapTypes ### MapTypes > The various ways in which the map to be displayed. > > | Enum | Description | > |-----------|--------------------------------------------| > | RoadMap | A graphical version emphasizing roads. | > | Satellite | Photographic images taken from satellites. | > | Hybrid | The RoadMap and Satellite types combined. |

forsearch

MobileMapViewer.TrackModes ### TrackModes > The ways in which the map can track devices. > > | Enum | Description | > |------|--------------------------------------------| > | None | The map does no tracking. | > | User | The map shows the user's current location. | ## Property descriptions

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

MobileMapViewer.AccessibilityHint **AccessibilityHint** As `String` > The accessibility hint is a longer description that is read aloud when VoiceOver is enabled. > > ``` xojo > Me.AccessibilityHint = "Click to calculate the value and display the next screen." > ``` > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

forsearch

MobileMapViewer.AccessibilityLabel **AccessibilityLabel** As `String` > The accessibility label of of a control is a short name that is read aloud when VoiceOver is enabled. > > ``` xojo > Me.AccessibilityLabel = "Calculate the value." > ```

forsearch

MobileMapViewer.ControlCount **ControlCount** As `Integer` > The number of child controls in the control. > > This property is read-only. > >

> >

> > Important > >

> > This property is supported for iOS only. > >

forsearch

MobileMapViewer.Enabled **Enabled** As `Boolean` > Indicates whether the control is enabled or disabled. > > Disable the button: > > ``` xojo > Button1.Enabled = False > ```

forsearch

MobileMapViewer.HasScaleIndicator **HasScaleIndicator** As `Boolean` > Allows to show or hide a visual element with the scale representation. > >

> >

> > Important > >

> > This is supported for iOS only. > >

forsearch

MobileMapViewer.Height **Height** As `Integer` > The height of the control. > > This property is read-only on iOS.

forsearch

MobileMapViewer.Latitude **Latitude** As `Double` > The angular distance of the center of the map north or south of the equator. > > This property is read-only.

forsearch

MobileMapViewer.Left **Left** As `Integer` > The left position of the control. > > This property is read-only on iOS.

forsearch

MobileMapViewer.LockBottom **LockBottom** As `Boolean` > Determines whether the bottom edge of the control should stay at a set distance from the bottom edge of the parent control, if there is one, or the owning screen. > >

> >

> > Important > >

> > This property is not currently supported for iOS. Use constraints instead. > >

> > This property can be set in the control's Inspector. The following example sets it in code. > > ``` xojo > Me.LockBottom = True > ```

forsearch

MobileMapViewer.LockLeft **LockLeft** As `Boolean` > Determines whether the left edge of the control should stay at a set distance from the left edge of the parent control, if there is one, or the owning screen. > > LockLeft and Locktop default to `True` when you add a new control to a screen. Existing controls will be altered only if LockRight and/or LockBottom are not set. *LockLeft* has no effect unless *LockRight* is `True`. > >

> >

> > Important > >

> > This property is not currently supported for iOS. Use constraints instead. > >

> > This property can be set in the control's Inspector. The following example sets it in code. > > ``` xojo > Me.LockLeft = True > ```

forsearch

MobileMapViewer.LockRight **LockRight** As `Boolean` > Determines whether the right edge of the control should stay at a set distance from the right edge of the parent control, if there is one, or the owning screen. > >

> >

> > Important > >

> > This property is not currently supported for iOS. Use constraints instead. > >

> > This property can be set in the control's Inspector. The following example sets it in code. > > ``` xojo > Me.LockRight = True > ```

forsearch

MobileMapViewer.LockTop **LockTop** As `Boolean` > Determines whether the top edge of the control should stay at a set distance from the top edge of the parent control, if there is one, or the owning screen. > > LockTop and LockLeft default to `True` when you add a control to a screen. Existing controls will be altered only if LockRight and/or LockBottom are not set. *LockTop* has no effect unless *LockBottom* is `True`. > >

> >

> > Important > >

> > This property is not currently supported for iOS. Use constraints instead. > >

> > This property can be set in the control's Inspector. The following example sets it in code. > > ``` xojo > Me.LockTop = True > ```

forsearch

MobileMapViewer.Longitude **Longitude** As `Double` > The angular distance of the center of the map east or west of the meridian at Greenwich, England. > > This property is read-only.

forsearch

MobileMapViewer.MapType **MapType** As `MapTypes` > The type of map being displayed. > > The map can be displayed as a Road, Satellite or Hybrid type. > > Set MapViewer1 to Hybrid: > > ``` xojo > MapViewer1.MapType = MobileMapViewer.MapTypes.Hybrid > ```

forsearch

MobileMapViewer.Name **Name** As `String` > The name of the control. > > This property is read-only.

forsearch

MobileMapViewer.Parent **Parent** As `MobileUIControl` > The parent (sometimes called a "Super") class of the control. > > This property is read-only.

forsearch

MobileMapViewer.TintColor **TintColor** As `ColorGroup` > Changes a control's tint color. > >

> >

> > Important > >

> > This is supported for iOS only. > >

> > On iOS, the following controls support TintColor: > > | Enum | Description | > |-------------|------------------------------------------------------------------------------| > | PopupMenu | The background color will be drawn in the TintColor. | > | ProgressBar | The area indicating the value of the control will be drawn in the TintColor. | > | Slider | The area indicating the value of the control will be drawn in the TintColor. | > | TextArea | The cursor and text highlight color will be drawn in the TintColor. | > | TextField | The cursor and text highlight color will be drawn in the TintColor. |

forsearch

MobileMapViewer.Top **Top** As `Integer` > The top position of the control. > > This property is read-only on iOS.

forsearch

MobileMapViewer.TrackMode **TrackMode** As `TrackModes` > Determines if the user's location is tracked on the map. > > Set MapViewer1 to track the user on the map: > > ``` xojo > MapViewer1.TrackMode = MobileMapViewer.TrackModes.User > ```

forsearch

MobileMapViewer.Visible **Visible** As `Boolean` > Indicates whether the control is visible. > > Make a button invisible: > > ``` xojo > Button1.Visible = False > ```

forsearch

MobileMapViewer.Width **Width** As `Integer` > The width of the control. > > This property is read-only on iOS.

forsearch

MobileMapViewer.ZoomRadius **ZoomRadius** As `Double` > The radius (in kilometers) displayed on the map. > > Set the zoom radius on MapViewer1 to 100 kilometers: > > ``` xojo > MapViewer1.ZoomRadius = 100 > ``` ## Method descriptions

forsearch

MobileMapViewer.AddConstraint **AddConstraint**(constraint As `iOSLayoutConstraint`, name As `String` = "") > Adds a *constraint* to the control. The optional *name* parameter can be used to `remove a constraint` that was added via code. > > This *constraint* is used by child controls that have been added to this control. > >

> >

> > Important > >

> > This is supported for iOS only. > >

forsearch

MobileMapViewer.AddControl **AddControl**(child As `MobileUIControl`, isBeingAdded As `Boolean` = `False`) > Adds a *child* control to the control. When the value of *isBeingAdded* is `True`, the Opening event is triggered for the child control being added. > >

> >

> > Important > >

> > This is supported for iOS only. > >

forsearch

MobileMapViewer.AddLocation **AddLocation**(locations() As `MapLocation`) > Adds the array of `location` objects to the map, indicated by pins. > > Add a location to the map: > > ``` xojo > Var location As New MapLocation("Fenway Park, Boston, MA") > MapViewer1.AddLocation(location) > ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **AddLocation**(`ParamArray` locations() As `MapLocation`) > Adds the `location` objects to the map, indicated by pins. > > The map will automatically set the `ZoomRadius` to fit all add *locations*. > > If you set the `MapLocation.Icon` of the MapLocation before adding it, the `Picture` you set as as icon will be drawn at the location rather than the default pin. > > Add the Grand Canyon and the White House locations to MapViewer1: > > ``` xojo > Var grandCanyon As New MapLocation(36.056595, -112.125092) > Var whiteHouse As New MapLocation(38.897957, -77.036560) > > MapViewer1.AddLocation(grandCanyon, whiteHouse) > ```

forsearch

MobileMapViewer.ClearFocus **ClearFocus** > Removes the focus from the control. > > ``` xojo > TextField1.ClearFocus > ```

forsearch

MobileMapViewer.Constraint **Constraint**(name As `String`) As `iOSLayoutConstraint` > Gets a reference to a named constraint so that you can modify its settings in code. > >

> >

> > Important > >

> > This is supported for iOS only. > >

> > Change an existing (and named) constraint of a control on the Screen: > > ``` xojo > ' "TAWidth" is a width constraint for a TextField that has been given > ' a name in the auto-layout Inspector properties. > Var c As iOSLayoutConstraint = Self.Constraint("TAWidth") > c.Offset = 200 > ```

forsearch

MobileMapViewer.ControlAt **ControlAt**(index As `Integer`) As `MobileUIControl` > Gets the child control at the specified *index*. > >

> >

> > Important > >

> > This is supported for iOS only. > >

forsearch

mobilemapviewer.Controls **Controls** As `Iterable` > Allows you to iterate through all the controls that have been added to this control. > >

> >

> > Important > >

> > This is supported for iOS only. > >

forsearch

MobileMapViewer.GoToLocation **GoToLocation**(latitude As `Double`, longitude As `Double`) > Centers the map on the provided position (*longitude* & *latitude*). > > If either the latitude or longitude are invalid, an `InvalidArgumentException` will occur. > > Show Hobbiton on MapViewer1: > > ``` xojo > MapViewer1.GoToLocation(-37.871826, 175.681283) > ```

forsearch

MobileMapViewer.GoToLocation **GoToLocation**(location As `MapLocation`) > Centers the map on the provided *location*. > > Show Hobbiton on MapViewer1: > > ``` xojo > Var location As New MapLocation(-37.871826, 175.681283) > MapViewer1.GotToLocation(location) > ```

forsearch

MobileMapViewer.Handle **Handle** As `Ptr` > The handle to the underlying native OS control. > >

> >

> > Important > >

> > This is supported for iOS only. > >

**Handle**(type As `HandlesTypes`) As `Ptr` > The handle to the underlying native OS control. > >

> >

> > Important > >

> > This is supported for Android only. > >

forsearch

MobileMapViewer.LocationsFromQuery **LocationsFromQuery**(query As `String`) As `MapLocation()` > Returns an array of MapLocations based upon the *query* passed. > > Find all the McDonalds locations near the center of the map currently being displayed and add them to it: > > ``` xojo > Var locationsFound() As MapLocation > locationsFound = MapViewer1.LocationsFromQuery("McDonalds") > MapViewer1.AddLocation(locationsFound) > ```

forsearch

MobileMapViewer.Refresh **Refresh** > Marks the control so that it will be redrawn during the next event loop. > > Call Refresh to force a Canvas to redraw itself: > > ``` xojo > Canvas1.Refresh > ```

forsearch

MobileMapViewer.RemoveConstraint **RemoveConstraint**(constraint As `iOSLayoutConstraint`) > Removes a *constraint* from the control. > >

> >

> > Important > >

> > This is supported for iOS only. > >

> >

> > Important > >

> > This is supported for iOS only. > >

forsearch

MobileMapViewer.RemoveControl **RemoveControl**(child As `MobileUIControl`) > Removes the control from the control. > >

> >

> > Important > >

> > This is supported for iOS only. > >

forsearch

MobileMapViewer.RemoveLocation **RemoveLocation**(locations() As `MapLocation`) **RemoveLocation**(`ParamArray` locations() As `MapLocation`) > Removes from the map the MapLocations passed. > > Specifically, the pins that represent the *locations* are removed. > > Remove the location stored in MyHouse from MapViewer1: > > ``` xojo > MapViewer1.RemoveLocation(MyHouse) > ```

forsearch

MobileMapViewer.SetFocus **SetFocus** > Sets the focus to the control. > > ``` xojo > TextField1.SetFocus > ```

forsearch

MobileMapViewer.ToPicture **ToPicture** > Creates a `Picture` from the map. The `Picture` is returned via the `RequestedPicture` event. > >

> >

> > Important > >

> > This method is supported for Android only. > >

**ToPicture** As `Picture` > Creates a `Picture` from the map. > >

> >

> > Important > >

> > This method is supported for iOS only. > >

## Event descriptions

forsearch

MobileMapViewer.Closing **Closing** > Called when the control's layout is closing.

forsearch

MobileMapViewer.LocationSelected **LocationSelected**(location As `MapLocation`) > The user has tapped on a *location* (displayed as a pin) that was added with the `AddLocation` method.

forsearch

MobileMapViewer.Opening **Opening** > Called when the control's layout is opening. > > This is where you typically put initialization code. > > This example in the Opening event of a label sets its text to "Hello": > > ``` xojo > Me.Text = "Hello" > ```

forsearch

MobileMapViewer.Pressed **Pressed**(latitude As `Double`, longitude As `Double`) > The user has long pressed/tapped on the map at the location specified by the *latitude* and *longitude* passed.

forsearch

MobileMapViewer.RequestedPicture **RequestedPicture**(map As `Picture`) > This event is called when `ToPicture` method is called. The event will come with a `Picture` representing the map. > >

> >

> > Important > >

> > This event is supported for Android only. > >

forsearch

MobileMapViewer.UserLocationChanged **UserLocationChanged**(latitude As `Double`, longitude As `Double`) > The location of the user has changed. > > The GPS in most smartphones is very sensitive and as a result, moving the device just very slightly will result in this event being called. ## Notes With the MobileMapViewer, you can `go to a specific location`, `add pins` that represent locations, `remove those locations` and `LocationsFromQuery` for locations by name, address, type, etc. To use MobileMapViewer in Android projects, you need a Google Maps API key from your Google Developer Account and it's required to display Google Maps in Android apps. This can be set in the App Inspector using `MobileApplication.GoogleMapsAPIKey`. For testing purposes during development, the key `demo_map_id` can be used. ## Sample code Show Hobbiton on MapViewer1: ``` xojo MapViewer1.GoToLocation(-37.871826, 175.681283) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Add the Grand Canyon and the White House locations to MapViewer1: ``` xojo Var locations() As MapLocation locations.Add(New MapLocation(36.056595, -112.125092)) 'Grand Canyon locations.Add(New MapLocation(38.897957, -77.036560)) 'White House MapViewer1.AddLocation(locations) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Find all the McDonalds locations near the center of the map currently being displayed and add them to it: ``` xojo Var locationsFound() As MapLocation locationsFound = MapViewer1.LocationsFromQuery("McDonalds") MapViewer1.AddLocation(locationsFound) ``` ## Compatibility | | | |-----------------------|--------| | **Project Types** | Mobile | | **Operating Systems** | All |

`MobileUIControl` parent class; `MapLocation` and `MobileLocation` classes.