Class TDOMElementHelper

Description
Hierarchy
Methods

Unit

CastleXmlUtils

Declaration

type TDOMElementHelper = class helper(TObject) for TDOMElement

Description

This item has no description.

Source: files/castlexmlutils.pas (line 69).

Hierarchy

  • TObject
  • TDOMElementHelper

Overview

Methods

Public function AttributeString(const AttrName: String; var Value: String): boolean; overload;
Public function AttributeUrl(const AttrName: String; const BaseUrl: String; var Url: String): boolean; overload;
Public function AttributeCardinal(const AttrName: String; var Value: Cardinal): boolean; overload;
Public function AttributeInteger(const AttrName: String; var Value: Integer): boolean; overload;
Public function AttributeInt64(const AttrName: String; var Value: Int64): boolean; overload;
Public function AttributeQWord(const AttrName: String; var Value: QWord): boolean; overload;
Public function AttributeSingle(const AttrName: String; var Value: Single): boolean; overload;
Public function AttributeFloat(const AttrName: String; var Value: Float): boolean; overload;
Public function AttributeBoolean(const AttrName: String; var Value: boolean): boolean; overload;
Public function AttributeColor(const AttrName: String; var Value: TCastleColor): Boolean; overload;
Public function AttributeColorRGB(const AttrName: String; var Value: TCastleColorRGB): Boolean; overload;
Public function AttributeVector2(const AttrName: String; var Value: TVector2): boolean; overload;
Public function AttributeVector3(const AttrName: String; var Value: TVector3): boolean; overload;
Public function AttributeVector4(const AttrName: String; var Value: TVector4): boolean; overload;
Public function AttributeString(const AttrName: String): String; overload;
Public function AttributeUrl(const AttrName: String; const BaseUrl: String): String; overload;
Public function AttributeCardinal(const AttrName: String): Cardinal; overload;
Public function AttributeInteger(const AttrName: String): Integer; overload;
Public function AttributeInt64(const AttrName: String): Int64; overload;
Public function AttributeQWord(const AttrName: String): QWord; overload;
Public function AttributeSingle(const AttrName: String): Single; overload;
Public function AttributeFloat(const AttrName: String): Float; overload;
Public function AttributeBoolean(const AttrName: String): boolean; overload;
Public function AttributeColor(const AttrName: String): TCastleColor; overload;
Public function AttributeColorRGB(const AttrName: String): TCastleColorRGB; overload;
Public function AttributeVector2(const AttrName: String): TVector2; overload;
Public function AttributeVector3(const AttrName: String): TVector3; overload;
Public function AttributeVector4(const AttrName: String): TVector4; overload;
Public function AttributeStringDef(const AttrName: String; const DefaultValue: String): String;
Public function AttributeCardinalDef(const AttrName: String; const DefaultValue: Cardinal): Cardinal;
Public function AttributeIntegerDef(const AttrName: String; const DefaultValue: Integer): Integer;
Public function AttributeInt64Def(const AttrName: String; const DefaultValue: Int64): Int64;
Public function AttributeQWordDef(const AttrName: String; const DefaultValue: QWord): QWord;
Public function AttributeSingleDef(const AttrName: String; const DefaultValue: Single): Single;
Public function AttributeFloatDef(const AttrName: String; const DefaultValue: Float): Float;
Public function AttributeBooleanDef(const AttrName: String; const DefaultValue: boolean): boolean;
Public function AttributeColorDef(const AttrName: String; const DefaultValue: TCastleColor): TCastleColor;
Public function AttributeColorRGBDef(const AttrName: String; const DefaultValue: TCastleColorRGB): TCastleColorRGB;
Public function AttributeVector2Def(const AttrName: String; const DefaultValue: TVector2): TVector2;
Public function AttributeVector3Def(const AttrName: String; const DefaultValue: TVector3): TVector3;
Public function AttributeVector4Def(const AttrName: String; const DefaultValue: TVector4): TVector4;
Public procedure AttributeSet(const AttrName: String; const Value: String); overload;
Public procedure AttributeSet(const AttrName: String; const Value: boolean); overload;
Public procedure AttributeSet(const AttrName: String; const Value: Integer); overload;
Public procedure AttributeSet(const AttrName: String; const Value: Int64); overload;
Public procedure AttributeSet(const AttrName: String; const Value: QWord); overload;
Public procedure AttributeSet(const AttrName: String; const Value: Cardinal); overload;
Public procedure AttributeSet(const AttrName: String; const Value: Single); overload;
Public procedure AttributeSet(const AttrName: String; const Value: TVector2); overload;
Public procedure AttributeSet(const AttrName: String; const Value: TVector3); overload;
Public procedure AttributeSet(const AttrName: String; const Value: TVector4); overload;
Public procedure AttributeColorSet(const AttrName: String; const Value: TCastleColor); overload;
Public procedure AttributeColorSet(const AttrName: String; const Value: TCastleColorRGB); overload;
Public function Child(const ChildName: String; const Required: boolean = true; const WarnOnMultiple: boolean = true): TDOMElement;
Public function ChildElement(const ChildName: String; const Required: boolean = true; const WarnOnMultiple: boolean = true): TDOMElement;
Public function CreateChild(const ChildName: String): TDOMElement;
Public function ChildrenIterator: TXMLElementIterator; overload;
Public function ChildrenIterator(const ChildName: String): TXMLElementIterator; overload;
Public function TextData: String;
Public function TagName8: String;

