Class TCastleConfig

Unit

Declaration

type TCastleConfig = class(TXMLConfig)

Description

Store configuration in XML format. Adds various Castle Game Engine extensions to the ancestor TXMLConfig class:

  • load/save from an URL or a TStream (not just a filename),

  • load/save to the default config file location (for user preferences),

  • load/save more types (floats, vectors, colors, URLs, multiline text...),

  • PathElement and MakePathElement utility, to use powerful DOM functions when needed to process something more complex,

  • encrypt/descrypt contents, just use BlowFishKeyPhrase property (this is actually built-in in our modified TXMLConfig).

See https://castle-engine.io/tutorial_user_prefs.php for more documentation.

Hierarchy

  • TXMLConfig
  • TCastleConfig

Overview

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function GetInteger(const APath: String): Integer; overload;
Public function GetBoolean(const APath: String): Boolean; overload;
Public function GetStringNonEmpty(const APath: string): string;
Public function GetNonEmptyValue(const APath: string): string; deprecated 'use GetStringNonEmpty';
Public function GetFloat(const APath: string; const ADefaultValue: Float): Float; overload;
Public function GetFloat(const APath: string): Float; overload;
Public procedure SetFloat(const APath: string; const AValue: Float);
Public procedure SetDeleteFloat(const APath: string; const AValue, ADefaultValue: Float);
Public function GetInt64(const APath: string; const ADefaultValue: Int64): Int64; overload;
Public function GetInt64(const APath: string): Int64; overload;
Public procedure SetInt64(const APath: string; const AValue: Int64);
Public procedure SetDeleteInt64(const APath: string; const AValue, ADefaultValue: Int64);
Public function GetVector2(const APath: string; const ADefaultValue: TVector2): TVector2; overload;
Public function GetVector2(const APath: string): TVector2; overload;
Public procedure SetVector2(const APath: string; const AValue: TVector2); overload;
Public procedure SetDeleteVector2(const APath: string; const AValue, ADefaultValue: TVector2); overload;
Public function GetVector3(const APath: string; const ADefaultValue: TVector3): TVector3; overload;
Public function GetVector3(const APath: string): TVector3; overload;
Public procedure SetVector3(const APath: string; const AValue: TVector3); overload;
Public procedure SetDeleteVector3(const APath: string; const AValue, ADefaultValue: TVector3); overload;
Public function GetVector4(const APath: string; const ADefaultValue: TVector4): TVector4; overload;
Public function GetVector4(const APath: string): TVector4; overload;
Public procedure SetVector4(const APath: string; const AValue: TVector4); overload;
Public procedure SetDeleteVector4(const APath: string; const AValue, ADefaultValue: TVector4); overload;
Public function GetValue(const APath: string; const ADefaultValue: TVector2): TVector2; overload; deprecated 'use GetVector2';
Public procedure SetValue(const APath: string; const AValue: TVector2); overload; deprecated 'use SetVector2';
Public procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector2); overload; deprecated 'use SetDeleteVector2';
Public function GetValue(const APath: string; const ADefaultValue: TVector3): TVector3; overload; deprecated 'use GetVector3';
Public procedure SetValue(const APath: string; const AValue: TVector3); overload; deprecated 'use SetVector3';
Public procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector3); overload; deprecated 'use SetDeleteVector3';
Public function GetValue(const APath: string; const ADefaultValue: TVector4): TVector4; overload; deprecated 'use GetVector4';
Public procedure SetValue(const APath: string; const AValue: TVector4); overload; deprecated 'use SetVector4';
Public procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector4); overload; deprecated 'use SetDeleteVector4';
Public function GetColorRGB(const APath: string; const ADefaultColor: TCastleColorRGB): TCastleColorRGB; overload;
Public function GetColorRGB(const APath: string): TCastleColorRGB; overload;
Public procedure SetColorRGB(const APath: string; const AColor: TCastleColorRGB); overload;
Public procedure SetDeleteColorRGB(const APath: string; const AColor, ADefaultColor: TCastleColorRGB); overload;
Public function GetColor(const APath: string; const ADefaultColor: TCastleColor): TCastleColor; overload;
Public function GetColor(const APath: string): TCastleColor; overload;
Public procedure SetColor(const APath: string; const AColor: TCastleColor); overload;
Public procedure SetDeleteColor(const APath: string; const AColor, ADefaultColor: TCastleColor); overload;
Public function PathElement(const APath: string; const RaiseExceptionWhenMissing: boolean = false): TDOMElement;
Public function MakePathElement(const APath: string): TDOMElement;
Public function PathChildren(const APath: string; const ChildName: string): TDOMNodeList; deprecated 'use PathChildrenIterator';
Public function PathChildrenIterator(const APath: string; const ChildName: string): TXMLElementIterator;
Public function GetURL(const APath: string; const EmptyIfNoAttribute: boolean = false): string;
Public function GetMultilineText(const APath: string; const DefaultValue: string): string; overload;
Public function GetMultilineText(const APath: string): string; overload;
Public procedure NotModified;
Public procedure MarkModified;
Public procedure AddLoadListener(const Listener: TCastleConfigEvent);
Public procedure AddSaveListener(const Listener: TCastleConfigEvent);
Public procedure RemoveLoadListener(const Listener: TCastleConfigEvent);
Public procedure RemoveSaveListener(const Listener: TCastleConfigEvent);
Public procedure Load; overload;
Public procedure Load(const AURL: string); overload;
Public procedure Load(const Stream: TStream; const PretendURL: string); overload;
Public procedure LoadFromString(const Data: string; const PretendURL: string);
Public procedure Save; overload;
Public procedure Save(const Stream: TStream); overload;
Public function SaveToString: string;

