//! Callback types for the Azul UI framework.

//!

//! This module defines the callback infrastructure used by the event system,

//! layout engine, and virtual view rendering. Key design patterns:

//!

//! - **Core vs Layout callback split**: `CoreCallbackType` and

//!   `CoreRenderImageCallbackType` store function pointers as `usize` to avoid

//!   circular dependencies between `azul-core` and `azul-layout`. The actual

//!   function pointer types are defined in `azul-layout` and transmuted at

//!   invocation time.

//!

//! - **FFI callable pattern**: Callback structs carry an optional

//!   `ctx: OptionRefAny` field that holds a foreign callable (e.g. a Python

//!   function object). The `extern "C"` trampoline stored in `cb` extracts

//!   both the user data and the foreign callable from `RefAny` and dispatches

//!   the call. Native Rust code sets `ctx` to `None`.

//!

//! - **Info structs**: `LayoutCallbackInfo`, `VirtualViewCallbackInfo`, and

//!   the layout-side `CallbackInfo` provide read-only access to framework

//!   resources (fonts, images, GL context, window size) during callback

//!   invocation.

#[cfg(not(feature = "std"))]

use alloc::string::ToString;

use alloc::{alloc::Layout, boxed::Box, collections::BTreeMap, sync::Arc, vec::Vec};

use core::{

    ffi::c_void,

    fmt,

    sync::atomic::{AtomicUsize, Ordering as AtomicOrdering},

};

#[cfg(feature = "std")]

use std::hash::Hash;

use azul_css::{

    css::{CssPath, CssPropertyValue},

    props::{

        basic::{

            AnimationInterpolationFunction, FontRef, InterpolateResolver, LayoutRect, LayoutSize,

        },

        property::{CssProperty, CssPropertyType},

    },

    system::SystemStyle,

    AzString,

};

use rust_fontconfig::{FcFontCache, OwnedFontSource};

use crate::{

    dom::{Dom, DomId, DomNodeId, EventFilter, OptionDom},

    geom::{LogicalPosition, LogicalRect, LogicalSize, OptionLogicalPosition, PhysicalSize},

    gl::OptionGlContextPtr,

    hit_test::OverflowingScrollNode,

    id::{NodeDataContainer, NodeDataContainerRef, NodeDataContainerRefMut, NodeId},

    prop_cache::CssPropertyCache,

    refany::{OptionRefAny, RefAny},

    resources::{

        DpiScaleFactor, FontInstanceKey, IdNamespace, ImageCache, ImageMask, ImageRef,

        RendererResources,

    },

    styled_dom::{

        NodeHierarchyItemId, NodeHierarchyItemVec, StyledNode,

        StyledNodeVec,

    },

    task::{

        Duration as AzDuration, GetSystemTimeCallback, Instant as AzInstant, Instant,

        TerminateTimer, ThreadId, ThreadReceiver, ThreadSendMsg, TimerId,

    },

    window::{

        AzStringPair, KeyboardState, MouseState, OptionChar, RawWindowHandle, UpdateFocusWarning,

        WindowFlags, WindowSize, WindowTheme,

    },

    FastBTreeSet, OrderedMap,

};

/// Specifies if the screen should be updated after the callback function has returned

#[repr(C)]

#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]

pub enum Update {

    /// The screen does not need to redraw after the callback has been called

    DoNothing,

    /// After the callback is called, the screen needs to redraw (layout() function being called

    /// again)

    RefreshDom,

    /// The layout has to be re-calculated for all windows

    RefreshDomAllWindows,

}

impl Update {

}

// -- layout callback

/// Callback function pointer (has to be a function pointer in

/// order to be compatible with C APIs later on).

///

/// IMPORTANT: The callback needs to deallocate the `RefAnyPtr` and `LayoutCallbackInfoPtr`,

/// otherwise that memory is leaked. If you use the official auto-generated

/// bindings, this is already done for you.

///

/// NOTE: The original callback was `fn(&self, LayoutCallbackInfo) -> Dom`

/// which then evolved to `fn(&RefAny, LayoutCallbackInfo) -> Dom`.

/// The indirection is necessary because of the memory management

/// around the C API

///

/// The memory management across the callback boundary is handled by

/// the caller (see `LayoutCallback` and `LayoutCallbackInfo`).

pub type LayoutCallbackType = extern "C" fn(RefAny, LayoutCallbackInfo) -> crate::dom::Dom;

/// Wrapper around the layout callback

///

/// For FFI languages (Python, Java, etc.), the RefAny contains both:

/// - The user's application data

/// - The callback function object from the foreign language

///

/// The trampoline function (stored in `cb`) knows how to extract both

