//  
//  GCControllerHomeButtonSettingsManager.h
//  GameController
//
//  Copyright © 2026 Apple Inc. All rights reserved.
//

#import <Foundation/Foundation.h>

#import <GameController/GCExtern.h>

NS_ASSUME_NONNULL_BEGIN

typedef NS_ENUM(NSInteger, GCControllerHomeButtonSettingsAction) {
    /** The controller home button action could not be accessed. */
    GCControllerHomeButtonSettingsActionUnavailable = 0,
    /** The controller home button action opens the current application. */
    GCControllerHomeButtonSettingsActionOpenCurrentApplication = 1,
    /** The controller home button action performs some other action. */
    GCControllerHomeButtonSettingsActionOther = NSIntegerMax,
    /** Controller home button actions are disabled. */
    GCControllerHomeButtonSettingsActionDisabled API_AVAILABLE(macos(27.0)) API_UNAVAILABLE(ios, tvos, visionos) = -1,
} NS_SWIFT_NAME(GCControllerHomeButtonSettingsManager.Action) API_AVAILABLE(macos(27.0), ios(27.0), visionos(27.0)) API_UNAVAILABLE(tvos);

/**
 *  A hint passed to `-openControllerHomeButtonSettingsForActivity:` that
 *  indicates the reason the app is requesting to open the Home button settings.
 */
typedef NS_ENUM(NSInteger, GCControllerHomeButtonSettingsActivity) {
    /** Customize the action that occurs in response to long press of the
     *  Home button. */
    GCControllerHomeButtonSettingsCustomizeActionActivity NS_SWIFT_NAME(customizeAction) = 1,
    /** Disable the system Home button actions while this app has focus. */
    GCControllerHomeButtonSettingsCustomizeOverridesActivity NS_SWIFT_NAME(customizeOverrides),
} NS_SWIFT_NAME(GCControllerHomeButtonSettingsManager.Activity) API_AVAILABLE(macos(27.0), ios(27.0), visionos(27.0)) API_UNAVAILABLE(tvos);


/**
 *  Access the game controller system Home button settings.
 *
 *  macOS, iOS, and visionOS allow the user to assign an action that launches a
 *  chosen application to a long press of the Home button (the logo button on
 *  PlayStation and Xbox controllers).  The \c GCControllerHomeButtonSettingsManager
 *  class allows your application to partially inspect the user's currently
 *  configured action, and to open the system game controller settings screen
 *  where the user can modify the action.
 *
 *  @note
 *  Performing operations on `GCControllerHomeButtonSettingsManager` is only
 *  permitted while a game controller is connected.
 */
API_AVAILABLE(macos(27.0), ios(27.0), visionos(27.0)) API_UNAVAILABLE(tvos)
@interface GCControllerHomeButtonSettingsManager : NSObject

- (nullable instancetype)initWithQueue:(nullable dispatch_queue_t)queue;
- (nullable instancetype)init;

/**
 *  A block that is called after shortcut settings change.
 *
 *  This block is called on the queue that the
 *  `GCControllerHomeButtonSettingsManager` was initialized with.
 */
@property (atomic, copy, nullable) dispatch_block_t settingsDidChangeHandler;

/**
 *  Opens the Settings app to the screen in game controller settings where
 *  the user can change the controller shortcut action.
 *
 *  @return
 *  YES if the Settings app was opened, NO if it could not be opened and
 *  \p error contains additional information.  This function returns immediately
 *  after attempting to open the Settings app.
 */
- (BOOL)openControllerHomeButtonSettingsForActivity:(GCControllerHomeButtonSettingsActivity)activity error:(NSError * __autoreleasing *)error;

/**
 *  Get the current controller Home button action.
 */
- (GCControllerHomeButtonSettingsAction)readControllerHomeButtonActionWithError:(NSError * _Nullable __autoreleasing * _Nullable)error NS_REFINED_FOR_SWIFT;

@end

NS_ASSUME_NONNULL_END