Properties

Public property Loaded: boolean read FLoaded;

Description

Methods

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public function GetInteger(const APath: String): Integer; overload;

Get a required integer attribute, raise exception if missing or invalid.

Exceptions raised
EMissingAttribute
If the attribute is missing or empty.
EConvertError
If the attribute exists but has invalid format.
Public function GetBoolean(const APath: String): Boolean; overload;

Get a required boolean attribute, raise exception if missing or invalid.

Exceptions raised
EMissingAttribute
If the attribute is missing or empty.
EConvertError
If the attribute exists but has invalid format.
Public function GetStringNonEmpty(const APath: string): string;

Get a required, non-empty string value. Value must exist and cannot be empty in XML file.

Exceptions raised
EMissingAttribute
If value doesn't exist or is empty in XML file.
Public function GetNonEmptyValue(const APath: string): string; deprecated 'use GetStringNonEmpty';

Warning: this symbol is deprecated: use GetStringNonEmpty

 
Public function GetFloat(const APath: string; const ADefaultValue: Float): Float; overload;

Float values reading/writing to config file.

Note: for powerful reading of float expressions, consider using GetFloatExpression instead of GetFloat. It can read expressions like "3.0 * 2.0" or "sin(2.0)". Use CastleScriptXML unit to introduce necessary class helper for this, see TCastleConfigScriptHelper.GetFloatExpression.

Exceptions raised
EMissingAttribute
Raised by GetFloat(string) (overloaded version without the ADefaultValue parameter) if the attribute is missing.
Public function GetFloat(const APath: string): Float; overload;
 
Public procedure SetFloat(const APath: string; const AValue: Float);
 
Public procedure SetDeleteFloat(const APath: string; const AValue, ADefaultValue: Float);
 
Public function GetInt64(const APath: string; const ADefaultValue: Int64): Int64; overload;

Int64 values reading/writing to config file.

Exceptions raised
EMissingAttribute
Raised by GetFloat(string) (overloaded version without the ADefaultValue parameter) if the attribute is missing.
Public function GetInt64(const APath: string): Int64; overload;
 
Public procedure SetInt64(const APath: string; const AValue: Int64);
 
Public procedure SetDeleteInt64(const APath: string; const AValue, ADefaultValue: Int64);
 
Public function GetVector2(const APath: string; const ADefaultValue: TVector2): TVector2; overload;

2D, 3D, 4D vectors reading/writing to config file.

They should be expressed in XML like

<myVector x="1" y="2" z="3" w="4" />

You can read such vector by

GetVector('example/path/to/myVector', Vector4(0, 0, 0, 0));

Public function GetVector2(const APath: string): TVector2; overload;
 
Public procedure SetVector2(const APath: string; const AValue: TVector2); overload;
 
Public procedure SetDeleteVector2(const APath: string; const AValue, ADefaultValue: TVector2); overload;
 
Public function GetVector3(const APath: string; const ADefaultValue: TVector3): TVector3; overload;
 
Public function GetVector3(const APath: string): TVector3; overload;
 
Public procedure SetVector3(const APath: string; const AValue: TVector3); overload;
 
Public procedure SetDeleteVector3(const APath: string; const AValue, ADefaultValue: TVector3); overload;
 
Public function GetVector4(const APath: string; const ADefaultValue: TVector4): TVector4; overload;
 
Public function GetVector4(const APath: string): TVector4; overload;
 
Public procedure SetVector4(const APath: string; const AValue: TVector4); overload;
 
Public procedure SetDeleteVector4(const APath: string; const AValue, ADefaultValue: TVector4); overload;
 
Public function GetValue(const APath: string; const ADefaultValue: TVector2): TVector2; overload; deprecated 'use GetVector2';

