Castle Game Engine: CastleXMLConfig: Class TCastleConfig

# Class TCastleConfig
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleXMLConfig ## Declaration `type TCastleConfig = class(TXMLConfig)` ## Description Store configuration in XML format. This is a descendant of TXMLConfig that adds various small extensions: float types (GetFloat, SetFloat, SetDeleteFloat), vector types, key (TKey) types, PathElement utility. ## Hierarchy TXMLConfig TCastleConfig ## Overview ### Methods
| `constructor Create(AOwner: TComponent); override;`
| `destructor Destroy; override;`
| `function GetFloat(const APath: string; const ADefaultValue: Float): Float;`
| `procedure SetFloat(const APath: string; const AValue: Float);`
| `procedure SetDeleteFloat(const APath: string; const AValue, ADefaultValue: Float);`
| `function GetValue(const APath: string; const ADefaultValue: TVector2Single): TVector2Single; overload;`
| `procedure SetValue(const APath: string; const AValue: TVector2Single); overload;`
| `procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector2Single); overload;`
| `function GetValue(const APath: string; const ADefaultValue: TVector3Single): TVector3Single; overload;`
| `procedure SetValue(const APath: string; const AValue: TVector3Single); overload;`
| `procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector3Single); overload;`
| `function GetValue(const APath: string; const ADefaultValue: TVector4Single): TVector4Single; overload;`
| `procedure SetValue(const APath: string; const AValue: TVector4Single); overload;`
| `procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector4Single); overload;`
| `function GetValue(const APath: string; const ADefaultValue: TKey): TKey; overload;`
| `procedure SetValue(const APath: string; const AValue: TKey); overload;`
| `procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TKey); overload;`
| `function GetColor(const APath: string; const ADefaultColor: TCastleColorRGB): TCastleColorRGB; overload;`
| `procedure SetColor(const APath: string; const AColor: TCastleColorRGB); overload;`
| `procedure SetDeleteColor(const APath: string; const AColor, ADefaultColor: TCastleColorRGB); overload;`
| `function GetColor(const APath: string; const ADefaultColor: TCastleColor): TCastleColor; overload;`
| `procedure SetColor(const APath: string; const AColor: TCastleColor); overload;`
| `procedure SetDeleteColor(const APath: string; const AColor, ADefaultColor: TCastleColor); overload;`
| `function PathElement(const APath: string; const RaiseExceptionWhenMissing: boolean = false): TDOMElement;`
| `function PathChildren(const APath: string; const ChildName: string): TDOMNodeList;`
| `function GetURL(const APath: string; const EmptyIfNoAttribute: boolean = false): string;`
| `function GetMultilineText(const APath: string; const DefaultValue: string): string;`
| `function GetNonEmptyValue(const APath: string): string;`
| `procedure NotModified;`
| `procedure Load(const AURL: string);`
| `procedure Load;`
| `procedure Load(const Stream: TStream);`
| `procedure Save;`
| `procedure Save(const Stream: TStream);`
### Properties
| `property OnLoad: TCastleConfigEventList read FOnLoad;`
| `property OnSave: TCastleConfigEventList read FOnSave;`
## Description ### Methods
| `constructor Create(AOwner: TComponent); override;`
| `destructor Destroy; override;`
| `function GetFloat(const APath: string; const ADefaultValue: Float): Float;`
| `procedure SetFloat(const APath: string; const AValue: Float);`
| `procedure SetDeleteFloat(const APath: string; const AValue, ADefaultValue: Float);`
| `function GetValue(const APath: string; const ADefaultValue: TVector2Single): TVector2Single; 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
     GetValue('example/path/to/myVector', Vector4Single(0, 0, 0, 0));
| `procedure SetValue(const APath: string; const AValue: TVector2Single); overload;`
| `procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector2Single); overload;`
| `function GetValue(const APath: string; const ADefaultValue: TVector3Single): TVector3Single; overload;`
| `procedure SetValue(const APath: string; const AValue: TVector3Single); overload;`
| `procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector3Single); overload;`
| `function GetValue(const APath: string; const ADefaultValue: TVector4Single): TVector4Single; overload;`
| `procedure SetValue(const APath: string; const AValue: TVector4Single); overload;`
| `procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TVector4Single); overload;`
| `function GetValue(const APath: string; const ADefaultValue: TKey): TKey; overload;`
Reading/writing key values to config file. Key names are expected to follow StrToKey and KeyToStr functions in CastleKeysMouse.
| `procedure SetValue(const APath: string; const AValue: TKey); overload;`
| `procedure SetDeleteValue(const APath: string; const AValue, ADefaultValue: TKey); overload;`
| `function GetColor(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 attribute names are better for colors (red, green, blue, alpha instead of x, y, z, w), we allow alternative color specification as hex. 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 := GetColor('example/path/to/myColorRGB', BlackRGB);
| `procedure SetColor(const APath: string; const AColor: TCastleColorRGB); overload;`
| `procedure SetDeleteColor(const APath: string; const AColor, ADefaultColor: TCastleColorRGB); overload;`
| `function GetColor(const APath: string; const ADefaultColor: TCastleColor): TCastleColor; overload;`
| `procedure SetColor(const APath: string; const AColor: TCastleColor); overload;`
| `procedure SetDeleteColor(const APath: string; const AColor, ADefaultColor: TCastleColor); overload;`
| `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 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 Get/SetValue methods.
| `function PathChildren(const APath: string; const ChildName: string): TDOMNodeList;`
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`.
| `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.
| `function GetMultilineText(const APath: string; const DefaultValue: string): string;`
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.
| `function GetNonEmptyValue(const APath: string): string;`
Get a value, as a string. Value must exist and cannot be empty in XML file. ###### Exceptions raised EMissingAttribute If value doesn't exist or is empty in XML file.
| `procedure NotModified;`
| `procedure Load(const AURL: string);`
Load the current configuration of the engine components. Sets `TXMLConfig.URL`, loading the appropriate file to our properties, and then calls the OnLoad callbacks to allow all engine components read their settings. Accepts URL as parameter, converting it to a local filename under the hood. The overloaded parameter-less version chooses a suitable filename for storing per-program user preferences. It uses ApplicationName to pick a filename that is unique to your application (usually you want to assign OnGetApplicationName callback to set your name, unless you're fine with default determination that looks at stuff like ParamStr(0)). See FPC OnGetApplicationName docs. It uses ApplicationConfig to determine location of this file. The overloaded version with TStream parameter loads from a stream. URL is set to empty.
| `procedure Load;`
| `procedure Load(const Stream: TStream);`
| `procedure Save;`
Save the configuration of all engine components. Calls the OnSave callbacks to allow all engine components to store their settings in our properties, and then flushes them to disk (using `TXMLConfig.URL` property) by inherited Flush method. 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.
| `procedure Save(const Stream: TStream);`
### Properties
| `property OnLoad: TCastleConfigEventList read FOnLoad;`
Called at Load.
| `property OnSave: TCastleConfigEventList read FOnSave;`
Called at Save.
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:13