/// from the RefAny and invoke the foreign callback with the user data.

#[repr(C)]

pub struct LayoutCallback {

    pub cb: LayoutCallbackType,

    /// For FFI: stores the foreign callable (e.g., PyFunction)

    /// Native Rust code sets this to None

    pub ctx: OptionRefAny,

}

impl_callback!(LayoutCallback, LayoutCallbackType);

impl LayoutCallback {

}

// Host-invoker plumbing for managed-FFI bindings (Lua, Ruby, Perl, …):

// expands to a static `az_layout_callback_thunk` (the `cb` we hand to the

// framework when the host calls `LayoutCallback::create_from_host_handle`),

// an `AzLayoutCallback_createFromHostHandle` C-ABI export, plus the

// `AzApp_setLayoutCallbackInvoker` setter the host calls once at module

// load. See `crate::host_invoker` for the design.

crate::impl_managed_callback! {

    wrapper:        LayoutCallback,

    info_ty:        LayoutCallbackInfo,

    return_ty:      crate::dom::Dom,

    default_ret:    crate::dom::Dom::create_body(),

    invoker_static: LAYOUT_CALLBACK_INVOKER,

    invoker_ty:     AzLayoutCallbackInvoker,

    thunk_fn:       az_layout_callback_thunk,

    setter_fn:      AzApp_setLayoutCallbackInvoker,

    from_handle_fn: AzLayoutCallback_createFromHostHandle,

}

impl Default for LayoutCallback {

}

// -- virtualized view callback

pub type VirtualViewCallbackType = extern "C" fn(RefAny, VirtualViewCallbackInfo) -> VirtualViewReturn;

/// Callback that, given a rectangle area on the screen, returns the DOM

/// appropriate for that bounds (useful for infinite lists)

#[repr(C)]

pub struct VirtualViewCallback {

    pub cb: VirtualViewCallbackType,

    /// For FFI: stores the foreign callable (e.g., PyFunction)

    /// Native Rust code sets this to None

    pub ctx: OptionRefAny,

}

impl_callback!(VirtualViewCallback, VirtualViewCallbackType);

// Host-invoker plumbing for VirtualViewCallback. See `crate::host_invoker`.

crate::impl_managed_callback! {

    wrapper:        VirtualViewCallback,

    info_ty:        VirtualViewCallbackInfo,

    return_ty:      VirtualViewReturn,

    default_ret:    VirtualViewReturn::default(),

    invoker_static: VIRTUAL_VIEW_CALLBACK_INVOKER,

    invoker_ty:     AzVirtualViewCallbackInvoker,

    thunk_fn:       az_virtual_view_callback_thunk,

    setter_fn:      AzApp_setVirtualViewCallbackInvoker,

    from_handle_fn: AzVirtualViewCallback_createFromHostHandle,

}

impl VirtualViewCallback {

}

/// Reason why a VirtualView callback is being invoked.

///

/// This helps the callback optimize its behavior based on why it's being called.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[repr(C, u8)]

pub enum VirtualViewCallbackReason {

    /// Initial render - first time the VirtualView appears

    InitialRender,

    /// Parent DOM was recreated (cache invalidated)

    DomRecreated,

    /// Window/VirtualView bounds expanded beyond current scroll_size

    BoundsExpanded,

    /// Scroll position is near an edge (within `EDGE_THRESHOLD`, currently 200px)

    EdgeScrolled(EdgeType),

    /// Scroll position extends beyond current scroll_size

    ScrollBeyondContent,

}

/// Which edge triggered a scroll-based re-invocation

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum EdgeType {

    Top,

    Bottom,

    Left,

    Right,

}

#[derive(Debug)]

#[repr(C)]

pub struct VirtualViewCallbackInfo {

    pub reason: VirtualViewCallbackReason,

    pub system_fonts: *const FcFontCache,

    pub image_cache: *const ImageCache,

    pub window_theme: WindowTheme,

    pub bounds: HidpiAdjustedBounds,

    pub scroll_size: LogicalSize,

    pub scroll_offset: LogicalPosition,

    pub virtual_scroll_size: LogicalSize,

    pub virtual_scroll_offset: LogicalPosition,

    /// Pointer to the callable (OptionRefAny) for FFI language bindings (Python, etc.)

    /// Set by the caller before invoking the callback. Native Rust callbacks have this as null.

    callable_ptr: *const OptionRefAny,

    /// Extension for future ABI stability (mutable data)

    _abi_mut: *mut c_void,

}

impl Clone for VirtualViewCallbackInfo {

}

impl VirtualViewCallbackInfo {

    /// Set the callable pointer for FFI language bindings

