INIClass Overview

Top  Previous  Next

 

The INIClass provides a simple interface to different methods of non-volatile storage (e.g., storage that is persistent beyond the life cycle of your programs). By default, the INIClass object centrally handles reads and writes for a given configuration (.INI) file. It also supports other methods of non-volatile storage by allowing read and write access to the Windows system registry or a local table. The INIClass Init method controls which access method is used.

INIClass Concepts

By convention an INI file is an ASCII text file that stores information between computing sessions and contains entries of the form:

[SECTION1]

ENTRY1=value

ENTRYn=value

[SECTIONn]

ENTRY1=value

ENTRYn=value

The INIClass automatically creates INI files and the sections and entries within them. The INI class also updates and deletes sections and entries. In particular, the INIClass makes it very easy to save and restore Window sizes and positions between sessions; plus it provides a single repository for INI file code, so you only need to specify the INI file name in one place.

INIClass Relationship to Other Application Builder Classes

The PopupClass and the PrintPreviewClass optionally use the INIClass; otherwise, it is completely independent of other Application Builder Classes.

INIClass ABC Template Implementation

The ABC Templates generate code to instantiate a global INIClass object called INIMgr. If you request to Use INI file to save and restore program settings in the Global Properties dialog, then each procedure based on the Window procedure template (Frame, Browse, and Form) calls the INIMgr to save and restore its WINDOW's position and size.

INIClass Source Files

The INIClass source code is installed by default to the Clarion \LIBSRC folder. The INIClass source code and its respective components are contained in:

 

ABUTIL.INC

INIClass declarations

 

ABUTIL.CLW

INIClass method definitions

INIClass Conceptual Example

The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate an INIClass object.

 PROGRAM

 

 INCLUDE('ABUTIL.INC')             !declare INIClass class

 MAP

 END

 

INIMgr  INIClass                    !declare INIMgr object

Sound   STRING('ON ')               !user's sound preference

Volume  BYTE(3)                     !user's volume preference

 

PWindow  WINDOW('Preferences'),AT(,,89,34),MAX,RESIZE

     CHECK('&Sound'),AT(8,6),USE(Sound),VALUE('ON','OFF')

     PROMPT('&Volume'),AT(31,19),USE(?VolumePrompt)

     SPIN(@s20),AT(8,20,21,7),USE(Volume),HVSCROLL,RANGE(0,9),STEP(1)

     BUTTON('OK'),AT(57,3,30,10),USE(?OK)

    END

CODE

INIMgr.Init('.\MyApp.INI')                     !initialize the INIMgr object

INIMgr.Fetch('Preferences','Sound',Sound)      !get sound, default 'ON'

Volume=INIMgr.TryFetch('Preferences','Volume') !get volume, no default

IF Volume

 Sound=INIMgr.FetchField('Preferences','Sound&Vol',1)  !get comma delimited sound

 Volume=INIMgr.FetchField('Preferences','Sound&Vol',2) !get comma delimited volume

END

OPEN(PWindow)

INIMgr.Fetch('Preferences',PWindow)             !restore window size & pos

ACCEPT

 IF EVENT() = EVENT:Accepted

  IF FIELD() = ?OK

   INIMgr.Update('Preferences','Sound',Sound)   !store sound

   INIMgr.Update('Preferences','Volume',Volume) !store volume

   INIMgr.Update('Preferences','Sound&Vol',|    !store comma delimited values

          CLIP(Sound)&','&Volume)       !e.g., Sound&Vol=ON,3

   POST(EVENT:CloseWindow)

  END

 END

END

INIMgr.Update('Preferences',PWindow)            !store window size & pos