Object Functions

Functions to create, modify, query, and manage metadata, color, description, type, value, and other properties of an object.

MTK_Object_AddMetadataField()

Add a new metadata field with value.

Signature 
int MTK_Object_AddMetadataField(
    MTK_Object* obj,
    const char* name,
    const char* value
    );
Parameters

  • obj: Pointer to an MTK_Object struct.

  • name: The field name (const char*).

  • value: The field value (const char*).
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_HasMetadataField

MTK_Object_ClearMetadata()

Remove all metadata from the object.

Signature 
int MTK_Object_ClearMetadata(MTK_Object* obj);
Parameters

obj: Pointer to an MTK_Object struct.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_RemoveMetadataField_Index

MTK_Object_RemoveMetadataField_Name

MTK_Object_Close()

Clean up the object.

Signature 
int MTK_Object_Close(MTK_Object* object);
Parameters

object: Pointer to an MTK_Object struct.
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetColour()

Get the RGB colour (0 to 255) of an object.

Signature 
int MTK_Object_GetColour(
    MTK_Object* obj,
    int* r, int* g, int* b
    );
Parameters

  • obj: Pointer to an MTK_Object struct.

  • r: Red.

  • g: Green.

  • b: Blue.
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetColourIndex()

Get the colour index of an object.

Signature 
int MTK_Object_GetColourIndex(
    MTK_Object* obj, int* index);
Parameters

  • obj: Pointer to an MTK_Object struct.

  • index: Object colour index (int*).
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetDescription()

Get the name of an object.

Signature 
int MTK_Object_GetDescription(
    MTK_Object* obj, char* desc);
Parameters

  • obj: Pointer to an MTK_Object struct.

  • desc: Buffer of length MTK_BUFFER_SIZE to receive the object description.
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetFeature()

Get the feature name of an object.

Signature 
int MTK_Object_GetFeature(
    MTK_Object* obj, char* feature);
Parameters

  • obj: Pointer to an MTK_Object struct.

  • feature: Buffer of length MTK_BUFFER_SIZE to receive the object feature.
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetGroup()

Get the group of an object.

Signature 
int MTK_Object_GetGroup(
    MTK_Object* obj, char* group);
Parameters

  • obj: Pointer to an MTK_Object struct.

  • group: Buffer of length MTK_BUFFER_SIZE to receive the object group.
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetMetadataFieldIndex()

Get the metadata field index from a specified name.

Signature 
int MTK_Object_GetMetadataFieldIndex(
    MTK_Object* obj,
    const char* field, int* index
    );
Parameters

  • obj: Pointer to an MTK_Object struct.

  • field: The field name.

  • index: Receives the field index.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_GetMetadataFieldValue_Name

MTK_Object_SetMetadataFieldValue_Name

MTK_Object_GetMetadataFieldName()

Get the metadata field name from a specified index.

Signature 
int MTK_Object_GetMetadataFieldName(
    MTK_Object* obj,
    const int& index, char* field
    );
Parameters

  • obj: Pointer to an MTK_Object struct.

  • index: The field index.

  • field: Receives the field name.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_GetMetadataFieldValue_Index

MTK_Object_SetMetadataFieldValue_Index

MTK_Object_GetMetadataFieldValue_Index()

Get the metadata field value from a specified index.

Signature 
int MTK_Object_GetMetadataFieldValue_Index(
    MTK_Object* obj,
    const int& index, char* value
    );
Parameters

  • obj: Pointer to an MTK_Object struct.

  • index: The field index.

  • value: Receives the field value.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_SetMetadataFieldValue_Index

MTK_Object_AddMetadataField

MTK_Object_GetMetadataFieldValue_Name()

Get the metadata field value from a specified name.

Signature 
int MTK_Object_GetMetadataFieldValue_Name(
    MTK_Object* obj,
    const char* name, char* value
    );
Parameters

  • obj: Pointer to an MTK_Object struct.

  • name: The field name.

  • value: Receives the field value.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_SetMetadataFieldValue_Name

MTK_Object_AddMetadataField

MTK_Object_GetName()

Get the name of an object.

Signature 
int MTK_Object_GetName(
    MTK_Object* obj, char* name);
Parameters

  • obj: Pointer to an MTK_Object struct.

  • name: Buffer of length MTK_BUFFER_SIZE to receive the object name.
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetPrimitive()

Get the primitive name of an object.

Signature 
int MTK_Object_GetPrimitive(
    MTK_Object* obj, char* primitive);
Parameters

  • obj: Pointer to an MTK_Object struct.

  • primitive: Buffer of length MTK_BUFFER_SIZE to receive the object primitive.
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetType()

Get the type of an object.

Signature 
int MTK_Object_GetType(
    MTK_Object* obj, MTK_ObjectType* type);
Parameters

  • obj: Pointer to an MTK_Object struct.

  • type: Receives the object type.
Return Value

0 on success; any other value indicates failure.

MTK_Object_GetValue()

Get the value of an object.

Signature 
int MTK_Object_GetValue(
    MTK_Object* obj, double* value);
