|  | overview |  | wiki |  | api reference |  | download

- Main Page
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Functions Variables Typedefs Enumerations Enumerator
Classes | Public Types | Public Member Functions | Static Public Member Functions
gameplay::Properties Class Reference

`#include <Properties.h>`

List of all members.

## Classes

struct | Property

## Public Types

enum | Type { NONE, STRING, NUMBER, VECTOR2, VECTOR3, VECTOR4, MATRIX }

## Public Member Functions

| ~Properties ()
const char * | getNextProperty ()
Properties * | getNextNamespace ()
void | rewind ()
Properties * | getNamespace (const char *id, bool searchNames=false, bool recurse=true) const
const char * | getNamespace () const
const char * | getId () const
bool | exists (const char *name) const
Type | getType (const char *name=NULL) const
const char * | getString (const char *name=NULL, const char *defaultValue=NULL) const
bool | setString (const char *name, const char *value)
bool | getBool (const char *name=NULL, bool defaultValue=false) const
int | getInt (const char *name=NULL) const
float | getFloat (const char *name=NULL) const
long | getLong (const char *name=NULL) const
bool | getMatrix (const char *name, Matrix *out) const
bool | getVector2 (const char *name, Vector2 *out) const
bool | getVector3 (const char *name, Vector3 *out) const
bool | getVector4 (const char *name, Vector4 *out) const
bool | getQuaternionFromAxisAngle (const char *name, Quaternion *out) const
bool | getColor (const char *name, Vector3 *out) const
bool | getColor (const char *name, Vector4 *out) const
bool | getPath (const char *name, std::string *path) const
const char * | getVariable (const char *name, const char *defaultValue=NULL) const
void | setVariable (const char *name, const char *value)

## Static Public Member Functions

static Properties * | create (const char *url)
static bool | parseVector2 (const char *str, Vector2 *out)
static bool | parseVector3 (const char *str, Vector3 *out)
static bool | parseVector4 (const char *str, Vector4 *out)
static bool | parseAxisAngle (const char *str, Quaternion *out)
static bool | parseColor (const char *str, Vector3 *out)
static bool | parseColor (const char *str, Vector4 *out)

## Detailed Description

Defines a properties file for loading text files.

A properties file has very simple syntax and can contain only namespaces and name/value pairs (the properties of a namespace). The file can have any file extension a user specifies.

Here's an example of a simple file that uses all the available features of the markup language:

        // This is a comment.

        // This property is in the default namespace:
        integerProperty = 5

        // This line defines a namespace of type "mynamespace" without an ID:
        mynamespace
        {
            // This namespace can be retrieved by searching for its ID, "spriteTexture",
            // or by its name "texture":
            texture spriteTexture
            {
                fileName = sprite.png
                width = 64
                height = 64
            }

            // This property is in the "space" namespace:
            booleanProperty = true

            // It's legal to have a name without a value if you leave out the '=' character:
            foo

            // In fact, the '=' character is optional if you'd rather write:
            bar 23

            // But don't write this or you'll get an error:
            // illegalProperty =

            // Or this:
            // = 15

            // Properties objects let you retrieve values as various types.
            floatProperty = 3.333
            stringProperty = This is a string.
            vector3Property = 1.0, 5.0, 3.55
            colorProperty = 1.0, 0.4, 0.0, 1.0
        }

Retrieving information out of a file like this could be done in two ways. If the available namespaces and name/value pairs are known in advance they can be queried by ID or name. For example, if the namespace "spriteTexture" and its properties are required then they can be retrieved with a call to getNamespace() followed by calls to getString() and getInt(). A namespace is stored and retrieved as a Properties object. Reading the spriteTexture properties out of the file above in this way could be done with the following code:

        // Create the top-level Properties object.
        Properties* properties = Properties::create("example.properties");
        // Retrieve the "spriteTexture" namespace.
        Properties* spriteTexture = properties->getNamespace("spriteTexture");

        // Get the values of known texture properties out of the namespace.
        const char* fileName = spriteTexture->getString("fileName");
        int width = spriteTexture->getInt("width");
        int height = spriteTexture->getInt("height");

        // Deleting the top-level Properties object will clean up all nested namespaces.
        SAFE_DELETE(properties);

