Unigine::Properties Class

Header:

#include <UnigineProperties.h>

List of functions:

The functions below are used to control the loading and managing of property libraries: you can create new libraries, load the existing ones, associate them with the current world. Also the functions provide access to properties stored in the libraries: you can get, clone, move, inherit or remove any property of the library.

Notice

To modify a property, use functions of the Property class.

Each library is a separate XML file with a .prop extension. Such file can be created manually, via Unigine API or via the Propertieswindow of UnigineEditor.

Notice

The library created via the create() function should be associated with the current world by using The addWorldLibrary() function. In this case, it will be automatically loaded/saved on world loading/saving. Otherwise, you will have toload and save by using the corresponding functions.

If you load the library as follows, all changes made in it will be saved on the worlds' saving:

Source code (C++)

// get a pointer to the property manager
Properties *properties = Properties::get();
// load the library and associate it with the current world
properties->addWorldLibrary("unigine_project/my_new_lib.prop");
// change the property library: inherit a property
properties->inheritProperty("my_surface_base","unigine_project/my_new_lib.prop","my_surface_base_0");

If you load the library without associating if with the world, you will need to save changes in the library as follows:

Source code (C++)

// get a pointer to the property manager
Properties *properties = Properties::get();
// load the library
properties->load("unigine_project/my_new_lib.prop");
// change the property library: inherit a property
properties->inheritProperty("my_surface_base","unigine_project/my_new_lib.prop","my_surface_base_0");
// save changes in the library
properties->save("unigine_project/my_new_lib.prop");

Setting Loading Order for Libraries

The loading order set for property libraries is important when properties are stored in several .prop files: child properties cannot be loaded (and, therefore, modified) before their parents. The loading order can be set via Unigine API using the addWorldLibrary() function:

Source code (C++)

// get a pointer to the property manager
Properties *properties = Properties::get();
// set the loading order
properties->addWorldLibrary("unigine_project/game_objects.prop");
properties->addWorldLibrary("unigine_project/game_objects_unit.prop");
properties->addWorldLibrary("unigine_project/game_objects_unit_weapon.prop");

Or the properties to load and their order can be specified directly in the .world file:

Source code (XML)

<world version="1.11">
<materials>
	...
</materials>
<properties>
	<library>project/game_objects.prop</library>
	<library>project/game_objects_unit.prop</library>
	<library>project/game_objects_unit_weapon.prop</library>
</properties>
...

Properties Class

Members

Property * get()

Returns a pointer to the existing property manager. The pointer to the property manager must be obtained to access functions of the Properties class:

Source code (C++)

Properties properties = Properties::get();
// access functions of the Properties class
...

Return value

Pointer to the existing property manager.

int isLibrary(const char * name)

Checks if the property library with the given name exists.

Arguments

const char * name - Path to the property library. The path can be both absolute or relative to the data folder.

Return value

1 if the property library exists; otherwise, 0.

int isLibraryEditable(int num)

Returns a value indicating if properties can be added to or removed from the given library.

Arguments

int num - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).

Return value

1 if the property library is editable; otherwise, 0.

const char * getLibraryName(int num)

Returns the path to the property library by its number.

Source code (C++)

Properties *properties = Properties::get();
for (int i = 0; i < properties->getNumLibraries(); i++){
	Log::message("getLibraryName(%d) returned %s\n",i,properties->getLibraryName(i));
}

Arguments

int num - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).

Return value

Path to the property library.

int getNumLibraries()

Returns the number of all loaded property libraries (i.e. associated and not associated with the current world).

Return value

The number of loaded property libraries.

int getNumProperties(int library)

Returns the number of properties in the given library.

Arguments

int library - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).

Return value

Number of properties in the library.

int getNumWorldLibraries()

Returns the number of property libraries associated with the current world.

Return value

Number of property libraries associated with the current world.

Ptr<Property> getProperty(int library, int num)

Returns a property by its number in the given library. The returned property can be modified by using methods of the Property class.

Source code (C++)

int library = properties->findLibrary("../data/unigine_project/unigine_project.prop");
Vector<PropertyPtr> my_properties;
for (int i = 0; i < properties->getNumProperties(library); i++) {
	my_properties.append(properties->getProperty(library,i));
}

