Add support for passing flags to preferences frames

Code that displays the preferences dialogue box can now pass
optional flags to each frame. Each flag is a UInt64 that has the
frame's unique index number in its high 32 bits and a frame specific
flag or bitmask in the lower 32 bits.
FrPrefsBase provides utility class methods for manipulating these
flags.

Author: delphidabbler

Src/FmPreferencesDlg.pas

@@ -50,6 +50,8 @@   TPreferencesDlg = class(TGenericOKDlg, INoPublicConstruct)
       ///  <summary>Records if main UI needs to be updated to reflect changed
       ///  preferences.</summary>
       fUpdateUI: Boolean;
+      ///  <summary>Records flags to be passed to frames.</summary>
+      fFrameFlags: UInt64;
       ///  <summary>Records index of currently select tab/list item.</summary>
       fCurrentPageIdx: Integer;
     ///  <summary>Creates the required frames and displays each in a tab sheet
@@ -108,7 +110,8 @@   TPreferencesDlg = class(TGenericOKDlg, INoPublicConstruct)
     ///  <returns>Boolean. True if user clicks OK to accept changes or False if
     ///  user cancels and no changes made.</returns>
     class function Execute(AOwner: TComponent;
-      const Pages: array of TPrefsFrameClass; out UpdateUI: Boolean): Boolean;
+      const Pages: array of TPrefsFrameClass; out UpdateUI: Boolean;
+      const Flags: UInt64 = 0): Boolean;
       overload;
     ///  <summary>Displays dialog with pages for each specified preferences
     ///  frame.</summary>
@@ -119,7 +122,8 @@   TPreferencesDlg = class(TGenericOKDlg, INoPublicConstruct)
     ///  <returns>Boolean. True if user clicks OK to accept changes or False if
     ///  user cancels and no changes made.</returns>
     class function Execute(AOwner: TComponent;
-      const Pages: array of TPrefsFrameClass): Boolean; overload;
+      const Pages: array of TPrefsFrameClass; const Flags: UInt64 = 0):
+      Boolean; overload;
     ///  <summary>Displays preferences dialog with all registered preference
     ///  frames.</summary>
     ///  <param name="AOwner">TComponent [in] Component that owns dialog.
@@ -128,8 +132,8 @@   TPreferencesDlg = class(TGenericOKDlg, INoPublicConstruct)
     ///  be updated as a result of preference changes.</param>
     ///  <returns>Boolean. True if user clicks OK to accept changes or False if
     ///  user cancels and no changes made.</returns>
-    class function Execute(AOwner: TComponent; out UpdateUI: Boolean): Boolean;
-      overload;
+    class function Execute(AOwner: TComponent; out UpdateUI: Boolean;
+      const Flags: UInt64 = 0): Boolean; overload;
     ///  <summary>Displays dialogue with showing a single frame, specified by
     ///  its class name.</summary>
     ///  <param name="AOwner">TComponent [in] Component that owns dialog.
@@ -141,7 +145,7 @@   TPreferencesDlg = class(TGenericOKDlg, INoPublicConstruct)
     ///  <returns>Boolean. True if user clicks OK to accept changes or False if
     ///  user cancels and no changes made.</returns>
     class function Execute(AOwner: TComponent; const PageClsName: string;
-      out UpdateUI: Boolean): Boolean; overload;
+      out UpdateUI: Boolean; const Flags: UInt64 = 0): Boolean; overload;
     ///  <summary>Registers given preferences frame class for inclusion in the
     ///  preferences dialog box.</summary>
     ///  <remarks>Registered frames are created when the dialog box is displayed
@@ -258,10 +262,12 @@ function TPreferencesDlg.CustomHelpKeyword: string;
 end;
 
 class function TPreferencesDlg.Execute(AOwner: TComponent;
-  const Pages: array of TPrefsFrameClass; out UpdateUI: Boolean): Boolean;
+  const Pages: array of TPrefsFrameClass; out UpdateUI: Boolean;
+  const Flags: UInt64): Boolean;
 begin
   with InternalCreate(AOwner) do
     try
+      fFrameFlags := Flags;
       CreatePages(Pages);
       Result := ShowModal = mrOK;
       if Result then
