SUVersionDisplay

Objective-C

@protocol SUVersionDisplay <NSObject>

Swift

protocol SUVersionDisplay : NSObjectProtocol

Applies special display formatting to version numbers of the bundle to update and the update before presenting them to the user.

  • Formats an update’s version string and bundle’s version string for display.

    This method is used to format both the display version of the update and the display version of the bundle to update.

    The display versions returned by this method are then used for presenting to the user when a new update is available, or when the user cannot download/install the latest update for a specific reason, or when the user has a newer version installed than the latest known version in the update feed.

    On input, the update.displayVersionString and *inOutBundleDisplayVersion may be the same, but the update.versionString and bundleVersion will differ. To differentiate between these display versions, you may choose to return different display version strings for the update and bundle.

    Declaration

    Objective-C

    - (nonnull NSString *)
    formatUpdateDisplayVersionFromUpdate:(nonnull SUAppcastItem *)update
                 andBundleDisplayVersion:
                     (NSString *_Nonnull *_Nonnull)inOutBundleDisplayVersion
                       withBundleVersion:(nonnull NSString *)bundleVersion;

    Swift

    func formatUpdateVersion(fromUpdate update: SUAppcastItem, andBundleDisplayVersion inOutBundleDisplayVersion: AutoreleasingUnsafeMutablePointer<NSString>, withBundleVersion bundleVersion: String) -> String

    Parameters

    update

    The update to format the update display version from. You can query update.displayVersionString and update.versionString to retrieve the update’s version information.
    inOutBundleDisplayVersion

    On input, the display version string (or CFBundleShortVersionString) of the bundle to update. On output, this is the display version string of the bundle to show to the user.
    bundleVersion

    The version (or CFBundleVersion) of the bundle to update.

    Return Value

    A new display version string of the update.displayVersionString to show to the user.

  • Formats a bundle’s version string for display.

    This method is used to format the display version of the bundle. This method may be used when no new update is available and the user is already on the latest known version. In this case, no new update version is shown to the user.

    This method is optional. If it’s not implemented, Sparkle will default to using the bundleDisplayVersion passed to this method.

    Declaration

    Objective-C

    - (nonnull NSString *)
    formatBundleDisplayVersion:(nonnull NSString *)bundleDisplayVersion
             withBundleVersion:(nonnull NSString *)bundleVersion
                matchingUpdate:(SUAppcastItem *_Nullable)matchingUpdate;

    Swift

    optional func formatBundleDisplayVersion(_ bundleDisplayVersion: String, withBundleVersion bundleVersion: String, matchingUpdate: SUAppcastItem?) -> String

    Parameters

    bundleDisplayVersion

    The display version string (or CFBundleShortVersionString) of the bundle to update.
    bundleVersion

    The version (or CFBundleVersion) of the bundle to update.
    matchingUpdate

    The update in the feed that corresponds to the current bundle, or nil if no matching update item could be found in the feed.

    Return Value

    A new display version string of the bundle to show to the user.

  • Deprecated

    Please use -formatUpdateDisplayVersionFromUpdate:andBundleDisplayVersion:withBundleVersion:

    Formats two version strings.

    Both versions are provided so that important distinguishing information can be displayed while also leaving out unnecessary/confusing parts.

    Declaration

    Objective-C

    - (void)formatVersion:(NSString *_Nonnull *_Nonnull)inOutVersionA
           andVersion:(NSString *_Nonnull *_Nonnull)inOutVersionB;

    Swift

    optional func formatVersion(_ inOutVersionA: AutoreleasingUnsafeMutablePointer<NSString>, andVersion inOutVersionB: AutoreleasingUnsafeMutablePointer<NSString>)