Update PJWdwState components to v5.6.1 of 28 Oct 2014

Author: delphidabbler

Src/3rdParty/PJWdwState.pas

@@ -3,10 +3,10 @@
  * v. 2.0. If a copy of the MPL was not distributed with this file, You can
  * obtain one at http://mozilla.org/MPL/2.0/
  *
- * Copyright (C) 1999-2013, Peter Johnson (www.delphidabbler.com).
+ * Copyright (C) 1999-2014, Peter Johnson (www.delphidabbler.com).
  *
- * $Rev$
- * $Date$
+ * $Rev: 1966 $
+ * $Date: 2014-10-28 01:20:04 +0000 (Tue, 28 Oct 2014) $
  *
  * DelphiDabbler Window state components.
 }
@@ -15,11 +15,14 @@
 unit PJWdwState;
 
 // Conditional defines
-// Note: Delphi 1/2 not included since code will not compile on these compilers
+// Note: There is no version checking for Delphi 1 and 2 not since this unit
+// will not compile with those compilers.
 {$DEFINE WarnDirs}          // $WARN compiler directives available
 {$DEFINE RegAccessFlags}    // TRegistry access flags available
+{$DEFINE RequiresFileCtrl}  // FileCtrl unit is required for ForceDirectories
 {$UNDEF RTLNameSpaces}      // Don't qualify RTL units names with namespaces
 {$UNDEF TScrollStyleMoved}  // TScrollStyle hasn't moved to System.UITypes units
+{$UNDEF SupportsPathDelim}  // PathDelim and related routine not defined
 {$IFDEF VER100} // Delphi 3
   {$UNDEF WarnDirs}
   {$UNDEF RegAccessFlags}
@@ -32,15 +35,18 @@
   {$UNDEF WarnDirs}
   {$UNDEF RegAccessFlags}
 {$ENDIF}
-{$IFDEF VER140} // Delphi 6
-  {$UNDEF WarnDirs}
-{$ENDIF}
 {$IFDEF CONDITIONALEXPRESSIONS}
-  {$IF CompilerVersion >= 23.0} // Delphi XE2
+  {$IF CompilerVersion >= 24.0} // Delphi XE3 and later
+    {$LEGACYIFEND ON}  // NOTE: this must come before all $IFEND directives
+    {$DEFINE TScrollStyleMoved}
+  {$IFEND}
+  {$IF CompilerVersion >= 23.0} // Delphi XE2 and later
     {$DEFINE RTLNameSpaces}
   {$IFEND}
-  {$IF CompilerVersion >= 24.0} // Delphi XE3
-    {$DEFINE TScrollStyleMoved}
+  {$IF CompilerVersion >= 14.0} // Delphi 6 and later
+    {$DEFINE SupportsPathDelim}
+    {$UNDEF WarnDirs}
+    {$UNDEF RequiresFileCtrl}
   {$IFEND}
 {$ENDIF}
 
@@ -54,7 +60,11 @@ interface
   System.Classes, Vcl.Controls, Winapi.Messages, Winapi.Windows, Vcl.Forms,
   System.SysUtils, System.Win.Registry;
   {$ELSE}
-  Classes, Controls, Messages, Windows, Forms, SysUtils, Registry;
+  Classes, Controls, Messages, Windows, Forms, SysUtils, Registry
+  {$IFDEF RequiresFileCtrl}
+  , FileCtrl  // needed for ForceDirectories since it's not in SysUtils yet.
+  {$ENDIF}
+  ;
   {$ENDIF}
 
 
@@ -65,6 +75,7 @@ interface
   // instructs MDI child components they can restore their windows
   PJM_RESTOREMDICHILD = WM_USER + 1;
 
+
 type
 
   TPJCustomWdwState = class;
@@ -637,15 +648,42 @@   TPJWdwState = class(TPJCustomWdwState)
   {
   TPJWdwStateGetRegData:
     Type of event that is triggered just before registry is accessed. It allows
-    handler to change the registry HKEY and sub key to be used.
-      @param RootKey [in/out] Registry root key. Default value passed in. May be
-        changed in event handler.
+    handler to change the registry root key and sub key to be used.
+      @param RootKey [in/out] Registry root key. Default HKEY value passed in.
+        May be changed in event handler.
       @param SubKey [in/out] Registry sub key. Default value passed in. May be
         changed in event handler.
   }
   TPJWdwStateGetRegData = procedure(var RootKey: HKEY;
     var SubKey: string) of object;
 