On the other hand, if the structure of the file is not known in advance its namespaces and name/value pairs can be retrieved one by one using the getNextNamespace() and getNextProperty() methods. The following method prints the contents of any properties file to the console:

        void printProperties(Properties* properties)
        {
            // Print the name and ID of the current namespace.
            const char* spacename = properties->getNamespace();
            const char* id = properties->getId();
            GP_WARN("Namespace: %s  ID: %s\n{", spacename, id);

            // Print all properties in this namespace.
            const char* name = properties->getNextProperty();
            const char* value = NULL;
            while (name != NULL)
            {
                value = properties->getString(name);
                GP_WARN("%s = %s", name, value);
                name = properties->getNextProperty();
            }
            GP_WARN("}\n");

            // Print the properties of every namespace within this one.
            Properties* space = properties->getNextNamespace();
            while (space != NULL)
            {
                printProperties(space);
                space = properties->getNextNamespace();
            }
        }

Note that this method does not keep track of the namespace hierarchy, but could be modified to do so. Also note that nothing in a properties file indicates the type of a property. If the type is unknown, its string can be retrieved and interpreted as necessary.

## Member Enumeration Documentation

enum gameplay::Properties::Type

Data types supported by the properties class.

## Constructor & Destructor Documentation

gameplay::Properties::~Properties | ( |  | ) |

Destructor.

## Member Function Documentation

static Properties* gameplay::Properties::create | ( | const char * | url | ) | `[static]`

Creates a Properties runtime settings from the specified URL, where the URL is of the format "<file-path>.<extension>#<namespace-id>/<namespace-id>/.../<namespace-id>" (and "#<namespace-id>/<namespace-id>/.../<namespace-id>" is optional).

Parameters:

  url | The URL to create the properties from.

Returns:
  The created Properties or NULL if there was an error.

bool gameplay::Properties::exists | ( | const char * | name | ) | const

Check if a property with the given name is specified in this Properties object.

Parameters:

  name | The name of the property to query.

Returns:
  True if the property exists, false otherwise.

bool gameplay::Properties::getBool | ( | const char * | name = `NULL`,
|  | bool | defaultValue = `false`
| ) |  | const

Interpret the value of the given property as a boolean.

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  defaultValue | the default value to return if the specified property does not exist within the properties file.

Returns:
  true if the property exists and its value is "true", otherwise false.

bool gameplay::Properties::getColor | ( | const char * | name,
|  | Vector3 * | out
| ) |  | const

