Files
sparkle-project.github.io/documentation/api-reference/Protocols/SUVersionDisplay.html
T
2025-02-23 14:54:02 +00:00

458 lines
27 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<title>SUVersionDisplay Protocol Reference</title>
<link rel="stylesheet" type="text/css" href="../css/jazzy.css" />
<link rel="stylesheet" type="text/css" href="../css/highlight.css" />
<meta charset='utf-8'>
<meta name="viewport" content="width=device-width, viewport-fit=cover, initial-scale=1.0" />
<script src="../js/jquery.min.js" defer></script>
<script src="../js/jazzy.js" defer></script>
</head>
<body>
<a name="//apple_ref/objc/Protocol/SUVersionDisplay" class="dashAnchor"></a>
<a title="SUVersionDisplay Protocol Reference"></a>
<header>
<div class="content-wrapper">
<p>
<a href="../index.html">Sparkle 2.7.0 Docs</a>
<span class="no-mobile"> (59% documented)</span>
</p>
</div>
</header>
<div id="breadcrumbs-container">
<div class="content-wrapper">
<p id="breadcrumbs">
<span class="no-mobile">
<a href="../index.html">Sparkle</a>
<img id="carat" src="../img/carat.png" alt=""/>
<a href="../Protocols.html">Protocols</a>
<img id="carat" src="../img/carat.png" alt=""/>
SUVersionDisplay Protocol Reference
</span>
</p>
</div>
</div>
<div class="wrapper">
<div class="article-wrapper">
<article class="main-content">
<section>
<section class="section">
<h1>SUVersionDisplay</h1>
<div class="declaration">
<div class="language">
<p class="aside-title">Objective-C</p>
<pre class="highlight objective_c"><code><span class="k">@protocol</span> <span class="nc">SUVersionDisplay</span> <span class="o">&lt;</span><span class="n">NSObject</span><span class="o">&gt;</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="kd">protocol</span> <span class="kt">SUVersionDisplay</span> <span class="p">:</span> <span class="kt">NSObjectProtocol</span></code></pre>
</div>
</div>
<p>Applies special display formatting to version numbers of the bundle to update and the update before presenting them to the user.</p>
</section>
<section class="section task-group-section">
<div class="task-group">
<ul>
<li class="item">
<div>
<code>
<a name="/c:objc(pl)SUVersionDisplay(im)formatUpdateDisplayVersionFromUpdate:andBundleDisplayVersion:withBundleVersion:"></a>
<a name="//apple_ref/objc/Method/-formatUpdateDisplayVersionFromUpdate:andBundleDisplayVersion:withBundleVersion:" class="dashAnchor"></a>
<a class="token" href="#/c:objc(pl)SUVersionDisplay(im)formatUpdateDisplayVersionFromUpdate:andBundleDisplayVersion:withBundleVersion:">-formatUpdateDisplayVersionFromUpdate:<wbr>andBundleDisplayVersion:<wbr>withBundleVersion:<wbr></a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>Formats an update&rsquo;s version string and bundle&rsquo;s version string for display.</p>
<p>This method is used to format both the display version of the update and the display version of the bundle to update.</p>
<p>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.</p>
<p>On input, the <code>update.displayVersionString</code> and <code>*inOutBundleDisplayVersion</code> may be the same, but the
<code>update.versionString</code> and <code>bundleVersion</code> will differ. To differentiate between these display versions, you may
choose to return different display version strings for the update and bundle.</p>
</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Objective-C</p>
<pre class="highlight objective_c"><code><span class="k">-</span> <span class="p">(</span><span class="n">nonnull</span> <span class="n">NSString</span> <span class="o">*</span><span class="p">)</span>
<span class="nf">formatUpdateDisplayVersionFromUpdate</span><span class="p">:(</span><span class="n">nonnull</span> <span class="n"><a href="../Classes/SUAppcastItem.html">SUAppcastItem</a></span> <span class="o">*</span><span class="p">)</span><span class="nv">update</span>
<span class="nf">andBundleDisplayVersion</span><span class="p">:</span>
<span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="n">_Nonnull</span> <span class="o">*</span><span class="n">_Nonnull</span><span class="p">)</span><span class="nv">inOutBundleDisplayVersion</span>
<span class="nf">withBundleVersion</span><span class="p">:(</span><span class="n">nonnull</span> <span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">bundleVersion</span><span class="p">;</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="kd">func</span> <span class="nf">formatUpdateVersion</span><span class="p">(</span><span class="n">fromUpdate</span> <span class="nv">update</span><span class="p">:</span> <span class="kt"><a href="../Classes/SUAppcastItem.html">SUAppcastItem</a></span><span class="p">,</span> <span class="n">andBundleDisplayVersion</span> <span class="nv">inOutBundleDisplayVersion</span><span class="p">:</span> <span class="kt">AutoreleasingUnsafeMutablePointer</span><span class="o">&lt;</span><span class="kt">NSString</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">withBundleVersion</span> <span class="nv">bundleVersion</span><span class="p">:</span> <span class="kt">String</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">String</span></code></pre>
</div>
</div>
<div>
<h4>Parameters</h4>
<table class="graybox">
<tbody>
<tr>
<td>
<code>
<em>update</em>
</code>
</td>
<td>
<div>
<p>The update to format the update display version from. You can query <code>update.displayVersionString</code> and <code>update.versionString</code> to retrieve the update&rsquo;s version information.</p>
</div>
</td>
</tr>
<tr>
<td>
<code>
<em>inOutBundleDisplayVersion</em>
</code>
</td>
<td>
<div>
<p>On input, the display version string (or <code>CFBundleShortVersionString</code>) of the bundle to update. On output, this is the display version string of the bundle to show to the user.</p>
</div>
</td>
</tr>
<tr>
<td>
<code>
<em>bundleVersion</em>
</code>
</td>
<td>
<div>
<p>The version (or CFBundleVersion) of the bundle to update.</p>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div>
<h4>Return Value</h4>
<p>A new display version string of the <code>update.displayVersionString</code> to show to the user.</p>
</div>
</section>
</div>
</li>
<li class="item">
<div>
<code>
<a name="/c:objc(pl)SUVersionDisplay(im)formatBundleDisplayVersion:withBundleVersion:matchingUpdate:"></a>
<a name="//apple_ref/objc/Method/-formatBundleDisplayVersion:withBundleVersion:matchingUpdate:" class="dashAnchor"></a>
<a class="token" href="#/c:objc(pl)SUVersionDisplay(im)formatBundleDisplayVersion:withBundleVersion:matchingUpdate:">-formatBundleDisplayVersion:<wbr>withBundleVersion:<wbr>matchingUpdate:<wbr></a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>Formats a bundle&rsquo;s version string for display.</p>
<p>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.</p>
<p>This method is optional. If it&rsquo;s not implemented, Sparkle will default to using the <code>bundleDisplayVersion</code> passed to this method.</p>
</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Objective-C</p>
<pre class="highlight objective_c"><code><span class="k">-</span> <span class="p">(</span><span class="n">nonnull</span> <span class="n">NSString</span> <span class="o">*</span><span class="p">)</span>
<span class="nf">formatBundleDisplayVersion</span><span class="p">:(</span><span class="n">nonnull</span> <span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">bundleDisplayVersion</span>
<span class="nf">withBundleVersion</span><span class="p">:(</span><span class="n">nonnull</span> <span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">bundleVersion</span>
<span class="nf">matchingUpdate</span><span class="p">:(</span><span class="n"><a href="../Classes/SUAppcastItem.html">SUAppcastItem</a></span> <span class="o">*</span><span class="n">_Nullable</span><span class="p">)</span><span class="nv">matchingUpdate</span><span class="p">;</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="kd">optional</span> <span class="kd">func</span> <span class="nf">formatBundleDisplayVersion</span><span class="p">(</span><span class="n">_</span> <span class="nv">bundleDisplayVersion</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span> <span class="n">withBundleVersion</span> <span class="nv">bundleVersion</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span> <span class="nv">matchingUpdate</span><span class="p">:</span> <span class="kt"><a href="../Classes/SUAppcastItem.html">SUAppcastItem</a></span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="kt">String</span></code></pre>
</div>
</div>
<div>
<h4>Parameters</h4>
<table class="graybox">
<tbody>
<tr>
<td>
<code>
<em>bundleDisplayVersion</em>
</code>
</td>
<td>
<div>
<p>The display version string (or <code>CFBundleShortVersionString</code>) of the bundle to update.</p>
</div>
</td>
</tr>
<tr>
<td>
<code>
<em>bundleVersion</em>
</code>
</td>
<td>
<div>
<p>The version (or <code>CFBundleVersion</code>) of the bundle to update.</p>
</div>
</td>
</tr>
<tr>
<td>
<code>
<em>matchingUpdate</em>
</code>
</td>
<td>
<div>
<p>The update in the feed that corresponds to the current bundle, or <code>nil</code> if no matching update item could be found in the feed.</p>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div>
<h4>Return Value</h4>
<p>A new display version string of the bundle to show to the user.</p>
</div>
</section>
</div>
</li>
<li class="item">
<div>
<code>
<a name="/c:objc(pl)SUVersionDisplay(im)formatVersion:andVersion:"></a>
<a name="//apple_ref/objc/Method/-formatVersion:andVersion:" class="dashAnchor"></a>
<a class="token discouraged" href="#/c:objc(pl)SUVersionDisplay(im)formatVersion:andVersion:">-formatVersion:<wbr>andVersion:<wbr></a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="aside aside-deprecated">
<p class="aside-title">Deprecated</p>
<p>Please use -formatUpdateDisplayVersionFromUpdate:andBundleDisplayVersion:withBundleVersion:</p>
</div>
<div class="abstract">
<p>Formats two version strings.</p>
<p>Both versions are provided so that important distinguishing information
can be displayed while also leaving out unnecessary/confusing parts.</p>
</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Objective-C</p>
<pre class="highlight objective_c"><code><span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">formatVersion</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="n">_Nonnull</span> <span class="o">*</span><span class="n">_Nonnull</span><span class="p">)</span><span class="nv">inOutVersionA</span>
<span class="nf">andVersion</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="n">_Nonnull</span> <span class="o">*</span><span class="n">_Nonnull</span><span class="p">)</span><span class="nv">inOutVersionB</span><span class="p">;</span></code></pre>
</div>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="kd">optional</span> <span class="kd">func</span> <span class="nf">formatVersion</span><span class="p">(</span><span class="n">_</span> <span class="nv">inOutVersionA</span><span class="p">:</span> <span class="kt">AutoreleasingUnsafeMutablePointer</span><span class="o">&lt;</span><span class="kt">NSString</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">andVersion</span> <span class="nv">inOutVersionB</span><span class="p">:</span> <span class="kt">AutoreleasingUnsafeMutablePointer</span><span class="o">&lt;</span><span class="kt">NSString</span><span class="o">&gt;</span><span class="p">)</span></code></pre>
</div>
</div>
</section>
</div>
</li>
</ul>
</div>
</section>
</section>
</article>
</div>
<div class="nav-wrapper">
<nav class="nav-bottom">
<ul class="nav-groups">
<li class="nav-group-name">
<a href="../Classes.html">Classes</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="../Classes/SPUDownloadData.html">SPUDownloadData</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SPUStandardUpdaterController.html">SPUStandardUpdaterController</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SPUStandardUserDriver.html">SPUStandardUserDriver</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SPUUpdatePermissionRequest.html">SPUUpdatePermissionRequest</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SPUUpdater.html">SPUUpdater</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SPUUpdaterSettings.html">SPUUpdaterSettings</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SPUUserUpdateState.html">SPUUserUpdateState</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SUAppcast.html">SUAppcast</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SUAppcastItem.html">SUAppcastItem</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SUStandardVersionComparator.html">SUStandardVersionComparator</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SUUpdatePermissionResponse.html">SUUpdatePermissionResponse</a>
</li>
<li class="nav-group-task">
<a href="../Classes/SUUpdater.html">SUUpdater</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="../Constants.html">Constants</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="../Constants.html#/c:@SPULatestAppcastItemFoundKey">SPULatestAppcastItemFoundKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SPUNoUpdateFoundReasonKey">SPUNoUpdateFoundReasonKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SPUNoUpdateFoundUserInitiatedKey">SPUNoUpdateFoundUserInitiatedKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSparkleErrorDomain">SUSparkleErrorDomain</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerApplicationNameKey">SUSystemProfilerApplicationNameKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerApplicationVersionKey">SUSystemProfilerApplicationVersionKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerCPU64bitKey">SUSystemProfilerCPU64bitKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerCPUCountKey">SUSystemProfilerCPUCountKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerCPUFrequencyKey">SUSystemProfilerCPUFrequencyKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerCPUSubtypeKey">SUSystemProfilerCPUSubtypeKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerCPUTypeKey">SUSystemProfilerCPUTypeKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerHardwareModelKey">SUSystemProfilerHardwareModelKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerMemoryKey">SUSystemProfilerMemoryKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerOperatingSystemVersionKey">SUSystemProfilerOperatingSystemVersionKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUSystemProfilerPreferredLanguageKey">SUSystemProfilerPreferredLanguageKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUUpdaterAppcastItemNotificationKey">SUUpdaterAppcastItemNotificationKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUUpdaterAppcastNotificationKey">SUUpdaterAppcastNotificationKey</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUUpdaterDidFindValidUpdateNotification">SUUpdaterDidFindValidUpdateNotification</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUUpdaterDidFinishLoadingAppCastNotification">SUUpdaterDidFinishLoadingAppCastNotification</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUUpdaterDidNotFindUpdateNotification">SUUpdaterDidNotFindUpdateNotification</a>
</li>
<li class="nav-group-task">
<a href="../Constants.html#/c:@SUUpdaterWillRestartNotification">SUUpdaterWillRestartNotification</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="../Enums.html">Enumerations</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="../Enums/SPUNoUpdateFoundReason.html">SPUNoUpdateFoundReason</a>
</li>
<li class="nav-group-task">
<a href="../Enums/SPUUpdateCheck.html">SPUUpdateCheck</a>
</li>
<li class="nav-group-task">
<a href="../Enums/SPUUserUpdateChoice.html">SPUUserUpdateChoice</a>
</li>
<li class="nav-group-task">
<a href="../Enums/SPUUserUpdateStage.html">SPUUserUpdateStage</a>
</li>
<li class="nav-group-task">
<a href="../Enums/SUError.html">SUError</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="../Protocols.html">Protocols</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="../Protocols/SPUStandardUserDriverDelegate.html">SPUStandardUserDriverDelegate</a>
</li>
<li class="nav-group-task">
<a href="../Protocols/SPUUpdaterDelegate.html">SPUUpdaterDelegate</a>
</li>
<li class="nav-group-task">
<a href="../Protocols/SPUUserDriver.html">SPUUserDriver</a>
</li>
<li class="nav-group-task">
<a href="../Protocols/SUUpdaterDelegate.html">SUUpdaterDelegate</a>
</li>
<li class="nav-group-task">
<a href="../Protocols/SUVersionComparison.html">SUVersionComparison</a>
</li>
<li class="nav-group-task">
<a href="../Protocols/SUVersionDisplay.html">SUVersionDisplay</a>
</li>
</ul>
</li>
</ul>
</nav>
</div>
<div class="footer-wrapper">
<section id="footer">
<p>&copy; 2025 <a class="link" href="https://sparkle-project.org" target="_blank" rel="external noopener">Sparkle Project</a>. All rights reserved. (Last updated: 2025-02-23)</p>
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external noopener">jazzy ♪♫ v0.15.3</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external noopener">Realm</a> project.</p>
</section>
</div>
</div>
</body>
</html>