+  {TPJRegRootKey:
+    Enumeration of values that represent the registry root keys supported by
+    TPJRegWdwState. Each value represents and maps to the similarly named
+    HKEY_* constant, as shown in the comments.
+  }
+  TPJRegRootKey = (
+    hkClassesRoot,      // HKEY_CLASSES_ROOT
+    hkCurrentUser,      // HKEY_CURRENT_USER
+    hkLocalMachine,     // HKEY_LOCAL_MACHINE
+    hkUsers,            // HKEY_USERS
+    hkPerformanceData,  // HKEY_PERFORMANCE_DATA
+    hkCurrentConfig,    // HKEY_CURRENT_CONFIG
+    hkDynData           // HKEY_DYN_DATA
+  );
+
+  {
+  TPJWdwStateGetRegDataEx:
+    Type of event that is triggered just before registry is accessed. It allows
+    handler to change the registry root key and sub key to be used.
+      @param RootKeyEx [in/out] Registry root key. Default TPJRegRootKey value
+        passed in. May be changed in event handler.
+      @param SubKey [in/out] Registry sub key. Default value passed in. May be
+        changed in event handler.
+  }
+  TPJWdwStateGetRegDataEx = procedure(var RootKeyEx: TPJRegRootKey;
+    var SubKey: string) of object;
+
   {
   TPJWdwStateRegAccessEvent:
     Type of event that is triggered after registry is opened, ready for access.
@@ -668,23 +706,34 @@   TPJWdwState = class(TPJCustomWdwState)
   }
   TPJRegWdwState = class(TPJCustomWdwState)
   private // properties
-    fRootKey: HKEY;
-      {Value of RootKey property}
+    fRootKeyEx: TPJRegRootKey;
+      {Value of RootKeyEx property}
     fSubKey: string;
       {Value of SubKey property}
     fOnGetRegData: TPJWdwStateGetRegData;
       {Event handler for OnGetRegData event}
+    fOnGetRegDataEx: TPJWdwStateGetRegDataEx;
+      {Event handler for OnGetRegDataEx event}
     fOnGettingRegData: TPJWdwStateRegAccessEvent; // Added by BJM
       {Event handler for OnGettingRegData event}
     fOnPuttingRegData: TPJWdwStateRegAccessEvent; // Added by BJM
       {Event handler for OnPuttingRegData event}
+    function GetRootKey: HKEY;
+      {Read accessor for RootKey property.
+        @return Required property value.
+      }
+    procedure SetRootKey(const Value: HKEY);
+      {Write accessor for RootKey property.
+        @param Value [in] New property value.
+        @exception ERangeError raised if value is not a recognised HKEY_* value.
+      }
     procedure SetSubKey(const Value: string);
       {Write accessor method for SubKey property.
         @param Value [in] New property value. If Value='' then the property is
           set to \Software\<App File Name>\Window\<Form Name>.
       }
   protected
-    procedure GetRegInfo(var ARootKey: HKEY; var ASubKey: string);
+    procedure GetRegInfo(var ARootKey: TPJRegRootKey; var ASubKey: string);
       {Triggers OnGetRegData event to get registry root key and sub key to be
       used when restoring / saving window state.
         @param ARootKey [in/out] Required root key value. Set to value of
@@ -729,19 +778,35 @@   TPJRegWdwState = class(TPJCustomWdwState)
     // Published inherited property
     property OnReadWdwState;
     // New properties
-    property RootKey: HKEY read fRootKey write fRootKey
+    property RootKey: HKEY read GetRootKey write SetRootKey
       default HKEY_CURRENT_USER;
-      {Registry root key to use. Must be set to a valid HKEY value}
+      {Registry root key to use. Must be set to a valid HKEY value. Setting this
+      property also sets RootKeyEx to a corresponding value}
+    property RootKeyEx: TPJRegRootKey read fRootKeyEx write fRootKeyEx
+      stored False default hkCurrentUser;
+      {Registry root key to use as specified by a value from the TPJRegRootKey
+      enumeration. Setting this property also sets RootKey to a corresponding
+      value.
+      NOTE: This property is provided to make it easier to set root keys at
+      design time to avoid remembering the root key value as an integer}
     property SubKey: string read fSubKey write SetSubKey;
       {The sub-key below root key where window state is to be stored. If set to
       empty string the value of '/Software/<Program Name>/Window/<Form Name>'
       is used}
     property OnGetRegData: TPJWdwStateGetRegData
       read fOnGetRegData write fOnGetRegData;
       {Event triggered just before registry is read when restoring and saving
-      window state. Allows handler to change registry HKEY and subkey to be used
-      to store window state. If this event is handled then RootKey and SubKey
-      properties are ignored}
+      window state. Allows handler to change root key and subkey to be used to
+      store window state. Root key is specified via its HKEY value. If this
+      event is handled then RootKey, RootKeyEx and SubKey properties are all
+      ignored}
+    property OnGetRegDataEx: TPJWdwStateGetRegDataEx
+      read fOnGetRegDataEx write fOnGetRegDataEx;
+      {Event triggered just before registry is read when restoring and saving
+      window state. Allows handler to change root key and subkey to be used to
+      store window state. Root key is specified via its TPJRegRootKey value. If
+      this event is handled then RootKey, RootKeyEx and SubKey properties are
+      all ignored}
     property OnGettingRegData: TPJWdwStateRegAccessEvent  // Added by BJM
       read fOnGettingRegData write fOnGettingRegData;
       {Event triggered when component is reading window state data from
@@ -786,6 +851,26 @@ procedure Register;
   );
 end;
 