@@ -274,21 +280,22 @@ class function TPreferencesDlg.Execute(AOwner: TComponent;
 end;
 
 class function TPreferencesDlg.Execute(AOwner: TComponent;
-  out UpdateUI: Boolean): Boolean;
+  out UpdateUI: Boolean; const Flags: UInt64): Boolean;
 begin
-  Result := Execute(AOwner, fPages.ToArray, UpdateUI);
+  Result := Execute(AOwner, fPages.ToArray, UpdateUI, Flags);
 end;
 
 class function TPreferencesDlg.Execute(AOwner: TComponent;
-  const Pages: array of TPrefsFrameClass): Boolean;
+  const Pages: array of TPrefsFrameClass; const Flags: UInt64): Boolean;
 var
   Dummy: Boolean; // unused UpdateUI parameters
 begin
-  Result := Execute(AOwner, Pages, Dummy);
+  Result := Execute(AOwner, Pages, Dummy, Flags);
 end;
 
 class function TPreferencesDlg.Execute(AOwner: TComponent;
-  const PageClsName: string; out UpdateUI: Boolean): Boolean;
+  const PageClsName: string; out UpdateUI: Boolean; const Flags: UInt64):
+  Boolean;
 var
   FrameClass: TPrefsFrameClass;
 begin
@@ -335,7 +342,7 @@ procedure TPreferencesDlg.InitForm;
   fLocalPrefs := (Preferences as IClonable).Clone as IPreferences;
   // Display and initialise required pages
   for TabIdx := 0 to Pred(pcMain.PageCount) do
-    MapTabSheetToPage(TabIdx).LoadPrefs(fLocalPrefs);
+    MapTabSheetToPage(TabIdx).LoadPrefs(fLocalPrefs, fFrameFlags);
   // Select last use tab sheet (or 1st if last not known)
   fCurrentPageIdx := GetLastTabIdx;
   if fCurrentPageIdx < 0 then
@@ -413,7 +420,7 @@ procedure TPreferencesDlg.SelectTab(TS: TTabSheet);
   Assert(Assigned(TS), ClassName + '.SelectTab: TS is nil');
   GetSelectedPage.Deactivate(fLocalPrefs);
   pcMain.ActivePage := TS;
-  GetSelectedPage.Activate(fLocalPrefs);
+  GetSelectedPage.Activate(fLocalPrefs, fFrameFlags);
   fCurrentPageIdx := pcMain.ActivePageIndex;
 end;
 

Src/FrCodeGenPrefs.pas

@@ -176,7 +176,8 @@   TCodeGenPrefsFrame = class(TPrefsBaseFrame)
     ///  <summary>Records details of warnings from given preferences object and
     ///  updates controls accordingly.</summary>
     ///  <remarks>Called when page is activated.</remarks>
-    procedure Activate(const Prefs: IPreferences); override;
+    procedure Activate(const Prefs: IPreferences; const Flags: UInt64);
+      override;
     ///  <summary>Updates given preferences object with details of warnings as
     ///  modified by user.</summary>
     ///  <remarks>Called when page is deactivated.</remarks>
@@ -322,7 +323,8 @@ procedure TCodeGenPrefsFrame.actDeleteUpdate(Sender: TObject);
   actDelete.Enabled := Assigned(fLVWarnings.Selected);
 end;
 
-procedure TCodeGenPrefsFrame.Activate(const Prefs: IPreferences);
+procedure TCodeGenPrefsFrame.Activate(const Prefs: IPreferences;
+  const Flags: UInt64);
 begin
   (fWarnings as IAssignable).Assign(Prefs.Warnings);
   chkWARNEnabled.Checked := fWarnings.Enabled;

Src/FrDisplayPrefs.pas

@@ -63,7 +63,8 @@   TDisplayPrefsFrame = class(TPrefsBaseFrame)
       {Class constructor. Sets up frame and populates controls.
         @param AOwner [in] Component that owns frame.
       }
-    procedure Activate(const Prefs: IPreferences); override;
+    procedure Activate(const Prefs: IPreferences; const Flags: UInt64);
+      override;
       {Called when page activated. Updates controls.
         @param Prefs [in] Object that provides info used to update controls.
       }
@@ -106,7 +107,8 @@ implementation
 
 { TDisplayPrefsFrame }
 