Warning: this symbol is deprecated: use GetVector2

 
Public procedure SetValue(const APath: string; const AValue: TVector2); overload; deprecated 'use SetVector2';

Warning: this symbol is deprecated: use SetVector2

 
Public procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector2); overload; deprecated 'use SetDeleteVector2';

Warning: this symbol is deprecated: use SetDeleteVector2

 
Public function GetValue(const APath: string; const ADefaultValue: TVector3): TVector3; overload; deprecated 'use GetVector3';

Warning: this symbol is deprecated: use GetVector3

 
Public procedure SetValue(const APath: string; const AValue: TVector3); overload; deprecated 'use SetVector3';

Warning: this symbol is deprecated: use SetVector3

 
Public procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector3); overload; deprecated 'use SetDeleteVector3';

Warning: this symbol is deprecated: use SetDeleteVector3

 
Public function GetValue(const APath: string; const ADefaultValue: TVector4): TVector4; overload; deprecated 'use GetVector4';

Warning: this symbol is deprecated: use GetVector4

 
Public procedure SetValue(const APath: string; const AValue: TVector4); overload; deprecated 'use SetVector4';

Warning: this symbol is deprecated: use SetVector4

 
Public procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector4); overload; deprecated 'use SetDeleteVector4';

Warning: this symbol is deprecated: use SetDeleteVector4

 
Public function GetColorRGB(const APath: string; const ADefaultColor: TCastleColorRGB): TCastleColorRGB; overload;

Colors reading/writing to config file.

This is very similar to 3D / 4D vector reading/writing to config file, however

  1. attribute names are better for colors (red, green, blue, alpha instead of x, y, z, w),

  2. we allow alternative color specification as hex.

  3. and we limit component values to 0..1 range.

They should be expressed in XML like

<myColor red="1" green="0.5" blue="0.25" alpha="1" />
<myColorRGB red="1" green="0.5" blue="0.25" />

or as hex colors (see HexToColor) like

<myColor hex="ff804011" />
<myColorRGB hex="ff8040" />

You can read such colors by

Color := GetColor('example/path/to/myColor', Black);
ColorRGB := GetColorRGB('example/path/to/myColorRGB', BlackRGB);

Public function GetColorRGB(const APath: string): TCastleColorRGB; overload;
 
Public procedure SetColorRGB(const APath: string; const AColor: TCastleColorRGB); overload;
 
Public procedure SetDeleteColorRGB(const APath: string; const AColor, ADefaultColor: TCastleColorRGB); overload;
 
Public function GetColor(const APath: string; const ADefaultColor: TCastleColor): TCastleColor; overload;
 
Public function GetColor(const APath: string): TCastleColor; overload;
 
Public procedure SetColor(const APath: string; const AColor: TCastleColor); overload;
 
Public procedure SetDeleteColor(const APath: string; const AColor, ADefaultColor: TCastleColor); overload;
 
Public function PathElement(const APath: string; const RaiseExceptionWhenMissing: boolean = false): TDOMElement;

For a given path, return corresponding DOM element of XML tree. This is useful if you want to mix XMLConfig style operations on the file and then use some real DOM functions to more directly operate/read on XML document.

Note that for paths that you pass to various SetValue / SetColor / SetFloat / SetVector versions, the last path component is the attribute name. You do not pass this here. Path passed here should end with the name of final element.

Path passed here may but doesn't have to be terminated by a final slash. In fact, for now the path is just splitted using slash character as a separator, so a path like /some////path/ is equivalent to a path like (some/path). But don't depend on this behavior.

If there is no such element: when RaiseExceptionWhenMissing=True, raises exception. when RaiseExceptionWhenMissing=False, returns Nil.

Remember that XMLConfig idea of XML document is limited. That's intentional (XMLConfig is supposed to offer only a simple limited XML access), and this means that some XML trees may confuse XMLConfig. For example, if there are two elements with the same TagName as a children of the same element: XMLConfig will (probably ?) just always ignore the second one. Which means that if you use this method to change some XML content, you should be careful when accessing this content from regular XMLConfig GetValue / SetValue methods.

Note that if you modify the DOM contents this way, you must manually call MarkModified afterwards, to make sure it will get saved later.

Public function MakePathElement(const APath: string): TDOMElement;

Similar to PathElement, but creates the necessary elements along the way as needed.

Public function PathChildren(const APath: string; const ChildName: string): TDOMNodeList; deprecated 'use PathChildrenIterator';

Warning: this symbol is deprecated: use PathChildrenIterator

For a given path, return corresponding children elements of a given DOM element of XML tree. For example, you have an XML like this:

<?xml version="1.0" encoding="UTF-8"?>
<CONFIG>
  <game_configuration>
    <locations>
      <location name="location_1st">...</location>
      <location name="location_2nd">...</location>
    </locations>
  </game_configuration>