+{$IFNDEF SupportsPathDelim}
+// Definitions used for versions of Delphi that don't implement the following
+// constant and function in SysUtils.
+
+const
+  // File path delimiter
+  PathDelim = '/';
+
+// Ensures that given directory or path ends with exactly one path delimiter.
+function IncludeTrailingPathDelimiter(const PathOrDir: string): string;
+begin
+  Result := PathOrDir;
+  // remove all trailing path delimiters if any, to get rid of any duplicates
+  while (Result <> '') and (Result[Length(Result)] = PathDelim) do
+    Result := Copy(Result, 1, Length(Result) - 1);
+  // add a single trailing delimiter
+  Result := Result + PathDelim;
+end;
+{$ENDIF}
+
 { TPJWdwStateHook }
 
 procedure TPJWdwStateHook.CMShowingChanged(var Msg: TMessage);
@@ -1647,6 +1732,43 @@ procedure TPJWdwState.SaveWdwState(const Left, Top, Width, Height,
 
 { TPJRegWdwState }
 
+resourcestring
+  // Error messages
+  sErrBadHKEY = '%d is not a valid HKEY value.';
+
+const
+  // Map of supported HKEY_ constants onto corresponding TPJRegRootKey values.
+  RegRootKeyMap: array[TPJRegRootKey] of HKEY = (
+    HKEY_CLASSES_ROOT,          // hkClassesRoot
+    HKEY_CURRENT_USER,          // hkCurrentUser
+    HKEY_LOCAL_MACHINE,         // hkLocalMachine
+    HKEY_USERS,                 // hkUsers
+    HKEY_PERFORMANCE_DATA,      // hkPerformanceData
+    HKEY_CURRENT_CONFIG,        // hkCurrentConfig
+    HKEY_DYN_DATA               // hkDynData
+  );
+
+function TryHKEYToCode(const RootKey: HKEY; var Value: TPJRegRootKey): Boolean;
+  {Attempts to convert a HKEY value into the corresponding TPJRegRootKey value.
+    @param RootKey [in] HKEY value to convert.
+    @param Value [in/out] Set to TPJRegRootKey value corresponding to RootKey.
+      Value is undefined if RootKey has no corresponding TPJRegRootKey value.
+    @return True if RootKey is valid and has corresponding TPJRegRootKey value
+      or False of not.
+  }
+var
+  Code: TPJRegRootKey;
+begin
+  Result := True;
+  for Code := Low(TPJRegRootKey) to High(TPJRegRootKey) do
+    if RegRootKeyMap[Code] = RootKey then
+    begin
+      Value := Code;
+      Exit;
+    end;
+  Result := False;
+end;
+
 function ReadRegInt(const Reg: TRegistry; const AName: string;
   const ADefault: Integer): Integer;
   {Reads integer value from current sub key in registry, using a default value
@@ -1709,26 +1831,45 @@ constructor TPJRegWdwState.Create(AOwner: TComponent);
   }
 begin
   inherited Create(AOwner);
-  fRootKey := HKEY_CURRENT_USER;
+  fRootKeyEx := hkCurrentUser;
   SetSubKey('');
 end;
 
-procedure TPJRegWdwState.GetRegInfo(var ARootKey: HKEY;
+procedure TPJRegWdwState.GetRegInfo(var ARootKey: TPJRegRootKey;
   var ASubKey: string);
-  {Triggers OnGetRegData event to get registry root key and sub key to be used
-  when restoring / saving window state.
+  {Triggers the OnGetRegDateEx event or, if that is not assigned, the
+  OnGetRegData event, to get registry root key and sub key to be used when
+  restoring / saving window state.
     @param ARootKey [in/out] Required root key value. Set to value of RootKey
       property by default. May be changed in event handler.
     @param ASubKey [in/ou] Required sub key. Set to value of SubKey property
       when called. May be changed in event handler.
   }
+var
+  RootHKey: HKEY; // used to get root key via its HKEY value
 begin
-  // Use RootKey and SubKey property values by default
-  ARootKey := RootKey;
+  // Use RootKeyEx and SubKey property values by default
+  ARootKey := RootKeyEx;
   ASubKey := SubKey;
-  // Allow user to change these by handling OnGetRegData event
-  if Assigned(fOnGetRegData) then
-    fOnGetRegData(ARootKey, ASubKey);
+  // Allow user to change these by handling either OnGetRegDataEx or
+  // OnGetRegData event
+  if Assigned(fOnGetRegDataEx) then
+    fOnGetRegDataEx(ARootKey, ASubKey)
+  else if Assigned(fOnGetRegData) then
+  begin
+    RootHKey := RegRootKeyMap[ARootKey];
+    fOnGetRegData(RootHKey, ASubKey);
+    if not TryHKEYToCode(RootHKey, ARootKey) then
+      raise ERangeError.CreateFmt(sErrBadHKEY, [RootHKey]);
+  end;
+end;
+
+function TPJRegWdwState.GetRootKey: HKEY;
+  {Read accessor for RootKey property.
+    @return Required property value.
+  }
+begin
+  Result := RegRootKeyMap[fRootKeyEx];
 end;
 
 procedure TPJRegWdwState.ReadWdwState(var Left, Top, Width, Height,
@@ -1747,16 +1888,16 @@ procedure TPJRegWdwState.ReadWdwState(var Left, Top, Width, Height,
       value is the ordinal value of a TWindowState value.
   }
 var
-  Reg: TRegistry;   // instance of registry object used to read info
-  ARootKey: HKEY;   // registry root key where window state is stored
-  ASubKey: string;  // sub key of registry from which to read window state
+  Reg: TRegistry;           // instance of registry object used to read info
+  ARootKey: TPJRegRootKey;  // registry root key where window state is stored
+  ASubKey: string;          // registry sub key from which to read window state
 begin
   // Get registry keys from which to read window state
   GetRegInfo(ARootKey, ASubKey);
   // Open registry at required key
   Reg := SafeCreateReg;
   try
-    Reg.RootKey := ARootKey;
+    Reg.RootKey := RegRootKeyMap[ARootKey];
     if Reg.OpenKey(ASubKey, False) then
     begin
       // Read position, size and state of window
@@ -1785,16 +1926,16 @@ procedure TPJRegWdwState.SaveWdwState(const Left, Top, Width, Height,
       value of a TWindowState value.
   }
 var
-  Reg: TRegistry;   // instance of registry object class used to write info
-  ARootKey: HKEY;   // registry root key where window state is stored
-  ASubKey: string;  // sub key of registry in which to save window state
+  Reg: TRegistry;           // instance of registry object used to write info
+  ARootKey: TPJRegRootKey;  // registry root key where window state is stored
+  ASubKey: string;          // sub key of registry in which to save window state
 begin
   // Get registry keys in which to save window state
   GetRegInfo(ARootKey, ASubKey);
   // Open registry at required key
   Reg := SafeCreateReg;
   try
-    Reg.RootKey := ARootKey;
+    Reg.RootKey := RegRootKeyMap[ARootKey];
     if Reg.OpenKey(ASubKey, True) then
     begin
       // Write window size, position and state from registry
@@ -1812,6 +1953,19 @@ procedure TPJRegWdwState.SaveWdwState(const Left, Top, Width, Height,
   end;
 end;
 
+procedure TPJRegWdwState.SetRootKey(const Value: HKEY);
+  {Write accessor for RootKey property.
+    @param Value [in] New property value.
+    @exception ERangeError raised if value is not a recognised HKEY_* value.
+  }
+begin
+  if not TryHKEYToCode(Value, fRootKeyEx) then
+  begin
+    fRootKeyEx := hkCurrentUser;
+    raise ERangeError.CreateFmt(sErrBadHKEY, [Value]);
+  end;
+end;
+
 procedure TPJRegWdwState.SetSubKey(const Value: string);
   {Write accessor method for SubKey property.
     @param Value [in] New property value. If Value='' then the property is set