Description

Methods

Public function AttributeString(const AttrName: String; var Value: String): boolean; overload;

Read from Element attribute value and returns True, or (if there is no such attribute) returns False and does not modify Value. Value is a "var", not "out" param, because in the latter case it's guaranteed that the old Value will not be cleared.

Note that the returned Value may be empty, even when this returns True, if the value is explicitly set to empty in XML (by xxx="" in XML).

Source: files/castlexmlutils.pas (line 84).

Public function AttributeUrl(const AttrName: String; const BaseUrl: String; var Url: String): boolean; overload;

Read from Element attribute value as URL and returns True, or (if there is no such attribute) returns False and does not modify Value.

Returned URL is always absolute. The value in file may be a relative URL, it is resolved with respect to BaseUrl, that must be absolute.

Source: files/castlexmlutils.pas (line 93).

Public function AttributeCardinal(const AttrName: String; var Value: Cardinal): boolean; overload;

Read from Element attribute value as Cardinal and returns True, or (if there is no such attribute) returns False and does not modify Value.

Source: files/castlexmlutils.pas (line 98).

Public function AttributeInteger(const AttrName: String; var Value: Integer): boolean; overload;

Read from Element attribute value as Integer and returns True, or (if there is no such attribute) returns False and does not modify Value.

Source: files/castlexmlutils.pas (line 103).

Public function AttributeInt64(const AttrName: String; var Value: Int64): boolean; overload;

Read from Element attribute value as Int64 and returns True, or (if there is no such attribute) returns False and does not modify Value.

Source: files/castlexmlutils.pas (line 108).

Public function AttributeQWord(const AttrName: String; var Value: QWord): boolean; overload;

Read from Element attribute value as QWord and returns True, or (if there is no such attribute) returns False and does not modify Value.

Source: files/castlexmlutils.pas (line 113).

Public function AttributeSingle(const AttrName: String; var Value: Single): boolean; overload;

Read from Element attribute value as Single and returns True, or (if there is no such attribute) returns False and does not modify Value.

Source: files/castlexmlutils.pas (line 118).

Public function AttributeFloat(const AttrName: String; var Value: Float): boolean; overload;

Read from Element attribute value as Float and returns True, or (if there is no such attribute) returns False and does not modify Value.

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

Source: files/castlexmlutils.pas (line 129).

Public function AttributeBoolean(const AttrName: String; var Value: boolean): boolean; overload;

Read from Element attribute value as Boolean and returns True, or (if there is no such attribute) returns False and does not modify Value.

A boolean value is interpreted just like FPC's TXMLConfig objects: true is designated by word true, false by word false, case is ignored. If attribute exists but it's value is not true or false, then returns False and doesn't modify Value paramater. So behaves just like the attribute didn't exist.

Source: files/castlexmlutils.pas (line 141).

Public function AttributeColor(const AttrName: String; var Value: TCastleColor): Boolean; overload;

Read from Element attribute value as color and returns True, or (if there is no such attribute) returns False and does not modify Value.

This can read a color value in any of these formats:

In effect, you can write TCastleColor values to XML using AttributeSet or AttributeColorSet, they both can be read back using this method.

Source: files/castlexmlutils.pas (line 160).

Public function AttributeColorRGB(const AttrName: String; var Value: TCastleColorRGB): Boolean; overload;

Read from Element attribute value as RGB color and returns True, or (if there is no such attribute) returns False and does not modify Value.