    /// Get the callable for FFI language bindings (Python, etc.)

        } else {

        }

}

/// Return value for a VirtualView rendering callback.

///

/// Contains two size/offset pairs for lazy loading and virtualization:

///

/// - `scroll_size` / `scroll_offset`: Size and position of actually rendered content

/// - `virtual_scroll_size` / `virtual_scroll_offset`: Size for scrollbar representation

///

/// The callback is re-invoked on: initial render, parent DOM recreation, window expansion

/// beyond `scroll_size`, or scrolling near content edges (`EDGE_THRESHOLD`, currently 200px).

///

/// Return `OptionDom::None` to keep the current DOM and only update scroll bounds.

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct VirtualViewReturn {

    /// The DOM with actual rendered content, or None to keep current DOM.

    ///

    /// - `OptionDom::Some(dom)` - Replace current content with this new DOM

    /// - `OptionDom::None` - Keep using the previous DOM, only update scroll bounds

    ///

    /// Returning `None` is an optimization when the callback determines that the

    /// current content is sufficient (e.g., already rendered ahead of scroll position).

    pub dom: OptionDom,

    /// Size of the actual rendered content rectangle.

    ///

    /// This is the size of the content in the `dom` field (if Some). It may be smaller than

    /// `virtual_scroll_size` if only a subset of content is rendered (virtualization).

    ///

    /// **Example**: For a table showing rows 10-30, this might be 600px tall

    /// (20 rows x 30px each).

    pub scroll_size: LogicalSize,

    /// Offset of the actual rendered content within the virtual coordinate space.

    ///

    /// This positions the rendered content within the larger virtual space. For

    /// virtualized content, this will be non-zero to indicate where the rendered

    /// "window" starts.

    ///

    /// **Example**: For a table showing rows 10-30, this might be y=300

    /// (row 10 starts 300px from the top).

    pub scroll_offset: LogicalPosition,

    /// Size of the virtual content rectangle (for scrollbar sizing).

    ///

    /// This is the size the scrollbar will represent. It can be much larger than

    /// `scroll_size` to enable lazy loading and virtualization.

    ///

    /// **Example**: For a 1000-row table, this might be 30,000px tall

    /// (1000 rows x 30px each), even though only 20 rows are actually rendered.

    pub virtual_scroll_size: LogicalSize,

    /// Offset of the virtual content (usually zero).

    ///

    /// This is typically `(0, 0)` since the virtual space usually starts at the origin.

    /// Advanced use cases might use this for complex virtualization scenarios.

    pub virtual_scroll_offset: LogicalPosition,

}

impl Default for VirtualViewReturn {

}

impl VirtualViewReturn {

    /// Creates a new VirtualViewReturn with updated DOM content.

    ///

    /// Use this when the callback has rendered new content to display.

    ///

    /// # Arguments

    /// - `dom` - The new DOM to render

    /// - `scroll_size` - Size of the actual rendered content

    /// - `scroll_offset` - Position of rendered content in virtual space

    /// - `virtual_scroll_size` - Size for scrollbar representation

    /// - `virtual_scroll_offset` - Usually `LogicalPosition::zero()`

    /// Creates a return value that keeps the current DOM unchanged.

    ///

    /// Use this when the callback determines that the existing content

    /// is sufficient (e.g., already rendered ahead of scroll position).

    /// This is an optimization to avoid rebuilding the DOM unnecessarily.

    ///

    /// # Arguments

    /// - `scroll_size` - Size of the current rendered content

    /// - `scroll_offset` - Position of current content in virtual space

    /// - `virtual_scroll_size` - Size for scrollbar representation

    /// - `virtual_scroll_offset` - Usually `LogicalPosition::zero()`

}

// --  thread callback

// -- timer callback

#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct TimerCallbackReturn {

    pub should_update: Update,

    pub should_terminate: TerminateTimer,

}

impl TimerCallbackReturn {

    /// Creates a new TimerCallbackReturn with the given update and terminate flags.

    /// Timer continues running, no DOM update needed.

    /// Timer continues running and DOM should be refreshed.

    /// Timer should stop, no DOM update needed.

    /// Timer should stop and DOM should be refreshed.

}

impl Default for TimerCallbackReturn {

}

/// Gives the `layout()` function access to the `RendererResources` and the `Window`

/// (for querying images and fonts, as well as width / height)

#[derive(Debug)]

#[repr(C)]

/// Reference data container for LayoutCallbackInfo (all read-only fields)

///

/// This struct consolidates all readonly references that layout callbacks need to query state.

/// By grouping these into a single struct, we reduce the number of parameters to

/// LayoutCallbackInfo::new() from 6 to 2, making the API more maintainable and easier to extend.

