Add start-up code to determine if What's New dialogue is required.

Some additional version information code was added to enable testing if a version number falls within a desired range.

Author: delphidabbler

Src/FirstRun.UConfigFile.pas

@@ -16,6 +16,11 @@
 interface
 
 
+uses
+  // Project
+  UVersionInfo;
+
+
 type
   ///  <summary>Class that manages the updating of older config files to the
   ///  current format. Missing files will also be created.</summary>
@@ -60,6 +65,9 @@   TConfigFileUpdater = class abstract(TObject)
     ///  <summary>Checks if program version in config file is same as current
     ///  program version.</summary>
     function IsCurrentProgramVer: Boolean; overload;
+    class function PreviousProgramVer(const CfgFileName: string):
+      TVersionNumber; overload;
+    function PreviousProgramVer: TVersionNumber; overload;
     ///  <summary>Stamps config file with current file version.</summary>
     procedure Stamp; virtual;
   end;
@@ -234,10 +242,25 @@ class function TConfigFileUpdater.IsCurrentProgramVer(
 var
   CfgProgVer: string;  // program version from config file
 begin
-  CfgProgVer := GetIniString('IniFile', 'ProgramVersion', '', CfgFileName);
+  CfgProgVer := PreviousProgramVer(CfgFileName);
   Result := CfgProgVer = TAppInfo.ProgramReleaseVersion;
 end;
 
+function TConfigFileUpdater.PreviousProgramVer: TVersionNumber;
+begin
+  Result := PreviousProgramVer(fCfgFileName);
+end;
+
+class function TConfigFileUpdater.PreviousProgramVer(
+  const CfgFileName: string): TVersionNumber;
+begin
+  if not TVersionNumber.TryStrToVersionNumber(
+    GetIniString('IniFile', 'ProgramVersion', '', CfgFileName),
+    Result
+  ) then
+    Exit(TVersionNumber.Nul);
+end;
+
 procedure TConfigFileUpdater.Stamp;
 begin
   if not TFile.Exists(fCfgFileName, False) then

Src/FirstRun.UMain.pas

@@ -19,7 +19,7 @@ interface
 
 uses
   // Project
-  FirstRun.UConfigFile, FirstRun.UDatabase, FirstRun.UInstallInfo;
+  FirstRun.UConfigFile, FirstRun.UDatabase, FirstRun.UInstallInfo, UVersionInfo;
 
 
 type
@@ -79,8 +79,17 @@   TFirstRun = class(TObject)
     ///  <summary>Creates a new, empty, Unicode encoded per-user config file for
     ///  current installation.</summary>
     procedure CreateEmptyUserCfgFile;
-    ///  <summary>
+    ///  <summary>Checks if the program has been updated since the last run.
+    ///  </summary>
+    ///  <remarks>Compares the version number stored in the brought forward
+    ///  config file against the current program version number from resources.
+    ///  </remarks>
     function IsProgramUpdated: Boolean;
+    ///  <summary>Checks if the previous program's version number, as specified
+    ///  in the user config file, is contained in the range Lo..Hi with range
+    ///  endpoints determined by IntervalEndPoints.</summary>
+    function IsPreviousProgramVerInRange(const Lo, Hi: TVersionNumber;
+      const IntervalEndPoints: TVersionNumber.TIntervalEndPoints): Boolean;
   end;
 
 type
@@ -108,7 +117,8 @@   TFirstRunMgr = class(TObject)
     class function IsProgramUpdated: Boolean;
   public
     ///  <summary>Runs start-up checks to detect if program has been run before
-    ///  and performs any required user config and user database updates.
+    ///  and performs any required user config and user database updates. In
+    ///  some circumstances a "what's new" dialogue box may be displayed.
     ///  </summary>
     class procedure Execute;
   end;
@@ -119,9 +129,10 @@ implementation
 
 uses
   // Delphi
-  SysUtils, IOUtils, Forms
-  {$IFNDEF PORTABLE}
+  SysUtils, IOUtils, Forms,
   // Project
+  FirstRun.FmWhatsNew
+  {$IFNDEF PORTABLE}
   ,
   FirstRun.FmV4ConfigDlg;
   {$ELSE}
@@ -187,6 +198,15 @@ function TFirstRun.HaveOldUserDB: Boolean;
   Result := TFile.Exists(fInstallInfo.PreviousUserDatabaseFileName, False);
 end;
 
+function TFirstRun.IsPreviousProgramVerInRange(const Lo, Hi: TVersionNumber;
+  const IntervalEndPoints: TVersionNumber.TIntervalEndPoints): Boolean;
+var
+  PrevProgVer: TVersionNumber;
+begin
+  PrevProgVer := fUserConfigFile.PreviousProgramVer;
+  Result := PrevProgVer.IsInRange(Lo, Hi, IntervalEndPoints);
+end;
+
 function TFirstRun.IsProgramUpdated: Boolean;
 begin
   Result := fUserConfigFile.IsCurrentProgramVer;
@@ -270,6 +290,12 @@ procedure TFirstRun.UpdateUserCfgFile(out Changes: TFirstRunCfgChangeSet);
 { TFirstRunMgr }
 
 class procedure TFirstRunMgr.Execute;
+const
+  // Version numbers specifying a range in which previous program version must
+  // lie in order to display "What's New" dialogue box.
+  // Range is [NeedWhatsNewLoVerIncl, NeedWhatsNewHiVerExcl)
+  NeedWhatsNewLoVerIncl: TVersionNumber = (V1: 4; V2: 0; V3: 0; V4: 0);
+  NeedWhatsNewHiVerExcl: TVersionNumber = (V1: 4; V2: 16; V3: 0; V4: 0);
 var
   FR: TFirstRun;
   Changes: TFirstRunCfgChangeSet;
@@ -295,7 +321,15 @@ class procedure TFirstRunMgr.Execute;
   begin
     FR := TFirstRun.Create;
     try
-      FR.UpdateUserCfgFile(Changes);
+      // We display "What's New" dialogue box if previous program version number
+      // is in the given range
+      if FR.IsPreviousProgramVerInRange(
+        NeedWhatsNewLoVerIncl,
+        NeedWhatsNewHiVerExcl,
+        TVersionNumber.TIntervalEndPoints.iepHalfOpenHi
+      ) then
+        TWhatsNewDlg.Execute(Application);
+      FR.UpdateUserCfgFile(Changes);  // we ignore Changes [out] param value
     finally
       FR.Free;
     end;

Src/UVersionInfo.pas

@@ -33,6 +33,17 @@   TVersionNumber = record
   strict private
     ///  <summary>Converts version number to a string.</summary>
     function ToString: string;
+  public
+    type
+      ///  <summary>Enumeration that specifies whether intervals used in range
+      ///  checks are open, closed or half-open.</summary>
+      ///  <remarks>
+      ///  <para><c>iepOpen</c> - open interval (x,y)</para>
+      ///  <para><c>iepHalfOpenLo</c> - half open interval (x,y]</para>
+      ///  <para><c>iepHalfOpenHi</c> - half open interval [x,y)</para>
+      ///  <para><c>iepClosed</c> - closed interval [x,y]</para>
+      ///  </remarks>
+      TIntervalEndPoints = (iepOpen, iepHalfOpenLo, iepHalfOpenHi, iepClosed);
   public
     V1: Word;   // Major version number
     V2: Word;   // Minor version number
@@ -45,6 +56,13 @@   TVersionNumber = record
       {Creates a nul version number with all fields set to zero.
         @return Required nul record.
       }
+    ///  <summary>Checks if the current version number is contained in the range
+    ///  Lo..Hi with range endpoints determined by EndPoints.</summary>
+    ///  <remarks>Note that when Lo=Hi the intervals (Lo,Hi), (Lo,Hi] and
+    ///  [Lo,Hi) represent the empty set, while [Lo,Hi] = {Lo}. When Lo &gt; Hi
+    ///  all interval types represent the empty set.</remarks>
+    function IsInRange(const Lo, Hi: TVersionNumber;
+      const EndPoints: TIntervalEndPoints): Boolean;
     ///  <summary>Attempts to convert a string to a version number.</summary>
     ///  <param name="S">string [in] String to convert.</param>
     ///  <param name="V">Word [out] Converted version number.</param>
@@ -170,6 +188,7 @@ implementation
   // Delphi
   SysUtils,
   // Project
+  UExceptions,
   UIStringList,
   UUtils;
 
@@ -318,6 +337,19 @@ class function TVersionInfo.SpecialBuildStr: string;
     raise EConvertError.CreateFmt(sError, [Str]);
 end;
 
+function TVersionNumber.IsInRange(const Lo, Hi: TVersionNumber;
+  const EndPoints: TIntervalEndPoints): Boolean;
+begin
+  case EndPoints of
+    iepOpen: Result := (Lo < Self) and (Self < Hi);
+    iepHalfOpenLo: Result := (Lo < Self) and (Self <= Hi);
+    iepHalfOpenHi: Result := (Lo <= Self) and (Self < Hi);
+    iepClosed: Result := (Lo <= Self) and (Self <= Hi);
+    else
+      raise EBug.Create('TVersionNumber.IsInRange: invalid Kind parameter');
+  end;
+end;
+
 function TVersionNumber.IsNull: Boolean;
 begin
   Result := Self = TVersionNumber.Nul;