Arguments

int library - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).
int num - The number of the property in range from 0 to the total number of properties in the specified library.

Return value

A property (an instance of the Property class).

int isProperty(const char * name)

Checks if the property with the given name exists in one of the loaded libraries.

Arguments

const char * name - Name of the property.

Return value

1 if the given property exists; otherwise, 0.

const char * getPropertyName(int library, int num)

Returns the name of the property by its number in the given library.

Arguments

int library - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).
int num - The number of the property in range from 0 to the total number of properties in the specified library..

Return value

Name of the property.

const char * getWorldLibraryName(int num)

Returns the name of the property library associated with the current world by the library index.

Source code (C++)

Properties properties = Properties::get();
for (int i = 0; i < properties->getNumWorldLibraries(); i++){
	Log::message("getWorldLibraryName(%d) returned %s\n",i,properties->getWorldLibraryName(i));
}

Arguments

int num - The number of the property library in range from 0 to the total number of property libraries associated with the world.

Return value

Path to the property library.

int addWorldLibrary(const char * name)

Loads a library and associates it with the current world. If the library file does not exist, an empty library is created. The libraries loaded via this function will be loaded/saved on the current world loading/saving.

Arguments

const char * name - Path to the property library to load. The path can be both absolute or relative to the data folder.

Return value

1 if the library is loaded or created successfully; otherwise, 0.

int clear(const char * name)

Unloads a given library and all its contents (if it was previously loaded). Note that you cannot unload a library, if some of its properties are parent to properties from other libraries.

Arguments

const char * name - Name of the property library.

Return value

1 if the property library is cleared successfully; otherwise, 0.

void clearWorldLibraries()

Clears the list of the property libraries associated with the current world. At that, the libraries will stay loaded.

int cloneProperty(const char * name, const char * new_library, const char * new_name)

Copies a property into the specified property library under the specified name.

NoticeThe root property (the property that has no parent) cannot be copied by using this function.

The loading order of the libraries should be taken into account: if the property to be copied has a parent property stored in the source library and the destination library is loaded before the source library, the parent property should be copied first.

NoticeThe property cannot be copied if the destination library or the property itself is non-editable.

Arguments

const char * name - Name of the property to copy.
const char * new_library - Path to the destination library, into which the property will be copied. The path can be both absolute or relative to the data folder.
const char * new_name - Name, under which the property will be added to the destination library.

Return value

1 if the property is copied successfully; otherwise, 0.

int create(const char * name)

Creates an empty property library. To be used, the created library should be loaded to the current world.

Source code (C++)

Properties properties = Properties::get();
properties->create("../data/unigine_project/property_library.prop");

Arguments

const char * name - Path to the property library including its name. A path can be both absolute or relative to the data folder.

Return value

1 if the property library is created successfully; otherwise, 0.

int findLibrary(const char * name)

Returns the number of the property library by its name.

Arguments

const char * name - Path to the property library. The path can be both absolute or relative to the data folder.

Return value

The number of the library if it is found; otherwise, -1.

int findLibraryProperty(int library, const Ptr<Property> & property)

Searches for the given property in the specified property library.

Arguments

int library - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).
const Ptr<Property> & property - A property (an instance of the Property class).

Return value

The number of the property, if it is found; otherwise, -1.

int findLibraryProperty(int library, const char * name)

Searches for the property with the given name in the given library.

Arguments

int library - Index of the property library.
const char * name - Name of the property.

Return value

The number of the property in the library, if it is found; otherwise, -1.

Ptr<Property> findProperty(const char * name)

Searches for the property with the given name. The returned property can be modified by using methods of the Property class.

Arguments

const char * name - Name of the property.

Return value

A property, if it is found ((an instance of the Property class)); otherwise, 0.

int findPropertyLibrary(const char * name)

Searches for the property library containing the given property.

Arguments

const char * name - Name of the property.

Return value

The number of the property library, if it is found; otherwise, -1.

int findPropertyLibrary(const Ptr<Property> & property)

Searches for the property library containing the given property.

Arguments

