Documentation/Programming Articles/Overview of TextBlock format

From NeoAxis 3D Engine Wiki

Jump to: navigation, search
Go to higher level

Contents

Introduction

TextBlock (text block) is the base format of the engine for keeping text data using hierarchical structure.

The following file types are stored in the engine using text block format:

Block structure

Any text block has a hierarchical structure. The block contains its name, the field for additional information(optional), attributes and child blocks. Each attribute is represented using "key-value" pair. The key is unique in local namespace.

TextBlock01.jpg

The text block is stored in the file using such format:

name data
{
 
}

name - name of the block, data - additional information that could be skipped. The content of the block (its attributes and child blocks) is written into the braces.

The attribute consists of several parameters:

  • the name of the attribute,
  • the value of the attribute.

The attribute is saved to the file using format name = value, where name is the name of the attribute and value is the value of the attribute.

Let's look at an example of a text block, taken from Girl.highMaterial file (it could be found in Data\Types\Units\Girl folder).

highLevelMaterial Girl
{
	template = ShaderBaseMaterial
	doubleSided = True
	alphaRejectFunction = Greater
	halfLambert = True
	diffuseColor = 0.8666667 0.7803922 0.7098039
	specularColor = 1 1 1
	diffuse1Map
	{
		texture = "Types\\Units\\Girl\\Girl_Diffuse.dds"
	}
	specularMap
	{
		texture = "Types\\Units\\Girl\\Girl_Specular.dds"
	}
}

There is a text block, which is named as highLevelMaterial and it has an additional information that contains the name of this material - Girl. This block has template, doubleSided, alphaRejectFunction attributes, etc. Also there are two child blocks: diffuse1Map and specularMap. Both child blocks contain texture attribute.

Reading and writing blocks

There is a special class that is used for work with text blocks - TextBlock, it is placed into Utils assembly.

The example of reading the block

Class TextBlockUtils is responsible for reading the text blocks. This class contains several overloaded methods: LoadFromVirtualFile (loads the file using the path in virtual file system ) and LoadFromRealFile (loads the file, using real file path).

The example of the loading of the block using virtual file path:

string error;
TextBlock rootBlock = TextBlockUtils.LoadFromVirtualFile( fileName, out error );
if( rootBlock == null )
{
	//error
}

There is a method for finding child block - FindChild, it tries to find the first block with specified name.

TextBlock block = rootBlock.FindChild( "highLevelMaterial" );
if( block != null )
{
	...
}

All child blocks could be accessed using Children property.

foreach( TextBlock childBlock in block.Children )
{
	...
}

Additional information of the block is kept in Data property.

string data = block.Data;

The value and existence of the attribute could be checked using GetAttribute and IsAttributeExist methods.

if( block.IsAttributeExist( "diffuseColor" ) )
{
	string value = block.GetAttribute( "diffuseColor" );
}

All attributes of the block could be accessed using Attributes property.

foreach( TextBlock.Attribute attribute in block.Attributes )
{
	...
}

The value of the attribute is a string type. In order to retrieve another type of the value, you should call Parse method with proper type of returned value. The example:

if( block.IsAttributeExist( "diffuseColor" ) )
{
	ColorValue diffuseColor = ColorValue.Parse( block.GetAttribute( "diffuseColor" ) );
	...
}

The example of writing to the block

The root block is created using TextBlock constructor method. AddChild method is used for adding child blocks.

TextBlock rootBlock = new TextBlock();
TextBlock block = rootBlock.AddChild( "highLevelMaterial", name );

Additional information could be set during the creation of the block or using Data property.

block.Data = name;

In order to add new attribute to the block, SetAttribute method should be called.

block.SetAttribute( "diffuseColor", diffuseColor.ToString() );

The block is saved to the file as the value with String type, which could be retrieved using DumpToString method.

string text = rootBlock.DumpToString();
try
{
	using( StreamWriter writer = new StreamWriter( realFileName ) )
	{
		writer.Write( text );
	}
}
catch( Exception ex )
{
	Log.Error( "Unable to save file \"{0}\" ({1}).", realFileName, ex.Message );
	return false;
}

