Options

Unit Options contains the following class definitions:

TOption

TOptions

EOptError


TOption

Properties Methods Events

TOption is a component that represents a program option.

Unit

Options

Description

A TOption object can hold a value of any type, a default value, and it can have an associated control that enables the user to change the option value. TOption can save its value to the registry or an ini file. Options are handled in a collection of a TOptions component.


Methods
TOption Methods

TOption

AcceptComponent

Create

Destroy

GetData

GetParentComponent

HasParent

SetData


Properties
TOption Properties

TOption

Public properties

AsBoolean

AsColor

AsDate

AsDateTime

AsFlags

AsFloat

AsFloatArray

AsFont

AsIntArray

AsInteger

AsStrArray

AsString

AsTime

Count

DefAsBoolean

DefAsColor

DefAsDate

DefAsDateTime

DefAsFlags

DefAsFloat

DefAsFloatArray

DefAsFont

DefAsIntArray

DefAsInteger

DefAsStrArray

DefAsString

DefAsTime

DefCount

Index

Options

Published properties

Associate

ArraySeparator

BoolStr

Category

DefValue

FloatMask

NameSeparator

OptionType

ParentArraySeparator

ParentBoolStr

ParentFloatMask

ParentNameSeparator

ParentStoreMode

StoreMode


Events
TOption Events

TOption

OnUpdated


TOptions

Properties Methods Events

TOptions is a container component that handles program preferences.

Unit

Options

Description

TOptions have a list of TOption objects. Each TOption object holds a program option value. The properties and methods of the class TOptions make it easy to handle the program options, create a preferences dialog box, read and write option values to the registry or an ini file.


Methods
TOptions Methods

TOptions

Add

Create

Destroy

IndexOf

GetData

Load

LoadAll

LoadCat

OptByName

Save

SaveAll

SaveCat

SetData

SetDefault

SetDefaults

SetDefaultsCat


Properties
TOptions Properties

TOptions

Public properties

Count

Items

MemIni

Published properties

ArraySeparator

AutoLoad

BoolStr

FloatMask

IniFileDir

IniFileLoc

IniFileName

NameSeparator

RegKey

RootKey

SaveOnFree

SaveOnUpdate

StoreMode

Target


Events
TOptions Events

TOptions

AfterLoad

AfterSave

BeforeLoad

BeforeSave

OnLoad

OnLoaded

OnSave

OnSaved

OnUpdated


EOptError

Properties Methods

EOptError is an exception class.

Unit

Options

Description

Any error in the methods of TOption or TOptions raises an EOptError exception.


Methods
EOptError Methods

EOptError

Create


Properties
EOptError Properties

EOptError

ErrorCode


Ini files
Storing formats in ini file

stmBinArray mode

    OBoolean=1

    OColor=255

    ODate=37417

    ODateTime=37417,5772569444

    OFlags_1=1

    OFlags_2=0

    OFlags_3=0

    OFlags_4=1

    OFloat=3,14

    OFloatArray_1=1,25

    OFloatArray_2=11,5

    OFloatArray_3=115,5

    OFloatArray_4=-54

    OFont_CHARSET=238

    OFont_COLOR=-2147483640

    OFont_NAME=Arial

    OFont_PITCH=0

    OFont_SIZE=10

    OFont_STYLE=1000

    OIntArray_1=1

    OIntArray_2=2

    OIntArray_3=3

    OInteger=1729

    OStrArray_1=one

    OStrArray_2=two

    OStrArray_3=three

    OString=This is a string

    OTime=0,578148148148148

stmBinary mode

    OBoolean=1

    OColor=255

    ODate=37417

    ODateTime=37417,5772569444

    OFlags=1001

    OFloat=3,14

    OFloatArray=1,25||11,5||115,5||-54||

    OFont=238||-2147483640||Arial||0||10||1000||

    OIntArray=1||2||3||

    OInteger=1729

    OStrArray=one||two||three||

    OString=This is a string

    OTime=0,578148148148148

stmStrArray mode

    OBoolean=True

    OColor=clRed

    ODate=06/10/2002

    ODateTime=06/10/2002 13:51:15

    OFlags_1=True

    OFlags_2=False

    OFlags_3=False

    OFlags_4=True

    OFloat=3,14

    OFloatArray_1=1,25

    OFloatArray_2=11,5

    OFloatArray_3=115,5

    OFloatArray_4=-54

    OFont_CHARSET=238

    OFont_COLOR=clWindowText

    OFont_NAME=Arial

    OFont_PITCH=DEFAULT

    OFont_SIZE=10

    OFont_STYLE=[BOLD]

    OIntArray_1=1

    OIntArray_2=2

    OIntArray_3=3

    OInteger=1729

    OStrArray_1=one

    OStrArray_2=two

    OStrArray_3=three

    OString=This is a string

    OTime=13:52:32

