usettingskeeper.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2003-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}

unit USettingsKeeper;

{Contains some simple classes to keep settings for different purposes, like for
 each form (and frame) of an application without knowing the details about the
 settings. A descendant of the class ~[link TAbstractSettings] has to be
 defined and only its methods have to be called from within each form.
 The application has also to call once each of
 ~[link TSettingsKeeper.SetIniFileName] and
 ~[link TSettingsKeeper.SaveSettings] to load and save the settings to a file.
}

interface

uses Classes, IniFiles, Forms;


type
  //the abstract base class to store settings
  TAbstractSettings = class;



   { * * *  ***  * * *  ***   TSettingsKeeper   ***  * * *  ***  * * *  }

  {Keeps the list of settings to save and load. The ini file is only read once
   when its path is set via ~[link SetIniFileName]. When ~[link SaveSettings]
   is called all settings are saved to the ini file. This class should not be
   created manually, the only instance is created inside this file.
   
   This class should not be used outside this file besides the two mentioned
   class methods.}
  TSettingsKeeper = class
  private
    //the name of the ini file to read and write settings from/to
    FIniFileName: String;
    //the contents of the ini file when starting the application
    //(i.e. calling ~[link SetIniFileName]);
    //its values should only be read and it should never be written to the file
    //again (i.e. it is of type TMemIniFile)
    FInitialization: TCustomIniFile;

    //the list of settings
    FSettings: TStringList;

  protected
    //Sets the name of the ini file and reads it.
    procedure InternalSetIniFileName(const IniFileName: String);
    //Saves all settings to the set ini file.
    procedure InternalSaveSettings;

    //Registers an object of settings to be kept. (visibility: file scope!)
    procedure RegisterSettings(Settings: TAbstractSettings);
    //Initializes settings from the ini file. (visibility: file scope!)
    procedure Initialize(Settings: TAbstractSettings);
    //Returns the kept object of the settings or nil. (visibility: file scope!)
    function GetSettings(const Name: String): TAbstractSettings;
  public
    //Creates the keeper of settings. (visibility: file scope!)
    constructor Create;
    //Frees the keeper of settings and the settings.
    destructor Destroy; override;

    //Sets the name of the ini file to read from and write to and reads its
    //content.
    class procedure SetIniFileName(const IniFileName: String);
    //Saves all settings to the set ini file.
    class procedure SaveSettings;
  end;












   { * * *  ***  * * *  ***   TAbstractSettings   ***  * * *  ***  * * *  }

  {The abstract base class to store settings.
   ~[diagram TAbstractSettings.tree
             /layout=post /size=8 /margin=5 /members /ShowFile=False]
  ~example with ~[code TSomeClass] being a specialized descendant of
           ~[code TAbstractSettings] with additional properties to hold the
           settings:
           ~[sample
            var     Settings: TSomeClass;
            ...

            //get object to load the settings from
            Settings := TSomeClass(TSomeClass.GetSettings('SomeName'));
            if not Assigned(Settings) then       //no object initialized?
             begin                                 //create a new object
              Settings := TSomeClass.Create('SomeName');
              //initialize with the default values
              Settings.SomeSetting := Self.SomeSetting;
              ...
              Settings.Initialize;                 //and read from the ini file
             end;
            //initialize with read values
            Self.SomeSetting := Settings.SomeSetting;
            ...
           ]}
  TAbstractSettings = class
  private
    //name of the settings; has to be unique (case-insensitive);
    //should be valid as a section in an ini file
    FName: String;
  protected
  public
    //Creates the object for settings and saves its associated name.
    constructor Create(const Name: String); 

    //Returns the kept object of the settings with the associated name or nil.
    class function GetSettings(const Name: String): TAbstractSettings;

    //Initializes the settings from the main ini file.
    procedure Initialize;


    {Loads the settings from the ini file.
    ~param Ini the ini file to load the settings from }
    procedure LoadFromIni(Ini: TCustomIniFile); virtual; abstract;
    {Saves the settings to the ini file.
    ~param Ini the ini file to save the settings to }
    procedure SaveToIni(Ini: TCustomIniFile); virtual; abstract;

    property Name: String read FName;
  end;






   { * * *  ***  * * *  ***   TFormSettings   ***  * * *  ***  * * *  }


  {Stores settings of the position of a form. May be used as a base class for
   settings pertaining a form. }
  TFormSettings = class(TAbstractSettings)
  private
    //not saved, just to decide whether the size of the form should be saved
    //(i.e. whether it is resizable)
    FSaveFormSize: Boolean;
    //not saved, just to decide whether the state of the form should be saved
    //(i.e. whether it can be maximized/minimized)
    FSaveFormState: Boolean;

    FWindowState: TWindowState;      //state of the form
    FLeft: Integer;                  //horizontal position of the form
    FTop: Integer;                   //vertical position of the form
    FWidth: Integer;                 //horizontal size of the form
    FHeight: Integer;                //vertical size of the form

    //Decides what settings of the form have to be saved.
    procedure ReadWhatToSave(Form: TForm);
  protected
  public
    //Saves the basic form values in settings by the name of its class.
    class procedure SaveBasicFormValues(Form: TForm);

    //Loads the settings from the ini file.
    procedure LoadFromIni(Ini: TCustomIniFile); override;
    //Saves the settings to the ini file.
    procedure SaveToIni(Ini: TCustomIniFile); override;

    //Gets the settings from the form.
    procedure GetValuesFromForm(Form: TForm);
    //Assigns the settings to the form.
    procedure SetValuesToForm(Form: TForm);


    property WindowState: TWindowState read FWindowState write FWindowState;
    property Left: Integer read FLeft write FLeft;
    property Top: Integer read FTop write FTop;
    property Width: Integer read FWidth write FWidth;
    property Height: Integer read FHeight write FHeight;
  end;




implementation

uses SysUtils;



    //the one and only instance of the keeper of settings
var SettingsKeeper: TSettingsKeeper = nil;



   { * * *  ***  * * *  ***   TSettingsKeeper   ***  * * *  ***  * * *  }


{Creates the keeper of settings. (visibility: file scope!) }
constructor TSettingsKeeper.Create;
begin
 inherited Create;                      //create the object

 FSettings := TStringList.Create;       //create the list for the settings
 FSettings.Sorted := True;              //it is accessed via the name
 FSettings.Duplicates := dupError;      //and the names have to be unique
end;

{Frees the keeper of settings and the settings. }
destructor TSettingsKeeper.Destroy;
var        i              :Integer;     //counter through the settings
begin
 FInitialization.Free;                  //free the content of the ini file

 if Assigned(FSettings) then            //settings available?
  begin
   for i := 0 to FSettings.Count - 1 do   //free all settings
    FSettings.Objects[i].Free;
   FSettings.Free;                        //free the list
  end;

 inherited Destroy;                     //free the object
end;




{Sets the name of the ini file and reads it.
~param IniFileName the name of the ini file to read and save the settings
                   from/to }
procedure TSettingsKeeper.InternalSetIniFileName(const IniFileName: String);
begin
 Assert(not Assigned(FInitialization));

 FIniFileName := IniFileName;                         //save name of the file
 FInitialization := TMemIniFile.Create(IniFileName);  //read its content
end;

{Saves all settings to the set ini file. }
procedure TSettingsKeeper.InternalSaveSettings;
var       Ini            :TCustomIniFile;   //the ini file
          i              :Integer;          //counter through all settings
begin
 Assert(Assigned(FInitialization));