Ikarus/libikarus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

finalise interface & documentation

Browse source 
Signed-off-by: Folling <mail@folling.io>
This commit is contained in:
Folling 2023-11-06 13:14:39 +01:00 • committed by Folling
parent 521c61c8fb
commit eb1f414fc4
No known key found for this signature in database
56 changed files with 2074 additions and 780 deletions
Download patch file Download diff file Expand all files Collapse all files

199
include/ikarus/objects/property.h
View file

@ -1,17 +1,16 @@
#pragma once
// IMPLEMENTATION_DETAIL_LAZY_VALUE_CREATION, IMPLEMENTATION_DETAIL_PROPERTY_TYPES
// IMPLEMENTATION_DETAIL_LAZY_VALUE_CREATION
/// \file property.h
/// \author Folling <mail@folling.io>
/// \author Folling <folling@ikarus.world>
#include <ikarus/id.h>
#include <ikarus/macros.h>
#include <ikarus/objects/blueprint.h>
#include <ikarus/objects/entity.h>
#include <ikarus/objects/property_type.h>
/// \defgroup properties Properties
/// \brief Properties define the structure and types of data.
/// @{
IKARUS_BEGIN_HEADER
@ -50,23 +49,181 @@ IKARUS_BEGIN_HEADER
/// 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 {
/// \private \brief The id of the property.
IkarusId id;
};
struct IkarusProperty;
/// \brief The type of a property.
/// \details Designates the type of data stored by the property as well as which settings are
/// available.
/// \see IkarusPropertySettings
enum IkarusPropertyType {
/// \brief A true/false boolean-like value.
IkarusPropertyType_Toggle,
/// \brief An arbitrary numeric value.
IkarusPropertyType_Number,
/// \brief An arbitrary textual value.
IkarusPropertyType_Text,
};
/// \brief Creates a property
/// \param project The project the property is part of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param property_source The property source the property is part of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param parent_folder The parent folder of the property.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param position The position of the property in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \param name The name of the property.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param property_info The info of the property.
/// \pre \li Must not be null.
/// \return The created property or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusProperty * ikarus_property_create(
struct IkarusProject * project,
struct IkarusPropertySource * property_source,
struct IkarusPropertyFolder * parent_folder,
size_t position,
char const * name,
struct IkarusPropertyTypeInfo * property_info
);
/// \brief Copies a property.
/// \details Creates a deep copy of the property including all of its settings and associated values.
/// \param property The property to copy.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param source The source to copy the property to.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param parent_folder The parent folder of the property.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param position The position of the property in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \param name The name of the property.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \return The created property or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusProperty * ikarus_property_copy(
struct IkarusProperty * property,
struct IkarusPropertySource * source,
struct IkarusPropertyFolder * parent_folder,
size_t position,
char const * name
);
/// \brief Deletes a property.
/// \param property The property to delete.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \remark The property must not be accessed after deletion.
IKA_API void ikarus_property_delete(struct IkarusProperty * property);
/// \brief Gets the project of a property.
/// \param property The property to get the project of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The project of the property or null if an error occurs.
IKA_API struct IkarusProject * ikarus_property_get_project(IkarusProperty const * property);
/// \brief Gets the parent folder of a property.
/// \param property The property to get the parent folder of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The parent folder of the property or null if an error occurs.
IKA_API struct IkarusPropertyFolder * ikarus_property_get_parent(IkarusProperty const * property);
/// \brief Gets the position of a property within its parent folder.
/// \param property The property to get the position of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The position of the property or undefined if an error occurs.
IKA_API size_t ikarus_property_get_position(IkarusProperty const * property);
/// \brief Gets the name of a property.
/// \param property The property to get the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The name of the property or null if an error occurs.
/// \remark The returned pointer is valid until the property is freed but may be invalidated by other operations.
IKA_API char const * ikarus_property_get_name(IkarusProperty const * property);
/// \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.
/// \return The type info of the property or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusPropertyTypeInfo * ikarus_property_get_type_info(IkarusProperty const * property);
/// \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.
/// \return The source of the property or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusPropertySource * ikarus_property_get_source(IkarusProperty const * property);
/// \brief Gets the default value of a property.
/// \param property The property to get the default value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \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);
/// \brief Sets the parent folder of a property.
/// \param property The property to set the parent folder of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_parent The new parent folder of the property.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_position The new position of the property in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \remark This adjusts the positions of old and new siblings.
IKA_API void ikarus_property_set_parent(
IkarusProperty * property, struct IkarusPropertyFolder * new_parent, size_t new_position
);
/// \brief Sets the position of a property within its parent folder.
/// \param property The property to set the position of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_position The new position of the property. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \remark This adjusts the positions of siblings.
IKA_API void ikarus_property_set_position(IkarusProperty * property, size_t new_position);
/// \brief Sets the name of a property.
/// \param property The property to set the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_name The new name of the property.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
IKA_API void ikarus_property_set_name(IkarusProperty * property, char const * new_name);
/// \brief Sets the type info of a property and resets all values to the new default value.
/// \param property The property to set the type info of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_type The new type info of the property.
/// \param attempt_conversion Whether to attempt to convert the property's values to the new type info. Conversion rules are
/// unspecified for now, but follow common sense.
IKA_API void ikarus_property_set_type_info(
IkarusProperty * property, struct IkarusPropertyTypeInfo new_type_info, bool attempt_conversion
);
/// \brief Converts a property to an object.
/// \param property The property to convert.
/// \return The constructed object, representing the property.
IKA_API struct IkarusObject * ikarus_property_to_object(IkarusProperty const * property);
/// \brief Compares two properties.
/// \param left The left property to compare.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param right The right property to compare.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return True if the two properties are equal, false otherwise.
/// \remark This neither performs a pointer comparison nor a deep comparison. When we say "equal" we mean that the two
/// properties reference the same property in the same project.
IKA_API bool ikarus_property_is_equal(IkarusProperty const * left, IkarusProperty const * right);
IKARUS_END_HEADER