stmString mode

    OBoolean=True

    OColor=clRed

    ODate=06/10/2002

    ODateTime=06/10/2002 13:51:15

    OFlags=True||False||False||True||

    OFloat=3,14

    OFloatArray=1,25||11,5||115,5||-54||

    OFont=238||clWindowText||Arial||DEFAULT||10||[BOLD]||

    OIntArray=1||2||3||

    OInteger=1729

    OStrArray=one||two||three||

    OString=This is a string

    OTime=13:52:32


Registry
Storing formats in registry

stmBinArray mode

    OBoolean           0x00000001 (1)

    OColor             0x000000ff (255)

    ODate              00 00 00 00 20 45 e2 40

    ODateTime          39 8e e3 78 32 45 e2 40

    OFlags_1           0x00000001 (1)

    OFlags_2           0x00000000 (0)

    OFlags_3           0x00000000 (0)

    OFlags_4           0x00000001 (1)

    OFloat             1f 85 eb 51 b8 1e 09 40

    FloatArray_1       00 00 00 00 00 00 f4 3f

    FloatArray_2       00 00 00 00 00 00 27 40

    FloatArray_3       00 00 00 00 00 e0 5c 40

    FloatArray_4       00 00 00 00 00 00 4b c0

    OFont_CHARSET      0x000000ee (238)

    OFont_COLOR        0x80000008 (2147483656)

    OFont_NAME         41 72 69 61 6c

    OFont_PITCH        0x00000000 (0)

    OFont_SIZE         0x0000000a (10)

    OFont_STYLE        0x00000001 (1)

    OIntArray_1        0x00000001 (1)

    OIntArray_2        0x00000002 (2)

    OIntArray_3        0x00000003 (3)

    OInteger           0x000006c1 (1729)

    OStrArray_1        6f 6e 65

    OStrArray_2        74 77 6f

    OStrArray_3        74 68 72 65 65

    OString            54 68 69 73 20 69 73 20 61 20 73 74 72 69 6e 67

    OTime              9d 41 91 8b 30 e2 3f

stmBinary mode

    OBoolean           0x00000001 (1)

    OColor             0x000000ff (255)

    ODate              00 00 00 00 20 45 e2 40

    ODateTime          39 8e e3 78 32 45 e2 40

    OFlags             04 00 00 00 09

    OFloat             1f 85 eb 51 b8 1e 09 40

    OFloatArray        00 00 00 00 00 00 f4 3f 00 00 00 00 00 00 27 40 00 00 00 00 00 e0 5c 40 00 00 00 00 00 00 4b c0

    OFont              ee 08 00 00 80 05 00 00 00 41 72 69 61 6c 00 0a 00 00 00 01

    OIntArray          01 00 00 00 02 00 00 00 03 00 00 00

    OInteger           0x000006c1 (1729)

    OStrArray          6f 6e 65 0d 0a 74 77 6f 0d 0a 74 68 72 65 65 0d 0a

    OString            54 68 69 73 20 69 73 20 61 20 73 74 72 69 6e 67

    OTime              9d 41 91 8b 30 e2 3f

stmStrArray mode

    OBoolean           "True"

    OColor             "clRed"

    ODate              "2002.06.10."

    ODateTime          "2002.06.10. 13:51:15"

    OFlags_1           "True"

    OFlags_2           "False"

    OFlags_3           "False"

    OFlags_4           "True"

    OFloat             "3,14"

    OFloatArray_1      "1,25"

    OFloatArray_2      "11,5"

    OFloatArray_3      "115,5"

    OFloatArray_4      "-54"

    OFont_CHARSET      "238"

    OFont_COLOR        "clWindowText"

    OFont_NAME         "Arial"

    OFont_PITCH        "DEFAULT"

    OFont_SIZE         "10"

    OFont_STYLE        "[BOLD]"

    OIntArray_1        "1"

    OIntArray_2        "2"

    OIntArray_3        "3"

    OInteger           "1729"

    OStrArray_1        "one"

    OStrArray_2        "two"

    OStrArray_3        "three"

    OString            "This is a string"

    OTime              "13:52:32"

stmString mode

    OBoolean           "True"

    OColor             "clRed"

    ODate              "2002.06.10."

    ODateTime          "2002.06.10. 13:51:15"

    OFlags             "True||False||True||False||"

    OFloat             "3,14"

    OFloatArray        "1,25||11,5||115,5||-54||"

    OFont              "238||clWindowText||Arial||DEFAULT||10||[BOLD]||"

    OIntArray          "1||2||3||"

    OInteger           "1729"

    OStrArray          "one||two||three||"

    OString            "This is a string"

    OTime              "13:52:32"


AcceptComponent
TOption.AcceptComponent

TOption

Determines if a component can be acceptable as an associated control.

function AcceptComponent(Component: TComponent): boolean;

Description

Only when AcceptComponent returns true, can be the Component an associated control for the current option. The acceptability depends on the OptionType. The following table shows the acceptable components for each option type.

