MDCInkView.h

// Copyright 2015-present the Material Components for iOS authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#import <UIKit/UIKit.h>

// TODO(b/151929968): Delete import of delegate headers when client code has been migrated to no
// longer import delegates as transitive dependencies.
#import "MDCInkViewDelegate.h"

API_DEPRECATED_BEGIN(
    "🕘 Schedule time to migrate. "
    "Use default system highlight behavior instead: go/material-ios-touch-response. "
    "This is go/material-ios-migrations#not-scriptable 🕘",
    ios(12, 12))

@protocol MDCInkViewDelegate;

/** Completion block signature for all ink animations. */
typedef void (^MDCInkCompletionBlock)(void);

/** Ink styles. */
typedef NS_ENUM(NSInteger, MDCInkStyle) {
  /** Ink is clipped to the view's bounds. */
  MDCInkStyleBounded,
  /** Ink is not clipped to the view's bounds. */
  MDCInkStyleUnbounded
};

/**
 A UIView that draws and animates the Material Design ink effect for touch interactions.

 There are two kinds of ink:

 Bounded ink: Ink that spreads from a point and is contained in the bounds of a UI element such as a
 button. The ink is visually clipped to the bounds of the UI element. Bounded ink is the most
 commonly-used ink in the system. Examples include basic Material buttons, list menu items, and tile
 grids.

 Unbounded ink: Ink that spreads out from a point "on top" of other UI elements. It typically
 reaches a maximum circle radius and then fades, unclipped by other UI elements. Typically used
 when interacting with small UI elements such as navigation bar icons or slider "thumb" controls.
 Examples include overflow menus, icon toggle buttons, and phone dialer keys.

 Note that the two kinds of ink are designed to have different animation parameters, that is,
 bounded ink isn't just clipped unbounded ink. Whether the ink is bounded or not depends on the kind
 of UI element the user is interacting with.
 */
__deprecated_msg("Please use MDCRippleView instead.") @interface MDCInkView : UIView

/**
 Ink view animation delegate. Clients set this delegate to receive updates when ink animations
 start and end.
 */
@property(nonatomic, weak, nullable) id<MDCInkViewDelegate> animationDelegate;

/**
 The style of ink for this view. Defaults to MDCInkStyleBounded.

 Changes only affect subsequent animations, not animations in progress.
 */
@property(nonatomic, assign) MDCInkStyle inkStyle;

/** The foreground color of the ink. The default value is defaultInkColor. */
@property(nonatomic, strong, null_resettable) UIColor *inkColor UI_APPEARANCE_SELECTOR;

/** Default color used for ink if no color is specified. */
@property(nonatomic, strong, readonly, nonnull) UIColor *defaultInkColor;

/**
 Maximum radius of the ink. If the radius <= 0 then half the length of the diagonal of self.bounds
 is used. This value is ignored if @c inkStyle is set to MDCInkStyleBounded and @c
 usesLegacyInkLayer is set to NO.
 */
@property(nonatomic, assign) CGFloat maxRippleRadius;

/**
 Use the older legacy version of the ink ripple. Default is YES.
 */
@property(nonatomic, assign) BOOL usesLegacyInkRipple;

/**
 Use a custom center for the ink splash. If YES, then customInkCenter is used, otherwise the
 center of self.bounds is used. Default is NO.

 Affects behavior only if usesLegacyInkRipple is enabled.
 */
@property(nonatomic, assign) BOOL usesCustomInkCenter;

/**
 Custom center for the ink splash in the view’s coordinate system.

 Affects behavior only if both usesCustomInkCenter and usesLegacyInkRipple are enabled.
 */
@property(nonatomic, assign) CGPoint customInkCenter;

/**
 A block that is invoked when the @c MDCInkView receives a call to @c
 traitCollectionDidChange:. The block is called after the call to the superclass.
 */
@property(nonatomic, copy, nullable) void (^traitCollectionDidChangeBlock)
    (MDCInkView *_Nonnull ink, UITraitCollection *_Nullable previousTraitCollection);

/**
 Start the first part of the "press and release" animation at a particular point.

 The "press and release" animation begins by fading in the ink ripple when this method is called.

 @param point The user interaction position in the view’s coordinate system.
 @param completionBlock Block called after the completion of the animation.
 */
- (void)startTouchBeganAnimationAtPoint:(CGPoint)point
                             completion:(nullable MDCInkCompletionBlock)completionBlock;

/**
 Start the second part of the "press and release" animation at a particular point.

 The "press and release" animation ends by completing the ink ripple expansion while fading out when
 this method is called.

 @param point The user interaction position in the view’s coordinate system.
 @param completionBlock Block called after the completion of the animation.
 */
- (void)startTouchEndedAnimationAtPoint:(CGPoint)point
                             completion:(nullable MDCInkCompletionBlock)completionBlock;

/**
 Cancel all animations.

 @param animated If false, remove the animations immediately.
 */
- (void)cancelAllAnimationsAnimated:(BOOL)animated;

/**
 Start the first part of spreading the ink at a particular point.

 This begins by fading in the ink ripple when this method is called.

 @param point The user interaction position in the view’s coordinate system.
 @param animated to add the ink sublayer with animation or not.
 @param completionBlock Block called after the completion of the animation.
 */
- (void)startTouchBeganAtPoint:(CGPoint)point
                      animated:(BOOL)animated
                withCompletion:(nullable MDCInkCompletionBlock)completionBlock;

/**
 Start the second part of evaporating the ink at a particular point.

 This ends by completing the ink ripple expansion while fading out when
 this method is called.

 @param point The user interaction position in the view’s coordinate system.
 @param animated to remove the ink sublayer with animation or not.
 @param completionBlock Block called after the completion of the animation.
 */
- (void)startTouchEndAtPoint:(CGPoint)point
                    animated:(BOOL)animated
              withCompletion:(nullable MDCInkCompletionBlock)completionBlock;

/**
 Enumerates the given view's subviews for an instance of MDCInkView and returns it if found, or
 creates and adds a new instance of MDCInkView if not.

 This method is a convenience method for adding ink to an arbitrary view without needing to subclass
 the target view. Use this method in situations where you expect there to be many distinct ink views
 in existence for a single ink touch controller. Example scenarios include:

 - Adding ink to individual collection view/table view cells

 This method can be used in your MDCInkTouchController delegate's
 -inkTouchController:inkViewAtTouchLocation; implementation.
 */
+ (nonnull MDCInkView *)injectedInkViewForView:(nonnull UIView *)view;

@end

API_DEPRECATED_END