INI Files and the Registry

Although you can store application settings any way you like, developers typically use INI files or the Registry to store and retrieve application settings.

The TIniFile Class

The TIniFile class enables you to store application settings in an INI file. An INI file is nothing more than a text file with a specific structure. The information in an INI file is stored in sections (strings in brackets) and the actual data is stored in these sections as key=value pairs.

Here's an example of an INI file:

[Application] Top=124 Left=142 Width=740 Height=520 Maximized=0 RollUp=0 LastFolder=C:\ [DefaultDisplay] CompressionQuality=75 BackgroundColor=0 [UndoSettings] MaxUndoSize=200

To use the TIniFile class in an application, you have to either add the IniFiles unit to the uses list or include the IniFile.hpp header file if you're using C++.

The constructor of the TIniFile class is a bit different from the constructors we've used so far. The constructor of the TIniFile accepts a string that contains the path and file name of the INI file:

constructor TIniFile.Create(const FileName: string);

Methods that enable you to store data in the INI file begin with Write: WriteInteger, WriteString, WriteBool, and so on. These methods accept three parameters: section and key names, and the value that is to be stored in the INI file.

procedure WriteString(const Section, Ident, Value: String);

Methods that enable you to read data from the INI file begin with Read: ReadInteger, ReadString, ReadBool, and so on. These functions also accept three parameters. The first two parameters are identical, and the last parameter is used to specify a default value that will be used if the section, key, or value don't exist:

function ReadString(const Section, Ident, Default: String): String;

Listing 18-4 illustrates how to store and retrieve form settings from an INI file.

Listing 18-4: Using the TIniFile Class

unit Unit1; interface uses   Windows, Messages, SysUtils, Variants, Classes,   Graphics, Controls, Forms, Dialogs, IniFiles; type   TForm1 = class(TForm)     procedure FormDestroy(Sender: TObject);     procedure FormCreate(Sender: TObject);   private     { Private declarations }     FIniPath: string;   public     { Public declarations }   end; var   Form1: TForm1; const   MAIN_SECTION = 'MainForm'; implementation {$R *.dfm} procedure TForm1.FormCreate(Sender: TObject); var   Ini: TIniFile; begin   { store the ini file in the application directory }   FIniPath := ChangeFileExt(Application.ExeName, '.ini');   { read stored values }   Ini := TIniFile.Create(FIniPath);   try     Left := Ini.ReadInteger(MAIN_SECTION, 'Left', 100);     Top := Ini.ReadInteger(MAIN_SECTION, 'Top', 100);     Color := Ini.ReadInteger(MAIN_SECTION, 'Color', clWhite);     Caption := Ini.ReadString(MAIN_SECTION, 'Caption', 'TIniFile');   finally     Ini.Free;   end; end; procedure TForm1.FormDestroy(Sender: TObject); var   Ini: TIniFile; begin   Ini := TIniFile.Create(FIniPath);   try     { store values }     Ini.WriteInteger(MAIN_SECTION, 'Left', Left);     Ini.WriteInteger(MAIN_SECTION, 'Top', Top);     Ini.WriteInteger(MAIN_SECTION, 'Color', Color);     Ini.WriteString(MAIN_SECTION, 'Caption', Caption);   finally     Ini.Free;   end; end; end.

The TRegistry Class

The Registry is the main system database that can store operating system and application related data. It is a huge hierarchical tree that stores data in nodes (keys). Every key in the Registry can contain subkeys and values, as shown below.

Figure 18-2: The Registry

To access the Registry in Delphi, you can use either the TRegistry or the TRegistryIniFile class (both classes are declared in the Registry unit). The TRegistry class is normally used to access the Registry, but you can use the TRegistryIniFile class if you want to work with the Registry as if it were an INI file.

In order to read or write Registry values, you have to open one of the following predefined root keys:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

• HKEY_CURRENT_CONFIG

By default, both the TRegistry and the TRegistryIniFile classes use the HKEY_CURRENT_USER key.

The TRegistryIniFile class, like the TIniFile class, accepts a file name parameter in the constructor. When using the TRegistryIniFile class to access the Registry, you have to pass the name of the key instead of a file name. The following example shows how to write a string to the Registry using the TRegistryIniFile class (see Listing 18-5). Don't forget to add the Registry unit to the uses list.

Listing 18-5: Writing to the Registry using the TRegistryIniFile class

procedure TForm1.FormCreate(Sender: TObject); var   Reg: TRegistryIniFile; begin   Reg := TRegistryIniFile.Create('MyApplication');   try     Reg.WriteString('Config', 'MyColor', 'Red');   finally     Reg.Free;   end; end;

The code in Listing 18-5 creates the MyApplication key under HKEY_ CURRENT_USER, adds a Config subkey to the MyApplication key, and writes the MyColor value under Config, as shown in Figure 18-3.

Figure 18-3: Keys and values written using the TRegistryIniFile class

When using the TRegistry class to access the Registry, you usually have to do the following:

1. Select a root key if you don't want to use the HKEY_CURRENT_USER key.

2. Open the key that you want to access.

3. Read or write data to the opened key.

4. Close the opened key when you're done reading or writing data.