///

/// This is pure syntax sugar - the struct lives on the stack in the caller and is passed by

/// reference.

pub struct LayoutCallbackInfoRefData<'a> {

    /// Allows the layout() function to reference image IDs

    pub image_cache: &'a ImageCache,

    /// OpenGL context so that the layout() function can render textures

    pub gl_context: &'a OptionGlContextPtr,

    /// Reference to the system font cache

    pub system_fonts: &'a FcFontCache,

    /// Platform-specific system style (colors, spacing, etc.)

    /// Used for CSD rendering and menu windows.

    pub system_style: Arc<SystemStyle>,

    /// Active route match (if routing is configured).

    /// Contains the matched pattern and extracted parameters.

    pub active_route: Option<&'a crate::resources::RouteMatch>,

}

/// What triggered the current `layout()` invocation.

///

/// The framework re-invokes the layout callback for any change that may

/// produce a structurally different DOM (resize across a CSS breakpoint,

/// theme toggle, route switch, callback returning `Update::RefreshDom`).

/// `LayoutCallbackInfo::relayout_reason()` exposes which trigger this

/// particular call corresponds to so the callback can branch — for

/// example, skip expensive analytics on `Resize` calls.

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub enum RelayoutReason {

    /// First layout call for this window.

    Initial,

    /// A user callback returned `Update::RefreshDom`.

    RefreshDom,

    /// Window size changed across a CSS breakpoint or DPI scale change.

    /// The callback can branch on `info.window_width_*` to emit a

    /// different tree (e.g. hamburger menu vs sidebar).

    Resize,

    /// System theme changed (light/dark).

    ThemeChange,

    /// `CallbackInfo::switch_route` or `set_route_param` produced a new

    /// route match. The callback should branch on

    /// `info.get_active_route()`.

    RouteChange,

    /// Catch-all for relayouts that don't fit one of the above categories.

    Other,

}

impl Default for RelayoutReason {

}

#[repr(C)]

pub struct LayoutCallbackInfo {

    /// Single reference to all readonly reference data

    /// This consolidates 4 individual parameters into 1, improving API ergonomics

    ref_data: *const LayoutCallbackInfoRefData<'static>,

    /// Window size (so that apps can return a different UI depending on

    /// the window size - mobile / desktop view). Should be later removed

    /// in favor of "resize" handlers and @media queries.

    pub window_size: WindowSize,

    /// Registers whether the UI is dependent on the window theme

    pub theme: WindowTheme,

    /// What triggered this `layout()` call. Read via `relayout_reason()`.

    pub relayout_reason: RelayoutReason,

    /// Pointer to the callable (OptionRefAny) for FFI language bindings (Python, etc.)

    /// Set by the caller before invoking the callback. Native Rust callbacks have this as null.

    callable_ptr: *const OptionRefAny,

    /// Extension for future ABI stability (mutable data)

    _abi_mut: *mut core::ffi::c_void,

}

impl Clone for LayoutCallbackInfo {

}

impl core::fmt::Debug for LayoutCallbackInfo {

}

impl LayoutCallbackInfo {

    /// Returns what triggered the current `layout()` invocation.

    /// Set the callable pointer for FFI language bindings

    /// Get the callable for FFI language bindings (Python, etc.)

        } else {

        }

    /// Get a clone of the system style Arc

                }

    /// Get the active route match (pattern + extracted parameters).

    ///

    /// Returns `None` if no routes are configured or no route is active.

    /// Get a route parameter by key (e.g. `get_route_param("id")` for `/user/:id`).

    ///

    /// Returns `None` if no route is active or the parameter doesn't exist.

    // Responsive layout helper methods

    /// Returns true if the window width is less than the given pixel value

    /// Returns true if the window width is greater than the given pixel value

    /// Returns true if the window width is between min and max (inclusive)

    /// Returns true if the window height is less than the given pixel value

    /// Returns true if the window height is greater than the given pixel value

    /// Returns true if the window height is between min and max (inclusive)

    /// Returns the current window width in pixels

    /// Returns the current window height in pixels

    /// Returns the current window DPI scale factor (1.0 = 96 DPI, 2.0 = 192 DPI)

}

/// Information about the bounds of a laid-out div rectangle.

///

/// Necessary when invoking `VirtualViewCallbacks` and `RenderImageCallbacks`, so

/// that they can change what their content is based on their size.

#[derive(Debug, Copy, Clone)]

#[repr(C)]

pub struct HidpiAdjustedBounds {

    pub logical_size: LogicalSize,

    pub hidpi_factor: DpiScaleFactor,

}

impl HidpiAdjustedBounds {

