#pragma once

/// \file entity_folder.h
/// \author Folling <folling@ikarus.world>

#include <ikarus/macros.h>

/// \addtogroup entities Entities
/// @{

IKARUS_BEGIN_HEADER

/// \brief A entity folder, storing entities and other entity folders.
struct IkarusEntityFolder;

/// \brief Creates a entity folder.
/// \param project The project the entity folder is part of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param parent The parent folder of the entity folder.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param position The position of the entity folder in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \param name The name of the entity folder.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \return The created entity folder or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API IkarusEntityFolder * ikarus_entity_folder_create(
    struct IkarusProject * project, IkarusEntityFolder * parent, size_t position, char const * name
);

/// \brief Copies a entity folder.
/// \details Creates a copy of the entity folder without its children.
/// \param entity_folder The entity folder to copy.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param parent The parent folder of the entity folder.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param position The position of the entity folder in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \param name The name of the entity folder.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \return The created entity folder or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API IkarusEntityFolder * ikarus_entity_folder_copy(
    IkarusEntityFolder * entity_folder, IkarusEntityFolder * parent, size_t position, char const * name
);

/// \brief Deletes a entity folder and all its children
/// \param entity_folder The entity folder to delete.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param keep_children If true, the children of the entity folder will be moved to the parent folder.
IKA_API void ikarus_entity_folder_delete(IkarusEntityFolder * entity_folder, bool keep_children);

/// \brief Gets the project of a entity folder.
/// \param entity_folder The entity folder to get the project of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The project of the entity folder or null if an error occurs.
IKA_API struct IkarusProject * ikarus_entity_folder_get_project(IkarusEntityFolder const * entity_folder);

/// \brief Gets the parent folder of a entity folder.
/// \param entity_folder The entity folder to get the parent folder of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The parent folder of the entity folder or null if an error occurs.
IKA_API struct IkarusEntityFolder * ikarus_entity_folder_get_parent(IkarusEntityFolder const * entity_folder);

/// \brief Gets the position of a entity folder within its parent folder.
/// \param entity_folder The entity folder to get the position of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The position of the entity folder or undefined if an error occurs.
IKA_API size_t ikarus_entity_folder_get_position(IkarusEntityFolder const * entity_folder);

/// \brief Gets the name of a entity folder.
/// \param entity_folder The entity folder to get the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The name of the entity folder or null if an error occurs.
/// \remark The returned pointer is valid until the entity folder is freed but may be invalidated by other operations.
IKA_API char const * ikarus_entity_folder_get_name(IkarusEntityFolder const * entity_folder);

/// \brief Gets the number of children of a entity folder.
/// \param entity_folder The entity folder to get the number of children of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The number of children or undefined if an error occurs.
IKA_API size_t ikarus_entity_folder_get_child_count(IkarusEntityFolder const * entity_folder);

/// \brief Gets the children of a entity folder.
/// \param entity_folder The entity folder to get the children of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param children_out The buffer to write the children to.
/// \pre \li Must not be null.
/// \param children_out_size The size of the buffer.
IKA_API void ikarus_entity_folder_get_children(
    IkarusEntityFolder const * entity_folder, struct IkarusEntityTreeItem ** children_out, size_t children_out_size
);

/// \brief Sets the parent folder of an entity folder.
/// \param entity_folder The entity folder 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 entity folder.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_position The new position of the entity folder 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_entity_folder_set_parent(
    IkarusEntityFolder * entity_folder, struct IkarusEntityFolder * new_parent, size_t new_position
);

/// \brief Sets the position of an entity folder within its parent folder.
/// \param entity_folder The entity folder to set the position of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_position The new position of the entity folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \remark This adjusts the positions of siblings.
IKA_API void ikarus_entity_folder_set_position(IkarusEntityFolder * entity_folder, size_t new_position);

/// \brief Sets the name of an entity folder.
/// \param entity_folder The entity folder to set the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_name The new name of the entity folder.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
IKA_API void ikarus_entity_folder_set_name(IkarusEntityFolder * entity_folder, char const * new_name);

/// \brief Converts a entity folder to a generic folder.
/// \param entity_folder The entity folder to convert.
/// \return The constructed folder, representing the entity folder.
IKA_API struct IkarusFolder * ikarus_entity_folder_to_folder(IkarusEntityFolder const * entity_folder);

/// \brief Converts a entity folder to an object.
/// \param entity_folder The entity folder to convert.
/// \return The constructed object, representing the entity folder.
IKA_API struct IkarusObject * ikarus_entity_folder_to_object(IkarusEntityFolder const * entity_folder);

IKARUS_END_HEADER

// @}