C++ Builder Tutorial

INI Files

Introduction

An ini file is a file used to store a list of strings whose considered items use the formula Name=Value. There is no strict rule as to what these files are used for or why. The person who, or the company that, creates such a file also decides what the file would be used for. In Microsoft Windows 3.X and early Windows 9X, ini files were highly used as configuration files, storing some information that other files of a program or the operating system would need. INI Files are still used on all MS Windows operating systems although Microsoft suggests that developers use the Registry to store configuration files. For example, there is (still) a file call Win.ini on most Microsoft Windows operating systems. If you have installed any kind of drivers on a computer (music, modem, etc), you have probably dealt with ini files.

The only regular rule ini files share is that they have an extension of ini. Inside, the body of a file contains two types of items: sections and strings. A string is a line of text in the form Name=Value. A section is a series of strings grouped as an entity.

Imagine you create a program as follows:

Here is its header file:

//---------------------------------------------------------------------------
#ifndef Unit1H
#define Unit1H
//---------------------------------------------------------------------------
#include <Classes.hpp>
#include <Controls.hpp>
#include <StdCtrls.hpp>
#include <Forms.hpp>
#include <ExtCtrls.hpp>
#include <Buttons.hpp>
//---------------------------------------------------------------------------
class TForm1 : public TForm
{
__published:	// IDE-managed Components
    TBevel *Bevel1;
    TComboBox *cboFonts;
    TLabel *Label3;
    TLabel *Label4;
    TComboBox *cboFontSizes;
    TBevel *Bevel2;
    TLabel *Label5;
    TLabel *Label6;
    TLabel *Label7;
    TScrollBar *scrRed;
    TScrollBar *scrGreen;
    TScrollBar *scrBlue;
    TBevel *Bevel3;
    TLabel *Label1;
    TEdit *edtPreview;
    TLabel *lblPreview;
    TLabel *lblShadow;
    TBitBtn *BitBtn1;
    TLabel *lblRed;
    TLabel *lblGreen;
    TLabel *lblBlue;
    void __fastcall BitBtn1Click(TObject *Sender);
    void __fastcall edtPreviewExit(TObject *Sender);
    void __fastcall cboFontsChange(TObject *Sender);
    void __fastcall cboFontSizesChange(TObject *Sender);
    void __fastcall scrRedChange(TObject *Sender);
    void __fastcall scrGreenChange(TObject *Sender);
    void __fastcall scrBlueChange(TObject *Sender);
private:	// User declarations
public:		// User declarations
    __fastcall TForm1(TComponent* Owner);
};
//---------------------------------------------------------------------------
extern PACKAGE TForm1 *Form1;
//---------------------------------------------------------------------------
#endif

Here is its source file:

//---------------------------------------------------------------------------
#include <vcl.h>
#include <IniFiles.hpp>
#pragma hdrstop

#include "Unit1.h"
//---------------------------------------------------------------------------
#pragma package(smart_init)
#pragma resource "*.dfm"
TForm1 *Form1;
//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
    : TForm(Owner)
{
}
//---------------------------------------------------------------------------
void __fastcall TForm1::BitBtn1Click(TObject *Sender)
{
    Close();
}
//---------------------------------------------------------------------------
void __fastcall TForm1::edtPreviewExit(TObject *Sender)
{
    lblPreview->Caption = edtPreview->Text;
    lblShadow->Caption  = edtPreview->Text;
}
//---------------------------------------------------------------------------
void __fastcall TForm1::cboFontsChange(TObject *Sender)
{
    lblPreview->Font->Name = cboFonts->Text;
    lblShadow->Font->Name  = cboFonts->Text;
}
//---------------------------------------------------------------------------
void __fastcall TForm1::cboFontSizesChange(TObject *Sender)
{
    lblPreview->Font->Size = StrToInt(cboFontSizes->Text);
    lblShadow->Font->Size  = StrToInt(cboFontSizes->Text);
}
//---------------------------------------------------------------------------
void __fastcall TForm1::scrRedChange(TObject *Sender)
{
    lblPreview->Font->Color = TColor(RGB(scrRed->Position,
                                         scrGreen->Position,
                                         scrBlue->Position));
    lblRed->Caption = scrRed->Position;
}
//---------------------------------------------------------------------------
void __fastcall TForm1::scrGreenChange(TObject *Sender)
{
    lblPreview->Font->Color = TColor(RGB(scrRed->Position,
                                         scrGreen->Position,
                                         scrBlue->Position));
    lblGreen->Caption = scrGreen->Position;
}
//---------------------------------------------------------------------------
void __fastcall TForm1::scrBlueChange(TObject *Sender)
{
    lblPreview->Color = TColor(RGB(scrRed->Position,
                                   scrGreen->Position,
                                   scrBlue->Position));
    lblBlue->Caption = scrBlue->Position;
}
//---------------------------------------------------------------------------