</CONFIG>

You could use PathElement('game_configuration/locations') to get the <locations> DOM element. Or you could use this method PathChildren('game_configuration/locations', 'location') to get a list of <location> elements.

Raises exception if element indicated by APath does not exist. (But it is OK if it is empty.) Never returns Nil.

Public function PathChildrenIterator(const APath: string; const ChildName: string): TXMLElementIterator;

For a given path, return iterator for elements of a given name.

For example, assume you have an XML like this:

<?xml version="1.0" encoding="UTF-8"?>
<CONFIG>
  <game_configuration>
    <locations>
      <location name="location_1st">...</location>
      <location name="location_2nd">...</location>
    </locations>
  </game_configuration>
</CONFIG>

You can process it like this:

var
  I: TXMLElementIterator;
begin
  I := PathChildrenIterator('game_configuration/locations', 'location');
  try
    while I.GetNext do
    begin
      // ... here goes your code to process I.Current ...
    end;
  finally FreeAndNil(I) end;
end;

Raises exception if element indicated by APath does not exist. (But it is OK if it is empty.) Never returns Nil.

Public function GetURL(const APath: string; const EmptyIfNoAttribute: boolean = false): string;

Read an URL from an XML attribute. The attribute in an XML file may be an absolute or relative URL, (we will look at own TXMLConfig.FileName directory to resolve relative URLs). The returned URL is always an absolute URL.

If EmptyIfNoAttribute, then this will just set URL to '' if appropriate XML attribute not found. Otherwise (when EmptyIfNoAttribute = False, this is default), error will be raised.

Exceptions raised
EMissingAttribute
If EmptyIfNoAttribute = False and no such attribute.
Public function GetMultilineText(const APath: string; const DefaultValue: string): string; overload;

Read string from a text content of given element. The text may be multiline, line endings are guaranteed to be converted to current OS newlines.

Public function GetMultilineText(const APath: string): string; overload;

Read required, non-empty string from a text content of given element. The text may be multiline, line endings are guaranteed to be converted to current OS newlines.

Public procedure NotModified;
 
Public procedure MarkModified;
 
Public procedure AddLoadListener(const Listener: TCastleConfigEvent);

Listeners, automatically called at the Load or Save calls.

If the config file is already loaded when you call AddLoadListener, then the Listener is called immediately. This is useful to make sure that Listener is always called, regardless of the order. (Regardless if you call Config.Load or Config.AddLoadListener first.)

Public procedure AddSaveListener(const Listener: TCastleConfigEvent);
 
Public procedure RemoveLoadListener(const Listener: TCastleConfigEvent);
 
Public procedure RemoveSaveListener(const Listener: TCastleConfigEvent);
 
Public procedure Load; overload;

Load the current persistent data (user preferences, savegames etc.).

All these methods call the listeners (from AddLoadListener). All these methods update the Loaded property and the URL property. All these methods are secured to never raise exception in case of a currupted config file – in this case, they silently load an empty config (but keep the new URL, so that following Save call with overwrite the config location with a good save.)

Never call the ancestor load / save methods, like TXMLConfig.LoadFromStream and TXMLConfig.SaveToStream, to be on the safe side. Use the methods below to load / save user config.

  • The overloaded Load parameter-less version chooses a default filename for storing application user preferences.

    It uses ApplicationName to pick a filename that is unique to your application. Usually you want to assign ApplicationProperties.ApplicationName, unless you're fine with the default name derived from ParamStr(0).

    It uses ApplicationConfig to determine location of this file.

  • The overloaded Load version with URL sets TXMLConfig.URL, loading the file from given URL. As always, URL may be just a simple filename, to just load a file from the local filesystem. It can also be a full-blown URL, with a 'file://' protocol, or 'http://', or other supported protocols, see https://castle-engine.io/tutorial_network.php

  • The overloaded Load version with TStream loads from a stream. URL is set to PretendURL (just pass empty string if you don't need to be able to save it back).

Public procedure Load(const AURL: string); overload;
 
Public procedure Load(const Stream: TStream; const PretendURL: string); overload;
 
Public procedure LoadFromString(const Data: string; const PretendURL: string);
 
Public procedure Save; overload;

Save the user persistent configuration. Calls all the listeners (registered by AddSaveListener).

  • The overloaded parameter-less version flushes the changes to disk, thus saving them back to the file from which they were read (in TXMLConfig.URL property).

  • The overloaded version with TStream parameter saves to a stream. If does not use inherited Flush method, instead it always unconditionally dumps contents to stream.

Public procedure Save(const Stream: TStream); overload;
 
Public function SaveToString: string;
 

Properties

Public property Loaded: boolean read FLoaded;
 

Generated by PasDoc 0.15.0.