Option type	Acceptable classes
String	TEdit, TMaskEdit, TComboBox, TMemo, TRichEdit
Integer	TEdit, TMaskEdit, TListBox, TRadioGroup, TTrackBar, TUpDown, TSpinEdit
Float	TEdit, TMaskEdit
Boolean	TCheckBox, TSpeedButton, TMenuItem
Color	TColorDialog
Date	TEdit, TMaskEdit, TDateTimePicker, TMonthCalendar
Time	TEdit, TMaskEdit, TDateTimePicker
DateTime	TEdit, TMaskEdit, TDateTimePicker
Font	TFontDialog
Flags	TGroupBox, TPanel, TCheckListBox
String array	TMemo, TRichEdit, TGroupBox, TPanel
Integer array	TMemo, TGroupBox, TPanel
Float array	TMemo, TGroupBox, TPanel

Array options can be associated with a TPanel or TGroupBox. In this case, all controls on the panel or group box acceptable for the array element type will hold an array item value.

Any descendant class is acceptable as well.

Setting Associate property will call AcceptComponent function to determine if the given component can be associated. You rarely need call AcceptComponent directly.


Create
TOption.Create

TOption

Creates an option instance.

constructor Create(AOwner: TComponent); override;

Description

You rarely need call TOption.Create directly. Call TOptions.Add instead.


Destroy
TOption.Destroy

TOption

Destroys a TOption instance and frees the allocated resources.

destructor Destroy; override;

Description

Never call Destroy directly. Call Free instead.


GetData
TOption.GetData

TOption

Gets option value from the associated control.

procedure GetData;

Description

If Associate is nil GetData does nothing.

If the associated control contains an invalid value (for example an invalid integer in an edit box) an exception will be raised.


GetParentComponent
TOption.GetParentComponent

TOption

Returns the TOptions object that contains tha option.

function GetParentComponent: TComponent; override;

Description

GetParentComponent is called by the streaming system that loads and saves VCL components. It ensures that objects are loaded and saved with their parent objects. TOption overrides the inherited method to identify its associated option container as its parent.


HasParent
TOption.HasParent

TOption

Indicates whether the option is contained in an option list.

function HasParent: boolean; override;

Description

HasParent is called by the streaming system that loads and saves VCL components. It ensures that objects are loaded and saved with their parent objects. TOption overrides the inherited method to return True if the option is contained in an option list.


SetData
TOption.SetData

TOption

Passes the option's current value to the associated control.

procedure SetData;

Description

If Associate is nil, SetData does nothing.


Add
TOptions.Add

TOptions

Creates a new option item and adds it to the option list.

function Add: TOption;

Description

Call Add to create a new item in the option list. The new item is placed at the end of the Items array.

Add returns the new option item.


Create
TOptions.Create

TOptions

Creates and initializes a new TOptions object.

constructor Create(AOwner: TComponent); override;


Destroy
TOptions.Destroy

TOptions

Destroys the option list.

destructor Destroy; override;

Description

TOptions.Destroy tries to free the option items in the list. As the owner of the item objects is not the TOptions object itself, the items may be freed by their owner (most likely the form that contains the option list). This is not a problem, because a TOption object deletes itself from the option list, before destroying itself. That may cause that the option list is already empty, when the TOptions object should be destroyed.


IndexOf
TOptions.IndexOf

TOptions

Returns the index of the first entry in the Items array with a specified value.

function IndexOf(AOption: TOption): integer;

Description

Call IndexOf to get the index for an option in the Items array. Specify the option as the AOption parameter.

The first item in the array has index 0, the second item has index 1, and so on. If an item is not in the list, IndexOf returns -1. If an option appears more than once in the array, IndexOf returns the index of the first appearance.


GetData
TOptions.GetData

TOptions

Gets option values from the associated controls.

procedure GetData;

Description

GetData passes along the Items array, and when an item's Associate property is not nil, calls its GetData method.


Load
TOptions.Load

TOptions

Loads an option value from the registry or an ini file.

procedure Load(index: integer);

Description

Load calls the appropriate method of the index'th option element in the Items array to get its value.


LoadAll
TOptions.LoadAll

TOptions

Loads all option values from the registry or an ini file.

procedure LoadAll;

Description

LoadAll passes along the Items array, and calls Load for each item.


LoadCat
TOptions.LoadCat

TOptions

Loads option values in a category from the registry or an ini file.

procedure LoadCat(Category: string);

Description

LoadCat passes along the Items array and calls Load for each item, that has a Category value matching the parameter.


OptByName
TOptions.OptByName

TOptions

Finds an option in the Items array by its name.

function OptByName(const AName: string): TOption;

Description

OptByName returns the first element in the Items array with a name that is matching the AName parameter. If there is not an element in the list with the given name, OptByName returns nil.


Save
TOptions.Save

TOptions

Saves an option value to the registry or an ini file.

procedure Save(index: integer);

Description

Save calls the appropriate method of the index'th option element in the Items array to save its value.


SaveAll
TOptions.SaveAll

TOptions

Saves all option values to the registry or an ini file.

procedure SaveAll;

Description

SaveAll passes along the Items array, and calls Save for each item.


SaveCat
TOptions.SaveCat

TOptions

Saves option values in a category to the registry or an ini file.

procedure SaveCat(Category: string);

Description

SaveCat passes along the Items array and calls Save for each item, that has a Category value matching the parameter.