API

TextBlock

Name Description
PublicMethod.gif TextBlock AddChild( String name, String data ) The method that adds child block with additional data.
PublicMethod.gif TextBlock AddChild( String name ) The method that adds child block.
PublicMethod.gif void AttachChild( TextBlock child ) The method that attaches specified block as a child.
PublicMethod.gif void DeleteAllAttributes() The method that removes all attributes of the block.
PublicMethod.gif void DeleteAttribute( String name ) The method that removes attribute with specified name.
PublicMethod.gif void DeleteChild( TextBlock child ) The method that removes specified child block.
PublicMethod.gif void DetachChild( TextBlock child ) The method that detaches specified block from its parent.
PublicMethod.gif string DumpToString() The method that converts the block into the string.
PublicMethod.gif TextBlock FindChild( String name ) The method that searches a child block with specified name. If the block with specified name is found, the method will return the first block with this name, in other case it will return null'.
PublicMethod.gif string GetAttribute( String name, String defaultValue ) The method that gets the value of the attribute with specified name. If the attribute with such name exists, the method will return the value of the attribute, if it doesn't then defaultValue will be returned in result.
PublicMethod.gif string GetAttribute( String name ) The method that gets the value of the attribute with specified name. If the attribute with such name exists, the method will return the value of the attribute, if it doesn't then empty String will be returned in result.
PublicMethod.gif bool IsAttributeExist( String name ) The method that checks the existence of the attribute with specified name. If the attribute with such name exists, True value will be returned, if it doesn't then False will returned in result.
PublicMethod.gif StaticMember.gif TextBlock Parse( String str, out String errorString ) The method that loads the block from the specified string. If the block is loaded successfully then it will be returned in result. If it doesn't then null value will be returned and error message will be put into errorString variable.
PublicMethod.gif void SetAttribute( String name, String value ) The method that sets the value for the attribute with specified name.
PublicProperty.gif IList<TextBlock.Attribute> Attributes The list of the attributes of the block.
PublicProperty.gif IList<TextBlock> Children The list of child blocks.
PublicProperty.gif String Data Additional information of the block is stored in this property.
PublicProperty.gif String Name The name of the block.
PublicProperty.gif TextBlock Parent The parent block.

TextBlockUtils

TextBlockUtils is an additional class that is used for reading the block from the file.

Name Description
PublicMethod.gif StaticMember.gif TextBlock LoadFromRealFile( String path, out String errorString, out Boolean fileNotFound ) The method that loads the block from the file, using the path in real file system. If the block is loaded successfully then it will be returned in result. In other case null value will be returned and an error message will be put into errorString variable. If the file doesn't exist then True value will be put into fileNotFound variable.
PublicMethod.gif StaticMember.gif TextBlock LoadFromRealFile( String path, out String errorString ) The method that loads the block from the file, using the path in real file system. If the block is loaded successfully then it will be returned in result. In other case null value will be returned and an error message will be put into errorString variable.
PublicMethod.gif StaticMember.gif TextBlock LoadFromRealFile( String path ) The method that loads the block from the file, using the path in real file system. If the block is loaded successfully then it will be returned in result. In other case null value will be returned in result.
PublicMethod.gif StaticMember.gif TextBlock LoadFromVirtualFile( String path, out String errorString, out Boolean fileNotFound ) The method that loads the block from the file, using the path in virtual file system. If the block is loaded successfully then it will be returned in result. In other case null value will be returned and an error message will be put into errorString variable. If the file doesn't exist then True value will be put into fileNotFound variable.
PublicMethod.gif StaticMember.gif TextBlock LoadFromVirtualFile( String path, out String errorString ) The method that loads the block from the file, using the path in virtual file system. If the block is loaded successfully then it will be returned in result. In other case null value will be returned and an error message will be put into errorString variable.
PublicMethod.gif StaticMember.gif TextBlock LoadFromVirtualFile( String path ) The method that loads the block from the file, using the path in virtual file system. If the block is loaded successfully then it will be returned in result. In other case null value will be returned in result.