// Copyright © SixtyFPS GmbH <info@slint.dev>
// SPDX-License-Identifier: MIT

/**
 * @file slint-safeui.h
 * @brief Public API provided by the SlintSafeUi library to C firmware.
 *
 * These functions are implemented in Rust and exported via `#[no_mangle]`.
 * This header is manually maintained (not generated by cbindgen) because
 * the surface is small and the build dependency is not justified for a
 * safety-critical project.
 *
 * For the functions that C firmware must **implement** (the platform
 * interface), see slint-safeui-platform-interface.h.
 *
 * For the FFI event types used with slint_safeui_dispatch_event(), see
 * slint-safeui-event.h.
 */

#ifndef SLINT_SAFEUI_H
#define SLINT_SAFEUI_H

#include "slint-safeui-event.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Schedule a callback to run on the Slint event loop thread.
 *
 * This is the primary mechanism for C firmware code (including ISR handlers)
 * to execute logic on the main Slint thread. The callback will be invoked
 * with the provided `user_data` pointer during the next event loop iteration.
 *
 * ISR-safe: no heap allocation, no blocking, no FPU usage.
 *
 * @param callback       Function to call on the Slint event loop thread.
 * @param user_data      Opaque pointer passed through to callback. May be NULL.
 * @param drop_user_data Called to free user_data. May be NULL.
 * @return 0 on success, -1 if the queue is full (callback dropped).
 */
int slint_safeui_invoke_from_event_loop(void (*callback)(void *user_data), void *user_data,
                                        void (*drop_user_data)(void *user_data));

/**
 * Push an input event into the Slint event queue.
 *
 * ISR-safe: no heap allocation, no blocking, no FPU usage.
 *
 * @param event Pointer to a fully initialized FfiEvent (read-only, copied).
 *              Must not be NULL.
 * @return 0 on success, -1 if event is NULL or the queue is full (event
 *         dropped).
 */
int slint_safeui_dispatch_event(const FfiEvent *event);

#ifdef __cplusplus
}
#endif

#endif /* SLINT_SAFEUI_H */