SetData
TOptions.SetData

TOptions

Passes option values to the associated controls.

procedure SetData;

Description

SetData passes along the Items array, and when an item's Associate property is not nil, calls its SetData method.


SetDefault
TOptions.SetDefault

TOptions

Sets default value for an option item.

procedure SetDefault(index: integer);

Description

SetDefault calls the appropriate method of the index'th option element in the Items array to set its value to default.


SetDefaults
TOptions.SetDefaults

TOptions

Sets default values for all option items.

procedure SetDefaults;

Description

SetDefaults passes along the Items array, and calls SetDefault for each item.


SetDefaultsCat
TOptions.SetDefaultsCat

TOptions

Sets default value for options in a category.

procedure SetDefaultsCat(Category: string);

Description

SetDefaultsCat passes along the Items array and calls SetDefault for each item, that has a Category value matching the parameter.


Create
EOptError.Create

EOptError

Creates an EOptError exception object.

constructor Create(Code: integer);

Description

Code parameter is the error code. Possible values are listed in the following table.

Code constant	Error
oerUnknownError	Invalid error code was passed to EOptError.Create.
oerInvalidName	The name of an option must be a valid Delphi identifier. Passing an invalid option name will raise this exception.
oerNameAlreadyExists	Option lists do not allow duplicate names. Setting an option name to a value that already exists in the list raises this exception.
oerNotInteger	Reading an option value as an integer caused a format convert error.
oerNotColor	Reading an option value as a color caused a format convert error.
oerNotFloat	Reading an option value as a float caused a format convert error.
oerNotDateTime	Reading an option value as a date, time or datetime caused a format convert error.
oerNotFont	Reading an option value as a font caused a format convert error.
oerIndexOutOfBounds	Invalid index was used when accessing the Items array or an option's value as flags, string array, integer array or float array.
oerRegLoad	An error has occured while reading an option value from the registry.


AsBoolean
TOption.AsBoolean

TOption

Represents an option's value as a boolean value.

property AsBoolean: boolean;

Description

AsBoolean provides a property to read the value of the option's data into a boolean, or to assign a boolean value to the contents of the option.

If the option's type is not boolean, getting its value as a boolean value leads to an unpredictable result.


AsColor
TOption.AsColor

TOption

Represents an option's value as a color.

property AsColor: TColor;

Description

AsColor provides a property to read the value of the option's data into a color, or to assign a color value to the contents of the option.

If the option's type is not color, getting its value as color may cause an exception.

AsColor differs from AsInteger, because the options store their values internally as strings. Options of type color use clXXX Delphi color constants.


AsDate
TOption.AsDate

TOption

Represents an option's value as a date.

property AsDate: TDateTime;

Description

AsDate provides a property to read the value of the option's data into a date, or to assign a date value to the contents of the option.

If the option's type is not date, getting its value as date may cause an exception.


AsDateTime
TOption.AsDateTime

TOption

Represents an option's value as a DateTime.

property AsDateTime: TDateTime;

Description

AsDateTime provides a property to read the value of the option's data into a DateTime, or to assign a DateTime value to the contents of the option.

If the option's type is not DateTime, getting its value as DateTime may cause an exception.


AsFlags
TOption.AsFlags

TOption

Represents an option's value as a boolean array.

property AsFlags[index: integer]: boolean;

Description

AsFlags provides a property to read the value of the option's data into a boolean array, or to assign a boolean array value to the contents of the option.

You can use Count to learn the number of array elements. The first item in the array has index 0. The last item in the array has index Count - 1. Getting option value as flags with an invalid index raises an exception. Setting value with an index greater then Count - 1 extends the array.

If the option's type is not flags, getting its value as flags leads to an unpredictable result.


AsFloat
TOption.AsFloat

TOption

Represents an option's value as a float value.

property AsFloat: double;

Description

AsFloat provides a property to read the value of the option's data into a float value, or to assign a float value to the contents of the option.

If the option's type is not float, getting its value as float may cause an exception.


AsFloatArray
TOption.AsFloatArray

TOption

Represents an option's value as a float array.

property AsFloatArray[index: integer]: double;

Description

AsFloatArray provides a property to read the value of the option's data into a float array, or to assign a float array value to the contents of the option.

You can use Count to learn the number of array elements. The first item in the array has index 0. The last item in the array has index Count - 1. Getting option value as float array with an invalid index raises an exception. Setting value with an index greater then Count - 1 extends the array.

If the option's type is not float array, getting its value as float array may cause an exception.


AsFont
TOption.AsFont

TOption

Represents an option's value as a font.

property AsFont: TFont;

Description

AsFont provides a property to read the value of the option's data into a font, or to assign a font to the contents of the option.

Getting AsFont creates a new TFont object. Destroying this object is the programmer's responsibility.

If the option's type is not font, getting its value as font may cause an exception.


AsIntArray
TOption.AsIntArray

TOption

Represents an option's value as an integer array.

property AsIntArray[index: integer]: integer;

Description