const Ptr<Property> & property - A property (an instance of the Property class).

Return value

The number of the property library, if it is found; otherwise, -1.

int inheritProperty(const char * name, const char * new_library, const char * new_name)

Inherits a property from the given property and adds it to the specified library under the specified name. The loading order of the libraries should be taken into account: if the property to inherit from has a parent property stored in the source library and the destination library is loaded before the source library, the property won't be inherited.

NoticeThe property cannot be inherited if the destination library is non-editable.

Arguments

const char * name - Name of the property to inherit from.
const char * new_library - Path to the destination library, into which the inherited property will be added. The path can be both absolute or relative to the data folder.
const char * new_name - Name, under which the inherited property will be added to the destination library.

Return value

1 if the property is inherited successfully; otherwise, 0.

int load(const char * name)

Loads the property library from the given file. Loaded in such way, the library won't be associated with the current world and, therefore, it won't be automatically loaded/saved on world loading/saving. So, if you want to save changes made in the loaded library (if any), you should call save() function.

Source code (C++)

Properties properties = Properties::get();
properties->load("../data/unigine_project/property_library.prop");

Arguments

const char * name - Path to the .prop file with the property library. A path can be both absolute or relative to the data folder.

Return value

1 if the property library is loaded successfully; otherwise, 0.

int moveProperty(const char * name, const char * new_library, const char * new_name)

Moves a property into the specified property library under the specified name.

NoticeThe root property (the property that has no parent) cannot be moved by using this function.

The loading order of the libraries should be taken into account:

If the property to be moved has a parent property stored in the source library and the destination library is loaded before the source library, the parent property should be moved first.
If the property to be moved has a child property stored in the source library and this source library is loaded before the destination library, the child property should also be moved.

Otherwise, the property will be simply renamed.

NoticeThe property cannot be moved if the destination or source library or the property itself is non-editable.

Arguments

const char * name - Name of the property to move.
const char * new_library - Path to the destination library, into which the property will be moved. The path can be both absolute or relative to the data folder.
const char * new_name - Name, under which the property will be added to the destination library.

Return value

1 if the property is moved successfully; otherwise, 0.

int removeProperty(const char * name)

Removes the property and all its children from the property library.

NoticeThe root property (the property that has no parent) or non-editable property cannot be removed by using this function. The property stored in the non-editable library cannot be removed as well.

Arguments

const char * name - Name of the property to remove.

Return value

1 if the property is removed successfully; otherwise, 0.

int removeWorldLibrary(const char * name)

Removes the property library associated with the world from the list of preloaded property libraries. The library remains loaded so its properties stay available.

Arguments

const char * name - Path to the property library to remove. The path can be both absolute or relative to the data folder.

Return value

1 if the library is removed successfully; otherwise, 0.

int replaceProperty(const Ptr<Property> & property, const char * new_name)

Replaces the specified property with a new one for all nodes. The property itself won't be replaced in the library. The new property that replaces the specified one should exist in a property library. For example, if you have 3 nodes with the same property, calling this method will change this property to the specified one for all these nodes.

Arguments

const Ptr<Property> & property - Property to be replaced.
const char * new_name - Name of the new property.

Return value

1 if the property is replaced successfully; otherwise, 0.

int replaceProperty(const char * name, const char * new_name)

Replaces the specified property with a new one for all nodes. The property itself won't be replaced in the library. The new property that replaces the specified one should exist in a property library. For example, if you have 3 nodes with the surface_base_0 property, calling this method will change this property to the specified one for all these nodes (e.g. it can be changed to surface_base_3).

Arguments

const char * name - Name of the property to be replaced.
const char * new_name - Name of the new property.

Return value

1 if the property is replaced successfully; otherwise, 0.

int save(const char * name)

Saves the property library into the specified file. The file name should be the same as the library name. This function should be called if you need to save changes in the library that isn't associated with the current world (loaded via the load() function). However, you can call it for the associated library, if you want to save changes in any way (independently of world saving).

Arguments

const char * name - Path to the file into which the property library should be saved. The path can be both absolute or relative to the data folder.

Return value

1 if the property library is saved successfully; otherwise, 0.

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)