-procedure TDisplayPrefsFrame.Activate(const Prefs: IPreferences);
+procedure TDisplayPrefsFrame.Activate(const Prefs: IPreferences;
+  const Flags: UInt64);
   {Called when page activated. Updates controls.
     @param Prefs [in] Object that provides info used to update controls.
   }

Src/FrGeneralPrefs.pas

@@ -45,7 +45,8 @@   TGeneralPrefsFrame = class(TPrefsBaseFrame)
       {Class constructor. Sets up frame and populates controls.
         @param AOwner [in] Component that owns frame.
       }
-    procedure Activate(const Prefs: IPreferences); override;
+    procedure Activate(const Prefs: IPreferences; const Flags: UInt64);
+      override;
       {Called when page activated. Updates controls.
         @param Prefs [in] Object that provides info used to update controls.
       }
@@ -88,7 +89,8 @@ implementation
 
 { TGeneralPrefsFrame }
 
-procedure TGeneralPrefsFrame.Activate(const Prefs: IPreferences);
+procedure TGeneralPrefsFrame.Activate(const Prefs: IPreferences;
+  const Flags: UInt64);
   {Called when page activated. Updates controls.
     @param Prefs [in] Object that provides info used to update controls.
   }

Src/FrHiliterPrefs.pas

@@ -143,7 +143,8 @@   THiliterPrefsFrame = class(TPrefsBaseFrame)
     ///  <summary>Updates controls from given preferences object.</summary>
     ///  <remarks>Called when the dialogue page containing the frame is
     ///  activated.</remarks>
-    procedure Activate(const Prefs: IPreferences); override;
+    procedure Activate(const Prefs: IPreferences; const Flags: UInt64);
+      override;
     ///  <summary>Updates given preferences object with data entered in controls.
     ///  </summary>
     ///  <remarks>Called when the dialogue page containing the frame is
@@ -254,7 +255,8 @@ implementation
 
 { THiliterPrefsFrame }
 
-procedure THiliterPrefsFrame.Activate(const Prefs: IPreferences);
+procedure THiliterPrefsFrame.Activate(const Prefs: IPreferences;
+  const Flags: UInt64);
 begin
   (fAttrs as IAssignable).Assign(Prefs.HiliteAttrs);
   (fNamedAttrs as IAssignable).Assign(Prefs.NamedHiliteAttrs);

Src/FrPrefsBase.pas

@@ -38,19 +38,24 @@   TPrefsFrameClass = class of TPrefsBaseFrame;
     preferences dialog box.
   }
   TPrefsBaseFrame = class(TFrame)
+  strict protected
+    class function IsFlagSupported(const Flag: UInt64): Boolean; inline;
+    class function ExtractFrameFlag(const Flag: UInt64): UInt32; inline;
   public
     procedure SavePrefs(const Prefs: IPreferences); virtual;
       {Saves information user entered in frame. By default the method simply
       calls Deactivate. May be overridden to save any custom data that doesn't
       use Prefs object.
         @param Prefs [in] Object used to store information.
       }
-    procedure LoadPrefs(const Prefs: IPreferences); virtual;
+    procedure LoadPrefs(const Prefs: IPreferences; const Flags: UInt64);
+      virtual;
       {Initialises controls. By default the method simply calls Activate. May be
       overridden to load any custom data that doesn't use Prefs object.
         @param Prefs [in] Object that provides info used to update controls.
       }
-    procedure Activate(const Prefs: IPreferences); virtual; abstract;
+    procedure Activate(const Prefs: IPreferences; const Flags: UInt64);
+      virtual; abstract;
       {Called when page activated. Must update controls from preferences.
         @param Prefs [in] Object that provides info used to update controls.
       }
@@ -77,23 +82,49 @@   TPrefsBaseFrame = class(TFrame)
       new entries at a later date.
         @return Required index number.
       }
+    class function MakeFrameFlag(const Flag: UInt32): UInt64; inline;
   end;
 
 
 implementation
 
+uses
+  // Delphi
+  SysUtils;
+
 
 {$R *.dfm}
 
 { TPrefsBaseFrame }
 
