script_event.h

Go to the documentation of this file.

/**
 * @file addons/script_event.h
 * @brief Mouse and keyboard events for Flecs script.
 */
 
#ifdef FLECS_SCRIPT_EVENT
 
#ifndef FLECS_SCRIPT
#define FLECS_SCRIPT
#endif
 
#ifndef FLECS_SCRIPT_ASYNC
#define FLECS_SCRIPT_ASYNC
#endif
 
/**
 * @defgroup c_addons_script_event Script Event
 * @ingroup c_addons
 * Mouse and keyboard events for Flecs script.
 * @{
 */
 
#ifndef FLECS_SCRIPT_EVENT_H
#define FLECS_SCRIPT_EVENT_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
/** Mouse event.
 * The application resolves the entity under the pointer, passes it as target
 * and provides local_x and local_y relative to that entity. An event is
 * delivered to its target only; when ecs_script_mouse_event() returns true the
 * application propagates the event to the parent of the target by calling it
 * again with the parent as target and coordinates relative to the parent. A
 * propagated event keeps the same screen position and button state.
 *
 * The module derives the kind of event from the button state of the previous
 * event: buttons that were not held produce press and drag, moving with a
 * held button produces drag (delivered to the pressed entity and its parents),
 * buttons that are no longer held produce release, and click when the target
 * is still the pressed entity. Moving without buttons produces move. When the
 * target changes, leave is delivered to the entities that are no longer under
 * the pointer and enter to the entities that newly are, so that moving
 * between children of an entity does not leave and enter the entity.
 */
typedef struct EcsScriptMouseEvent {
    ecs_entity_t target; /**< Entity under the pointer, 0 if none. */
 
    float screen_x;    /**< X position in window coordinates. */
    float screen_y;    /**< Y position in window coordinates. */
 
    float local_x;     /**< X position relative to the target. */
    float local_y;     /**< Y position relative to the target. */
 
    float delta_x;     /**< Horizontal movement since the previous event. */
    float delta_y;     /**< Vertical movement since the previous event. */
 
    int32_t button;    /**< Button that changed state: 0=left, 1=middle, 2=right. */
    uint32_t buttons;  /**< Bitmask of buttons that are held down. */
 
    bool ctrl;         /**< Control key is held down. */
    bool shift;        /**< Shift key is held down. */
    bool alt;          /**< Alt/Option key is held down. */
    bool meta;         /**< Meta (Command/Windows) key is held down. */
} EcsScriptMouseEvent;
 
/** Keyboard event.
 * Keyboard events are delivered to the entity that received the last mouse
 * press and to its parents.
 */
typedef struct EcsScriptKeyboardEvent {
    char *key;         /**< Key value, for example "a", "Enter" or "ArrowLeft". Not owned. */
    bool down;         /**< True when the key was pressed, false when released. */
    bool repeat;       /**< Event was generated by key auto-repeat. */
 
    bool ctrl;         /**< Ctrl key is held down. */
    bool shift;        /**< Shift key is held down. */
    bool alt;          /**< Alt/Option key is held down. */
    bool meta;         /**< Meta (Command/Windows) key is held down. */
} EcsScriptKeyboardEvent;
 
FLECS_API
extern ECS_COMPONENT_DECLARE(EcsScriptMouseEvent);
 
FLECS_API
extern ECS_COMPONENT_DECLARE(EcsScriptKeyboardEvent);
 
/** Emit mouse event.
 * Resolves the on.press, on.drag, on.release, on.click, on.move, on.enter and
 * on.leave calls that wait for the event on its target and resumes the async
 * blocks that became ready. When delta_x and delta_y are both zero they are
 * computed from the previous event.
 *
 * @param world The world.
 * @param evt The event.
 * @return Whether the event should be propagated to the parent of the target.
 */
FLECS_API
bool ecs_script_mouse_event(
    ecs_world_t *world,
    const EcsScriptMouseEvent *evt);
 
/** Emit keyboard event.
 * Resolves the on.key_down and on.key_up calls that wait for the event and
 * resumes the async blocks that became ready.
 *
 * @param world The world.
 * @param evt The event.
 */
FLECS_API
void ecs_script_keyboard_event(
    ecs_world_t *world,
    const EcsScriptKeyboardEvent *evt);
 
/** Script event import function.
 * Usage:
 * @code
 * ECS_IMPORT(world, FlecsScriptEvent)
 * @endcode
 *
 * @param world The world.
 */
FLECS_API
void FlecsScriptEventImport(
    ecs_world_t *world);
 
#ifdef __cplusplus
}
#endif
 
#endif
 
/** @} */
 
#endif