    #[inline(always)]

}

/// Defines the focus_targeted node ID for the next frame

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C, u8)]

pub enum FocusTarget {

    Id(DomNodeId),

    Path(FocusTargetPath),

    Previous,

    Next,

    First,

    Last,

    NoFocus,

}

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct FocusTargetPath {

    pub dom: DomId,

    pub css_path: CssPath,

}

// -- normal callback

// core callback types (usize-based placeholders)

//

// These types use `usize` instead of function pointers to avoid creating

// a circular dependency between azul-core and azul-layout.

//

// The actual function pointers will be stored in azul-layout, which will

// use unsafe code to transmute between usize and the real function pointers.

//

// IMPORTANT: The memory layout must be identical to the real types!

//

// Naming convention: "Core" prefix indicates these are the low-level types

/// Core callback type - uses usize instead of function pointer to avoid circular dependencies.

///

/// **IMPORTANT**: This is NOT actually a usize at runtime - it's a function pointer that is

/// cast to usize for storage in the data model. When invoking the callback, this usize is

/// unsafely cast back to the actual function pointer type:

/// `extern "C" fn(RefAny, CallbackInfo) -> Update`

///

/// This design allows azul-core to store callbacks without depending on azul-layout's CallbackInfo

/// type. The actual function pointer type is defined in azul-layout as `CallbackType`.

pub type CoreCallbackType = usize;

/// Stores a callback as usize (actually a function pointer cast to usize)

///

/// **IMPORTANT**: The `cb` field stores a function pointer disguised as usize to avoid

/// circular dependencies between azul-core and azul-layout. When creating a CoreCallback,

/// you can directly assign a function pointer - Rust will implicitly cast it to usize.

/// When invoking, the usize must be unsafely cast back to the function pointer type.

///

/// Must return an `Update` that denotes if the screen should be redrawn.

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct CoreCallback {

    pub cb: CoreCallbackType,

    /// For FFI: stores the foreign callable (e.g., PyFunction)

    /// Native Rust code sets this to None

    pub ctx: OptionRefAny,

}

/// Allow creating CoreCallback from a raw function pointer (as usize)

/// Sets callable to None (for native Rust/C usage)

impl From<CoreCallbackType> for CoreCallback {

}

impl_option!(

    CoreCallback,

    OptionCoreCallback,

    [Debug, Eq, Clone, PartialEq, PartialOrd, Ord, Hash]

);

/// Data associated with a callback (event filter, callback, and user data)

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct CoreCallbackData {

    pub event: EventFilter,

    pub callback: CoreCallback,

    pub refany: RefAny,

}

impl_option!(

    CoreCallbackData,

    OptionCoreCallbackData,

    copy = false,

    [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl_vec!(CoreCallbackData, CoreCallbackDataVec, CoreCallbackDataVecDestructor, CoreCallbackDataVecDestructorType, CoreCallbackDataVecSlice, OptionCoreCallbackData);

impl_vec_clone!(

    CoreCallbackData,

    CoreCallbackDataVec,

    CoreCallbackDataVecDestructor

);

impl_vec_mut!(CoreCallbackData, CoreCallbackDataVec);

impl_vec_debug!(CoreCallbackData, CoreCallbackDataVec);

impl_vec_partialord!(CoreCallbackData, CoreCallbackDataVec);

impl_vec_ord!(CoreCallbackData, CoreCallbackDataVec);

impl_vec_partialeq!(CoreCallbackData, CoreCallbackDataVec);

impl_vec_eq!(CoreCallbackData, CoreCallbackDataVec);

impl_vec_hash!(CoreCallbackData, CoreCallbackDataVec);

impl CoreCallbackDataVec {

    #[inline]

    #[inline]

}

// -- image rendering callback

/// Image rendering callback type - uses usize instead of function pointer

pub type CoreRenderImageCallbackType = usize;

/// Callback that returns a rendered OpenGL texture (usize placeholder)

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct CoreRenderImageCallback {

    pub cb: CoreRenderImageCallbackType,

    /// For FFI: stores the foreign callable (e.g., PyFunction)

    /// Native Rust code sets this to None

    pub ctx: OptionRefAny,

}

/// Allow creating CoreRenderImageCallback from a raw function pointer (as usize)

/// Sets callable to None (for native Rust/C usage)

impl From<CoreRenderImageCallbackType> for CoreRenderImageCallback {

}

/// Image callback with associated data

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct CoreImageCallback {

    pub refany: RefAny,

    pub callback: CoreRenderImageCallback,

}

impl_option!(

    CoreImageCallback,

    OptionCoreImageCallback,

    copy = false,

    [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);