|
| 1 | +// |
| 2 | +// SPUStandardUpdaterController.h |
| 3 | +// Sparkle |
| 4 | +// |
| 5 | +// Created by Mayur Pawashe on 2/28/16. |
| 6 | +// Copyright © 2016 Sparkle Project. All rights reserved. |
| 7 | +// |
| 8 | + |
| 9 | +#if __has_feature(modules) |
| 10 | +#if __has_warning("-Watimport-in-framework-header") |
| 11 | +#pragma clang diagnostic ignored "-Watimport-in-framework-header" |
| 12 | +#endif |
| 13 | +@import Foundation; |
| 14 | +#else |
| 15 | +#import <Foundation/Foundation.h> |
| 16 | +#endif |
| 17 | +#import <Sparkle/SUExport.h> |
| 18 | + |
| 19 | +NS_ASSUME_NONNULL_BEGIN |
| 20 | + |
| 21 | +@class SPUUpdater; |
| 22 | +@class SPUStandardUserDriver; |
| 23 | +@class NSMenuItem; |
| 24 | +@protocol SPUUserDriver, SPUUpdaterDelegate, SPUStandardUserDriverDelegate; |
| 25 | + |
| 26 | +/** |
| 27 | + A controller class that instantiates a `SPUUpdater` and allows binding UI to its updater settings. |
| 28 | + |
| 29 | + This class can be instantiated in a nib or created programatically using `-initWithUpdaterDelegate:userDriverDelegate:` or `-initWithStartingUpdater:updaterDelegate:userDriverDelegate:`. |
| 30 | + |
| 31 | + The controller's updater targets the application's main bundle and uses Sparkle's standard user interface. |
| 32 | + Typically, this class is used by sticking it as a custom NSObject subclass in an Interface Builder nib (probably in MainMenu) but it works well programatically too. |
| 33 | + |
| 34 | + The controller creates an `SPUUpdater` instance using a `SPUStandardUserDriver` and allows hooking up the check for updates action and handling menu item validation. |
| 35 | + It also allows hooking up the updater's and user driver's delegates. |
| 36 | + |
| 37 | + If you need more control over what bundle you want to update, or you want to provide a custom user interface (via `SPUUserDriver`), please use `SPUUpdater` directly instead. |
| 38 | + */ |
| 39 | +SU_EXPORT @interface SPUStandardUpdaterController : NSObject |
| 40 | +{ |
| 41 | + /** |
| 42 | + * Interface builder outlet for the updater's delegate. |
| 43 | + */ |
| 44 | + IBOutlet __weak id<SPUUpdaterDelegate> updaterDelegate; |
| 45 | + |
| 46 | + /** |
| 47 | + * Interface builder outlet for the user driver's delegate. |
| 48 | + */ |
| 49 | + IBOutlet __weak id<SPUStandardUserDriverDelegate> userDriverDelegate; |
| 50 | +} |
| 51 | + |
| 52 | +/** |
| 53 | + Accessible property for the updater. Some properties on the updater can be binded via KVO |
| 54 | + |
| 55 | + When instantiated from a nib, don't perform update checks before the application has finished launching in a MainMenu nib (i.e applicationDidFinishLaunching:) or before the corresponding window/view controller has been loaded (i.e, windowDidLoad or viewDidLoad). The updater is not guaranteed to be started yet before these points. |
| 56 | + */ |
| 57 | +@property (nonatomic, readonly) SPUUpdater *updater; |
| 58 | + |
| 59 | +/** |
| 60 | + Accessible property for the updater's user driver. |
| 61 | + */ |
| 62 | +@property (nonatomic, readonly) SPUStandardUserDriver *userDriver; |
| 63 | + |
| 64 | +/** |
| 65 | + Create a new `SPUStandardUpdaterController` from a nib. |
| 66 | + |
| 67 | + You cannot call this initializer directly. You must instantiate a `SPUStandardUpdaterController` inside of a nib (typically the MainMenu nib) to use it. |
| 68 | + |
| 69 | + To create a `SPUStandardUpdaterController` programatically, use `-initWithUpdaterDelegate:userDriverDelegate:` or `-initWithStartingUpdater:updaterDelegate:userDriverDelegate:` instead. |
| 70 | + */ |
| 71 | +- (instancetype)init NS_UNAVAILABLE; |
| 72 | + |
| 73 | +/** |
| 74 | + Create a new `SPUStandardUpdaterController` programmatically. |
| 75 | + |
| 76 | + The updater is started automatically. See `-startUpdater` for more information. |
| 77 | + */ |
| 78 | +- (instancetype)initWithUpdaterDelegate:(nullable id<SPUUpdaterDelegate>)updaterDelegate userDriverDelegate:(nullable id<SPUStandardUserDriverDelegate>)userDriverDelegate; |
| 79 | + |
| 80 | +/** |
| 81 | + Create a new `SPUStandardUpdaterController` programmatically allowing you to specify whether or not to start the updater immediately. |
| 82 | + |
| 83 | + You can specify whether or not you want to start the updater immediately. |
| 84 | + If you do not start the updater, you must invoke `-startUpdater` at a later time to start it. |
| 85 | + */ |
| 86 | +- (instancetype)initWithStartingUpdater:(BOOL)startUpdater updaterDelegate:(nullable id<SPUUpdaterDelegate>)updaterDelegate userDriverDelegate:(nullable id<SPUStandardUserDriverDelegate>)userDriverDelegate; |
| 87 | + |
| 88 | +/** |
| 89 | + Starts the updater if it has not already been started. |
| 90 | + |
| 91 | + You should only call this method yourself if you opted out of starting the updater on initialization. |
| 92 | + Hence, do not call this yourself if you are instantiating this controller from a nib. |
| 93 | + |
| 94 | + This invokes `-[SPUUpdater startUpdater:]`. If the application is misconfigured with Sparkle, an error is logged and an alert is shown to the user (after a few seconds) to contact the developer. |
| 95 | + If you want more control over this behavior, you can create your own `SPUUpdater` instead of using `SPUStandardUpdaterController`. |
| 96 | + */ |
| 97 | +- (void)startUpdater; |
| 98 | + |
| 99 | +/** |
| 100 | + Explicitly checks for updates and displays a progress dialog while doing so. |
| 101 | + |
| 102 | + This method is meant for a main menu item. |
| 103 | + Connect any NSMenuItem to this action in Interface Builder or programmatically, |
| 104 | + and Sparkle will check for updates and report back its findings verbosely when it is invoked. |
| 105 | + |
| 106 | + When the target/action of the menu item is set to this controller and this method, |
| 107 | + this controller also handles enabling/disabling the menu item by checking |
| 108 | + `-[SPUUpdater canCheckForUpdates]` |
| 109 | + |
| 110 | + This action checks updates by invoking `-[SPUUpdater checkForUpdates]` |
| 111 | + */ |
| 112 | +- (IBAction)checkForUpdates:(nullable id)sender; |
| 113 | + |
| 114 | +@end |
| 115 | + |
| 116 | +NS_ASSUME_NONNULL_END |
0 commit comments