AsIntArray provides a property to read the value of the option's data into an integer array, or to assign an integer array value to the contents of the option.

You can use Count to learn the number of array elements. The first item in the array has index 0. The last item in the array has index Count - 1. Getting option value as integer array with an invalid index raises an exception. Setting value with an index greater then Count - 1 extends the array.

If the option's type is not integer array, getting its value as integer array may cause an exception.


AsInteger
TOption.AsInteger

TOption

Represents an option's value as an integer value.

property AsInteger: integer;

Description

AsInteger provides a property to read the value of the option's data into an integer value, or to assign an integer value to the contents of the option.

If the option's type is not integer, getting its value as integer may cause an exception.


AsStrArray
TOption.AsStrArray

TOption

Represents an option's value as a string array.

property AsStrArray[index: integer]: string;

Description

AsStrArray provides a property to read the value of the option's data into a string array, or to assign a string array value to the contents of the option.

You can use Count to learn the number of array elements. The first item in the array has index 0. The last item in the array has index Count - 1. Getting option value as string array with an invalid index raises an exception. Setting value with an index greater then Count - 1 extends the array.


AsString
TOption.AsString

TOption

Represents an option's value as a string value.

property AsString: string;

Description

AsString provides a property to read the value of the option's data into a string, or to assign a string value to the contents of the option.

As options store their values internally as strings, AsString gives always a valid string value. If you want to get an integer option's value as a string, you can use Option1.AsString instead of IntToStr(Option1.AsInteger).


AsTime
TOption.AsTime

TOption

Represents an option's value as a time value.

property AsTime: TDateTime;

Description

AsTime provides a property to read the value of the option's data into a time value, or to assign a time value to the contents of the option.

If the option's type is not time, getting its value as time may cause an exception.


Count
TOption.Count

TOption

Returns the number of elements for an array option.

property Count: integer;

Description

Count is read only and runtime only. Array type options (flags, string array, integer array, float array) use Count to give the current number of elements. Count always results 1 for a non-array type option.


DefAsBoolean
TOption.DefAsBoolean

TOption

Represents an option's default value as a boolean value.

property DefAsBoolean: boolean;

Description

Same as the AsBoolean property for the default value.

DefAsBoolean is used rarely in applications, as default values are usually set at design time.


DefAsColor
TOption.DefAsColor

TOption

Represents an option's default value as a color value.

property DefAsColor: TColor;

Description

Same as the AsColor property for the default value.

DefAsColor is used rarely in applications, as default values are usually set at design time.


DefAsDate
TOption.DefAsDate

TOption

Represents an option's default value as a date value.

property DefAsDate: TDateTime;

Description

Same as the AsDate property for the default value.

DefAsDate is used rarely in applications, as default values are usually set at design time.


DefAsDateTime
TOption.DefAsDateTime

TOption

Represents an option's default value as a DateTime value.

property DefAsDateTime: TDateTime;

Description

Same as the AsDateTime property for the default value.

DefAsDateTime is used rarely in applications, as default values are usually set at design time.


DefAsFlags
TOption.DefAsFlags

TOption

Represents an option's default value as a boolean array value.

property DefAsFlags[index: integer]: boolean;

Description

Same as the AsFlags property for the default value.

DefAsFlags is used rarely in applications, as default values are usually set at design time.


DefAsFloat
TOption.DefAsFloat

TOption

Represents an option's default value as a float value.

property DefAsFloat: double;

Description

Same as the AsFloat property for the default value.

DefAsFloat is used rarely in applications, as default values are usually set at design time.


DefAsFloatArray
TOption.DefAsFloatArray

TOption

Represents an option's default value as a float array.

property DefAsFloatArray[index: integer]: double;

Description

Same as the AsFloatArray property for the default value.

DefAsFloatArray is used rarely in applications, as default values are usually set at design time.


DefAsFont
TOption.DefAsFont

TOption

Represents an option's default value as a font.

property DefAsFont: TFont;

Description

Same as the AsFont property for the default value.

DefAsFont is used rarely in applications, as default values are usually set at design time.

Getting DefAsFont creates a new TFont object. Destroying this object is the programmer's responsibility.


DefAsIntArray
TOption.DefAsIntArray

TOption

Represents an option's default value as an integer array.

property DefAsIntArray[index: integer]: integer;

Description

Same as the AsIntArray property for the default value.

DefAsIntArray is used rarely in applications, as default values are usually set at design time.


DefAsInteger
TOption.DefAsInteger

TOption

Represents an option's default value as an integer value.

property DefAsInteger: integer;

Description

Same as the AsInteger property for the default value.

DefAsInteger is used rarely in applications, as default values are usually set at design time.


DefAsStrArray
TOption.DefAsStrArray

TOption

Represents an option's default value as a string array.

property DefAsStrArray[index: integer]: string;

Description

Same as the AsStrArray property for the default value.

DefAsStrArray is used rarely in applications, as default values are usually set at design time.


DefAsString
TOption.DefAsString

TOption

Represents an option's default value as a string value.

property DefAsString: string;

Description

Same as the AsString property for the default value.

