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 c5157bd849
commit 52580a4382
Signed by: folling
SSH key fingerprint: SHA256:S9qEx5WCFFLK49tE/LKnKuJYM5sw+++Dn6qJbbyxnCY
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