135 lines
5.9 KiB
C
135 lines
5.9 KiB
C
#pragma once
|
|
|
|
/// \file property.h
|
|
/// \author Folling <folling@ikarus.world>
|
|
|
|
#include <ikarus/errors.h>
|
|
#include <ikarus/macros.h>
|
|
#include <ikarus/objects/properties/property_type.h>
|
|
#include <ikarus/stdtypes.h>
|
|
|
|
/// \defgroup properties Properties
|
|
/// \brief Properties define the structure and types of data.
|
|
/// @{
|
|
|
|
IKARUS_BEGIN_HEADER
|
|
|
|
/// \brief Properties are the placeholders of values for entities.
|
|
/// \details Each entity can have any number of properties.
|
|
/// Every property has a type that identifies the kind of data that can be put in.
|
|
///
|
|
/// The following types currently exist:
|
|
/// - Toggle: A true/false boolean-like value
|
|
/// - Number: An arbitrary numeric value
|
|
/// - Text: An arbitrary textual value
|
|
///
|
|
/// Property Examples:
|
|
/// - Is Dead (Toggle)
|
|
/// - Age (Number)
|
|
/// - ISBN (Text)
|
|
///
|
|
/// Every property has settings which can be used to customise the property further.
|
|
/// Two settings that are shared among all properties are the following:
|
|
/// - List
|
|
/// - May be undefined
|
|
///
|
|
/// Additionally, each property has a default value. If no default value is provided, a sensible default is chosen.
|
|
/// Setting a default value that isn't valid for the property is an error. Changing settings so that the current default
|
|
/// value becomes invalid is valid but unsets the custom default value.
|
|
///
|
|
/// The former transforms a property into a list. Instead of one number, you could then specify a series of numbers.
|
|
/// The latter allows you to specify an "unknown" value for a property.
|
|
/// It might not be known if a character is dead or not for example.
|
|
///
|
|
/// Each entity associated with the property has a value for it.
|
|
///
|
|
/// Properties can also be added to blueprints in which case they are available for all entities associated with the
|
|
/// blueprint.
|
|
///
|
|
/// We call properties within entities "Entity Properties" and properties within blueprints "Blueprint Properties".
|
|
///
|
|
///
|
|
/// \remark Properties are scoped to the blueprint or entity they are associated with.
|
|
/// \remark Values for properties are lazily created as space saving measure.
|
|
/// Fetching the value for some property of some entity will return the property's default value if none is specified.
|
|
/// This default value is specified when the property is created and can be updated later.
|
|
/// \remark Properties' tree structures are scoped to the entity or blueprint they are associated with.
|
|
struct IkarusProperty;
|
|
|
|
/// \brief Deletes a property.
|
|
/// \param property The property to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \remark The property must not be accessed after deletion.
|
|
IKA_API void ikarus_property_delete(IkarusProperty * property, IkarusErrorData * error_out);
|
|
|
|
/// \brief Gets the type info of a property.
|
|
/// \param property The property to get the type info of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The type info of the property or null if an error occurs.
|
|
IKA_API IkarusPropertyType ikarus_property_get_type(IkarusProperty const * property, IkarusErrorData * error_out);
|
|
|
|
/// \brief Gets the source of a property.
|
|
/// \param property The property to get the source of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The source of the property or null if an error occurs.
|
|
/// \remark Must be freed using #ikarus_free.
|
|
IKA_API struct IkarusPropertyScope const * ikarus_property_get_scope(IkarusProperty const * property, IkarusErrorData * error_out);
|
|
|
|
/// \brief Gets the default value of a property.
|
|
/// \param property The property to get the type info of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The default value of the property or null if an error occurs.
|
|
/// \remark Must be freed using #ikarus_free.
|
|
IKA_API struct IkarusValue * ikarus_property_get_default_value(IkarusProperty const * property, IkarusErrorData * error_out);
|
|
|
|
/// \brief Visits a property. Calling the appropriate function for the property's type.
|
|
/// \param property The property to visit.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param toggle_property_visitor The function to call if the property is a toggle property. Skipped if null.
|
|
/// \param number_property_visitor The function to call if the property is a number property. Skipped if null.
|
|
/// \param text_property_visitor The function to call if the property is a text property. Skipped if null.
|
|
/// \param data The data to pass to the functions.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_property_visit(
|
|
IkarusProperty * property,
|
|
void (*toggle_property_visitor)(struct IkarusToggleProperty *, void *),
|
|
void (*number_property_visitor)(struct IkarusNumberProperty *, void *),
|
|
void (*text_property_visitor)(struct IkarusTextProperty *, void *),
|
|
void * data,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \see ikarus_property_visit
|
|
IKA_API void ikarus_property_visit_const(
|
|
IkarusProperty const * property,
|
|
void (*toggle_property_visitor)(struct IkarusToggleProperty const *, void *),
|
|
void (*number_property_visitor)(struct IkarusNumberProperty const *, void *),
|
|
void (*text_property_visitor)(struct IkarusTextProperty const *, void *),
|
|
void * data,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Casts a property to an object.
|
|
/// \param property The property to cast.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The property represented as an object or null if an error occurs.
|
|
/// \remark This operation is guaranteed to be very fast and is intended to be used frequently.
|
|
IKA_API struct IkarusObject * ikarus_property_to_object(IkarusProperty * property, IkarusErrorData * error_out);
|
|
|
|
/// \see ikarus_property_to_object
|
|
IKA_API struct IkarusObject const * ikarus_property_to_object_const(IkarusProperty const * property, IkarusErrorData * error_out);
|
|
|
|
IKARUS_END_HEADER
|
|
|
|
// @}
|