DefAsString is used rarely in applications, as default values are usually set at design time.


DefAsTime
TOption.DefAsTime

TOption

Represents an option's default value as a time value.

property DefAsTime: TDateTime;

Description

Same as the AsTime property for the default value.

DefAsTime is used rarely in applications, as default values are usually set at design time.


DefCount
TOption.DefCount

TOption

Gives the number of elements in the default value for an array option.

property DefCount: integer;

Description

DefCount is read only and runtime only. Array type options (flags, string array, integer array, float array) use DefCount to give the current number of elements in the default value. DefCount always results 1 for a non-array type option.


Index
TOption.Index

TOption

Returns the item's position in the Items array of TOptions.

property Index: Integer;

Description

Each TOption is indexed in the Items array of the TOptions to which it belongs. The Index property of the TOption contains the item's index value in that array.

Items is a zero-based array. The first member of the option list has an index value of 0, the second member has an index value of 1, and so forth.


Options
TOption.Options

TOption

Specifies the TOptions instance to which the TOption belongs.

property Options: TOptions;

Description

Each TOption belongs to the TOptions which creates it. The Options property points to the option list object to which the item belongs.

Setting Options to nil deletes the option from the list, but does not destroy it.

Setting Options to any valid TOptions instance removes the option from the old option list and adds it to the end of the new one.


Associate
TOption.Associate

TOption

Specifies a component for the option wich allows its value to be modified.

property Associate: TComponent;

Description

A component can only be associated to the option if AcceptComponent returns true.

SetData passes the option value to the associated component, GetData takes back the modified value. This makes it easy to build a program preferences dialog box.


ArraySeparator
TOption.ArraySeparator

TOption

Specifies an item separator string for storing option value in non-array modes.

property ArraySeparator: string;

Description

When using stmBinary or stmString modes for storing the option value, array elements will be separated with ArraySeparator. Only array options and font options use this property.

Options use #13#10 to separate their elements internally. This is useful when it's needed to find an item with a simple code. But it's not acceptable for storing values in ini files.

You should stick to printable characters, when using an ini file.

Default value is '||'.


BoolStr
TOption.BoolStr

TOption

Specifies strings for boolean values.

type TBoolStr = (bsTrue, bsTrueUpper, bsTrueLower, bsOn, bsOnUpper, bsOnLower, bsNum);

property BoolStr: TBoolStr;

Description

Options of boolean and flags type use this property. When storing option values in string modes, appearance of boolean values depends on BoolStr. The following table shows the meaning of the bsXXX values.

BoolStr	False / True values
bsTrue	False / True
bsTrueUpper	FALSE / TRUE
bsTrueLower	false / true
bsOn	Off / On
bsOnUpper	OFF / ON
bsOnLower	off / on
bsNum	0 / 1

Default value is bsTrue.


Category
TOption.Category

TOption

Specifies the option's category.

type TCategory = string;

property Category: TCategory;

Description

When using an ini file for storing option values, it is required to specify a category for each option. Category is used to identify the ini section, where the option value should be stored. Options without a category can't be stored in an ini file.

When using the registry for storing option values, category can be an empty string. If an option's category is empty, it will be stored directly in RegKey. Options with non-empty category will be placed into RegKey\Category.


DefValue
TOption.DefValue

TOption

Represents the default value of an option.

type TDefValue = string;

property DefValue: TDefValue;

Description

DefValue is used internally. This property is used rarely in applications, as default values are usually set at design time.


FloatMask
TOption.FloatMask

TOption

Specifies a mask for float option values.

property FloatMask: string;

Description

Only options of type float and float array use this property.

Default value is '0.##'.


NameSeparator
TOption.NameSeparator

TOption

Specifies a string for option names when using array storing modes.

property NameSeparator: string;

Description

Only options of type array and font use this property. when using array storing modes, each option element will be stored with a name OptionName_i, where OptionName is the name of the option, "_" is the NameSeparator, and i is the index of the element. Font options use OptionName_PropertyName format, where PropertyName is a font property (CHARSET, NAME, and so on).

NameSeparator can be an empty string.

Default value is '_'.


OptionType
TOption.OptionType

TOption

Specifies the option's type.

type TOptionType = (otString, otInteger, otFloat, otBoolean, otColor, otDate, otTime, otDateTime, otFont, otFlags, otStrArray, otIntArray, otFloatArray);

property OptionType: TOptionType;

Description

Option values are stored as strings internally. An option value can be accessed through AsXXX properties, corresponding to its type.


ParentArraySeparator
TOption.ParentArraySeparator

TOption

Determines if the option uses its parent's ArraySeparator.

property ParentArraySeparator: boolean;

Description

If ParentArraySeparator is true, the option uses its parent option list's ArraySeparator property.

Default value is true.


ParentBoolStr
TOption.ParentBoolStr

TOption

Determines if the option uses its parent's BoolStr.

property ParentBoolStr: boolean;

Description

If ParentBoolStr is true, the option uses its parent option list's BoolStr property.

Default value is true.


ParentFloatMask
TOption.ParentFloatMask

