UIFocus.h

#if USE_UIKIT_PUBLIC_HEADERS || !__has_include(<UIKitCore/UIFocus.h>)
//
//  UIFocus.h
//  UIKit
//
//  Copyright © 2015-2018 Apple Inc. All rights reserved.
//

#import <Foundation/Foundation.h>
#import <UIKit/UIFocusGuide.h>
#import <UIKit/UIFocusAnimationCoordinator.h>
#import <UIKit/UIKitDefines.h>
@class UIView, UIFocusUpdateContext, UIFocusMovementHint;
@protocol UICoordinateSpace, UIFocusItemContainer;



/* 焦点更新状态 <枚举> */
typedef NS_OPTIONS(NSUInteger, UIFocusHeading) {
    UIFocusHeadingNone          = 0,        /// 没有焦点更新
    UIFocusHeadingUp            = 1 << 0,   /// 焦点更新正朝着向上的方向发展
    UIFocusHeadingDown          = 1 << 1,   /// 焦点更新正朝着向下的方向发展
    UIFocusHeadingLeft          = 1 << 2,   /// 焦点更新正朝着向左的方向发展
    UIFocusHeadingRight         = 1 << 3,   /// 焦点更新正朝着向右的方向发展
    UIFocusHeadingNext          = 1 << 4,   /// 焦点更新将转向下一个项目
    UIFocusHeadingPrevious      = 1 << 5,   /// 焦点更新将转向上一个项目
} NS_ENUM_AVAILABLE_IOS(9_0);



/*
 声音焦点标识符
    • 要为自定义声音文件指定标识符,请调用UIFocusSystem的 - registerURL:forSoundIdentifier: 方法
 */
#if UIKIT_STRING_ENUMS
typedef NSString * UIFocusSoundIdentifier NS_TYPED_EXTENSIBLE_ENUM;
#else
typedef NSString * UIFocusSoundIdentifier;
#endif

NS_ASSUME_NONNULL_BEGIN



///!!!: 焦点环境 <协议>
/*
 概述
    • 提供了一个通用界面,用于指定和响应整个App中的焦点行为;换句话说,直接或间接控制屏幕上视图的类
    • UIKit中遵守此协议的类有:UIView,UIViewController,UIWindow,UIPresentationController
 */
NS_CLASS_AVAILABLE_IOS(9_0) @protocol UIFocusEnvironment <NSObject>

/// 首选焦点环境 (按优先级排序的一系列焦点环境,在焦点更新期间,此环境更喜欢将焦点指向该焦点环境)
@property (nonatomic, copy, readonly) NSArray<id<UIFocusEnvironment>> *preferredFocusEnvironments;
/// 父焦点环境 (如果不存在父容器,则此属性为nil)
@property (nonatomic, weak, readonly, nullable) id<UIFocusEnvironment> parentFocusEnvironment NS_SWIFT_NAME(parentFocusEnvironment) API_AVAILABLE(tvos(12.0), ios(12.0));
/// 焦点项目容器 (任何子容器都在此焦点环境中聚焦项目,如果不存在容器,则为nil)
@property (nonatomic, readonly, nullable) id<UIFocusItemContainer> focusItemContainer API_AVAILABLE(tvos(12.0), ios(12.0));

// 设置焦点的更新 (向焦点引擎提交请求以在此环境中进行焦点更新)
- (void)setNeedsFocusUpdate;
// 立即更新焦点 (告诉焦点引擎立即强制进行焦点更新)
- (void)updateFocusIfNeeded;

// 是否允许焦点更新 (指定上下文的焦点)
- (BOOL)shouldUpdateFocusInContext:(UIFocusUpdateContext *)context;
// 焦点已经更新 (当屏幕的焦点项目更新为新项目时调用;使用动画协调器来安排与焦点相关的动画以响应更新)
- (void)didUpdateFocusInContext:(UIFocusUpdateContext *)context withAnimationCoordinator:(UIFocusAnimationCoordinator *)coordinator;

@optional
/* 焦点更新后播放的声音设置
 概述
    • 新的对象获得焦点时,会回调此方法
    • 方法中返回声音的标识符,系统会根据标识符播放对应的声音
    • 系统提供两种声音标识符:
        UIFocusSoundIdentifierDefault   系统默认声音
        UIFocusSoundIdentifierNone      无声
    • 可在此之前使用 registerURL:forSoundIdentifier:UIFocusSystem 方法注册自定义声音,就可返回自定义声音标识符
 */

- (nullable UIFocusSoundIdentifier)soundIdentifierForFocusUpdateInContext:(UIFocusUpdateContext *)context API_AVAILABLE(tvos(11.0)) API_UNAVAILABLE(ios, watchos);

