Using TIniFile and TMemIniFile

From RAD Studio
Jump to: navigation, search

Go Up to Working with ini Files and the System Registry

The INI file format is still popular, many configuration files (such as the DSK Desktop settings file) are in this format. This format is especially useful in applications where you cannot always rely on a system Registry for storing configuration information. The VCL/RTL provides two classes, TIniFile and TMemIniFile, to make reading and writing INI files very easy.

TIniFile works directly with the INI file on disk while TMemIniFile buffers all changes in memory and does not write them to disk until you call the UpdateFile method.

Note: When working with TMemIniFile, you can use the AutoSave property to automatically save the changes in memory to the INI file. Using this property you avoid the loss of information that can be produced when calling the destructor before calling the UpdateFile method.

When you instantiate the TIniFile or TMemIniFile object, you pass the name of the INI file as a parameter to the constructor. If the file does not exist, it is automatically created. You are then free to read values using the various read methods, such as ReadString, ReadDate, ReadInteger, or ReadBool. Alternatively, if you want to read an entire section of the INI file, you can use the ReadSection method. Similarly, you can write values using methods such as WriteBool, WriteInteger, WriteDate, or WriteString.

Following is an example of reading configuration information from an INI file in a form's OnCreate event handler and writing values in the OnClose event handler.

Delphi:

 
 procedure TForm1.FormCreate(Sender: TObject);
 var
   Ini: TIniFile;
 begin
   Ini := TIniFile.Create( ChangeFileExt( Application.ExeName, '.INI' ) );
   try
     Top     := Ini.ReadInteger( 'Form', 'Top', 100 );
     Left    := Ini.ReadInteger( 'Form', 'Left', 100 );
     Caption := Ini.ReadString( 'Form', 'Caption', 'New Form' );
     if Ini.ReadBool( 'Form', 'InitMax', false ) then
       WindowState := wsMaximized
     else
       WindowState := wsNormal;
   finally
     Ini.Free;
   end;
 end;
 
 procedure TForm1.FormClose(Sender: TObject; var Action TCloseAction)
 var
   Ini: TIniFile;
 begin
   Ini := TIniFile.Create( ChangeFileExt( Application.ExeName, '.INI' ) );
   try
     Ini.WriteInteger( 'Form', 'Top', Top);
     Ini.WriteInteger( 'Form', 'Left', Left);
     Ini.WriteString( 'Form', 'Caption', Caption );
     Ini.WriteBool( 'Form', 'InitMax', WindowState = wsMaximized );
   finally
     Ini.Free;
   end;
 end;

C++:

 __fastcall TForm1::TForm1(TComponent *Owner) : TForm(Owner)
 {
    TIniFile *ini;
    ini = new TIniFile( ChangeFileExt( Application->ExeName, ".INI" ) );
    Top    =  ini->ReadInteger( "Form", "Top", 100 );
    Left   =  ini->ReadInteger( "Form", "Left", 100 ); 
    Caption = ini->ReadString ( "Form", "Caption", "Default Caption" );
    ini->ReadBool( "Form", "initMax", false ) ?
          WindowState = wsMaximized :
          WindowState = wsNormal;

    delete ini;
  }

  void __fastcall TForm1::FormClose)TObject *Sender, TCloseAction &Action)
  {
    TIniFile *ini;
    ini = new TIniFile(ChangeFileExt( Application->ExeName, ".INI" ) );
    ini->WriteInteger( "Form", "Top", Top );
    ini->WriteInteger( "Form", "Left", Left );
    ini->WriteString ( "Form", "Caption", Caption );
    ini->WriteBool   ( "Form", "InitMax", WindowState == wsMaximized );

  delete ini;
  }

Each of the Read routines takes three parameters. The first parameter identifies the section of the INI file. The second parameter identifies the value you want to read, and the third is a default value in case the section or value doesn't exist in the INI file. Just as the Read methods gracefully handle the case when a section or value does not exist, the Write routines create the section and/or value if they do not exist. The example code creates an INI file the first time it is run that looks like this:

[Form]
Top=100
Left=100
Caption=Default Caption
InitMax=0

On subsequent execution of this application, the INI values are read in when the form is created and written back out in the OnClose event.

See Also