This can read a color value in any of these formats:

In effect, you can write TCastleColorRGB values to XML using AttributeSet or AttributeColorSet, they both can be read back using this method.

Source: files/castlexmlutils.pas (line 179).

Public function AttributeVector2(const AttrName: String; var Value: TVector2): boolean; overload;

Read from Element attribute as a 2D vector (2 floats), and returns True, or (if there is no such attribute) returns False and does not modify Value.

Exceptions raised
EConvertError
If the attribute exists in XML, but has invalid format.

Source: files/castlexmlutils.pas (line 186).

Public function AttributeVector3(const AttrName: String; var Value: TVector3): boolean; overload;

Read from Element attribute as a 3D vector (3 floats), and returns True, or (if there is no such attribute) returns False and does not modify Value.

Exceptions raised
EConvertError
If the attribute exists in XML, but has invalid format.

Source: files/castlexmlutils.pas (line 193).

Public function AttributeVector4(const AttrName: String; var Value: TVector4): boolean; overload;

Read from Element attribute as a 4D vector(4 floats, e.g. rotation), and returns True, or (if there is no such attribute) returns False and does not modify Value.

Exceptions raised
EConvertError
If the attribute exists in XML, but has invalid format.

Source: files/castlexmlutils.pas (line 200).

Public function AttributeString(const AttrName: String): String; overload;

Retrieves from Element given attribute as a string, raises EDOMAttributeMissing if missing.

Note that the attribute is required, but it's value may still be empty if it's explicitly set to empty in XML (by xxx="" in XML). This is different than TCastleConfig.GetStringNonEmpty method, that serves a similar purpose for TCastleConfig, but it requires non-empty value exists. Here, we only require that the value exists, but it may still be empty.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 216).

Public function AttributeUrl(const AttrName: String; const BaseUrl: String): String; overload;

Retrieves from Element given attribute as an absolute URL, raises EDOMAttributeMissing if missing. Returned URL is always absolute. The value in file may be a relative URL, it is resolved with respect to BaseUrl, that must be absolute.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 223).

Public function AttributeCardinal(const AttrName: String): Cardinal; overload;

Retrieves from Element given attribute as a Cardinal, raises EDOMAttributeMissing if missing.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 228).

Public function AttributeInteger(const AttrName: String): Integer; overload;

Retrieves from Element given attribute as an Integer, raises EDOMAttributeMissing if missing.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 233).

Public function AttributeInt64(const AttrName: String): Int64; overload;

Retrieves from Element given attribute as an Int64, raises EDOMAttributeMissing if missing.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 238).

Public function AttributeQWord(const AttrName: String): QWord; overload;

Retrieves from Element given attribute as an QWord, raises EDOMAttributeMissing if missing.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 243).

Public function AttributeSingle(const AttrName: String): Single; overload;

Retrieves from Element given attribute as a Single, raises EDOMAttributeMissing if missing.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 248).

Public function AttributeFloat(const AttrName: String): Float; overload;

Retrieves from Element given attribute as a Float, raises EDOMAttributeMissing if missing.

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

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 260).

Public function AttributeBoolean(const AttrName: String): boolean; overload;

Retrieves from Element given attribute as a boolean, raises EDOMAttributeMissing if missing or has invalid value. A boolean value is interpreted just like FPC's TXMLConfig objects: true is designated by word true, false by word false, case is ignored.

If attribute exists but it's value is not true or false, then raises EDOMAttributeMissing. So behaves just like the attribute didn't exist.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 273).

Public function AttributeColor(const AttrName: String): TCastleColor; overload;

Retrieves from Element given attribute as a color, raises EDOMAttributeMissing if missing or has invalid format.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 278).

Public function AttributeColorRGB(const AttrName: String): TCastleColorRGB; overload;

Retrieves from Element given attribute as an RGB color, raises EDOMAttributeMissing if missing or has invalid format.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 283).

Public function AttributeVector2(const AttrName: String): TVector2; overload;

Retrieves from Element given attribute as a 2D vector (2 floats), raises EDOMAttributeMissing if missing or has invalid format.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 288).

Public function AttributeVector3(const AttrName: String): TVector3; overload;

Retrieves from Element given attribute as a 3D vector (3 floats), raises EDOMAttributeMissing if missing or has invalid format.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 293).

Public function AttributeVector4(const AttrName: String): TVector4; overload;