Parameters

  • obj: Pointer to an MTK_Object struct.

  • value: Receives the object’s numeric value.
Return Value

0 on success; any other value indicates failure.

MTK_Object_HasMetadata()

Checks if the object has metadata.

Signature 
int MTK_Object_HasMetadata(MTK_Object* obj);
Parameters

obj: Pointer to an MTK_Object struct.
Return Value

  • 1 if the object has metadata

  • 0 if the object does not have metadata

  • Any other value: Failure

MTK_Object_HasMetadataField()

Get if an object has a specified metadata field.

Signature 
int MTK_Object_HasMetadataField(
    MTK_Object* obj, const char* field);
Parameters

  • obj: Pointer to an MTK_Object struct

  • field: The field name
Return Value

  • 1 if the object has the field

  • 0 if the object does not have the field

  • Any other value: Failure
See Also

MTK_Object_AddMetadataField

MTK_Object_RemoveMetadataField_Name

MTK_Object_New()

Create a blank MTK_Object that values can be set to.

Signature 
MTK_Object* MTK_Object_New();
Parameters (None)
Return Value

  • Pointer to an empty MTK_Object struct on success

  • Null pointer on failure

MTK_Object_NMetadataFields()

Get the number of metadata fields in an object.

Signature 
int MTK_Object_NMetadataFields(MTK_Object* obj);

Version added: 9.0.0.1030
Parameters

obj: Pointer to an MTK_Object struct.
Return Value

  • Number of metadata fields in the object

  • Below 0: Failure
See Also

MTK_Object_HasMetadata

MTK_Object_RemoveMetadataField_Index()

Remove a metadata field by index.

Signature 
int MTK_Object_RemoveMetadataField_Index(
    MTK_Object* obj, const int& index);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • index: Index of the field to remove.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_HasMetadataField

MTK_Object_ClearMetadata

MTK_Object_RemoveMetadataField_Name()

Remove a metadata field by name.

Signature 
int MTK_Object_RemoveMetadataField_Name(
    MTK_Object* obj, const char* field);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • field: Name of the field to remove.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_HasMetadataField

MTK_Object_ClearMetadata

MTK_Object_SetColour()

Set the colour of an object.

Signature 
int MTK_Object_SetColour(
    MTK_Object* obj, const int& colour);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • colour: Object colour.
Return Value

0 on success; any other value indicates failure.

MTK_Object_SetDescription()

Set the description of an object.

Signature 
int MTK_Object_SetDescription(
    MTK_Object* obj, const char* desc);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • desc: Object description.
Return Value

0 on success; any other value indicates failure.

MTK_Object_SetFeature()

Set the feature of an object.

Signature 
int MTK_Object_SetFeature(
    MTK_Object* obj, const char* feature);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • feature: Object feature.
Return Value

0 on success; any other value indicates failure.

MTK_Object_SetGroup()

Set the group of an object.

Signature 
int MTK_Object_SetGroup(
    MTK_Object* obj, const char* group);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • group: Object group.
Return Value

0 on success; any other value indicates failure.

MTK_Object_SetMetadataFieldValue_Index()

Set the value of a metadata field.

Signature 
int MTK_Object_SetMetadataFieldValue_Index(
    MTK_Object* obj,
    const int& index, const char* value
    );

Version added: 9.0.0.1030
Parameters
  • obj: Pointer to an MTK_Object struct.
  • index: Index of the field to set.
  • value: Desired value.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_GetMetadataFieldValue_Index

MTK_Object_SetMetadataFieldValue_Name()

Set the value of a metadata field.

Signature 
int MTK_Object_SetMetadataFieldValue_Name(
    MTK_Object* obj,
    const char* field, const char* value
    );

Version added: 9.0.0.1030
Parameters
  • obj: Pointer to an MTK_Object struct.
  • field: Name of the field to set.
  • value: Desired value.
Return Value

0 on success; any other value indicates failure.
See Also

MTK_Object_GetMetadataFieldValue_Name

MTK_Object_SetName()

Set the name of an object.

Signature 
int MTK_Object_SetName(
    MTK_Object* obj, const char* name);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • name: Object name.
Return Value

0 on success; any other value indicates failure.

MTK_Object_SetPrimitive()

Set the primitive of an object.

Signature 
int MTK_Object_SetPrimitive(
    MTK_Object* obj, const char* primitive);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • primitive: Object primitive.
Return Value

0 on success; any other value indicates failure.

MTK_Object_SetType()

Set the type of an object. This will clear the object completely. Should usually be called immediately after MTK_Object_New.

Signature 
int MTK_Object_SetType(
    MTK_Object* obj, const MTK_ObjectType& type);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • type: Object type.
Return Value

0 on success; any other value indicates failure.

MTK_Object_SetValue()

Set the value of an object.

Signature 
int MTK_Object_SetValue(
    MTK_Object* obj, const double& value);
Parameters
  • obj: Pointer to an MTK_Object struct.
  • value: Value to assign to the object.
Return Value

0 on success; any other value indicates failure.