TOption

Determines if the option uses its parent's FloatMask.

property ParentFloatMask: boolean;

Description

If ParentFloatMask is true, the option uses its parent option list's FloatMask property.

Default value is true.


ParentNameSeparator
TOption.ParentNameSeparator

TOption

Determines if the option uses its parent's NameSeparator.

property ParentNameSeparator: boolean;

Description

If ParentNameSeparator is true, the option uses its parent option list's NameSeparator property.

Default value is true.


ParentStoreMode
TOption.ParentStoreMode

TOption

Determines if the option uses its parent's StoreMode.

property ParentStoreMode: boolean;

Description

If ParentStoreMode is true, the option uses its parent option list's StoreMode property.

Default value is true.


StoreMode
TOption.StoreMode

TOption

Specifies a storing mode for the option value.

type TStoreMode = (stmString, stmBinary, stmStrArray, stmBinArray);

property StoreMode: TStoreMode;

Description

See the appearance of option values when using different storing modes.

Storing formats in ini files

Storing formats in registry

Default value is stmStrArray.


OnUpdated
TOption.OnUpdated

TOption

Occurs when an option value has been changed.

property OnUpdated: TNotifyEvent;

Description

Sender is the TOption object that has triggered the event.


Count
TOptions.Count

TOptions

Returns the number of items in the option list.

property Count: integer;

Description

Read only and runtime only property.

Count contains the number of items in the Items array. Since Items is indexed starting with 0, the value of Count is always one greater than the index of the last member of Items.


Items
TOptions.Items

TOptions

Provides indexed access to the items in the option list.

property Items[index: integer]: TOption;

Description

Use Items to access individual items in the option list. The value of the index parameter corresponds to the Index property of TOption. It represents the position of the item in the option list.

Items is the default property of TOptions objects. The Items identifier can be omitted when accessing the Items property of a descendant of TOptions. For example, MyOptions.Items[0] is equivalent with MyOptions[0].


MemIni
TOptions.MemIni

TOptions

Provides the saved option values in a string list.

property MemIni: TStrings;

Description

Option lists use the MemIni property when Target is stMem. In this case, the option values will be stored in MemIni, using the same format as in ini files. MemIni can be assigned to any valid TStrings object or can be saved to any file or stream after saving option values. When a TString was assgined to MemIni, or MemIni was loaded from some file or stream, the options can be read from it as well.

When using MemIni to store options, AutoLoad will be useless of course. Since MemIni will surely be empty when initializing the TOptions object, calling LoadAll results absolutely nothing.

TOptions initializes MemIni in its constructor, and destroys it in the destructor. You won't need to change its value. You should use its Assign method instead. If you still want to do this (for example to link a Memo's Lines property directly to the option list), don't forget to destroy the original MemIni object, and set MemIni to nil before destroying the TOptions object.


ArraySeparator
TOptions.ArraySeparator

TOptions

Specifies an item separator string for storing option values in non-array modes.

property ArraySeparator: string;

Description

It has the same meaning as TOption.ArraySeparator. If an option's ParentArraySeparator is true, it uses this value.

Default value is '||'.


AutoLoad
TOptions.AutoLoad

TOptions

Controls the automatic loading of options.

property AutoLoad: boolean;

Description

When AutoLoad is true, the option list calls LoadAll automatically when the owner form has been initialized.

Default value is true.


BoolStr
TOptions.BoolStr

TOptions

Specifies strings for boolean values.

property BoolStr: TBoolStr;

Description

Same as TOption.BoolStr. When an option's ParentBoolStr property is true, it uses this value.

Default value is bsTrue.


FloatMask
TOptions.FloatMask

TOptions

Specifies a mask for float option values.

property FloatMask: string;

Description

Same as TOption.FloatMask. When an option's ParentFloatMask property is true, it uses this value.

Default value is '0.##'.


IniFileDir
TOptions.IniFileDir

TOptions

Specifies a target directory for the ini file.

property IniFileDir: string;

Description

If Target is not stIni, the option list does not use IniFileDir.

Default value is an empty string. This value indicates the current directory.


IniFileLoc
TOptions.IniFileLoc

TOptions

Specifies a special Windows directory as a storing place for the ini file.

type TDirLocation = (dirAppData, dirApplication, dirDevice, dirCommonAltStartUp, dirCommonDesktop, dirCommonFavorites, dirCommonFiles, dirCommonPrograms, dirCommonStartMenu, dirCommonStartUp, dirConfig, dirControls, dirCookies, dirDesktop, dirDesktopDir, dirFavorites, dirFonts, dirHistory, dirInternetCache, dirMedia, dirMyDocuments, dirNetHood, dirNone, dirOtherDevice, dirPrintHood, dirProgramFiles, dirPrograms, dirRecent, dirSendTo, dirStartMenu, dirStartUp, dirSystem, dirTemp, dirTemplates, dirWallpaper, dirWindows);

property IniFileLoc: TDirLocation;

Description

If Target is not stIni, the option list does not use IniFileLoc.

The value dirApplication means the directory, where the application's exe file has been stored.

