Class TDOMElementHelper

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).

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.

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

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

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

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

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

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.

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.

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:

• Hexadecimal format, like set by AttributeColorSet.

• 4D vector format, with 4 vector components in range 0..1, separated by whitespace. Like set by AttributeSet(TVector4) overload.

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

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:

• Hexadecimal format, like set by AttributeColorSet.

• 3D vector format, with 3 vector components in range 0..1, separated by whitespace. Like set by AttributeSet(TVector3) overload.

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

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.

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.

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.

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

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

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

Exceptions raised

EDOMAttributeMissing

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

Exceptions raised

EDOMAttributeMissing

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

Exceptions raised

EDOMAttributeMissing

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

Exceptions raised

EDOMAttributeMissing

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

Exceptions raised

EDOMAttributeMissing

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

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

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

Exceptions raised

EDOMAttributeMissing

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

Exceptions raised

EDOMAttributeMissing

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

Exceptions raised

EDOMAttributeMissing

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

Exceptions raised

EDOMAttributeMissing

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

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

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

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

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

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

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

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.

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

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

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

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.

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.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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.

Same as Child.

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

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;

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;

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.

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).