Objective-C

cs193p, CoreLocation.m

@property (readonly) CLLocationCoordinate2D coordinate;
typedef {
	CLLocationDegrees latitude; //a double
	CLLocationDegrees longtitude; //a double
} CLLocationCoordinate2D;

@property (readonly) CLLocationDistance altitude; //meters. A negative value means "below sea level"


@property (readonly) CLLocationAccuracy horizontalAccuracy; //in meters
@property (readonly) CLLocationAccuracy verticalAccuracy; //in meters
kCLLocationAccuracyBestForNavigation;
kCLLocationAccuracyBest;
kCLLocationAccuracyKilometers;
kCLLocationAccuracyThreeKilometers;

@property (readonly) CLLocationSpeed speed; // in meters/second
@property (readonly) CLLocationDirection course; // in degrees, O is north, clockwise

@property (readonly) NSDate *timestamp;

- (CLLocationDistance) distanceFromLocation:(CLLocation *) otherLocation;

// How do you get a CLLocation?
// from a CLLocationManager

//CLLocationManager: General appoach to using it: (4 steps)
//1. Check to see if the hardware youare on/user supports the kind of location updating you want
//2. Create a  CLLocation instance and set the delegate to receive updates
//3. Configure the manager according to what kind of location updating you want
//4. Start the manager monitoring for location changes

// Kind of location monitoring
	// Accuracy-based continual updates
	// Updates only when "Significant" changes in location occur
	// Region-based updates.
	// Heading monitoring

// Check to see what your hardware can do

+ (BOOL) locationServiceszEnabled; // has the user enabled the location monitoring in settings?
+ (BOOL) headingAvailable; // can this hardware provide heading info (compass)?
+ (BOOL) significantLocationChangeMonitoringAvailable; // only if device has cellular?
+ (BOOL) regionMonitoringAvailable; // only certain iOS4 devices
+ (BOOL) regionMonitoringEnabled; // by the user Settings;



// When your application first tries to use location monitoring, user will be asked if it's okay to do so.
// You can provide a string which describes your app's purpose in using the location services.
@property (copy) NSString *purpose;
// If the user denies you, the appropriate method above will return NO


@property CLLocationAccuracy desiredAccuracy; // always set this as low as possible

@property CLLocationDistance distanceFilter; // Only changes in location of at least this distance will fire a location update to you

// Starting and stopping the monitoring
- (void) startUpdatingLocation;
- (void) stopUpdatingLocation;
// Be sure to turn off when your application is not going to consume the changes!

- (void) locationManager:(CLLocationManager *) manager
	 didUpdateToLocation:(CLLocation *) newLocation
	 		fromLocation:(CLLocation *) oldLocation;

// Heading monitoring

@property CLLocationDegrees headingFilter;
@property CLHeadingOrientation headingOrientation;

- (void) startUpdatingHeading;
- (void) stopUpdatingHeading;

// get notified via CLLocationManager's delegate
- (void) locationManager:(CLLocationManager *)manager
			 didUpdating:(CLHeading *)newHeading;


// CLHeading
@property (readonly) CLLocationDirection magneticHeading;
@property (readonly) CLLocationDirection trueHeading;

@property (readonly) CLLocationDirection headingAccuracy;
@property (readonly) NSDate *timestamp;

// Heading calibration user-interface

- (BOOL) locationManagerShouldDisplayHeadingCalibration:(CLLocationManager *)manager;
- (void) dismissHeadingCalibrationDisplay;

// Error reporting to the delegate
- (void) locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error;
//Not always a fatal thing, so pay attention to this delegate method:
kCLErrorLocationUnknown  // likely temporary, keep waiting (for a while at least)
kCLErrorDenied // user refused to allow your application to receive updates
kCLErrorHeadingFailure //too much local magnetic interference keep waiting


// Significant location change monitoring in CLLocationManager
	// "Significant" is not strictly defined. Think vehicles, not walking. Likely uses cell towers
	- (void) startMonitoringSignificantLocationChanges;
	- (void) stopMonitoringSignificantLocationChanges;

	// Get notified via the CLLocationManager's delegte
		// same as for accuracy-based updating if your application is running
	// But this works even if your application is not running! You will get launched and your application delegate will receive message

