Class: MKAnnotationView
Overview
The MKAnnotationView class is responsible for presenting annotations visually in a map view. Annotation views are loosely coupled to a corresponding annotation object, which is an object that corresponds to the MKAnnotation protocol. When an annotation’s coordinate point is in the visible region, the map view asks its delegate to provide a corresponding annotation view. Annotation views may be recycled later and put into a reuse queue that is maintained by the map view.
Direct Known Subclasses
Instance Attribute Summary (collapse)
-
- annotation
The annotation object currently associated with the view.
-
- calloutOffset
The offset (in pixels) at which to place the callout bubble.
-
- canShowCallout
A Boolean value indicating whether the annotation view is able to display extra information in a callout bubble.
-
- centerOffset
The offset (in pixels) at which to display the view.
-
- draggable
A Boolean indicating whether the annotation view is draggable.
-
- dragState
The current drag state of the annotation view.
-
- enabled
A Boolean value indicating whether the annotation is enabled.
-
- highlighted
A Boolean value indicating whether the annotation view is highlighted.
-
- image
The image to be displayed by the annotation view.
-
- leftCalloutAccessoryView
The view to display on the left side of the standard callout bubble.
-
- reuseIdentifier
readonly
The string that identifies that this annotation view is reusable.
-
- rightCalloutAccessoryView
The view to display on the right side of the standard callout bubble.
-
- selected
A Boolean value indicating whether the annotation view is currently selected.
Attributes inherited from UIView
#alpha, #autoresizesSubviews, #autoresizingMask, #backgroundColor, #bounds, #center, #clearsContextBeforeDrawing, #clipsToBounds, #contentMode, #contentScaleFactor, #exclusiveTouch, #frame, #gestureRecognizers, #hidden, #layer, #multipleTouchEnabled, #opaque, #restorationIdentifier, #subviews, #superview, #tag, #transform, #userInteractionEnabled, #window
Attributes inherited from UIResponder
#inputAccessoryView, #inputView, #undoManager
Instance Method Summary (collapse)
-
- initWithAnnotation:reuseIdentifier:
Initializes and returns a new annotation view.
-
- prepareForReuse
Called when the view is removed from the reuse queue.
-
- setDragState:animated:
Sets the current drag state for the annotation view.
-
- setSelected:animated:
Sets the selection state of the annotation view.
Methods inherited from UIView
#addConstraint:, #addConstraints:, #addGestureRecognizer:, #addSubview:, #alignmentRectForFrame:, #alignmentRectInsets, animateWithDuration:animations:, animateWithDuration:animations:completion:, animateWithDuration:delay:options:animations:completion:, areAnimationsEnabled, beginAnimations:context:, #bringSubviewToFront:, commitAnimations, #constraints, #constraintsAffectingLayoutForAxis:, #contentCompressionResistancePriorityForAxis:, #contentHuggingPriorityForAxis:, #convertPoint:fromView:, #convertPoint:toView:, #convertRect:fromView:, #convertRect:toView:, #decodeRestorableStateWithCoder:, #didAddSubview:, #didMoveToSuperview, #didMoveToWindow, #drawRect:, #drawRect:forViewPrintFormatter:, #encodeRestorableStateWithCoder:, #endEditing:, #exchangeSubviewAtIndex:withSubviewAtIndex:, #exerciseAmbiguityInLayout, #frameForAlignmentRect:, #gestureRecognizerShouldBegin:, #hasAmbiguousLayout, #hitTest:withEvent:, #initWithFrame:, #insertSubview:aboveSubview:, #insertSubview:atIndex:, #insertSubview:belowSubview:, #intrinsicContentSize, #invalidateIntrinsicContentSize, #isDescendantOfView:, layerClass, #layoutIfNeeded, #layoutSubviews, #needsUpdateConstraints, #pointInside:withEvent:, #removeConstraint:, #removeConstraints:, #removeFromSuperview, #removeGestureRecognizer:, requiresConstraintBasedLayout, #sendSubviewToBack:, setAnimationBeginsFromCurrentState:, setAnimationCurve:, setAnimationDelay:, setAnimationDelegate:, setAnimationDidStopSelector:, setAnimationDuration:, setAnimationRepeatAutoreverses:, setAnimationRepeatCount:, setAnimationStartDate:, setAnimationTransition:forView:cache:, setAnimationWillStartSelector:, setAnimationsEnabled:, #setContentCompressionResistancePriority:forAxis:, #setContentHuggingPriority:forAxis:, #setNeedsDisplay, #setNeedsDisplayInRect:, #setNeedsLayout, #setNeedsUpdateConstraints, #setTranslatesAutoresizingMaskIntoConstraints:, #sizeThatFits:, #sizeToFit, #systemLayoutSizeFittingSize:, transitionFromView:toView:duration:options:completion:, transitionWithView:duration:options:animations:completion:, #translatesAutoresizingMaskIntoConstraints, #updateConstraints, #updateConstraintsIfNeeded, #viewForBaselineLayout, #viewPrintFormatter, #viewWithTag:, #willMoveToSuperview:, #willMoveToWindow:, #willRemoveSubview:
Methods inherited from UIResponder
#becomeFirstResponder, #canBecomeFirstResponder, #canPerformAction:withSender:, #canResignFirstResponder, #isFirstResponder, #motionBegan:withEvent:, #motionCancelled:withEvent:, #motionEnded:withEvent:, #nextResponder, #reloadInputViews, #remoteControlReceivedWithEvent:, #resignFirstResponder, #touchesBegan:withEvent:, #touchesCancelled:withEvent:, #touchesEnded:withEvent:, #touchesMoved:withEvent:
Methods inherited from NSObject
#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version
Constructor Details
This class inherits a constructor from NSObject
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class NSObject
Instance Attribute Details
- (Object) annotation
The annotation object currently associated with the view. You should not change the value of this property directly. This property contains a non-nil value only while the annotation view is visible on the map. If the view is queued and waiting to be reused, the value is nil
- (CGPoint) calloutOffset
The offset (in pixels) at which to place the callout bubble. This property determines the additional distance by which to move the callout bubble. When this property is set to (0, 0), the anchor point of the callout bubble is placed on the top-center point of the annotation view’s frame. Specifying positive offset values moves the callout bubble down and to the right, while specifying negative values moves it up and to the left.
- (Boolean) canShowCallout
A Boolean value indicating whether the annotation view is able to display extra information in a callout bubble. If the value of this property is YES, a standard callout bubble is shown when the user taps a selected annotation view. The callout uses the title and subtitle text from the associated annotation object. If there is no title text, though, the annotation view is treated as if its enabled property is set to NO. The callout also displays any custom callout views stored in the leftCalloutAccessoryView and rightCalloutAccessoryView properties. If the value of this property is NO, the value of the title and subtitle strings are ignored and the annotation view remains enabled by default. You can still disable the view explicitly using the enabled property.
- (CGPoint) centerOffset
The offset (in pixels) at which to display the view. By default, the center point of an annotation view is placed at the coordinate point of the associated annotation. You can use this property to reposition the annotation view as needed. This x and y offset values are measured in pixels. Positive offset values move the annotation view down and to the right, while negative values move it up and to the left.
- (Boolean) draggable
A Boolean indicating whether the annotation view is draggable. Setting this property to YES makes an annotation draggable by the user. If YES, the associated annotation object must also implement the setCoordinate: method. The default value of this property is NO. Setting this property to YES, lets the map view know that the annotation is always draggable. In other words, you cannot conditionalize drag operations by attempting to stop an operation that has already been initiated; doing so can lead to undefined behavior. Once begun, the drag operation should always continue to completion.
- (MKAnnotationViewDragState) dragState
The current drag state of the annotation view. Applications targeting iOS 4.1 and earlier can use this property to support drag operations in custom annotation views. If your application runs in iOS 4.2 or later, you should override the setDragState:animated: method and use it to manage the drag state instead. To support drag operations, you must override the implementation of this property and update the drag state at the following times:When the drag state changes to MKAnnotationViewDragStateStarting, you should set the state to MKAnnotationViewDragStateDragging. If you perform an animation to indicate the beginning of a drag, you should perform that animation before changing the state. Changing the state to the new value lets the map know that your animations are done. When the state changes to either MKAnnotationViewDragStateCanceling or MKAnnotationViewDragStateEnding, set the state to MKAnnotationViewDragStateNone. If you perform an animation at the end of a drag, you should perform that animation before changing the state. Changing the state to the MKAnnotationViewDragStateDragging or MKAnnotationViewDragStateNone value is the way to signal to the map view that you are done with any animations you wanted to perform. For example, when a drag operation begins for a pin annotation, the MKPinAnnotationView class executes an animation to lift the pin off the map. Similarly, when the pin is dropped, the class performs a drop animation. Even if you do not perform any animations, you should still change the value of this property to reflect the correct state. You must not try to abort a new drag operation by changing the state from MKAnnotationViewDragStateStarting to MKAnnotationViewDragStateNone. If you do not want your annotation view to be draggable, set the draggable property to NO.
- (Boolean) enabled
A Boolean value indicating whether the annotation is enabled. The default value of this property is YES. If the value of this property is NO, the annotation view ignores touch events and cannot be selected. Subclasses may also display the annotation contents differently depending on the value of this property.
- (Boolean) highlighted
A Boolean value indicating whether the annotation view is highlighted. You should not set the value of this property directly. The map view sets it in response to touch events entering or exiting the annotation view’s bounds.
- (UIImage) image
The image to be displayed by the annotation view. Assigning a new image to this property also changes the size of the view’s frame so that it matches the width and height of the new image. The position of the view’s frame does not change.
- (UIView) leftCalloutAccessoryView
The view to display on the left side of the standard callout bubble. The default value of this property is nil. The left callout view is typically used to display information about the annotation or to link to custom information provided by your application. The height of your view should be 32 pixels or less. If the view you specify is also a descendant of the UIControl class, you can use the map view’s delegate to receive notifications when your control is tapped. If it does not descend from UIControl, your view is responsible for handling any touch events within its bounds.
- (String) reuseIdentifier (readonly)
The string that identifies that this annotation view is reusable. (read-only) You specify the reuse identifier when you create the view. You use this type later to retrieve an annotation view that was created previously but which is currently unused because its annotation is not on screen. If you define distinctly different types of annotations (with distinctly different annotation views to go with them), you can differentiate between the annotation types by specifying different reuse identifiers for each one.
- (UIView) rightCalloutAccessoryView
The view to display on the right side of the standard callout bubble. This property is set to nil by default. The right callout view is typically used to link to more detailed information about the annotation. The height of your view should be 32 pixels or less. A common view to specify for this property is UIButton object whose type is set to UIButtonTypeDetailDisclosure. If the view you specify is also a descendant of the UIControl class, you can use the map view’s delegate to receive notifications when your control is tapped. If it does not descend from UIControl, your view is responsible for handling any touch events within its bounds.
- (Boolean) selected
A Boolean value indicating whether the annotation view is currently selected. You should not set the value of this property directly. If the property contains YES, the annotation view is displaying a callout bubble.
Instance Method Details
- (Object) initWithAnnotation(annotation, reuseIdentifier:reuseIdentifier)
Initializes and returns a new annotation view. The reuse identifier provides a way for you to improve performance by recycling annotation views as they are scrolled on and off of the map. As views are no longer needed, they are moved to a reuse queue by the map view. When a new annotation becomes visible, your application can request a view for that annotation by passing the appropriate reuse identifier string to the dequeueReusableAnnotationViewWithIdentifier: method of MKMapView.
- (Object) prepareForReuse
Called when the view is removed from the reuse queue. The default implementation of this method does nothing. You can override it in your custom annotation views and use it to put the view in a known state before it is returned to your map view delegate.
- (Object) setDragState(newDragState, animated:animated)
Sets the current drag state for the annotation view. Applications targeting iOS 4.2 and later can override this method and use it to implement drag support for custom annotation views. As the system detects user actions that would indicate a drag, it calls this method to update the drag state. In response to these changes, your custom implementation of this method should do the following:When the drag state changes to MKAnnotationViewDragStateStarting, set the state to MKAnnotationViewDragStateDragging. If you perform an animation to indicate the beginning of a drag, and the animated parameter is YES, perform that animation before changing the state.When the state changes to either MKAnnotationViewDragStateCanceling or MKAnnotationViewDragStateEnding, set the state to MKAnnotationViewDragStateNone. If you perform an animation at the end of a drag, and the animated parameter is YES, you should perform that animation before changing the state. The default implementation of this method sets the value of the dragState property to the value in the newDragState parameter only. Therefore, direct subclasses can simply call the inherited version of this method to change the drag state; otherwise, just change the value in the draggable property directly. Changing the state to MKAnnotationViewDragStateDragging or MKAnnotationViewDragStateNone is the way to signal to the map view that you are done with any animations you wanted to perform. For example, when a drag operation begins for a pin annotation, the MKPinAnnotationView class executes an animation to lift the pin off the map. Similarly, when the pin is dropped, the class performs a drop animation. Even if you do not perform any animations, you should call the inherited version of this method to update the dragState property.You must not try to abort a new drag operation by changing the state from MKAnnotationViewDragStateStarting to MKAnnotationViewDragStateNone. If you do not want your annotation view to be draggable, set the draggable property to NO.