Retrieves from Element given attribute as a 4D vector (4 floats, e.g. rotation), raises EDOMAttributeMissing if missing or has invalid format.

Exceptions raised
EDOMAttributeMissing

Source: files/castlexmlutils.pas (line 298).

Public function AttributeStringDef(const AttrName: String; const DefaultValue: String): String;

Retrieves from Element given attribute as a string, or a default value if the attribute was not explicitly given.

Source: files/castlexmlutils.pas (line 305).

Public function AttributeCardinalDef(const AttrName: String; const DefaultValue: Cardinal): Cardinal;

Retrieves from Element given attribute as a Cardinal, or a default value.

Source: files/castlexmlutils.pas (line 308).

Public function AttributeIntegerDef(const AttrName: String; const DefaultValue: Integer): Integer;

Retrieves from Element given attribute as an Integer, or a default value.

Source: files/castlexmlutils.pas (line 311).

Public function AttributeInt64Def(const AttrName: String; const DefaultValue: Int64): Int64;

Retrieves from Element given attribute as an Int64, or a default value.

Source: files/castlexmlutils.pas (line 314).

Public function AttributeQWordDef(const AttrName: String; const DefaultValue: QWord): QWord;

Retrieves from Element given attribute as an QWord, or a default value.

Source: files/castlexmlutils.pas (line 317).

Public function AttributeSingleDef(const AttrName: String; const DefaultValue: Single): Single;

Retrieves from Element given attribute as a Single, or a default value.

Source: files/castlexmlutils.pas (line 320).

Public function AttributeFloatDef(const AttrName: String; const DefaultValue: Float): Float;

Retrieves from Element given attribute as a Float, or a default value.

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

Source: files/castlexmlutils.pas (line 329).

Public function AttributeBooleanDef(const AttrName: String; const DefaultValue: boolean): boolean;

Retrieves from Element given attribute as a boolean, returns a default value if missing or has invalid value.

Source: files/castlexmlutils.pas (line 333).

Public function AttributeColorDef(const AttrName: String; const DefaultValue: TCastleColor): TCastleColor;

Retrieves from Element given attribute as a color, or a default value.

Source: files/castlexmlutils.pas (line 336).

Public function AttributeColorRGBDef(const AttrName: String; const DefaultValue: TCastleColorRGB): TCastleColorRGB;

Retrieves from Element given attribute as an RGB color, or a default value.

Source: files/castlexmlutils.pas (line 339).

Public function AttributeVector2Def(const AttrName: String; const DefaultValue: TVector2): TVector2;

Retrieves from Element given attribute as a 2D vector (2 floats), or a default value.

Exceptions raised
EConvertError
If the value exists in XML, but has invalid format.

Source: files/castlexmlutils.pas (line 343).

Public function AttributeVector3Def(const AttrName: String; const DefaultValue: TVector3): TVector3;

Retrieves from Element given attribute as a 3D vector (3 floats), or a default value.

Exceptions raised
EConvertError
If the value exists in XML, but has invalid format.

Source: files/castlexmlutils.pas (line 347).

Public function AttributeVector4Def(const AttrName: String; const DefaultValue: TVector4): TVector4;

Retrieves from Element given attribute as a 4D vector (4 floats), or a default value.

Exceptions raised
EConvertError
If the value exists in XML, but has invalid format.

Source: files/castlexmlutils.pas (line 351).

Public procedure AttributeSet(const AttrName: String; const Value: String); overload;

Set the attribute as string. Equivalent to standard SetAttribute in DOM unit, but provided here for consistency with other AttributeSet overloads.

Source: files/castlexmlutils.pas (line 357).

Public procedure AttributeSet(const AttrName: String; const Value: boolean); overload;

Set the attribute as boolean, such that it's readable back by AttributeBoolean and AttributeBooleanDef.

Source: files/castlexmlutils.pas (line 361).

Public procedure AttributeSet(const AttrName: String; const Value: Integer); overload;

Set the attribute as Integer, such that it's readable back by AttributeInteger and AttributeIntegerDef.

Source: files/castlexmlutils.pas (line 365).

Public procedure AttributeSet(const AttrName: String; const Value: Int64); overload;

Set the attribute as Int64, such that it's readable back by AttributeInt64 and AttributeInt64Def.

Source: files/castlexmlutils.pas (line 369).

Public procedure AttributeSet(const AttrName: String; const Value: QWord); overload;

Set the attribute as QWord, such that it's readable back by AttributeQWord and AttributeQWordDef.

