TIniFile Class

TIniFile stores and retrieves application-specific information and settings from INI files.

Pascal

TIniFile = class(TCustomIniFile);

C++

class TIniFile : public TCustomIniFile;

File

IniFiles

Description

TIniFile enables handling the storage and retrieval of application-specific information and settings in a standard INI file. An INI file stores information in logical groupings, called "sections." Within each section, actual data values are stored in named keys. Keys take the form:

Copy Code

<keyname>=<value>

A FileName is passed to the TIniFile constructor and identifies the INI file that the object accesses.

Note: On Windows, a related object, TMemIniFile, works the same way as TIniFile, but buffers writes in memory to minimize disk access.

Note: On Linux, TIniFile is the same as TMemIniFile.

C++ Examples:

Copy Code

/*
This example demonstrates the usage of Ini files in order to store
and load form configuration between sessions. Example assumes
a RadioGroup and two buttons are present on the main form.
*/
void __fastcall TForm2::btStoreClick(TObject *Sender)
{
    /* Open an instance */
    TCustomIniFile* SettingsFile = OpenIniFileInstance();

    // Store current form properties to be used in later sessions.
    try
    {
        SettingsFile->WriteInteger (Name, "Top", Top);
        SettingsFile->WriteInteger (Name, "Left", Left);
        SettingsFile->WriteInteger (Name, "Width", Width);
        SettingsFile->WriteInteger (Name, "Height", Height);
        SettingsFile->WriteString  (Name, "Caption", Caption);
        SettingsFile->WriteBool    (Name, "InitMax", WindowState == wsMaximized );
    }
    catch(Exception* e)
    {
    }

    delete SettingsFile;
}

void __fastcall TForm2::btLoadClick(TObject *Sender)
{
    /* Open an instance */
    TCustomIniFile* SettingsFile = OpenIniFileInstance();

    try
    {
        /*
        Read all saved values from the last session. The section name
        is the name of the form. Also use form's properties as defaults
        */
        Top     = SettingsFile->ReadInteger(Name, "Top", Top );
        Left    = SettingsFile->ReadInteger(Name, "Left", Left );
        Width   = SettingsFile->ReadInteger(Name, "Width", Width );
        Height  = SettingsFile->ReadInteger(Name, "Height", Height );
        Caption = SettingsFile->ReadString (Name, "Caption", Caption);

        // Load last window state
        if (SettingsFile->ReadBool(Name, "InitMax", WindowState == wsMaximized))
            WindowState = wsMaximized;
        else
            WindowState = wsNormal;
    }
    catch(Exception* e)
    {
    }

    delete SettingsFile;
}

TCustomIniFile* __fastcall TForm2::OpenIniFileInstance()
{
    /*
    Open/create a new INI file that has the same name as our executable
    only with the INI extension.
    */

    switch (RadioGroup1->ItemIndex)
    {
        case 0:
            /* Registry mode selected: in HKEY_CURRENT_USER\Software\... */
            return new TRegistryIniFile(String("Software\\") + Application->Title);
        case 1:
            /* Ini file mode selected */
            return new TIniFile(ChangeFileExt(Application->ExeName, ".INI"));
        case 2:
            /* Memory based Ini file mode selected */
            return new TMemIniFile(ChangeFileExt(Application->ExeName, ".INI"));
      }
}

Delphi Examples:

Copy Code

{
This example demonstrates the use of Ini files in order to store
and load form configurations between sessions. This example requires
a RadioGroup and two buttons.
}
procedure TForm2.btLoadClick(Sender: TObject);
var
  SettingsFile : TCustomIniFile;
begin
  { Open an instance }
  SettingsFile := OpenIniFileInstance();

  try
    {
    Read all saved values from the last session. The section name
    is the name of the form. Also use form's properties as defaults
    }
    Top     := SettingsFile.ReadInteger(Name, 'Top', Top );
    Left    := SettingsFile.ReadInteger(Name, 'Left', Left );
    Width   := SettingsFile.ReadInteger(Name, 'Width', Width );
    Height  := SettingsFile.ReadInteger(Name, 'Height', Height );
    Caption := SettingsFile.ReadString (Name, 'Caption', Caption);

    { Load last window state }
    case SettingsFile.ReadBool(Name, 'InitMax', WindowState = wsMaximized) of
      true : WindowState := wsMaximized;
      false: WindowState := wsNormal;
    end;

  finally
    SettingsFile.Free;
  end;
end;

procedure TForm2.btStoreClick(Sender: TObject);
var
  SettingsFile: TCustomIniFile;
begin
  { Open an instance }
  SettingsFile := OpenIniFileInstance();

  {
  Store current form properties to be used in later sessions.
  }
  try
    SettingsFile.WriteInteger (Name, 'Top', Top);
    SettingsFile.WriteInteger (Name, 'Left', Left);
    SettingsFile.WriteInteger (Name, 'Width', Width);
    SettingsFile.WriteInteger (Name, 'Height', Height);
    SettingsFile.WriteString  (Name, 'Caption', Caption);
    SettingsFile.WriteBool    (Name, 'InitMax', WindowState = wsMaximized );
    SettingsFile.WriteDateTime(Name, 'LastRun', Now);
  finally
    SettingsFile.Free;
  end;

end;

function TForm2.OpenIniFileInstance: TCustomIniFile;
begin
  {
  Open/create a new INI file that has the same name as our executable
  only with the INI extension.
  }

  case RadioGroup1.ItemIndex of
    0:
      begin
        { Registry mode selected: in HKEY_CURRENT_USER\Software\... }
        Result := TRegistryIniFile.Create('Software\' + Application.Title);
      end;
    1:
      begin
        { Ini file mode selected }
        Result := TIniFile.Create(ChangeFileExt(Application.ExeName, '.INI'));
      end;
    2:
      begin
        { Memory based Ini file mode selected }
        Result := TMemIniFile.Create(ChangeFileExt(Application.ExeName, '.INI'));
      end;
  end;
end;