Class TDOMElementHelper

Unit

Declaration

type TDOMElementHelper = class helper(TObject) for TDOMElement

Description

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 function Child(const ChildName: string; const Required: boolean = true): TDOMElement;
Public function ChildElement(const ChildName: string; const Required: 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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.
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.
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.
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
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
Public function AttributeCardinal(const AttrName: string): Cardinal; overload;

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

Exceptions raised
EDOMAttributeMissing
Public function AttributeInteger(const AttrName: string): Integer; overload;

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

Exceptions raised
EDOMAttributeMissing
Public function AttributeInt64(const AttrName: string): Int64; overload;

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

Exceptions raised
EDOMAttributeMissing
Public function AttributeQWord(const AttrName: string): QWord; overload;

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

Exceptions raised
EDOMAttributeMissing
Public function AttributeSingle(const AttrName: string): Single; overload;

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

Exceptions raised
EDOMAttributeMissing
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
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
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
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
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
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
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
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.

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

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

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

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

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

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

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

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

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

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

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.

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.

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

Public function Child(const ChildName: string; const Required: 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).

Exceptions raised
EDOMChildElementError
If child not found (or found more than once), and Required = True.
Public function ChildElement(const ChildName: string; const Required: boolean = true): TDOMElement;

Same as Child.

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

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

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;

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;

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.

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


Generated by PasDoc 0.16.0.