components/FeatureHighlight/src/MDCFeatureHighlightViewController.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>

API_DEPRECATED_BEGIN("🕘 Schedule time to migrate. "
                     "Consider using a modal sheet to explain new features instead. "
                     "This is go/material-ios-migrations#not-scriptable 🕘",
                     ios(12, 12))

/** The default alpha for the outer highlight circle. */
extern const CGFloat kMDCFeatureHighlightOuterHighlightAlpha;

/**
 Completion block called when the feature highlight is dismissed either by calling |acceptFeature|
 or |rejectFeature| on the feature highlight or the user accepts or rejects the highlight by tapping
 somewhere on the highlight view.

 @param accepted Whether the highlight was accepted or rejected
 */
typedef void (^MDCFeatureHighlightCompletion)(BOOL accepted);

/**
 MDCFeatureHighlightViewController highlights an element of a UI to introduce features or
 functionality that a user hasn’t tried.

 https://material.io/guidelines/growth-communications/feature-discovery.html

 MDCFeatureHighlightViewController should be presented modally and dismissed using either
 |acceptFeature| or |rejectFeature|.

 While MDCFeatureHighlightViewController supports changing state while presented, it is not
 recommended as the design spec does not specify any patterns for that behavior.

 @note Due to a bug in the iOS simulator it is possible that the feature highlight will not render
 correctly in the simulator. If you're encountering issues make sure to test on device.
 */
@interface MDCFeatureHighlightViewController : UIViewController <UIContentSizeCategoryAdjusting>

/**
 Initializes the controller.

 @param highlightedView The highlight will be presented above the |center| of |highlightedView|
 @param displayedView Added to the highlight view and centered at the |center| of |highlightedView|
 @param completion The completion block called when the highlight is dismissed
 */
- (nonnull instancetype)initWithHighlightedView:(nonnull UIView *)highlightedView
                                    andShowView:(nonnull UIView *)displayedView
                                     completion:(nullable MDCFeatureHighlightCompletion)completion
    NS_DESIGNATED_INITIALIZER;

/**
 Initializes the controller.

 This is a convience method for |initWithHighlightedView:andShowView:| with a snapshot of
 |highlightedView| sent as |displayedView|.

 @param highlightedView The highlight will be presented above the |center| of |highlightedView|
 */
- (nonnull instancetype)initWithHighlightedView:(nonnull UIView *)highlightedView
                                     completion:(nullable MDCFeatureHighlightCompletion)completion;

/**
 Feature Highlight controllers must be created with either initWithHighlightedView: constructor.
 */
- (nonnull instancetype)initWithNibName:(nullable NSString *)nibNameOrNil
                                 bundle:(nullable NSBundle *)nibBundleOrNil NS_UNAVAILABLE;
- (nonnull instancetype)initWithCoder:(nonnull NSCoder *)aDecoder NS_UNAVAILABLE;
- (nonnull instancetype)init NS_UNAVAILABLE;

/**
 Sets the text to be displayed as the header of the help text.

 The header is displayed above the body text.
 */
@property(nonatomic, copy, nullable) NSString *titleText;

/**
 Sets the text to be displayed as the body of the help text.

 The body is displayed below the header text. If you are only showing a single block of text without
 any header/body distinction, prefer |titleText|.
 */
@property(nonatomic, copy, nullable) NSString *bodyText;

/**
 Sets the color to be used for the outer highlight. Defaults to blue with an alpha of
 kMDCFeatureHighlightOuterHighlightAlpha.

 Alpha should be set to kMDCFeatureHighlightOuterHighlightAlpha.
 */
@property(nonatomic, strong, null_resettable) UIColor *outerHighlightColor;

/**
 Sets the color to be used for the inner highlight. Defaults to white.

 Should be opaque.
 */
@property(nonatomic, strong, null_resettable) UIColor *innerHighlightColor;

/**
 Sets the color to be used for the title text. If nil upon presentation, a color of sufficient
 contrast to the |outerHighlightColor| will be automatically chosen.

 Defaults to nil.
 */
@property(nonatomic, strong, nullable) UIColor *titleColor;

/**
 Sets the color to be used for the body text. If nil upon presentation, a color of sufficient
 contrast to the |outerHighlightColor| will be automatically chosen upon presentation.

 Defaults to nil.
 */
@property(nonatomic, strong, nullable) UIColor *bodyColor;

/**
 Sets the custom font to be used for the title text.

 Defaults to nil.
 */
@property(nonatomic, strong, nullable) UIFont *titleFont;

/**
 Sets the custom font to be used for the body text.

 Defaults to nil.
 */
@property(nonatomic, strong, nullable) UIFont *bodyFont;

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

/**
 Dismisses the feature highlight using the 'accept' style dismissal animation and triggers the
 completion block with accepted set to YES.

 Identical to the user tapping on the inner highlight.
 */
- (void)acceptFeature;

/**
 Dismisses the feature highlight using the 'reject' style dismissal animation and triggers the
 completion block with accepted set to NO.

 Identical to the user tapping outside of the inner highlight.
 */
- (void)rejectFeature;

@end

API_DEPRECATED_END