Unigine.Properties Class

The functions below are used to control property loading and management within the project: you can get, clone, inherit, or remove any property within the project. Reparenting is supported for all non-manual and editable properties.

Notice

This class is a singleton.
To modify a single property, use functions of the Property class.

Adding Callbacks#

You can add callbacks to track any changes made to any property and perform certain actions. The signature of the callback function must be as follows:

Source code (C++)

void callback_function_name(Property property);

Here is an example of tracking property removal via callbacks:

Source code (C#)

public void property_removed(Property property)
{
	Log.Message("Property \"{0}\" was removed.\n", property.Name);
    // ...
}

// somewhere in the code

// inheriting a new property named "my_prop" from the base property "surface_base"
Property property = Properties.FindManualProperty("surface_base").Inherit("my_prop");

// setting our callback function on property removal
Properties.AddCallback(Properties.CALLBACK_REMOVED, property_removed);

// removing the property named "my_prop"
Properties.RemoveProperty(Properties.FindProperty("my_prop").GUID);

Properties:

Name	Description
int NumProperties	The total number of properties loaded for the current project.

Methods:

Name	Description View: Sort by:
GetProperty	Returns a property by its number.
IsProperty	Checks if a property with the given name exists.
IsManualProperty	Checks if a property with the given name exists.
GetPropertyName	Returns the name of the property by its number.
CloneProperty	Clones the property and assigns the specified name and path to the clone.
FindProperty	Searches for a property with the given name.
FindManualProperty	Searches for a manual property with the given name.
FindPropertyByGUID	Searches for a property with the given GUID.
FindPropertyByPath	Searches for a property with the given path.
FindPropertyByFileGUID	Searches for a property with the given *.prop file GUID.
LoadProperty	Loads a property from the specified *.prop file.
InheritProperty	Inherits a property from the given property and assigns the specified name and path to the new property.
RemoveProperty	Removes the property with the specified GUID.
RenameProperty	Changes the name of the property with the specified GUID.
ReplaceProperty	Replaces the specified property with a new one for all nodes and surfaces.
ReparentProperty	Sets a new parent for the specified property.
ReloadProperties	Reloads all *.prop files from all data folders.
SaveProperties	Saves all properties that can be saved to corresponding *.prop files.
AddCallback	Adds a callback of the specified type.
RemoveCallback	Removes the specified callback from the list of callbacks of the specified type.
ClearCallbacks	Clears all added callbacks of the specified type.

Variables:

Name	Description
CALLBACK_CREATED = 0	Property created callback. This callback is fired when a new property is created.
CALLBACK_MOVED = 1	Property moved callback. This callback is fired when the path of a property is changed.
CALLBACK_REMOVED = 4	Property removed callback. This callback is fired when a property is removed.
CALLBACK_RENAMED = 2	Property renamed callback. This callback is fired when the name of a property is changed.
CALLBACK_REPARENTED = 3	Property reparented callback. This callback is fired when the parent of a property is changed.

Properties Class

Properties

int NumProperties#

The total number of properties loaded for the current project.

Members

Property GetProperty ( int num ) #

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

Source code (C#)

Property[] my_properties = new Property[properties.getNumProperties()];
for (int i = 0; i < properties.getNumProperties(); i++)
{
	my_properties[i] = properties.getProperty(i);
}

Arguments

int num - Number of the property in range from 0 to the total number of properties.

Return value

Property instance if it exists or NULL.

bool IsProperty ( string name ) #

Checks if a property with the given name exists.

Arguments

string name - Name of the property.

Return value

1 if a property with the given name exists; otherwise, 0.

bool IsProperty ( UGUID guid ) #

Checks if a property with the given GUID exists.

Arguments

UGUID guid - GUID of the property.

Return value

1 if a property with the given GUID exists; otherwise, 0.

bool IsManualProperty ( string name ) #

Checks if a property with the given name exists.

Arguments

string name - Name of the manual property.

Return value

1 if a manual property with the given name exists; otherwise, 0.

string GetPropertyName ( int num ) #

Returns the name of the property by its number.

Arguments

int num - Number of the property in range from 0 to the total number of properties.

Return value

Name of the property.

NoticeIf the property with the specified number is internal and has a parent, the parent's name will be returned.

Property CloneProperty ( UGUID guid, string name = 0, string path = 0 ) #

Clones the property and assigns the specified name and path to the clone.

Notice

Without a name the cloned property won't be displayed in the properties hierarchy, without a path it won't be saved when saveProperties() is called.

Arguments

UGUID guid - GUID of the property to clone.
string name - Cloned property name.
string path - Path to save the cloned property.

Return value

Property instance if the property with the specified GUID exists or nullptr.

Property FindProperty ( string name ) #

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

Arguments

string name - Property name.

Return value

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

Property FindManualProperty ( string name ) #

Searches for a manual property with the given name. The returned property can be managed using the methods of the Property class.

Arguments

string name - Manual property name.

Return value

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

Property FindPropertyByGUID ( UGUID guid ) #

Searches for a property with the given GUID. The returned property can be managed using the methods of the Property class.

Arguments

UGUID guid - Property GUID.

Return value

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

Property FindPropertyByPath ( string path ) #

Searches for a property with the given path. The returned property can be managed using the methods of the Property class.

Arguments

string path - Property path.

Return value

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

Property FindPropertyByFileGUID ( UGUID guid ) #

Searches for a property with the given *.prop file GUID. The returned property can be managed using the methods of the Property class.

Arguments

UGUID guid - Property file GUID.

Return value

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

Property LoadProperty ( string path ) #

Loads a property from the specified *.prop file. The returned property can be managed using the methods of the Property class.

Arguments

string path - Path to the *.prop file to load a property from.

Return value

Property, if it is loaded successfully (an instance of the Property class); otherwise, nullptr.

Property InheritProperty ( UGUID guid, string name = 0, string path = 0 ) #

Inherits a property from the given property and assigns the specified name and path to the new property.

Notice

Without a name the inherited property won't be displayed in the properties hierarchy, without a path it won't be saved when saveProperties() is called.

Arguments

UGUID guid - GUID of the property to inherit from.
string name - Inherited property name.
string path - Path to save the inherited property.

Return value

Property instance if the property with the specified GUID exists or nullptr.

bool RemoveProperty ( UGUID guid, bool remove_file = 0, bool remove_children = 1 ) #

Removes the property with the specified GUID.

Notice

A root property (the property that has no parent) or a non-editable property cannot be removed using this function.

Arguments

UGUID guid - GUID of the property to remove.
bool remove_file - Flag indicating if the corresponding *.prop file will be deleted. Set 1 to delete the file, or 0 to keep it.
bool remove_children - Flag indicating if all children of the property will be deleted. Set 1 to delete all children of the property, or 0 to link all children to the parent.

Return value

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

bool RenameProperty ( UGUID guid, string new_name ) #

Changes the name of the property with the specified GUID.

Notice

The name of the *.prop file is not affected.
This method is not available for the manual and non-editable properties.

Arguments

UGUID guid - GUID of the property to be renamed.
string new_name - New name for the property to be set.

Return value

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

bool ReplaceProperty ( Property property, Property new_property ) #

Replaces the specified property with a new one for all nodes and surfaces. The new property that replaces the specified one must exist. 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

Property property - Property to be replaced.
Property new_property - New property.

Return value

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

bool ReparentProperty ( UGUID guid, UGUID new_parent, bool save_all_values = 0 ) #

Sets a new parent for the specified property. Both properties with given GUIDs must exist.

Notice

The method isn't available for the manual and non-editable properties.

Arguments

UGUID guid - GUID of the property whose parent is to be changed.
UGUID new_parent - GUID of the property to be set as a new parent.
bool save_all_values - Flag indicating if parameter values of the specified property will be saved after reparenting.

Return value

1 if the parent for the property is changed successfully; otherwise, 0.

void ReloadProperties ( ) #

Reloads all *.prop files from all data folders.

NoticeIf new *.prop files are found, they will be loaded automatically. The hierarchy will be rebuilt if necessary, while keeping all overridden parameter values.

int SaveProperties ( ) #

Saves all properties that can be saved to corresponding *.prop files.

Notice

This method will save only the properties that:

are not manual
are editable
have a name (not internal)
have a path

Return value

1 if all properties are saved successfully; otherwise, 0.

IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #

Adds a callback of the specified type. Callback functions can be used to determine actions to be performed when any changes to any property are made. The signature of the callback function must be as follows:

Source code (C++)

void callback_function_name(PropertyPtr property);

Here is an example of tracking property removal via callbacks:

Source code (C#)

public void property_removed(Property property)
{
	Log.Message("Property \"{0}\" was removed.\n", property.Name);
    // ...
}

// somewhere in the code

// inheriting a new property named "my_prop" from the base property "surface_base"
Property property = Properties.FindManualProperty("surface_base").Inherit("my_prop");

// setting our callback function on property removal
Properties.AddCallback(Properties.CALLBACK_REMOVED, property_removed);

// removing the property named "my_prop"
Properties.RemoveProperty(properties.FindProperty("my_prop").GUID);

Arguments

CALLBACK_INDEX callback - Callback type. One of the CALLBACK_* variables.
CallbackDelegate func - Callback function with the following signature: void CallbackDelegate(Property property)

Return value

ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool RemoveCallback ( CALLBACK_INDEX callback, IntPtr id ) #

Removes the specified callback from the list of callbacks of the specified type. Callback functions can be used to determine actions to be performed when any changes to any property are made.

Arguments

CALLBACK_INDEX callback - Callback type. One of the CALLBACK_* variables.
IntPtr id - Callback ID obtained when adding it.

Return value

True if the callback with the given ID was removed successfully; otherwise false.

void ClearCallbacks ( CALLBACK_INDEX callback ) #

Clears all added callbacks of the specified type. Callback functions can be used to determine actions to be performed when any changes to any property are made.

Arguments

CALLBACK_INDEX callback - Callback type. One of the CALLBACK_* variables.

Last update: 2020-07-31

Help improve this article

Was this article helpful?

Report a problem related to this article

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

Unigine.Properties Class

Adding Callbacks#

See Also#

Properties:

Methods:

Variables:

Properties Class

Properties

int NumProperties#

Members

Property GetProperty ( int num ) #

Arguments

Return value

bool IsProperty ( string name ) #

Arguments

Return value

bool IsProperty ( UGUID guid ) #

Arguments

Return value

bool IsManualProperty ( string name ) #

Arguments

Return value

string GetPropertyName ( int num ) #

Arguments

Return value

Property CloneProperty ( UGUID guid, string name = 0, string path = 0 ) #

Arguments

Return value

Property FindProperty ( string name ) #

Arguments

Return value

Property FindManualProperty ( string name ) #

Arguments

Return value

Property FindPropertyByGUID ( UGUID guid ) #

Arguments

Return value

Property FindPropertyByPath ( string path ) #

Arguments

Return value

Property FindPropertyByFileGUID ( UGUID guid ) #

Arguments

Return value

Property LoadProperty ( string path ) #

Arguments

Return value

Property InheritProperty ( UGUID guid, string name = 0, string path = 0 ) #

Arguments

Return value

bool RemoveProperty ( UGUID guid, bool remove_file = 0, bool remove_children = 1 ) #

Arguments

Return value

bool RenameProperty ( UGUID guid, string new_name ) #

Arguments

Return value

bool ReplaceProperty ( Property property, Property new_property ) #

Arguments

Return value

bool ReparentProperty ( UGUID guid, UGUID new_parent, bool save_all_values = 0 ) #

Arguments

Return value

void ReloadProperties ( ) #

int SaveProperties ( ) #

Return value

IntPtr AddCallback ( CALLBACK_INDEX callback, CallbackDelegate func ) #

Arguments

Return value

bool RemoveCallback ( CALLBACK_INDEX callback, IntPtr id ) #

Arguments

Return value

void ClearCallbacks ( CALLBACK_INDEX callback ) #

Arguments