application:didFinishLaunchingWithOptions: // with an options dictionary that will contain
UIApplicationLaunchOptionsLocationKey // Create a CLLocationManager (if you don't have one) then get the latest location via
@property (readonly) CLLocation *location;

// Region-based location monitoring in CLLocationManager
- (void) startMonitoringForRegion:(CLRegion *)  desiredAccuracy:(CLLocationAccuracy);
- (void) stopMonitoringForRegion:(CLRegion *);

// Get notified via the CLLocationManager's delegate
- (void)locationManager:(CLLocationManager *)manager didEnterRegion:(CLRegion *)region;
- (void)locationManager:(CLLocationManager *)manager didExitRegion:(CLRegion *)region;

   - (void)locationManager:(CLLocationManager *)manager
monitoringDidFailForRegion:(CLRegion *)region
				 withError:(NSError *)error;

// Works even if your application is not running
	// In exactly the same way as "significant location change" monitoring
	// The set of monitored regions persists across application termination/launch

@property (readonly) NSSet *monitoredRegions; // Property on CLLocationManager

// CLRegion s are tracked by name
@property (readonly) CLLocationDistance maximumRegionMonitoringDistance;

// Displays an array of objects which implement MKAnnotation
@property (readonly) NSArray *annotations; // contains id <MKAnnotation> objects

// MKAnnotation protocol
@protocol MKAnnotation <NSObject>
@property (readonly) CLLocationCoordinate2D coordinate;

@optional
@property (readonly) NSString *title;
@property (readonly) NSString *subtitle;
@end

typedef {
	CLLocationDegrees latitude;
	CLLocationDegrees longtitude;
} CLLocationCoordinate2D;

// Note that the annotations property is read only
@property (readonly) NSArray *annotations // contains id <MKAnnotation> objets
// MUST add/remove annotations explicitly

- (void)addAnnotation:(id <MKAnnotation>)annotation;
- (void)addAnnotations:(NSArray *)annotations;
- (void)removeAnnotation:(id <MKAnnotation>)annotation;
- (void)removeAnnotations:(NSArray *)annotations;

// When you toudh on an annotation, the following delegate is called

- (void)mapView:(MKMapView *)sender didSelectAnnotationView:(MKAnnotationView *)aView;
// This is a great place to set up the MKAnnotationView's callout accessory views lazily
// For example, you migh want to wait until this method is called to download an image to show


// How are MKAnnotationViews Created & associated w/annotations?
// Very similar to UITableViewCells in a UITableView
// Implement the following MKMapViewDelegate method (if not implemented, returns a pin view)

- (MKAnnotationView *)mapView:(MKMapView *)sender  viewForAnnotation:(id <MKAnnotation>)annotation
{
	MKAnnotationView *aView = [sender dequeueReusableAnnotionViewWithIdentifier:IDENT];
	if  (!aView){
		aView = [[MKPinAnnotationView alloc] initWithAnnotation:annotation reuseIdentifier:IDENT];

		// set canShowCallOut to YES and build aView's callout accessory views here
	} 
	aView.annotation = annotation; // yes, this happens twice if no dequeue
	// maybe load up accessory views here (if not too expensive)
	// or reset them and wait until mapView:didSelectAnnotationView: to load actual data

	return aView;
}

 
// MKAnnotationView  interesting properties (all nonatomic, strong if a pointer)
@property id <MKAnnotation> annotation; //the annotation, treat as if readonly
@property UIImage *image; // instead of the pin, for example
@property UIView *leftCalloutAccessoryView; // maybe a UIImageView
@property UIView *rightCalloutAccessoryView; // maybe a disclosure UIButton
@property BOOL enabled; // NO means it ignores touch events, no delegate method, no callout
@property CGPoint centerOffset; // where the "head of the pin" is relative to the image
@proprtty BOOL dragable; // only works if the annotation implements setCoordinate:

// if you set one of thecallout accessory views to a UIControl
// e.g. aView.rightCalloutAccessoryView = [UIButton buttonWithType:UIButtonTypeDisclosure];

// the following MKMapViewDelegate method will get called when the accessory view is touched...

- (void)mapView:(MKMapView *)sender annotationView:(MKAnnotationVIew *)aView calloutAccessoryControlTapped:(UIControl *)control;


// Using didSelectAnnotationView: to load up callout accessories
	// example... downloaded thumbnail image in leftCalloutAccessoryView
	// Creat the UIImageView and assign it to leftCalloutAccessoryView in mapView:viewForAnnotation:
	// Reset the UIImageView's image to nil there as well

	// then load the image on demand in mapView:didSelectAnnotationView ...

- (void)mapView:(MKMapVIew *)sender didSelectAnnotationView:(MKAnnotationView *)aView
{
	if ([aView.leftCalloutAccessoryView isKindOfClass:[UIImageView class]]) {
		UIImageView *imageView = (UIImageVIew *)aView.leftCalloutAccessoryView;
		imageView.image = ...; // if you do this in a GCD queue, be careful, views are reused!
	}
}


// Configure the map view's display type
@property MKMapType mapType;
MKMapTypeStandrd, MKMapTypeSatelite, MKMapTypeHybird;

// show the user's current location
@property BOOL showUserLocation;
@property (readonly) BOOL isUserLocationVisible;
@property (readonly) MKUserLocation *userLocation;
MKUserLocation is an object which conforms to MKAnnotation which holds the users location

// Restricting the user's interaction with the map

@property BOOL zoomEnabled;
@property BOOL scrollEnabled;

// Controlling the region the map displaying
@property MKCoordinateRegion region;
typedef struct {
	CLLocationCoordinate2D center;
	MKCoordinateSpan span;
} MKCoordinateRegion;
typedef struct {
	CLLocationDegrees latitudeDelta;
	CLLocationDegrees longtitudeDelta;
}

- (void)setRegion:(MKCoordinateRegion)region animated:(BOOL)animated; //animate

// Can also set the center point only
@property CLLocationCoordinate2D centerCoordinate;
- (void)setCenterCoordinate:(CLLocationCoordinate2D)center animated:(BOOL)animated;

// Map loading notifications
// remenber that the maps are downloaded from Google earth

- (void)mapViewWillStartLoadingMap:(MKMapView *)sender;
- (void)mapViewDidFinishLoadingMap:(MKMapView *)sender;
- (void)maoViewDidFailLoadingMap:(MKMapView *)sender withError:(NSError *)error;

// Lots of C functions to convert points, regions, rects, etc
// see documentation, e.g. MKMapRectContainsPoint, MKMapPointForCoordinate, etc


// Overlays: Mechanism is similar to annotations (uses MKOverlayView instead of MKAnnotationView)

- (void)addOverlay:(id <MKOverlay>)overlay;
- (void)removeOverlay:(id <MKOverlay>) overlay;

// MKOverlay protocol
// Protocol which includes MKAnnotation plus...
@property (readonly)MKMapRect boundingMapRect;
- (BOOL)intersectsMapRect:(MKMapRect)mapRect; // optional, uses boundingMapRect otherwise

// Overlays are associated with MKOverlayView s via delegate
// just like annotations are associated with MKAnnotationViews...
- (MKOverlayView *)mapView:(MKMapView *)sender viewForOverlay:(id <MKOverlay>)overlay;
// MKOverlayView subclasses must be able to draw the overlay 
- (void)drawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale inContext:(CGContextRef)context;

// this is not quite like drawRect: (because you'll notice that you are provided the context)
// But you will still use CoreGraphics to draw (this method must be thead-safe, by the way).
// Also notice that the rectangle to draw is in map coordinates, not view coordinates

// Converting to/from map point/rects from/to view coordinates

- (MKMapPoint)mapPointForPoint:(CGPoint)point;
- (MKMapRect)mapRectForRect:(CGRect)rect;
- (CGPont)pointForMapPoint:(MKMapPoint)mapPoint;
- (CGRect)rectForMapRect:(MKMapRect)mapRect;