/MapView/Map/RMMapContents.h
C Header | 283 lines | 147 code | 58 blank | 78 comment | 0 complexity | c9307c2ad3b4f1f3e068b2f20ad71cf8 MD5 | raw file
1// 2// RMMapContents.h 3// 4// Copyright (c) 2008-2009, Route-Me Contributors 5// All rights reserved. 6// 7// Redistribution and use in source and binary forms, with or without 8// modification, are permitted provided that the following conditions are met: 9// 10// * Redistributions of source code must retain the above copyright notice, this 11// list of conditions and the following disclaimer. 12// * Redistributions in binary form must reproduce the above copyright notice, 13// this list of conditions and the following disclaimer in the documentation 14// and/or other materials provided with the distribution. 15// 16// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 20// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26// POSSIBILITY OF SUCH DAMAGE. 27#import <UIKit/UIKit.h> 28 29#import "RMFoundation.h" 30#import "RMLatLong.h" 31#import "RMTile.h" 32 33#import "RMTilesUpdateDelegate.h" 34 35 36// constants for boundingMask 37enum { 38 // Map can be zoomed out past view limits 39 RMMapNoMinBound = 0, 40 // Minimum map height when zooming out restricted to view height 41 RMMapMinHeightBound = 1, 42 // Minimum map width when zooming out restricted to view width ( default ) 43 RMMapMinWidthBound = 2 44}; 45 46#define kDefaultInitialLatitude -33.858771 47#define kDefaultInitialLongitude 151.201596 48 49#define kDefaultMinimumZoomLevel 0.0 50#define kDefaultMaximumZoomLevel 25.0 51#define kDefaultInitialZoomLevel 13.0 52 53@class RMMarkerManager; 54@class RMProjection; 55@class RMMercatorToScreenProjection; 56@class RMTileImageSet; 57@class RMTileLoader; 58@class RMMapRenderer; 59@class RMMapLayer; 60@class RMLayerCollection; 61@class RMMarker; 62@protocol RMMercatorToTileProjection; 63@protocol RMTileSource; 64 65 66@protocol RMMapContentsAnimationCallback <NSObject> 67@optional 68- (void)animationFinishedWithZoomFactor:(float)zoomFactor near:(CGPoint)p; 69- (void)animationStepped; 70@end 71 72 73/*! \brief The cartographic and data components of a map. Do not retain. 74 75 There is exactly one RMMapContents instance for each RMMapView instance. 76 77 \warning Do not retain an RMMapContents instance. Instead, ask the RMMapView for its contents 78 when you need it. It is an error for an RMMapContents instance to exist without a view, and 79 if you retain the RMMapContents, it can't go away when the RMMapView is released. 80 81 At some point, it's likely that RMMapContents and RMMapView will be merged into one class. 82 83 */ 84@interface RMMapContents : NSObject 85{ 86 /// This is the underlying UIView's layer. 87 CALayer *layer; 88 89 RMMarkerManager *markerManager; 90 /// subview for the image displayed while tiles are loading. Set its contents by providing your own "loading.png". 91 RMMapLayer *background; 92 /// subview for markers and paths 93 RMLayerCollection *overlay; 94 95 /// (guess) the projection object to convert from latitude/longitude to meters. 96 /// Latlong is calculated dynamically from mercatorBounds. 97 RMProjection *projection; 98 99 id<RMMercatorToTileProjection> mercatorToTileProjection; 100// RMTileRect tileBounds; 101 102 /// (guess) converts from projected meters to screen pixel coordinates 103 RMMercatorToScreenProjection *mercatorToScreenProjection; 104 105 /// controls what images are used. Can be changed while the view is visible, but see http://code.google.com/p/route-me/issues/detail?id=12 106 id<RMTileSource> tileSource; 107 108 RMTileImageSet *imagesOnScreen; 109 RMTileLoader *tileLoader; 110 111 RMMapRenderer *renderer; 112 NSUInteger boundingMask; 113 114 /// minimum zoom number allowed for the view. #minZoom and #maxZoom must be within the limits of #tileSource but can be stricter; they are clamped to tilesource limits if needed. 115 float minZoom; 116 /// maximum zoom number allowed for the view. #minZoom and #maxZoom must be within the limits of #tileSource but can be stricter; they are clamped to tilesource limits if needed. 117 float maxZoom; 118 119 float screenScale; 120 121 id<RMTilesUpdateDelegate> tilesUpdateDelegate; 122} 123 124@property (readwrite) CLLocationCoordinate2D mapCenter; 125@property (readwrite) RMProjectedPoint centerProjectedPoint; 126@property (readwrite) RMProjectedRect projectedBounds; 127@property (readonly) RMTileRect tileBounds; 128@property (readonly) CGRect screenBounds; 129@property (readwrite) float metersPerPixel; 130@property (readonly) float scaledMetersPerPixel; 131/// zoom level is clamped to range (minZoom, maxZoom) 132@property (readwrite) float zoom; 133 134@property (nonatomic, readwrite) float minZoom, maxZoom; 135 136@property (nonatomic, readonly) float screenScale; 137 138@property (readonly) RMTileImageSet *imagesOnScreen; 139@property (readonly) RMTileLoader *tileLoader; 140 141@property (readonly) RMProjection *projection; 142@property (readonly) id<RMMercatorToTileProjection> mercatorToTileProjection; 143@property (readonly) RMMercatorToScreenProjection *mercatorToScreenProjection; 144 145@property (retain, readwrite) id<RMTileSource> tileSource; 146@property (retain, readwrite) RMMapRenderer *renderer; 147 148@property (readonly) CALayer *layer; 149 150@property (retain, readwrite) RMMapLayer *background; 151@property (retain, readwrite) RMLayerCollection *overlay; 152@property (retain, readonly) RMMarkerManager *markerManager; 153/// \bug probably shouldn't be retaining this delegate 154@property (nonatomic, retain) id<RMTilesUpdateDelegate> tilesUpdateDelegate; 155@property (readwrite) NSUInteger boundingMask; 156/// The denominator in a cartographic scale like 1/24000, 1/50000, 1/2000000. 157@property (readonly)double scaleDenominator; 158 159// tileDepth defaults to zero. if tiles have no alpha, set this higher, 3 or so, to make zooming smoother 160@property (readwrite, assign) short tileDepth; 161@property (readonly, assign) BOOL fullyLoaded; 162 163- (id)initWithView: (UIView*) view; 164- (id)initWithView: (UIView*) view screenScale:(float)theScreenScale; 165- (id)initWithView: (UIView*) view tilesource:(id<RMTileSource>)newTilesource; 166- (id)initWithView: (UIView*) view tilesource:(id<RMTileSource>)newTilesource screenScale:(float)theScreenScale; 167/// designated initializer 168- (id)initWithView:(UIView*)view 169 tilesource:(id<RMTileSource>)tilesource 170 centerLatLon:(CLLocationCoordinate2D)initialCenter 171 zoomLevel:(float)initialZoomLevel 172 maxZoomLevel:(float)maxZoomLevel 173 minZoomLevel:(float)minZoomLevel 174 backgroundImage:(UIImage *)backgroundImage 175 screenScale:(float)theScreenScale; 176 177/// \deprecated subject to removal at any moment after 0.5 is released 178- (id) initForView: (UIView*) view; 179/// \deprecated subject to removal at any moment after 0.5 is released 180- (id) initForView: (UIView*) view WithLocation:(CLLocationCoordinate2D)latlong; 181/// \deprecated subject to removal at any moment after 0.5 is released 182- (id)initForView:(UIView*)view WithTileSource:(id<RMTileSource>)tileSource WithRenderer:(RMMapRenderer*)renderer LookingAt:(CLLocationCoordinate2D)latlong; 183 184- (void)setFrame:(CGRect)frame; 185 186- (void)handleMemoryWarningNotification:(NSNotification *)notification; 187- (void)didReceiveMemoryWarning; 188 189- (void)moveToLatLong: (CLLocationCoordinate2D)latlong; 190/// \deprecate Use setCenterProjectedPoint: instead. 191- (void)moveToProjectedPoint: (RMProjectedPoint)aPoint; 192 193- (void)moveBy: (CGSize) delta; 194- (void)zoomByFactor: (float) zoomFactor near:(CGPoint) center; 195- (void)zoomInToNextNativeZoomAt:(CGPoint) pivot animated:(BOOL) animated; 196- (void)zoomOutToNextNativeZoomAt:(CGPoint) pivot animated:(BOOL) animated; 197- (void)zoomByFactor: (float) zoomFactor near:(CGPoint) center animated:(BOOL) animated; 198- (void)zoomByFactor: (float) zoomFactor near:(CGPoint) center animated:(BOOL) animated withCallback:(id<RMMapContentsAnimationCallback>)callback; 199 200- (void)zoomInToNextNativeZoomAt:(CGPoint) pivot; 201- (void)zoomOutToNextNativeZoomAt:(CGPoint) pivot; 202- (float)adjustZoomForBoundingMask:(float)zoomFactor; 203- (void)adjustMapPlacementWithScale:(float)aScale; 204- (float)nextNativeZoomFactor; 205- (float)prevNativeZoomFactor; 206 207- (void) drawRect: (CGRect) rect; 208 209//-(void)addLayer: (id<RMMapLayer>) layer above: (id<RMMapLayer>) other; 210//-(void)addLayer: (id<RMMapLayer>) layer below: (id<RMMapLayer>) other; 211//-(void)removeLayer: (id<RMMapLayer>) layer; 212 213// During touch and move operations on the iphone its good practice to 214// hold off on any particularly expensive operations so the user's 215+ (BOOL) performExpensiveOperations; 216+ (void) setPerformExpensiveOperations: (BOOL)p; 217 218- (CGPoint)latLongToPixel:(CLLocationCoordinate2D)latlong; 219- (CGPoint)latLongToPixel:(CLLocationCoordinate2D)latlong withMetersPerPixel:(float)aScale; 220- (RMTilePoint)latLongToTilePoint:(CLLocationCoordinate2D)latlong withMetersPerPixel:(float)aScale; 221- (CLLocationCoordinate2D)pixelToLatLong:(CGPoint)aPixel; 222- (CLLocationCoordinate2D)pixelToLatLong:(CGPoint)aPixel withMetersPerPixel:(float)aScale; 223 224- (void)zoomWithLatLngBoundsNorthEast:(CLLocationCoordinate2D)ne SouthWest:(CLLocationCoordinate2D)se; 225- (void)zoomWithRMMercatorRectBounds:(RMProjectedRect)bounds; 226 227/// returns the smallest bounding box containing the entire screen 228- (RMSphericalTrapezium) latitudeLongitudeBoundingBoxForScreen; 229/// returns the smallest bounding box containing a rectangular region of the screen 230- (RMSphericalTrapezium) latitudeLongitudeBoundingBoxFor:(CGRect) rect; 231 232- (void)setRotation:(float)angle; 233 234- (void) tilesUpdatedRegion:(CGRect)region; 235 236/*! \brief Clear all images from the #tileSource's caching system. 237 238 All of the existing RMTileSource implementations load tile images via NSURLRequest. It's possible that some images will remain in your 239 application's shared URL cache. If you need to clear this out too, use this call: 240 \code 241 [[NSURLCache sharedURLCache] removeAllCachedResponses]; 242 \endcode 243 */ 244-(void)removeAllCachedImages; 245 246@end 247 248/// Appears to be the methods actually implemented by RMMapContents, but generally invoked on RMMapView, and forwarded to the contents object. 249@protocol RMMapContentsFacade 250 251@optional 252- (void)moveToLatLong: (CLLocationCoordinate2D)latlong; 253- (void)moveToProjectedPoint: (RMProjectedPoint)aPoint; 254 255- (void)moveBy: (CGSize) delta; 256- (void)zoomByFactor: (float) zoomFactor near:(CGPoint) center; 257- (void)zoomInToNextNativeZoomAt:(CGPoint) pivot animated:(BOOL) animated; 258- (void)zoomOutToNextNativeZoomAt:(CGPoint) pivot animated:(BOOL) animated; 259- (void)zoomByFactor: (float) zoomFactor near:(CGPoint) center animated:(BOOL) animated; 260 261- (void)zoomInToNextNativeZoomAt:(CGPoint) pivot; 262- (void)zoomOutToNextNativeZoomAt:(CGPoint) pivot; 263- (float)adjustZoomForBoundingMask:(float)zoomFactor; 264- (void)adjustMapPlacementWithScale:(float)aScale; 265 266- (CGPoint)latLongToPixel:(CLLocationCoordinate2D)latlong; 267- (CGPoint)latLongToPixel:(CLLocationCoordinate2D)latlong withMetersPerPixel:(float)aScale; 268- (CLLocationCoordinate2D)pixelToLatLong:(CGPoint)aPixel; 269- (CLLocationCoordinate2D)pixelToLatLong:(CGPoint)aPixel withMetersPerPixel:(float)aScale; 270 271- (void)zoomWithLatLngBoundsNorthEast:(CLLocationCoordinate2D)ne SouthWest:(CLLocationCoordinate2D)se; 272- (void)zoomWithRMMercatorRectBounds:(RMProjectedRect)bounds; 273 274/// \deprecated name change pending after 0.5 275- (RMSphericalTrapezium) latitudeLongitudeBoundingBoxForScreen; 276/// \deprecated name change pending after 0.5 277- (RMSphericalTrapezium) latitudeLongitudeBoundingBoxFor:(CGRect) rect; 278 279- (void) tilesUpdatedRegion:(CGRect)region; 280 281 282@end 283