-procedure TPrefsBaseFrame.LoadPrefs(const Prefs: IPreferences);
+class function TPrefsBaseFrame.ExtractFrameFlag(const Flag: UInt64): UInt32;
+begin
+  if not IsFlagSupported(Flag) then
+    Exit(0);
+  Result := Int64Rec(Flag).Lo;
+end;
+
+class function TPrefsBaseFrame.IsFlagSupported(const Flag: UInt64): Boolean;
+begin
+  Result := Int64Rec(Flag).Hi = UInt32(Index);
+end;
+
+procedure TPrefsBaseFrame.LoadPrefs(const Prefs: IPreferences;
+  const Flags: UInt64);
   {Initialises controls. By default the method simply calls Activate. May be
   overridden to load any custom data that doesn't use Prefs object.
     @param Prefs [in] Object that provides info used to update controls.
   }
 begin
-  Activate(Prefs);
+  Activate(Prefs, Flags);
+end;
+
+class function TPrefsBaseFrame.MakeFrameFlag(const Flag: UInt32): UInt64;
+begin
+  // Frame flag is in form $IIIIIIIIFFFFFFFF where $IIIIIIII is the frame's
+  // index number and $FFFFFFFF is the 32 bit flag or bitmask of flags
+  Int64Rec(Result).Hi := UInt32(Index);
+  Int64Rec(Result).Lo := Flag;
 end;
 
 procedure TPrefsBaseFrame.SavePrefs(const Prefs: IPreferences);

Src/FrPrintingPrefs.pas

@@ -60,7 +60,8 @@   TPrintingPrefsFrame = class(TPrefsBaseFrame)
     constructor Create(AOwner: TComponent); override;
       {Class constructor. Sets up frame object.
       }
-    procedure Activate(const Prefs: IPreferences); override;
+    procedure Activate(const Prefs: IPreferences; const Flags: UInt64);
+      override;
       {Called when page activated. Updates controls.
         @param Prefs [in] Object that provides info used to update controls.
       }
@@ -141,7 +142,8 @@   TPrintingPrefsPreview = class(TObject)
 
 { TPrintingPrefsFrame }
 
-procedure TPrintingPrefsFrame.Activate(const Prefs: IPreferences);
+procedure TPrintingPrefsFrame.Activate(const Prefs: IPreferences;
+  const Flags: UInt64);
   {Called when page activated. Updates controls.
     @param Prefs [in] Object that provides info used to update controls.
   }

Src/FrSnippetLayoutPrefs.pas

@@ -64,7 +64,8 @@   TSnippetLayoutPrefsFrame = class(TPrefsBaseFrame)
   public
     constructor Create(AOwner: TComponent); override;
     destructor Destroy; override;
-    procedure Activate(const Prefs: IPreferences); override;
+    procedure Activate(const Prefs: IPreferences; const Flags: UInt64);
+      override;
     procedure Deactivate(const Prefs: IPreferences); override;
     ///  <summary>Checks if preference changes require that main window UI is
     ///  updated.</summary>
@@ -146,7 +147,8 @@ procedure TSnippetLayoutPrefsFrame.actIncludeFragmentUpdate(Sender: TObject);
     and (lbAvailableFragments.ItemIndex >= 0);
 end;
 
-procedure TSnippetLayoutPrefsFrame.Activate(const Prefs: IPreferences);
+procedure TSnippetLayoutPrefsFrame.Activate(const Prefs: IPreferences;
+  const Flags: UInt64);
 begin
   fPageStructs.Assign(Prefs.PageStructures);
   UpdateFragmentInfo;

Src/FrSourcePrefs.pas

@@ -74,7 +74,8 @@   TSourcePrefsFrame = class(TPrefsBaseFrame)
     constructor Create(AOwner: TComponent); override;
       {Class constructor. Initialises controls.
       }
-    procedure Activate(const Prefs: IPreferences); override;
+    procedure Activate(const Prefs: IPreferences; const Flags: UInt64);
+      override;
       {Called when page activated. Updates controls.
         @param Prefs [in] Object that provides info used to update controls.
       }
@@ -165,7 +166,8 @@   TSourcePrefsPreview = class(TObject)
 
 { TSourcePrefsFrame }
 
-procedure TSourcePrefsFrame.Activate(const Prefs: IPreferences);
+procedure TSourcePrefsFrame.Activate(const Prefs: IPreferences;
+  const Flags: UInt64);
   {Called when page activated. Updates controls.
     @param Prefs [in] Object that provides info used to update controls.
   }