diff options
author | Muller, Alexander (A.) <amulle19@ford.com> | 2016-07-17 15:28:26 -0700 |
---|---|---|
committer | Muller, Alexander (A.) <amulle19@ford.com> | 2016-07-17 15:28:26 -0700 |
commit | f822b52cdd133ada19727f2d118768e50030b794 (patch) | |
tree | 7887cc262a05d11663778bd4a79499d0875d68bd /SmartDeviceLink | |
parent | 469648112a3950277c77d47b77be15ef5b4f4238 (diff) | |
download | sdl_ios-f822b52cdd133ada19727f2d118768e50030b794.tar.gz |
Added documentation
Diffstat (limited to 'SmartDeviceLink')
-rw-r--r-- | SmartDeviceLink/CGPoint_Util.h | 21 | ||||
-rw-r--r-- | SmartDeviceLink/SDLPinchGesture.h | 34 | ||||
-rw-r--r-- | SmartDeviceLink/SDLTouch.h | 32 | ||||
-rw-r--r-- | SmartDeviceLink/SDLTouchManager.h | 30 | ||||
-rw-r--r-- | SmartDeviceLink/SDLTouchManager.m | 29 | ||||
-rw-r--r-- | SmartDeviceLink/SDLTouchManagerListener.h | 75 |
6 files changed, 213 insertions, 8 deletions
diff --git a/SmartDeviceLink/CGPoint_Util.h b/SmartDeviceLink/CGPoint_Util.h index 8b5815e0f..9ea06e1b6 100644 --- a/SmartDeviceLink/CGPoint_Util.h +++ b/SmartDeviceLink/CGPoint_Util.h @@ -12,7 +12,28 @@ #include <stdio.h> #include <CoreGraphics/CGGeometry.h> +/** + * @abstract + * Calculate the center of two points. + * @param point1 + * First point. + * @param point2 + * Second point. + * @return CGPoint + * Center of the points. + */ CGPoint CGPointCenterOfPoints(CGPoint point1, CGPoint point2); + +/** + * @abstract + * Calculate the distance between two points. + * @param point1 + * First point. + * @param point2 + * Second point. + * @return CGFloat + * Distance between the points. + */ CGFloat CGPointDistanceBetweenPoints(CGPoint point1, CGPoint point2); #endif /* CGPoint_Util_h */ diff --git a/SmartDeviceLink/SDLPinchGesture.h b/SmartDeviceLink/SDLPinchGesture.h index 69ffec09a..ed1533759 100644 --- a/SmartDeviceLink/SDLPinchGesture.h +++ b/SmartDeviceLink/SDLPinchGesture.h @@ -14,13 +14,47 @@ NS_ASSUME_NONNULL_BEGIN @interface SDLPinchGesture : NSObject +/** + * @abstract + * Initializes a pinch gesture. + * @param firstTouch + * First touch of the gesture + * @param secondTouch + * Second touch of the gesture + * @return SDLPinchGesture + * Instance of SDLPinchGesture. + */ - (instancetype)initWithFirstTouch:(SDLTouch*)firstTouch secondTouch:(SDLTouch*)secondTouch; +/** + * @abstract + * First touch of a pinch gesture. + */ @property (nonatomic, copy) SDLTouch* firstTouch; + +/** + * @abstract + * Second touch of a pinch gesture. + */ @property (nonatomic, copy) SDLTouch* secondTouch; +/** + * @abstract + * Distance between first and second touches. + */ @property (nonatomic, assign, readonly) CGFloat distance; + +/** + * @abstract + * Center point between first and second touches. + */ @property (nonatomic, assign, readonly) CGPoint center; + +/** + * @abstract + * Returns whether or not the pinch gesture is valid. This is true if both touches + * are non null. + */ @property (nonatomic, assign, readonly) BOOL isValid; @end diff --git a/SmartDeviceLink/SDLTouch.h b/SmartDeviceLink/SDLTouch.h index 4d5553eb6..6cfb1f2db 100644 --- a/SmartDeviceLink/SDLTouch.h +++ b/SmartDeviceLink/SDLTouch.h @@ -19,13 +19,45 @@ NS_ASSUME_NONNULL_BEGIN @interface SDLTouch : NSObject +/** + * @abstract + * Initializes a touch. + * @param touchEvent + * Incoming touch event from onOnTouchEvent notification. + * @return SDLTouch + * Instance of SDLTouch. + */ - (instancetype)initWithTouchEvent:(SDLTouchEvent*)touchEvent; +/** + * @abstract + * Identifier of the touch's finger. Refer to SDLTouchIdentifier for valid + * identifiers. + */ @property (nonatomic, assign, readonly) NSInteger identifier; + +/** + * @abstract + * Location of touch point, in the head unit's coordinate system. + */ @property (nonatomic, assign, readonly) CGPoint location; + +/** + * @abstract + * Timestamp in which the touch occured. + */ @property (nonatomic, assign, readonly) NSUInteger timeStamp; +/** + * @abstract + * Returns whether or not this touch is a first finger. + */ @property (nonatomic, assign, readonly) BOOL isFirstFinger; + +/** + * @abstract + * Returns whether or not this touch is a second finger. + */ @property (nonatomic, assign, readonly) BOOL isSecondFinger; @end diff --git a/SmartDeviceLink/SDLTouchManager.h b/SmartDeviceLink/SDLTouchManager.h index 6377a2022..c46eae6cf 100644 --- a/SmartDeviceLink/SDLTouchManager.h +++ b/SmartDeviceLink/SDLTouchManager.h @@ -15,21 +15,39 @@ NS_ASSUME_NONNULL_BEGIN @property (nonatomic, weak, nullable) id<SDLTouchManagerListener> touchEventListener; -/* - * Distance between taps. +/** + * @abstract + * Distance between two taps on the screen, in the head unit's coordinate system, used + * for registering double-tap callbacks. + * @remark + * Default is 50 pixels. */ @property (nonatomic, assign) CGFloat tapDistanceThreshold; -/* - * Duration between taps (in seconds). +/** + * @abstract + * Time (in seconds) between tap events to register a double-tap callback. + * @remark + * Default is 0.4 seconds. */ @property (nonatomic, assign) CGFloat tapTimeThreshold; -/* - * Time between pan events (in seconds). +/** + * @abstract + * Time (in seconds) between movement events to register panning or pinching + * callbacks. + * @remark + * Default is 0.5 seconds. */ @property (nonatomic, assign) CGFloat movementTimeThreshold; +/** + * @abstract + * Boolean denoting whether or not the touch manager should deliver touch event + * callbacks. + * @remark + * Default is true. + */ @property (nonatomic, assign, getter=isTouchEnabled) BOOL touchEnabled; @end diff --git a/SmartDeviceLink/SDLTouchManager.m b/SmartDeviceLink/SDLTouchManager.m index 01d024bdb..496c1ea82 100644 --- a/SmartDeviceLink/SDLTouchManager.m +++ b/SmartDeviceLink/SDLTouchManager.m @@ -28,23 +28,48 @@ typedef NS_ENUM(NSUInteger, SDLPerformingTouchType) { SDLPerformingTouchTypePanningTouch }; +/*! + * @abstract + * Touch Manager will ignore touches that represent more than 2 fingers on the screen. + */ static NSUInteger const MaximumNumberOfTouches = 2; @interface SDLTouchManager () <SDLProxyListener> +/*! + * @abstract + * First Touch received from onOnTouchEvent. + */ @property (nonatomic, strong, nullable) SDLTouch* previousTouch; -/* - * Only used for caching previous single taps for double tap detection +/*! + * @abstract + * Cached previous single tap used for double tap detection. */ @property (nonatomic, strong, nullable) SDLTouch* singleTapTouch; +/*! + * @abstract + * Distance of a previously generated pinch event. Used to calculate the scale of zoom motion. + */ @property (nonatomic, assign) CGFloat previousPinchDistance; +/*! + * @abstract + * Current in-progress pinch gesture. + */ @property (nonatomic, strong, nullable) SDLPinchGesture* currentPinchGesture; +/*! + * @abstract + * Timer used for distinguishing between single & double taps. + */ @property (nonatomic, strong, nullable) dispatch_source_t singleTapTimer; +/*! + * @abstract + * Current touch type being performed. + */ @property (nonatomic, assign) SDLPerformingTouchType performingTouchType; @end diff --git a/SmartDeviceLink/SDLTouchManagerListener.h b/SmartDeviceLink/SDLTouchManagerListener.h index 5d8ab95bf..743e238b1 100644 --- a/SmartDeviceLink/SDLTouchManagerListener.h +++ b/SmartDeviceLink/SDLTouchManagerListener.h @@ -13,15 +13,90 @@ NS_ASSUME_NONNULL_BEGIN @protocol SDLTouchManagerListener <NSObject> @optional + +/** + * @abstract + * Single tap was received. + * @param manager + * Current initalized SDLTouchManager issuing the callback. + * @param point + * Location of the single tap in the head unit's coordinate system. + */ - (void)touchManager:(SDLTouchManager*)manager didReceiveSingleTapAtPoint:(CGPoint)point; + +/** + * @abstract + * Double tap was received. + * @param manager + * Current initalized SDLTouchManager issuing the callback. + * @param point + * Location of the double tap in the head unit's coordinate system. This is the + * average of the first and second tap. + */ - (void)touchManager:(SDLTouchManager*)manager didReceiveDoubleTapAtPoint:(CGPoint)point; +/** + * @abstract + * Panning did start. + * @param manager + * Current initalized SDLTouchManager issuing the callback. + * @param point + * Location of the panning start point in the head unit's coordinate system. + */ - (void)touchManager:(SDLTouchManager*)manager panningDidStartAtPoint:(CGPoint)point; + +/** + * @abstract + * Panning did move. + * @param manager + * Current initalized SDLTouchManager issuing the callback. + * @param fromPoint + * Location of the panning's previous point in the head unit's coordinate system. + * @param toPoint + * Location of the panning's new point in the head unit's coordinate system. + */ - (void)touchManager:(SDLTouchManager*)manager didReceivePanningFromPoint:(CGPoint)fromPoint toPoint:(CGPoint)toPoint; + +/** + * @abstract + * Panning did end. + * @param manager + * Current initalized SDLTouchManager issuing the callback. + * @param point + * Location of the panning's end point in the head unit's coordinate system. + */ - (void)touchManager:(SDLTouchManager*)manager panningDidEndAtPoint:(CGPoint)point; +/** + * @abstract + * Pinch did start. + * @param manager + * Current initalized SDLTouchManager issuing the callback. + * @param point + * Center point of the pinch in the head unit's coordinate system. + */ - (void)touchManager:(SDLTouchManager*)manager pinchDidStartAtCenterPoint:(CGPoint)point; + +/** + * @abstract + * Pinch did move. + * @param manager + * Current initalized SDLTouchManager issuing the callback. + * @param point + * Center point of the pinch in the head unit's coordinate system. + * @param scale + * Scale relative to the distance between touch points. + */ - (void)touchManager:(SDLTouchManager*)manager didReceivePinchAtCenterPoint:(CGPoint)point withScale:(CGFloat)scale; + +/** + * @abstract + * Pinch did end. + * @param manager + * Current initalized SDLTouchManager issuing the callback. + * @param point + * Center point of the pinch in the head unit's coordinate system. + */ - (void)touchManager:(SDLTouchManager*)manager pinchDidEndAtCenterPoint:(CGPoint)point; @end |