/// 已弃用,请改用preferredFocusEnvironments
@property (nonatomic, weak, readonly, nullable) UIView *preferredFocusedView NS_DEPRECATED_IOS(9_0, 10_0, "Use -preferredFocusEnvironments instead.");

@end



///!!!: 焦点项 <协议>
NS_CLASS_AVAILABLE_IOS(10_0) @protocol UIFocusItem <UIFocusEnvironment>

/* 项目是否可以成为焦点 */
#if UIKIT_DEFINE_AS_PROPERTIES
@property(nonatomic, readonly) BOOL canBecomeFocused;
#else
- (BOOL)canBecomeFocused;
#endif

/// 焦点项在UIFocusItemContainer中的frame
@property (nonatomic, readonly) CGRect frame API_AVAILABLE(tvos(12.0), ios(12.0));

@optional
// 当前聚焦的项目可能发生焦点移动(每当用户的figner在遥控器上移动时,焦点引擎就会突出焦点项目)
- (void)didHintFocusMovement:(UIFocusMovementHint *)hint;

@end



///!!!: 焦点项容器 <协议>
NS_CLASS_AVAILABLE_IOS(12_0) @protocol UIFocusItemContainer <NSObject>

/// 焦点项的坐标空间
@property (nonatomic, readonly) id<UICoordinateSpace> coordinateSpace;

// 获取容器中指定范围内的焦点项
- (NSArray<id<UIFocusItem>> *)focusItemsInRect:(CGRect)rect;

@end



///!!!: 焦点项可滚动容器 <协议>
NS_CLASS_AVAILABLE_IOS(12_0) @protocol UIFocusItemScrollableContainer <UIFocusItemContainer>

/// 容器偏移量
@property (nonatomic, readwrite) CGPoint contentOffset;
/// 容器内容尺寸(如果此大小超过容器可见大小,则可以滚动)
@property (nonatomic, readonly) CGSize contentSize;
/// 容器可见尺寸
@property (nonatomic, readonly) CGSize visibleSize;

@end





#pragma mark - 焦点更新上下文 Class
#pragma mark -
/*
 概述
    - 提供从一个视图到另一个视图的特定焦点更新相关的信息
    - 它们是短暂的对象,通常在更新完成后被丢弃
 */
NS_CLASS_AVAILABLE_IOS(9_0) @interface UIFocusUpdateContext : NSObject

/// 焦点更新前关注的项目(在更新之前聚焦的项目,即焦点从哪里更新;如果没有项目被聚焦则可能为nil,如最初设置焦点时)
@property (nonatomic, weak, readonly, nullable) id<UIFocusItem> previouslyFocusedItem NS_AVAILABLE_IOS(10_0);
/// 焦点更新后关注的项目(更新后聚焦的项目,即焦点更新的位置;如果没有项目被聚焦则可能是nil,这意味着焦点丢失)
@property (nonatomic, weak, readonly, nullable) id<UIFocusItem> nextFocusedItem NS_AVAILABLE_IOS(10_0);
/// 此属性将在以后的版本中弃用,请改用previousFocusedItem
@property (nonatomic, weak, readonly, nullable) UIView *previouslyFocusedView;
/// 此属性将在以后的版本中弃用,请改用nextFocusedItem
@property (nonatomic, weak, readonly, nullable) UIView *nextFocusedView;
/// 焦点更新状态
@property (nonatomic, assign, readonly) UIFocusHeading focusHeading;

@end





/// 焦点已经更新通知
UIKIT_EXTERN NSNotificationName const UIFocusDidUpdateNotification API_AVAILABLE(ios(11.0), tvos(11.0));
/// 焦点移动失败通知
UIKIT_EXTERN NSNotificationName const UIFocusMovementDidFailNotification API_AVAILABLE(ios(11.0), tvos(11.0));

/// 焦点更新上下文密钥
UIKIT_EXTERN NSString * const UIFocusUpdateContextKey API_AVAILABLE(ios(11.0), tvos(11.0));
/// 焦点更新动画协调密钥
UIKIT_EXTERN NSString * const UIFocusUpdateAnimationCoordinatorKey API_AVAILABLE(ios(11.0), tvos(11.0));

/// 焦点更新期间禁用声音的声音标识符
UIKIT_EXTERN UIFocusSoundIdentifier const UIFocusSoundIdentifierNone API_AVAILABLE(tvos(11.0)) API_UNAVAILABLE(ios, watchos);
/// 焦点更新期间播放默认声音的声音标识符
UIKIT_EXTERN UIFocusSoundIdentifier const UIFocusSoundIdentifierDefault API_AVAILABLE(tvos(11.0)) API_UNAVAILABLE(ios, watchos);



NS_ASSUME_NONNULL_END
#else
#import <UIKitCore/UIFocus.h>
#endif