When this property is set, IniFileDir reflects the change immediately.

Default value is dirNone.


IniFileName
TOptions.IniFileName

TOptions

Specifies the name of the ini file.

property IniFileName: string;

Description

If Target is not stIni, the option list does not use IniFileName.

Default value is an empty string. You should change it before using.


NameSeparator
TOptions.NameSeparator

TOptions

Specifies a string for option names when using array storing modes.

property NameSeparator: string;

Description

Same as TOption.NameSeparator. If an option's ParentNameSeparator property is true, it uses this value.

Default value is '_'.


RegKey
TOptions.RegKey

TOptions

Specifies the registry key, where the options should be stored.

property RegKey: string;

Description

If Target is not stReg, the option list does not use RegKey.

Default value is '\software\Company\Project'. You should change it before using.


RootKey
TOptions.RootKey

TOptions

Identifies the registry section, where the options should be stored.

property RootKey: HKEY;

Description

If Target is not stReg, the option list does not use RootKey.

Note that on an NT system the user may not write to any registry section. This may cause an error.

Default value is HKEY_CURRENT_USER.


SaveOnFree
TOptions.SaveOnFree

TOptions

Controls the automatic saving of options.

property SaveOnFree: boolean;

Description

When SaveOnFree is true, the option list calls SaveAll automatically before the owner form is destroyed.

Default value is true.


SaveOnUpdate
TOptions.SaveOnUpdate

TOptions

Controls the automatic saving of options.

property SaveOnUpdate: boolean;

Description

When SaveOnUpdate is true, all option in the option list will be saved automatically every time, when its value has been changed.

Default value is false.


StoreMode
TOptions.StoreMode

TOptions

Specifies a storing mode for the option values.

property StoreMode: TStoreMode;

Description

Same as TOption.StoreMode. When an option's ParentStoreMode property is true, it uses this value.

Default value is stmStrArray.


Target
TOptions.Target

TOptions

Specifies target object for saving and loading the options.

type TTarget = (stReg, stIni, stMem);

property Target: TTarget;

Description

Value stReg indicates that the option values will be stored in the system registry. When using value stIni, the option values will be stored in an ini file. Value stMem stores the values in the memory.

IniFileDir, IniFileLoc and IniFileName properties specify the ini file.

RegKey and RootKey properties control the using of the registry.

When using memory as target, the public MemIni property presents the saved values.

Default value is stReg.


AfterLoad
TOptions.AfterLoad

TOptions

Occurs when the option list has loaded the option values.

property AfterLoad: TNotifyEvent;

Description

AfterLoad is fired when LoadAll or LoadCat has been finished successfully.


AfterSave
TOptions.AfterSave

TOptions

Occurs when the option list has saved the option values.

property AfterSave: TNotifyEvent;

Description

AfterSave is fired when SaveAll or SaveCat has been finished successfully.


BeforeLoad
TOptions.BeforeLoad

TOptions

Occurs before the option list loads the option values.

property BeforeLoad: TNotifyEvent;

Description

This event is triggered in LoadAll and LoadCat.


BeforeSave
TOptions.BeforeSave

TOptions

Occurs before the option list saves the option values.

property BeforeSave: TNotifyEvent;

Description

This event is triggered in SaveAll and SaveCat.


OnLoad
TOptions.OnLoad

TOptions

Occurs when an option value is about to load.

type TBeforeStoreEvent = procedure(Sender: TObject; Item: TOption; var Accept: boolean) of object;

property OnLoad: TBeforeStoreEvent;

Description

Sender is the TOptions object. Item is the TOption item is about to load. Setting Accept to false prevents the lodin of the option value.


OnLoaded
TOptions.OnLoaded

TOptions

Occurs when an option value has been loaded.

type TOptionEvent = procedure(Sender: TObject; Item: TOption) of object;

property OnLoaded: TOptionEvent;

Description

Sender is the TOptions object, Item is the TOption item that has been just loaded.


OnSave
TOptions.OnSave

TOptions

Occurs when an option value is about to save.

type TBeforeStoreEvent = procedure(Sender: TObject; Item: TOption; var Accept: boolean) of object;

property OnSave: TBeforeStoreEvent;

Description

Sender is the TOptions object. Item is the TOption item is about to save. Setting Accept to false prevents the saving of the option value.


OnSaved
TOptions.OnSaved

TOptions

Occurs when an option value has been saved.

type TOptionEvent = procedure(Sender: TObject; Item: TOption) of object;

property OnSaved: TOptionEvent;

Description

Sender is the TOptions object, Item is the TOption item that has been just saved.


OnUpdated
TOptions.OnUpdated

TOptions

Occurs when an option in the option list has been updated.

type TOptionEvent = procedure(Sender: TObject; Item: TOption) of object;

property OnUpdated: TOptionEvent;

Description

When any option in the list changes its value, the option list triggers this event. Sender is the option list object, Item is the updated option.


ErrorCode
EOptError.ErrorCode

EOptError

Contains the code of an error.

property ErrorCode: integer;

Description

See the table of possible error codes.