Source: files/castlexmlutils.pas (line 373).

Public procedure AttributeSet(const AttrName: String; const Value: Cardinal); overload;

Set the attribute as Cardinal, such that it's readable back by AttributeCardinal and AttributeCardinalDef.

Source: files/castlexmlutils.pas (line 377).

Public procedure AttributeSet(const AttrName: String; const Value: Single); overload;

Set the attribute as Single, such that it's readable back by AttributeSingle and AttributeSingleDef.

Source: files/castlexmlutils.pas (line 381).

Public procedure AttributeSet(const AttrName: String; const Value: TVector2); overload;

Set the attribute as TVector2, such that it's readable back by AttributeVector2 and AttributeVector2Def.

Source: files/castlexmlutils.pas (line 385).

Public procedure AttributeSet(const AttrName: String; const Value: TVector3); overload;

Set the attribute as TVector3, such that it's readable back by AttributeVector3 and AttributeVector3Def.

Source: files/castlexmlutils.pas (line 389).

Public procedure AttributeSet(const AttrName: String; const Value: TVector4); overload;

Set the attribute as TVector4, such that it's readable back by AttributeVector4 and AttributeVector4Def.

Source: files/castlexmlutils.pas (line 393).

Public procedure AttributeColorSet(const AttrName: String; const Value: TCastleColor); overload;

Set the attribute as TCastleColor converted to HEX string, such that it's readable back by AttributeColor and AttributeColorDef.

Source: files/castlexmlutils.pas (line 397).

Public procedure AttributeColorSet(const AttrName: String; const Value: TCastleColorRGB); overload;

Set the attribute as TCastleColorRGB converted to HEX string, such that it's readable back by AttributeColorRGB and AttributeColorRGBDef.

Source: files/castlexmlutils.pas (line 401).

Public function Child(const ChildName: String; const Required: boolean = true; const WarnOnMultiple: boolean = true): TDOMElement;

Get child element with given ChildName.

For example use LevelElement.Child('items') to get the <items> element within <level> element, as in example below. 

<level>
  <creatures>
    ...
  </creatures>
  <items>
    ...
  </items>
</level>

There must be one and only one child element with this name. In case there's zero, or more than one such element, we will raise EDOMChildElementError (if Required is True, default) or return Nil (if Required is False).

If there are multiple occurences and Required is False, then we return Nil. If WarnOnMultiple we will also make a warning in this case, since we don't know which to return, but it it probably a mistake in XML file.

Exceptions raised
EDOMChildElementError
If child not found (or found more than once), and Required = True.

Source: files/castlexmlutils.pas (line 432).

Public function ChildElement(const ChildName: String; const Required: boolean = true; const WarnOnMultiple: boolean = true): TDOMElement;

Same as Child.

Source: files/castlexmlutils.pas (line 437).

Public function CreateChild(const ChildName: String): TDOMElement;

Create a new child element under this element, and return it.

Source: files/castlexmlutils.pas (line 442).

Public function ChildrenIterator: TXMLElementIterator; overload;

Iterator over all children elements. Use like this: 

var
  I: TXMLElementIterator;
begin
  I := Element.ChildrenIterator;
  try
    while I.GetNext do
    begin
      // ... here goes your code to process I.Current ...
    end;
  finally FreeAndNil(I) end;
end;

Source: files/castlexmlutils.pas (line 459).

Public function ChildrenIterator(const ChildName: String): TXMLElementIterator; overload;

Iterator over all children elements named ChildName. Use like this: 

var
  I: TXMLElementIterator;
begin
  I := Element.ChildrenIterator('item');
  try
    while I.GetNext do
    begin
      // ... here goes your code to process I.Current ...
    end;
  finally FreeAndNil(I) end;
end;

Source: files/castlexmlutils.pas (line 476).

Public function TextData: String;

The text data contained in this element.

This is suitable if an element is supposed to contain only some text. Like <some_value>This is a text inside.</some_value>. It raises an error if an element contains anything else as child.

If there are no text data nodes, e.g. if the element is empty, it returns empty string without raising any error.

Source: files/castlexmlutils.pas (line 486).

Public function TagName8: String;

Tag name (element name). Expressed as an 8-bit string (in UTF-8 encoding), contrary to the TagName from FPC DOM unit that is a WideString (DOMString).

Source: files/castlexmlutils.pas (line 491).

Generated by PasDoc 0.17.0.snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.