Interpret the value of the given property as an RGB color in hex and write this color to a Vector3. E.g. 0xff0000 represents red and sets the vector to (1, 0, 0). If the property does not exist, out will be set to Vector3(0.0f, 0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector3(0.0f, 0.0f, 0.0f).

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  out | The vector to set to this property's interpreted value.

Returns:
  True on success, false if the property does not exist or could not be scanned.

bool gameplay::Properties::getColor | ( | const char * | name,
|  | Vector4 * | out
| ) |  | const

Interpret the value of the given property as an RGBA color in hex and write this color to a Vector4. E.g. 0xff0000ff represents opaque red and sets the vector to (1, 0, 0, 1). If the property does not exist, out will be set to Vector4(0.0f, 0.0f, 0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector4(0.0f, 0.0f, 0.0f, 0.0f).

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  out | The vector to set to this property's interpreted value.

Returns:
  True on success, false if the property does not exist or could not be scanned.

float gameplay::Properties::getFloat | ( | const char * | name = `NULL` | ) | const

Interpret the value of the given property as a floating-point number. If the property does not exist, zero will be returned. If the property exists but could not be scanned, an error will be logged and zero will be returned.

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.

Returns:
  The value of the given property interpreted as a float. Zero if the property does not exist or could not be scanned.

const char* gameplay::Properties::getId | ( |  | ) | const

Get the ID of this Property's namespace. The ID should be a unique identifier, but its uniqueness is not enforced.

Returns:
  The ID of this Property's namespace.

int gameplay::Properties::getInt | ( | const char * | name = `NULL` | ) | const

Interpret the value of the given property as an integer. If the property does not exist, zero will be returned. If the property exists but could not be scanned, an error will be logged and zero will be returned.

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.

Returns:
  The value of the given property interpreted as an integer. Zero if the property does not exist or could not be scanned.

long gameplay::Properties::getLong | ( | const char * | name = `NULL` | ) | const

Interpret the value of the given property as a long integer. If the property does not exist, zero will be returned. If the property exists but could not be scanned, an error will be logged and zero will be returned.

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.

Returns:
  The value of the given property interpreted as a long. Zero if the property does not exist or could not be scanned.

bool gameplay::Properties::getMatrix | ( | const char * | name,
|  | Matrix * | out
| ) |  | const

Interpret the value of the given property as a Matrix. If the property does not exist, out will be set to the identity matrix. If the property exists but could not be scanned, an error will be logged and out will be set to the identity matrix.

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  out | The matrix to set to this property's interpreted value.

Returns:
  True on success, false if the property does not exist or could not be scanned.

Properties* gameplay::Properties::getNamespace | ( | const char * | id,
|  | bool | searchNames = `false`,
|  | bool | recurse = `true`
| ) |  | const

Get a specific namespace by ID or name. This method will optionally perform a depth-first search on all namespaces and inner namespaces within this Property.

Parameters:

  id | The ID or name of the namespace to find.
  searchNames | If true, namespace names are used in the search, instead of namespace IDs. By default this parameter is false and namespace IDs are searched.
  recurse | If true, perform a depth-first search, otherwise search only the immediate child namespaces.

Returns:
  A properties object with the given ID or name.

const char* gameplay::Properties::getNamespace | ( |  | ) | const

Get the name of this Property's namespace.

Returns:
  The name of this Property's namespace.

Properties* gameplay::Properties::getNextNamespace | ( |  | ) |

Get the next namespace.

const char* gameplay::Properties::getNextProperty | ( |  | ) |

Get the name of the next property.

If a valid next property is returned, the value of the property can be retrieved using any of the get methods in this class, passing NULL for the property name.

Returns:
  The name of the next property, or NULL if there are no properties remaining.

bool gameplay::Properties::getPath | ( | const char * | name,
|  | std::string * | path
| ) |  | const

Gets the file path for the given property if the file exists.

This method will first search for the file relative to the working directory. If the file is not found then it will search relative to the directory the bundle file is in.

Parameters:

  name | The name of the property.
  path | The string to copy the path to if the file exists.

Returns:
  True if the property exists and the file exists, false otherwise.

bool gameplay::Properties::getQuaternionFromAxisAngle | ( | const char * | name,
|  | Quaternion * | out
| ) |  | const

Interpret the value of the given property as a Quaternion specified as an axis angle. If the property does not exist, out will be set to Quaternion(). If the property exists but could not be scanned, an error will be logged and out will be set to Quaternion().

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  out | The quaternion to set to this property's interpreted value.

Returns:
  True on success, false if the property does not exist or could not be scanned.

const char* gameplay::Properties::getString | ( | const char * | name = `NULL`,
|  | const char * | defaultValue = `NULL`
| ) |  | const

Get the value of the given property as a string. This can always be retrieved, whatever the intended type of the property.

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  defaultValue | The default value to return if the specified property does not exist.

Returns:
  The value of the given property as a string, or the empty string if no property with that name exists.

Type gameplay::Properties::getType | ( | const char * | name = `NULL` | ) | const

Returns the type of a property.

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's type.

Returns:
  The type of the property.

const char* gameplay::Properties::getVariable | ( | const char * | name,
|  | const char * | defaultValue = `NULL`
| ) |  | const

Returns the value of a variable that is set in this Properties object.

Variables take on the format ${name} and are inherited from parent Property objects.

Parameters:

  name | Name of the variable to get.
  defaultValue | Value to return if the variable is not found.

Returns:
  The value of the specified variable, or defaultValue if not found.

bool gameplay::Properties::getVector2 | ( | const char * | name,
|  | Vector2 * | out
| ) |  | const

Interpret the value of the given property as a Vector2. If the property does not exist, out will be set to Vector2(0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector2(0.0f, 0.0f).

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  out | The vector to set to this property's interpreted value.

Returns:
  True on success, false if the property does not exist or could not be scanned.

bool gameplay::Properties::getVector3 | ( | const char * | name,
|  | Vector3 * | out
| ) |  | const

Interpret the value of the given property as a Vector3. If the property does not exist, out will be set to Vector3(0.0f, 0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector3(0.0f, 0.0f, 0.0f).

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  out | The vector to set to this property's interpreted value.

Returns:
  True on success, false if the property does not exist or could not be scanned.

bool gameplay::Properties::getVector4 | ( | const char * | name,
|  | Vector4 * | out
| ) |  | const

Interpret the value of the given property as a Vector4. If the property does not exist, out will be set to Vector4(0.0f, 0.0f, 0.0f, 0.0f). If the property exists but could not be scanned, an error will be logged and out will be set to Vector4(0.0f, 0.0f, 0.0f, 0.0f).

Parameters:

  name | The name of the property to interpret, or NULL to return the current property's value.
  out | The vector to set to this property's interpreted value.

Returns:
  True on success, false if the property does not exist or could not be scanned.

static bool gameplay::Properties::parseAxisAngle | ( | const char * | str,
|  | Quaternion * | out
| ) |  | `[static]`

Attempts to parse the specified string as an axis-angle value.

The specified string is expected to contain four comma-separated values, where the first three values represents the axis and the fourth value represents the angle, in degrees.

On error, false is returned and the output is set to all zero values.

Parameters:

  str | The string to parse.
  out | A Quaternion populated with the orientation of the axis-angle, if successful.

Returns:
  True if a valid axis-angle was parsed, false otherwise.

static bool gameplay::Properties::parseColor | ( | const char * | str,
|  | Vector3 * | out
| ) |  | `[static]`

Atempts to parse the specified string as an RGB color value.

Parameters:

  str | The string to parse.
  out | The value to populate if successful.

Returns:
  True if a valid RGB color was parsed, false otherwise.

static bool gameplay::Properties::parseColor | ( | const char * | str,
|  | Vector4 * | out
| ) |  | `[static]`

Atempts to parse the specified string as an RGBA color value.

Parameters:

  str | The string to parse.
  out | The value to populate if successful.

Returns:
  True if a valid RGBA color was parsed, false otherwise.

static bool gameplay::Properties::parseVector2 | ( | const char * | str,
|  | Vector2 * | out
| ) |  | `[static]`

Attempts to parse the specified string as a Vector2 value.

On error, false is returned and the output is set to all zero values.

Parameters:

  str | The string to parse.
  out | The value to populate if successful.

Returns:
  True if a valid Vector2 was parsed, false otherwise.

static bool gameplay::Properties::parseVector3 | ( | const char * | str,
|  | Vector3 * | out
| ) |  | `[static]`

Attempts to parse the specified string as a Vector3 value.

On error, false is returned and the output is set to all zero values.

Parameters:

  str | The string to parse.
  out | The value to populate if successful.

Returns:
  True if a valid Vector3 was parsed, false otherwise.

static bool gameplay::Properties::parseVector4 | ( | const char * | str,
|  | Vector4 * | out
| ) |  | `[static]`

Attempts to parse the specified string as a Vector4 value.

On error, false is returned and the output is set to all zero values.

Parameters:

  str | The string to parse.
  out | The value to populate if successful.

Returns:
  True if a valid Vector4 was parsed, false otherwise.

void gameplay::Properties::rewind | ( |  | ) |

Rewind the getNextProperty() and getNextNamespace() iterators to the beginning of the file.

bool gameplay::Properties::setString | ( | const char * | name,
|  | const char * | value
| ) |  |

Sets the value of the property with the specified name.

If there is no property in this namespace with the current name, one is added. Otherwise, the value of the first property with the specified name is updated.

If name is NULL, the value current property (see getNextProperty) is set, unless there is no current property, in which case false is returned.

Parameters:

  name | The name of the property to set.
  value | The property value.

Returns:
  True if the property was set, false otherwise.

void gameplay::Properties::setVariable | ( | const char * | name,
|  | const char * | value
| ) |  |

Sets the value of the specified variable.

Parameters:

  name | Name of the variable to set.
  value | The value to set.

All Classes Functions Variables Typedefs Enumerations Enumerator