tinifile

Many applications use ini files to store configuration information. BaseCLX includes two classes for working with ini files: TIniFile and TMemIniFile. Using ini files has the advantage that they can be used in cross-platform applications and they are easy to read and edit. For information on these classes, see Using TIniFile and TMemIniFile below for more information.

Many Windows applications replace the use of ini files with the system Registry. The Windows system Registry is a hierarchical database that acts as a centralized storage space for configuration information. The VCL includes classes for working with the system Registry. While these are technically not part of BaseCLX (because they are only available on Windows), two of these classes, TRegistryIniFile and TRegistry, are discussed here because of their similarity to the classes for working with ini files.

Using TIniFile and TMemIniFile

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 cross-platform applications, where you can't always count on a system Registry for storing configuration information. BaseCLX provides two classes, TIniFile and TMemIniFile, to make reading and writing ini files very easy.

On Linux, TMemIniFile and TIniFile are identical. On Windows, 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.

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 constructor and writing values in the OnClose event handler.

__fastcall TForm1::TForm1(TComponent *Owner) : TForm(Owner)
{
   TIniFile *ini;
   ini = new TIniFile( ChangeFileExt( Application->ExeName, ".INI" ) );
   Top     =  ini->ReadInteger( "Form", "Top", 118);
   Left    =  ini->ReadInteger( "Form", "Left", 268);
   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=210
Left=320
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.

 

What is ini file?

The ini file is very useful in case when you need to store some configuration and retrieve them back to you programs. An ini file could save the information group by a logic function, call it "section". In the section, all detail data could be saved as a format of "keyname=value". Keyname means the name of a specify thing you want to store while value, that is, the value of this thing.

Let us see an example of win.ini of windows 2k under the winnt folder.

; for 16-bit app support
[fonts]
[extensions]
[mci extensions]
[files]
[Mail]
MAPI=1
[MCI Extensions.BAK]
asf=MPEGVideo
asx=MPEGVideo
ivf=MPEGVideo
m3u=MPEGVideo
mp2v=MPEGVideo
mp3=MPEGVideo
mpv2=MPEGVideo
wax=MPEGVideo
wm=MPEGVideo
wma=MPEGVideo
wmv=MPEGVideo
wvx=MPEGVideo
wmp=MPEGVideo2
wmx=MPEGVideo2

Here the [fonts],[extensions],[mci extensions],[files],[Mail],[MCI Extensions.BAK] are all the sections. While these lines:
asf=MPEGVideo
asx=MPEGVideo
ivf=MPEGVideo
are stored as an form of "name=value", so it is just the detail information.

In C++Builder, TIniFile let you to operate an ini file easily. Take an example of reading and writing configuration information of a from from and to an ini file. Create a new project in your c++builder enviroment. Add the following codes in the form's constructor and in the OnClose event handler.

void __fastcall TForm1::FormClose(TObject *Sender, TCloseAction &Action)
{
   TIniFile *ini;
   ini = new TIniFile(ExtractFilePath(Application->ExeName) + ".ini");
   ini->WriteInteger("myForm", "Top", this->Top);
   ini->WriteInteger("myForm", "Left", this->Left);
   ini->WriteInteger("myForm", "Width", this->Width);
   ini->WriteInteger("myForm", "Height", this->Height);
   ini->WriteString ("myForm", "Caption", "My Form's Caption Could be Stored");
   ini->WriteBool("myForm", "InitMax", WindowState == wsMaximized);
   delete ini;
}

__fastcall TForm1::TForm1(TComponent *Owner) : TForm(Owner)

{
   TIniFile *ini;
   ini = new TIniFile(ExtractFilePath(Application->ExeName) + ".ini");
   Top = ini->ReadInteger("myForm", "Top", 50);
   Left = ini->ReadInteger( "myForm", "Left", 50);
   Top = ini->ReadInteger("myForm", "Width", 800);
   Left = ini->ReadInteger( "myForm", "Height", 600);
   Caption = ini->ReadString( "myForm", "Caption", "myForm" );
   ini->ReadBool("myForm", "InitMax", false ) ? WindowState = wsMaximized : WindowState = wsNormal;
   delete ini;
}

Run you program, then terminate it, open the file under the root folder of your project, you would found the ini file has been showed as the following:

[myForm]
Top=243
Left=202
Width=800
Height=600
Caption=My Form's Caption Could be Stored

Note: to test this code, you need add the "include " in the head.
InitMax=0