CLHeading Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSCopying
NSObject (NSObject)
Framework
/System/Library/Frameworks/CoreLocation.framework
Availability
Available in iOS 3.0 and later.
Companion guide
Location Awareness Programming Guide
Declared in
CLHeading.h
Related sample code

Overview

A CLHeading object contains heading data generated by a CLLocationManager object. The heading data consists of computed values for true and magnetic north. It also includes the raw data for the three-dimensional vector used to compute those values.

Typically, you do not create instances of this class yourself, nor do you subclass it. Instead, you receive instances of this class through the delegate assigned to the CLLocationManager object whose startUpdatingHeading method you called.

Tasks

Accessing the Heading Attributes

Accessing the Raw Heading Data

Properties

headingAccuracy

The maximum deviation (measured in degrees) between the reported heading and the true geomagnetic heading. (read-only)

@property(readonly, nonatomic) CLLocationDirection headingAccuracy
Discussion

A positive value in this property represents the potential error between the value reported by the magneticHeading property and the actual direction of magnetic north. Thus, the lower the value of this property, the more accurate the heading. A negative value means that the reported heading is invalid, which can occur when the device is uncalibrated or there is strong interference from local magnetic fields.

Availability
  • Available in iOS 3.0 and later.
Declared In
CLHeading.h

magneticHeading

The heading (measured in degrees) relative to magnetic north. (read-only)

@property(readonly, nonatomic) CLLocationDirection magneticHeading
Discussion

The value in this property represents the heading relative to the magnetic North Pole, which is different from the geographic North Pole. The value 0 means the device is pointed toward magnetic north, 90 means it is pointed east, 180 means it is pointed south, and so on. The value in this property should always be valid.

In iOS 3.x and earlier, the value in this property is always measured relative to the top of the device in a portrait orientation, regardless of the device’s actual physical or interface orientation. In iOS 4.0 and later, the value is measured relative to the heading orientation specified by the location manager. For more information, see the headingOrientation property in CLLocationManager Class Reference.

If the headingAccuracy property contains a negative value, the value in this property should be considered unreliable.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
CLHeading.h

timestamp

The time at which this heading was determined. (read-only)

@property(readonly, nonatomic) NSDate *timestamp
Availability
  • Available in iOS 3.0 and later.
Declared In
CLHeading.h

trueHeading

The heading (measured in degrees) relative to true north. (read-only)

@property(readonly, nonatomic) CLLocationDirection trueHeading
Discussion

The value in this property represents the heading relative to the geographic North Pole. The value 0 means the device is pointed toward true north, 90 means it is pointed due east, 180 means it is pointed due south, and so on. A negative value indicates that the heading could not be determined.

In iOS 3.x and earlier, the value in this property is always measured relative to the top of the device in a portrait orientation, regardless of the device’s actual physical or interface orientation. In iOS 4.0 and later, the value is measured relative to the heading orientation specified by the location manager. For more information, see the headingOrientation property in CLLocationManager Class Reference.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
CLHeading.h

x

The geomagnetic data (measured in microteslas) for the x-axis. (read-only)

@property(readonly, nonatomic) CLHeadingComponentValue x
Discussion

This value represents the x-axis deviation from the magnetic field lines being tracked by the device.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
CLHeading.h

y

The geomagnetic data (measured in microteslas) for the y-axis. (read-only)

@property(readonly, nonatomic) CLHeadingComponentValue y
Discussion

This value represents the y-axis deviation from the magnetic field lines being tracked by the device.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
CLHeading.h

z

The geomagnetic data (measured in microteslas) for the z-axis. (read-only)

@property(readonly, nonatomic) CLHeadingComponentValue z
Discussion

This value represents the z-axis deviation from the magnetic field lines being tracked by the device.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
CLHeading.h

Instance Methods

description

Returns the heading data in a formatted text string.

- (NSString *)description
Return Value

A string of the form “magneticHeading <magnetic> trueHeading <heading> accuracy <accuracy> x <x> y <y> z <z> @ <date-time>” where <magnetic>, <heading>, <accuracy>, <x>, <y>, and <z> are formatted floating-point numbers and <date-time> is a formatted date string that includes date, time, and time zone information.

Availability
  • Available in iOS 3.0 and later.
Declared In
CLHeading.h

Constants

CLHeadingComponentValue

A type used to report magnetic differences reported by the onboard hardware. 

typedef double CLHeadingComponentValue;
Availability
  • Available in iOS 3.0 and later.
Declared In
CLHeading.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-06-11)

Did this document help you? Yes It's good, but... Not helpful...