You can use an INI file to restore the characteristics of this application when it comes up so the user doesn't have to do everything from scratch.

Creating an INI File

To manage INI files, the VCL provides a series a classes. The main class used to create and manage INI files is the TCustomIniFile. One of the classes used to create and manage INI files is the TIniFile class, which is derived from TCustomIniFile. Because TCustomIniFile is an abstract class, you cannot used it directly. To create an INI file, declare an instance of this class using the new operator on the constructor. This constructor takes one argument as a string, the name of the file. If the file is being used for the first time, it would be created. If the file already exists, for example, if the file has been used already at least once, it would be opened and updated. Here is an example:

TIniFile *Initials = new TIniFile("FileToUse.ini");

To create and manage the sections that make up an INI file, the TIniFile provides a series of methods such as ReadSection() and ReadSections(). To create and manage the strings of an INI file, you use the methods of the parent class TCustomIniFile. When creating the strings, you use Read() methods.

Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    TIniFile *StartUp = new TIniFile("IValues.ini");

    Left = StartUp->ReadInteger("FormPos", "Left", 250);
    Top  = StartUp->ReadInteger("FormPos", "Top", 200);

    delete StartUp;
}
//---------------------------------------------------------------------------

To retrieve the values of the strings, you use Write() methods. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormClose(TObject *Sender, TCloseAction &Action)
{
    TIniFile *StartUp = new TIniFile("IValues.ini");

    StartUp->WriteInteger("FormPos", "Left", Left);
    StartUp->WriteInteger("FormPos", "Top", Top);

    delete StartUp;
}
//---------------------------------------------------------------------------

As stated already, an INI file can have more than one section. Each section starts with a name enclosed between square brackets. To create difference sections, start each with a distinct name. The file could look as follows:

You can change the header file as follows:

private: AnsiString txtPreview; AnsiString FontSelected; AnsiString FontSize; int RedPos, GreenPos, BluePos; // User declarations public: // User declarations __fastcall TForm1(TComponent* Owner); }; //---------------------------------------------------------------------------

Here is an example of how you would create the sections:

//--------------------------------------------------------------------------- void __fastcall TForm1::FormCreate(TObject *Sender) { TIniFile *StartUp = new TIniFile("IValues.ini"); // The FormPos section Left = StartUp->ReadInteger("FormPos", "Left", 250); Top = StartUp->ReadInteger("FormPos", "Top", 200); // The controls values section edtPreview->Text = StartUp->ReadString("CtlValues", "txtPreview", "Euzhan Palcy"); cboFonts->Text = StartUp->ReadString("CtlValues", "FontSelected", "Times New Roman"); cboFontSizes->Text = StartUp->ReadString("CtlValues", "FontSize", "24"); scrRed->Position = StartUp->ReadInteger("CtlValues", "RedPos", 0); scrGreen->Position = StartUp->ReadInteger("CtlValues", "GreenPos", 0); scrBlue->Position = StartUp->ReadInteger("CtlValues", "BluePos", 0); delete StartUp; lblPreview->Caption = edtPreview->Text; lblShadow->Caption = edtPreview->Text; lblPreview->Font->Name = cboFonts->Text; lblShadow->Font->Name = cboFonts->Text; lblPreview->Font->Size = StrToInt(cboFontSizes->Text); lblShadow->Font->Size = StrToInt(cboFontSizes->Text); lblPreview->Font->Color = TColor(RGB(scrRed->Position, scrGreen->Position, scrBlue->Position)); } //--------------------------------------------------------------------------- void __fastcall TForm1::FormClose(TObject *Sender, TCloseAction &Action) { TIniFile *StartUp = new TIniFile("IValues.ini"); StartUp->WriteInteger("FormPos", "this->Left", Left); StartUp->WriteInteger("FormPos", "this->Top", Top); StartUp->WriteString("CtlValues", "txtPreview", edtPreview->Text); StartUp->WriteString("CtlValues", "FontSelected", cboFonts->Text); StartUp->WriteString("CtlValues", "FontSize", cboFontSizes->Text); StartUp->WriteInteger("CtlValues", "RedPos", scrRed->Position); StartUp->WriteInteger("CtlValues", "GreenPos", scrGreen->Position); StartUp->WriteInteger("CtlValues", "BluePos", scrBlue->Position); delete StartUp; } //---------------------------------------------------------------------------


Copyright © 2003-2007 FunctionX, Inc.