[ios] Add MGLMapView.showsScale to control scale bar visibility (#11335)

- Fixes scale bar not being visible until a camera change event.
- Adds IBInspectable for scale bar visibility.
- Add tests of the scale bar being added to the map view

8 files changed, 112 insertions, 13 deletions

diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index b0f3e741e6..95759a2f9b 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -49,6 +49,8 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 * Long-pressing the attribution button causes the SDK’s version number to be displayed in the action sheet that appears. ([#10650](https://github.com/mapbox/mapbox-gl-native/pull/10650))
 * Reduced offline download size for styles with symbol layers that render only icons, and no text. ([#11055](https://github.com/mapbox/mapbox-gl-native/pull/11055))
 * Added haptic feedback that occurs when the user rotates the map to due north, configurable via `MGLMapView.hapticFeedbackEnabled`. ([#10847](https://github.com/mapbox/mapbox-gl-native/pull/10847))
+* Added `MGLMapView.showsScale` as the recommended way to show the scale bar. This property can be set directly in Interface Builder. ([#11335](https://github.com/mapbox/mapbox-gl-native/pull/11335))
+* Fixed an issue where the scale bar would not appear until the map had moved. ([#11335](https://github.com/mapbox/mapbox-gl-native/pull/11335))
 
 ## 3.7.5 - February 16, 2018
 
diff --git a/platform/ios/app/MBXViewController.m b/platform/ios/app/MBXViewController.m
index 5b9363af27..4da810a7af 100644
--- a/platform/ios/app/MBXViewController.m
+++ b/platform/ios/app/MBXViewController.m
@@ -164,7 +164,7 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
     [self restoreState:nil];
 
     self.debugLoggingEnabled = [[NSUserDefaults standardUserDefaults] boolForKey:@"MGLMapboxMetricsDebugLoggingEnabled"];
-    self.mapView.scaleBar.hidden = NO;
+    self.mapView.showsScale = YES;
     self.mapView.showsUserHeadingIndicator = YES;
     if ([UIFont respondsToSelector:@selector(monospacedDigitSystemFontOfSize:weight:)]) {
         self.hudLabel.titleLabel.font = [UIFont monospacedDigitSystemFontOfSize:10 weight:UIFontWeightRegular];
diff --git a/platform/ios/ios.xcodeproj/project.pbxproj b/platform/ios/ios.xcodeproj/project.pbxproj
index f19047cdc9..b2d89fe962 100644
--- a/platform/ios/ios.xcodeproj/project.pbxproj
+++ b/platform/ios/ios.xcodeproj/project.pbxproj
@@ -313,6 +313,7 @@
 		9620BB3B1E69FE1700705A1D /* MGLSDKUpdateChecker.mm in Sources */ = {isa = PBXBuildFile; fileRef = 9620BB371E69FE1700705A1D /* MGLSDKUpdateChecker.mm */; };
 		9654C1261FFC1AB900DB6A19 /* MGLPolyline_Private.h in Headers */ = {isa = PBXBuildFile; fileRef = 9654C1251FFC1AB900DB6A19 /* MGLPolyline_Private.h */; };
 		9654C1291FFC1CCD00DB6A19 /* MGLPolygon_Private.h in Headers */ = {isa = PBXBuildFile; fileRef = 9654C1271FFC1CC000DB6A19 /* MGLPolygon_Private.h */; };
+		9658C155204761FC00D8A674 /* MGLMapViewScaleBarTests.m in Sources */ = {isa = PBXBuildFile; fileRef = 9658C154204761FC00D8A674 /* MGLMapViewScaleBarTests.m */; };
 		966FCF4C1F3A5C9200F2B6DE /* MGLUserLocationHeadingBeamLayer.h in Headers */ = {isa = PBXBuildFile; fileRef = 966FCF4A1F3A5C9200F2B6DE /* MGLUserLocationHeadingBeamLayer.h */; };
 		966FCF4E1F3A5C9200F2B6DE /* MGLUserLocationHeadingBeamLayer.m in Sources */ = {isa = PBXBuildFile; fileRef = 966FCF4B1F3A5C9200F2B6DE /* MGLUserLocationHeadingBeamLayer.m */; };
 		966FCF4F1F3A5C9200F2B6DE /* MGLUserLocationHeadingBeamLayer.m in Sources */ = {isa = PBXBuildFile; fileRef = 966FCF4B1F3A5C9200F2B6DE /* MGLUserLocationHeadingBeamLayer.m */; };
@@ -952,6 +953,7 @@
 		9620BB371E69FE1700705A1D /* MGLSDKUpdateChecker.mm */ = {isa = PBXFileReference; explicitFileType = sourcecode.cpp.objcpp; fileEncoding = 4; path = MGLSDKUpdateChecker.mm; sourceTree = "<group>"; };
 		9654C1251FFC1AB900DB6A19 /* MGLPolyline_Private.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLPolyline_Private.h; sourceTree = "<group>"; };
 		9654C1271FFC1CC000DB6A19 /* MGLPolygon_Private.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLPolygon_Private.h; sourceTree = "<group>"; };
+		9658C154204761FC00D8A674 /* MGLMapViewScaleBarTests.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MGLMapViewScaleBarTests.m; sourceTree = "<group>"; };
 		9660916B1E5BBFD700A9A03B /* es */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = es; path = es.lproj/Localizable.strings; sourceTree = "<group>"; };
 		9660916C1E5BBFD900A9A03B /* pl */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = pl; path = pl.lproj/Localizable.strings; sourceTree = "<group>"; };
 		9660916D1E5BBFDB00A9A03B /* ru */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = ru; path = ru.lproj/Localizable.strings; sourceTree = "<group>"; };
@@ -1773,24 +1775,25 @@
 				4031ACFD1E9FD26900A3EA26 /* Test Helpers */,
 				409F43FB1E9E77D10048729D /* Swift Integration */,
 				357579811D502AD4000B822E /* Styling */,
-				DAEDC4331D603417000224FF /* MGLAttributionInfoTests.m */,
 				353D23951D0B0DFE002BE09D /* MGLAnnotationViewTests.m */,
+				DAEDC4331D603417000224FF /* MGLAttributionInfoTests.m */,
 				DA35A2C31CCA9F8300E826B2 /* MGLClockDirectionFormatterTests.m */,
 				35D9DDE11DA25EEC00DAAD69 /* MGLCodingTests.m */,
 				DA35A2C41CCA9F8300E826B2 /* MGLCompassDirectionFormatterTests.m */,
 				DA35A2A91CCA058D00E826B2 /* MGLCoordinateFormatterTests.m */,
+				3598544C1E1D38AA00B29F84 /* MGLDistanceFormatterTests.m */,
 				6407D66F1E0085FD00F6A9C3 /* MGLDocumentationExampleTests.swift */,
 				DA1F8F3C1EBD287B00367E42 /* MGLDocumentationGuideTests.swift */,
 				DD58A4C51D822BD000E1F038 /* MGLExpressionTests.mm */,
-				3598544C1E1D38AA00B29F84 /* MGLDistanceFormatterTests.m */,
 				DA0CD58F1CF56F6A00A5F5A5 /* MGLFeatureTests.mm */,
 				DA2E885C1CC0382C00F24E7B /* MGLGeometryTests.mm */,
 				DA5DB1291FABF1EE001C2326 /* MGLMapAccessibilityElementTests.m */,
 				16376B481FFEED010000563E /* MGLMapViewLayoutTests.m */,
+				9658C154204761FC00D8A674 /* MGLMapViewScaleBarTests.m */,
 				35E208A61D24210F00EC9A46 /* MGLNSDataAdditionsTests.m */,
 				1F95931C1E6DE2E900D5B294 /* MGLNSDateAdditionsTests.mm */,
-				DAE7DEC11E245455007505A6 /* MGLNSStringAdditionsTests.m */,
 				96036A0520059BBA00510F3D /* MGLNSOrthographyAdditionsTests.m */,
+				DAE7DEC11E245455007505A6 /* MGLNSStringAdditionsTests.m */,
 				DA2E885D1CC0382C00F24E7B /* MGLOfflinePackTests.m */,
 				DA2E885E1CC0382C00F24E7B /* MGLOfflineRegionTests.m */,
 				55E2AD121E5B125400E8C587 /* MGLOfflineStorageTests.mm */,
@@ -2827,6 +2830,7 @@
 				1F95931D1E6DE2E900D5B294 /* MGLNSDateAdditionsTests.mm in Sources */,
 				DD58A4C61D822BD000E1F038 /* MGLExpressionTests.mm in Sources */,
 				3575798B1D502B0C000B822E /* MGLBackgroundStyleLayerTests.mm in Sources */,
+				9658C155204761FC00D8A674 /* MGLMapViewScaleBarTests.m in Sources */,
 				409D0A0D1ED614CE00C95D0C /* MGLAnnotationViewIntegrationTests.swift in Sources */,
 				DA2E88621CC0382C00F24E7B /* MGLOfflinePackTests.m in Sources */,
 				55E2AD131E5B125400E8C587 /* MGLOfflineStorageTests.mm in Sources */,
diff --git a/platform/ios/src/MGLMapView+IBAdditions.h b/platform/ios/src/MGLMapView+IBAdditions.h
index 6d5351df2b..64016e8319 100644
--- a/platform/ios/src/MGLMapView+IBAdditions.h
+++ b/platform/ios/src/MGLMapView+IBAdditions.h
@@ -44,6 +44,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic) IBInspectable BOOL allowsTilting;
 @property (nonatomic) IBInspectable BOOL showsUserLocation;
 @property (nonatomic) IBInspectable BOOL showsHeading;
+@property (nonatomic) IBInspectable BOOL showsScale;
 
 @end
 
diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 44130f3c6d..52d28d871c 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -221,8 +221,17 @@ MGL_EXPORT IB_DESIGNABLE
 - (IBAction)reloadStyle:(id)sender;
 
 /**
+ A Boolean value indicating whether the map may display scale information.
+
+ The scale bar may not be shown at all zoom levels. The view controlled by this
+ property is available at `scaleBar`. The default value of this property is
+ `NO`.
+ */
+@property (nonatomic, assign) BOOL showsScale;
+
+/**
  A control indicating the scale of the map. The scale bar is positioned in the
- upper-left corner. The scale bar is hidden by default.
+ upper-left corner. Enable the scale bar via `showsScale`.
  */
 @property (nonatomic, readonly) UIView *scaleBar;
 
diff --git a/platform/ios/src/MGLMapView.mm b/platform/ios/src/MGLMapView.mm
index bb8948150f..5a68736ec5 100644
--- a/platform/ios/src/MGLMapView.mm
+++ b/platform/ios/src/MGLMapView.mm
@@ -975,8 +975,8 @@ public:
 - (void)layoutSubviews
 {
     // Calling this here instead of in the scale bar itself because if this is done in the
-    // scale bar instance, it triggers a call to this this `layoutSubviews` method that
-    // calls `_mbglMap->setSize()` just below that triggers rendering update which triggers
+    // scale bar instance, it triggers a call to this `layoutSubviews` method that calls
+    // `_mbglMap->setSize()` just below that triggers rendering update which triggers
     // another scale bar update which causes a rendering update loop and a major performace
     // degradation. The only time the scale bar's intrinsic content size _must_ invalidated
     // is here as a reaction to this object's view dimension changes.
@@ -2362,6 +2362,17 @@ public:
     self.twoFingerDrag.enabled = pitchEnabled;
 }
 
+- (void)setShowsScale:(BOOL)showsScale
+{
+    _showsScale = showsScale;
+    self.scaleBar.hidden = !showsScale;
+
+    if (showsScale)
+    {
+        [self updateScaleBar];
+    }
+}
+
 #pragma mark - Accessibility -
 
 - (NSString *)accessibilityValue
@@ -5413,10 +5424,7 @@ public:
     }
 
     [self updateCompass];
-    
-    if (!self.scaleBar.hidden) {
-        [(MGLScaleBar *)self.scaleBar setMetersPerPoint:[self metersPerPointAtLatitude:self.centerCoordinate.latitude]];
-    }
+    [self updateScaleBar];
 
     if ([self.delegate respondsToSelector:@selector(mapView:regionIsChangingWithReason:)])
     {
@@ -5434,6 +5442,7 @@ public:
     }
 
     [self updateCompass];
+    [self updateScaleBar];
 
     if ( ! [self isSuppressingChangeDelimiters])
     {
@@ -5878,6 +5887,17 @@ public:
     }
 }
 
+- (void)updateScaleBar
+{
+    // Use the `hidden` property (instead of `self.showsScale`) so that we don't
+    // break developers who still rely on the <4.0.0 approach of directly
+    // setting this property.
+    if ( ! self.scaleBar.hidden)
+    {
+        [(MGLScaleBar *)self.scaleBar setMetersPerPoint:[self metersPerPointAtLatitude:self.centerCoordinate.latitude]];
+    }
+}
+
 + (UIImage *)resourceImageNamed:(NSString *)imageName
 {
     UIImage *image = [UIImage imageNamed:imageName
diff --git a/platform/ios/test/MGLMapViewLayoutTests.m b/platform/ios/test/MGLMapViewLayoutTests.m
index e707cfdb41..16f6cdada3 100644
--- a/platform/ios/test/MGLMapViewLayoutTests.m
+++ b/platform/ios/test/MGLMapViewLayoutTests.m
@@ -37,14 +37,15 @@
     self.styleLoadingExpectation = [self expectationWithDescription:@"Map view should finish loading style."];
     [self waitForExpectationsWithTimeout:1 handler:nil];
 
+    self.mapView.showsScale = YES;
+
     //set zoom and heading so that scale bar and compass will be shown
-    [self.mapView setZoomLevel:4.5 animated:NO];
+    [self.mapView setZoomLevel:10.0 animated:NO];
     [self.mapView.camera setHeading:12.0];
 
     //invoke layout
     [self.superView setNeedsLayout];
     [self.superView layoutIfNeeded];
-
 }
 
 - (void)mapView:(MGLMapView *)mapView didFinishLoadingStyle:(MGLStyle *)style {
diff --git a/platform/ios/test/MGLMapViewScaleBarTests.m b/platform/ios/test/MGLMapViewScaleBarTests.m
new file mode 100644
index 0000000000..11d1187263
--- /dev/null
+++ b/platform/ios/test/MGLMapViewScaleBarTests.m
@@ -0,0 +1,62 @@
+#import <Mapbox/Mapbox.h>
+#import <XCTest/XCTest.h>
+
+@interface MGLMapViewScaleBarTests : XCTestCase
+
+@property (nonatomic) MGLMapView *mapView;
+
+@end
+
+@implementation MGLMapViewScaleBarTests
+
+- (void)setUp {
+    [super setUp];
+
+    [MGLAccountManager setAccessToken:@"pk.feedcafedeadbeefbadebede"];
+    NSURL *styleURL = [[NSBundle bundleForClass:[self class]] URLForResource:@"one-liner" withExtension:@"json"];
+    self.mapView = [[MGLMapView alloc] initWithFrame:UIScreen.mainScreen.bounds styleURL:styleURL];
+}
+
+- (void)tearDown {
+    self.mapView = nil;
+
+    [super tearDown];
+}
+
+- (void)testShowsScale {
+    UIView *scaleBar = self.mapView.scaleBar;
+
+    // Scale bar should not be enabled by default.
+    XCTAssertFalse(self.mapView.showsScale);
+    XCTAssertTrue(scaleBar.hidden);
+
+    self.mapView.showsScale = YES;
+
+    XCTAssertFalse(scaleBar.hidden);
+
+    // Scale bar should not be visible at default zoom (~z0), but it should be ready.
+    XCTAssertFalse(CGRectIsEmpty(scaleBar.frame));
+    XCTAssertEqual(scaleBar.alpha, 0);
+
+    self.mapView.zoomLevel = 15;
+    XCTAssertGreaterThan(scaleBar.alpha, 0);
+}
+
+- (void)testDirectlySettingScaleBarViewHiddenProperty {
+    UIView *scaleBar = self.mapView.scaleBar;
+
+    scaleBar.hidden = NO;
+    XCTAssertFalse(scaleBar.hidden);
+
+    // Directly setting `.hidden` after the map has finished initializing will not update the scale bar.
+    XCTAssertTrue(CGRectIsEmpty(scaleBar.frame));
+
+    // ... but triggering any camera event will update it.
+    self.mapView.zoomLevel = 1;
+    XCTAssertFalse(CGRectIsEmpty(scaleBar.frame));
+    XCTAssertEqual(scaleBar.alpha, 0);
+
+    self.mapView.zoomLevel = 15;
+    XCTAssertGreaterThan(scaleBar.alpha, 0);
+}
+@end