Selecting another root key is pretty easy. You only have to assign one of the already mentioned root keys to the RootKey property of the TRegistry class.

To open a Registry key, use the OpenKey method. The OpenKey method accepts two parameters: a string parameter that accepts the name of the key that you want to open and a Boolean parameter that enables you to create the key if it doesn't exist. To create the key if it doesn't exist, pass True as the second parameter. Here's the declaraction of the OpenKey method:

function OpenKey(const Key: String; CanCreate: Boolean): Boolean;

To close the opened key, call the CloseKey method. The CloseKey method accepts no parameters.

Listing 18-6 shows how you can use the TRegistry class in the Delphi Text Editor example to register the Delphi Text Editor as the default application for text documents.

Listing 18-6: Using the TRegistry class

procedure TMainForm.FormCreate(Sender: TObject); var   Reg: TRegistry; begin   if MessageDlg('Always use this application to open text documents?',     mtConfirmation, mbYesNo, 0) = mrYes then     begin       Reg := TRegistry.Create;       try         { register the application }         Reg.OpenKey('Software\Classes\Applications\Project1.exe' +           '\shell\open\command', True);         Reg.WriteString('', '"' + Application.ExeName + '" "%1"');         Reg.CloseKey;         { tell Windows to use the Delphi Text Editor           to load text documents }         Reg.OpenKey('Software\Microsoft\Windows\CurrentVersion\' +           'Explorer\FileExts\.txt', True);         Reg.WriteString('Application', 'Project1.exe');         Reg.CloseKey;       finally         Reg.Free;       end;           // try (Reg)     end;             // if   { open the file selected in the Explorer }   FOpenedFile := ParamStr(1);   if FOpenedFile <> '' then     Editor.Lines.LoadFromFile(ParamStr(1)); end;

If you want to use this code in a real-world application, you'll have to change at least two things:

1. Change the file name from  Project1.exe to something more meaningful.

2. Move the registration code from the OnCreate event handler to a specific option that will enable the user to register the application as the default application for a specific file type.

The TFileStream Class

The best tool for writing data to files and reading data from files is the TFileStream class (declared in the Classes unit). The TFileStream class enables you to:

• Read or write any kind of data.

• Read or write components.

• Copy data to another stream.

To start reading or writing data to a file, you have to create an instance of the TFileStream class. The TFileStream constructor accepts two parameters:

constructor Create(const FileName: string; Mode: Word);

The first parameter is the file name and the second parameter indicates how the file should be opened — whether it be created, opened for reading, opened for writing, opened for reading and writing, etc. The following table contains the list of constants that can be passed as the Mode parameter.

Table 18-2: Common TFileStream open modes

Constant	Description
fmCreate	Create a new file or open for writing if the file exists
fmOpenRead	Open the file for reading only
fmOpenWrite	Open the file for writing only
fmOpenReadWrite	Open the file for both reading and writing

Reading and writing is done with the Read and Write methods. Both methods accept two parameters:

function Read(var Buffer; Count: Longint): Longint;  function Write(const Buffer; Count: Longint): Longint;

The Read method reads Count bytes from the file and places the data into the Buffer variable. The Write method writes Count bytes from the Buffer to the file. Both methods update the Position property, which indicates the position of the stream.

Listing 18-7 illustrates how to write a component and two values to a file using the TFileStream class.

Listing 18-7: Using the TFileStream class

procedure TForm1.WriteToFile(Sender: TObject); var   fs: TFileStream;   n: Integer;   s: string; begin   fs := TFileStream.Create('c:\test.txt', fmCreate);   try     fs.WriteComponent(Label1);     n := 5650;     fs.Write(n, SizeOf(Integer));     { when writing strings, you have to tell Write to       start writing from the first character }     s := 'Some text';     fs.Write(s[1], Length(s));   finally     fs.Free;   end;       // try (fs) end;

A lot of VCL components have the ability to load data from streams (LoadFromStream method) or save data to streams (SaveToStream method). The following example shows how to use the SaveToStream method to save the contents of two TMemo components to a single text file.

Listing 18-8: Saving TMemo contents to a stream

procedure TForm1.WriteMemosToFile(Sender: TObject); var   fs: TFileStream; begin   { write the contents of two TMemo components to a single text file }   fs := TFileStream.Create('c:\test2.txt', fmCreate);   try     Memo1.Lines.SaveToStream(fs);     Memo2.Lines.SaveToStream(fs);   finally     fs.Free;   end; end;

Copying data from one stream to another is done with the CopyFrom method. The CopyFrom method accepts two parameters: the source stream and the number of bytes that are to be copied from one stream to the other. The following example shows just how easy it is to copy a file using the TFileStream class.

Listing 18-9: Using the CopyFrom method to copy files

procedure TForm1.CopyingFiles(Sender: TObject); var   src, dest: TFileStream; begin   src := TFileStream.Create('c:\source.txt', fmOpenRead);   try     dest := TFileStream.Create('c:\dest.txt', fmCreate);     try       { copy the file }       dest.CopyFrom(src, src.Size)     finally       dest.Free;     end;         // try (dest)   finally     src.Free;   end;           // try (src) end;