rust_constructor/

lib.rs

//! # Rust Constructor V2
//!
//! A cross-platform `GUI` framework built on `egui` as well as compatible with `bevy`, the simplest way to develop `GUI` projects with `Rust`
//!
//! 基于`egui`构建的跨平台`GUI`框架, 同时兼容`bevy`, 用`Rust`开发`GUI`项目最简单的方式
//!
//! ## Overview 概述
//!
//! `Rust Constructor` is a fully functional GUI framework that leverages the power of `egui` to provide
//! a simple and intuitive instrument for building cross-platform applications.
//!
//! `Rust Constructor`是一个功能全面的GUI框架，它利用了`egui`的强大功能，为构建跨平台应用程序提供了一个简单直观的工具。
//!
//! ## Quick Start 快速入门
//!
//! Due to dependency issues, we cannot provide the test cases directly within the code. However, you can
//! find the directly usable code in the `README`.
//!
//! 由于依赖问题，我们无法直接在代码中提供测试用例，你可以在`README`中找到能直接使用的代码。
//!
//! ## Documentation 文档
//!
//! - [Rust Constructor Guide](https://github.com/ChepleBob30/Rust-Constructor-Guide)
//! - [GitHub Repository](https://github.com/ChepleBob30/Rust-Constructor)
//! - [Binder 必达](https://github.com/Binder-organize) - Other projects from our organization 我们组织的其他项目
pub mod advance_front;
pub mod app;
pub mod background;
pub mod basic_front;
#[cfg(all(feature = "standard", feature = "bevy"))]
compile_error!(
    "You cannot use both 'bevy' and 'standard' features simultaneously!
    If you are developing using Rust Constructor independently, please select 'standard'; if you are developing using bevy, please select 'bevy'."
);
#[cfg(not(any(feature = "standard", feature = "bevy")))]
compile_error!(
    "You must enable at least one of the 'bevy' or 'standard' features!
    If you are developing using Rust Constructor independently, please select 'standard'; if you are developing using bevy, please select 'bevy'."
);
use crate::advance_front::BackgroundType;
#[cfg(feature = "bevy")]
use egui_bevy::{Context, Ui};
#[cfg(feature = "standard")]
use egui_standard::Ui;
use std::{
    any::{Any, type_name, type_name_of_val},
    error::Error,
    fmt::{Debug, Display, Formatter},
    time::Instant,
    vec::Vec,
};

/// Core trait for managing Rust Constructor resources uniformly.
///
/// 统一管理Rust Constructor资源的核心特性。
///
/// This trait provides a common interface for all GUI resources in the framework,
/// allowing for the acquisition and modification of specific resources and their details.
///
/// 此特征为框架中的所有GUI资源提供了一个公共接口，允许获取具体资源及其细节并对其进行修改。
///
/// # Thread Safety
///
/// This trait is automatically impl'd for types that implement `Send` and `Sync`,
/// allowing `App` to be used in multi-threaded contexts (e.g., Bevy).
///
/// # 线程安全
///
/// 此特征自动为实现了 `Send` 和 `Sync` 的类型 impl，使 `App` 可以在多线程上下文中使用（例如 Bevy）。
pub trait RustConstructorResource: Debug + Send + Sync {
    /// Returns a reference to the resource as `Any` for extract the specific type.
    ///
    /// 以`Any`返回对资源的引用，用于取出具体类型。
    ///
    /// This allows downcasting to the concrete type when the actual type is known.
    ///
    /// 当实际类型已知时，允许向下转换到具体类型。
    fn as_any(&self) -> &dyn Any;

    /// Returns a mutable reference to the resource as `Any` for extract the specific type.
    ///
    /// 以`Any`返回对资源的可变引用，用于取出具体类型。
    ///
    /// This allows mutable downcasting when the actual type is known.
    ///
    /// 当实际类型已知时，允许向下可变转换到具体类型。
    fn as_any_mut(&mut self) -> &mut dyn Any;

    /// Retrieves the display info field for this resource.
    ///
    /// 取出此资源的显示信息字段。
    ///
    /// Returns `Some(DisplayInfo)` if the resource has display info field,
    /// or `None` if it doesn't have display info field.
    ///
    /// 如果资源具有显示信息字段则返回`Some(DisplayInfo)`，如果资源没有显示信息字段则返回`None`。
    fn display_display_info(&self) -> Option<DisplayInfo>;

    /// Updates the display info field for this resource.
    ///
    /// 更新此资源的显示信息字段。
    fn modify_display_info(&mut self, display_info: DisplayInfo);

    /// Returns all tags associated with this resource.
    ///
    /// 返回与此资源关联的所有标签。
    ///
    /// Tags are stored as key-value pairs (`[String; 2]`) and can be used
    /// for categorization, filtering, or metadata storage.
    ///
    /// 标签以键值对（`[String; 2]`）的形式存储，可用于分类、过滤或元数据存储。
    fn display_tags(&self) -> Vec<[String; 2]>;

    /// Updates the tags for this resource.
    ///
    /// 更新此资源的标签。
    ///
    /// # Arguments
    ///
    /// * `replace` - If `true`, replaces all existing tags;
    ///   if `false`, merges with existing tags.
    ///
    /// # 参数
    ///
    /// * `replace` - 若为`true`，则替换所有现有的标签；
    ///   若为`false`，则与现有标签合并。
    fn modify_tags(&mut self, tags: &[[String; 2]], replace: bool);
}

/// Trait for managing basic front resources that are displayed to the user.
///
/// 用于管理显示给用户的基本前端资源的特征。
///
/// This trait extends `RustConstructorResource` with additional methods specific
/// to visual elements.
///
/// 此特征扩展了`RustConstructorResource`，添加了特定视觉元素的方法。
pub trait BasicFrontResource: RustConstructorResource {
    /// Returns the complete basic resource config.
    ///
    /// 返回完整的基本前端资源配置。
    ///
    /// This includes both position/size config and clipping information.
    ///
    /// 包括位置/大小配置和裁剪信息。
    fn display_basic_front_resource_config(&self) -> BasicFrontResourceConfig;

    /// Returns the position and size config for this resource.
    ///
    /// 返回此资源的位置和大小配置。
    ///
    /// Includes grid-based positioning, alignment settings, and offset values.
    ///
    /// 包括基于网格的定位、对齐设置和偏移值。
    fn display_position_size_config(&self) -> PositionSizeConfig;

    /// Returns the clipping rectangle config if this resource has one.
    ///
    /// 返回裁剪矩形配置（如果此资源有的话）。
    ///
    /// Clipping rectangles define the visible area of the resource.
    ///
    /// 裁剪矩形定义资源的可见区域。
    ///
    /// Returns `None` if no clipping is applied.
    ///
    /// 如果没有应用裁剪矩形，则返回`None`。
    fn display_clip_rect(&self) -> Option<PositionSizeConfig>;

    /// Returns the current display position of the resource.
    ///
    /// 返回资源的当前显示位置。
    ///
    /// The position is returned as `[x, y]` coordinates.
    ///
    /// 位置以`[x, y]`坐标返回。
    fn display_position(&self) -> [f32; 2];

    /// Returns the current display size of the resource.
    ///
    /// 返回资源的当前显示大小。
    ///
    /// The size is returned as `[width, height]`.
    ///
    /// 大小以`[width, height]`返回。
    fn display_size(&self) -> [f32; 2];

    /// Updates the complete basic resource config.
    ///
    /// 更新完整的前端资源配置。
    fn modify_basic_front_resource_config(
        &mut self,
        basic_front_resource_config: BasicFrontResourceConfig,
    );

    /// Updates the position and size config.
    ///
    /// 更新位置和大小配置。
    fn modify_position_size_config(&mut self, position_size_config: PositionSizeConfig);

    /// Updates the clipping rectangle config.
    ///
    /// 更新裁剪矩形配置。
    fn modify_clip_rect(&mut self, clip_rect: Option<PositionSizeConfig>);
}

/// Unique identifier for Rust Constructor resources.
///
/// Rust Constructor资源的唯一标识符。
///
/// This struct combines a resource name and type to create a unique identifier
/// that can be used to reference resources throughout the application.
///
/// 这个结构体结合了资源名称和类型来创建一个唯一的标识符，可以在整个应用程序中用来引用资源。
#[derive(Debug, Default, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct RustConstructorId {
    /// Unique name identifying the resource instance, Resources of different
    /// types can have the same name.
    ///
    /// 标识资源实例的唯一名称，不同类型的资源可以重名。
    pub name: String,

    /// Type of the resource (e.g., `Image`).
    ///
    /// 资源的类型（例如`Image`）。
    pub discern_type: String,
}

/// Container for Rust Constructor resources with type-erased storage.
///
/// 具有类型擦除存储的Rust Constructor资源的容器。
///
/// This struct pairs a resource identifier with the actual resource content,
/// allowing for heterogeneous storage of different resource types while
/// maintaining the ability to identify and manage them individually.
///
/// 这个结构体将资源标识符与实际资源内容配对，允许不同资源类型的异构存储，同时保持单独识别和管理它们的能力。
///
/// # Type Erasure 类型擦除
///
/// The `content` field uses a `Box<dyn RustConstructorResource>` to store
/// any type that implements the `RustConstructorResource` trait, enabling
/// polymorphic behavior and storage.
///
/// `content`字段使用`Box<dyn RustConstructorResource>`来存储任何实现`RustConstructorResource`
/// 特征的类型，从而启用多态行为和存储。
#[derive(Debug)]
pub struct RustConstructorResourceBox {
    /// Unique identifier for the contained resource.
    ///
    /// 所包含资源的唯一标识符。
    pub id: RustConstructorId,

    /// Type-erased resource content.
    ///
    /// 类型擦除的资源内容。
    pub content: Box<dyn RustConstructorResource>,
}

unsafe impl Send for RustConstructorResourceBox {}

unsafe impl Sync for RustConstructorResourceBox {}

impl RustConstructorResourceBox {
    pub fn new(name: &str, discern_type: &str, content: Box<dyn RustConstructorResource>) -> Self {
        Self {
            id: RustConstructorId {
                name: name.to_string(),
                discern_type: discern_type.to_string(),
            },
            content,
        }
    }
}

/// Config for basic front resources.
///
/// 基本前端资源的配置。
///
/// This struct contains all the essential config needed for positioning,
/// sizing, and clipping visual elements in the GUI.
///
/// 这个结构体包含了在GUI中定位、调整大小和裁剪可视元素所需的所有配置。
#[derive(Debug, Default, Clone, PartialEq, PartialOrd)]
pub struct BasicFrontResourceConfig {
    /// Config for position, size, and layout properties.
    ///
    /// 位置、大小和布局属性的配置。
    pub position_size_config: PositionSizeConfig,

    /// Optional clipping rectangle that defines the visible area.
    /// If `None`, the resource is rendered without clipping.
    ///
    /// 可选的裁剪矩形，用于定义可见区域。如果为`None`，则渲染资源时不进行裁剪。
    pub clip_rect: Option<PositionSizeConfig>,
}

impl BasicFrontResourceConfig {
    #[inline]
    pub fn position_size_config(mut self, position_size_config: PositionSizeConfig) -> Self {
        self.position_size_config = position_size_config;
        self
    }

    #[inline]
    pub fn clip_rect(mut self, clip_rect: Option<PositionSizeConfig>) -> Self {
        self.clip_rect = clip_rect;
        self
    }
}

/// Config for positioning and sizing resources in a flexible grid system.
///
/// 用于在灵活的网格系统中定位和调整资源大小的配置。
///
/// This struct provides comprehensive control over how resources are positioned
/// and sized within the GUI, supporting grid-based layouts with multiple alignment options.
///
/// 这个结构体提供了对GUI中资源如何定位和大小的全面控制，支持具有多种对齐选项的基于网格的布局。
///
/// # Grid System 网格系统
///
/// The grid system allows for relative positioning and sizing using fractions of
/// the available space, making layouts responsive and adaptable to different screen sizes.
///
/// 网格系统允许使用可用空间的一部分进行相对定位和大小调整，使布局响应并适应不同的屏幕尺寸。
#[derive(Debug, Copy, Clone, PartialEq, PartialOrd)]
pub struct PositionSizeConfig {
    /// Absolute position coordinates in pixels (`[x, y]`).
    ///
    /// 以像素为单位的绝对位置坐标（`[x, y]`）。
    pub origin_position: [f32; 2],

    /// Absolute size dimensions in pixels (`[width, height]`).
    ///
    /// 以像素为单位的绝对尺寸（`[width, height]`）。
    pub origin_size: [f32; 2],

    /// Grid-based X-axis positioning (`[numerator, denominator]`).
    ///
    /// 基于网格的x轴定位（`[numerator, denominator]`）。
    ///
    /// Position = (total_width * numerator / denominator)
    ///
    /// 位置 = （总宽度 * 分子 / 分母）
    pub x_location_grid: [f32; 2],

    /// Grid-based Y-axis positioning (`[numerator, denominator]`).
    ///
    /// 基于网格的y轴定位（`[numerator, denominator]`）。
    ///
    /// Position = (total_height * numerator / denominator)
    ///
    /// 位置 = （总高度 * 分子 / 分母）
    pub y_location_grid: [f32; 2],

    /// Grid-based X-axis sizing (`[numerator, denominator]`).
    ///
    /// 基于网格的x轴缩放（`[numerator, denominator]`）。
    ///
    /// Width = (total_width * numerator / denominator)
    ///
    /// 宽度 = （总宽度 * 分子 / 分母）
    pub x_size_grid: [f32; 2],

    /// Grid-based Y-axis sizing (`[numerator, denominator]`).
    ///
    /// 基于网格的y轴缩放（`[numerator, denominator]`）。
    ///
    /// Height = (total_height * numerator / denominator)
    ///
    /// 高度 = （总高度 * 分子 / 分母）
    pub y_size_grid: [f32; 2],

    /// Horizontal and vertical alignment methods.
    ///
    /// 水平和垂直对齐方法。
    pub display_method: (HorizontalAlign, VerticalAlign),

    /// Additional offset in pixels (`[x_offset, y_offset]`).
    ///
    /// 额外的像素偏移量（`[x_offset, y_offset]`）。
    pub offset: [f32; 2],
}

impl Default for PositionSizeConfig {
    fn default() -> Self {
        PositionSizeConfig {
            origin_position: [0_f32, 0_f32],
            origin_size: [0_f32, 0_f32],
            x_location_grid: [0_f32, 0_f32],
            y_location_grid: [0_f32, 0_f32],
            x_size_grid: [0_f32, 0_f32],
            y_size_grid: [0_f32, 0_f32],
            display_method: (HorizontalAlign::default(), VerticalAlign::default()),
            offset: [0_f32, 0_f32],
        }
    }
}

impl PositionSizeConfig {
    #[inline]
    pub fn origin_position(mut self, x: f32, y: f32) -> Self {
        self.origin_position = [x, y];
        self
    }

    #[inline]
    pub fn origin_size(mut self, width: f32, height: f32) -> Self {
        self.origin_size = [width, height];
        self
    }

    #[inline]
    pub fn x_size_grid(mut self, fetch: f32, total: f32) -> Self {
        self.x_size_grid = [fetch, total];
        self
    }

    #[inline]
    pub fn y_size_grid(mut self, fetch: f32, total: f32) -> Self {
        self.y_size_grid = [fetch, total];
        self
    }

    #[inline]
    pub fn x_location_grid(mut self, fetch: f32, total: f32) -> Self {
        self.x_location_grid = [fetch, total];
        self
    }

    #[inline]
    pub fn y_location_grid(mut self, fetch: f32, total: f32) -> Self {
        self.y_location_grid = [fetch, total];
        self
    }

    #[inline]
    pub fn display_method(
        mut self,
        horizontal_align: HorizontalAlign,
        vertical_align: VerticalAlign,
    ) -> Self {
        self.display_method = (horizontal_align, vertical_align);
        self
    }

    #[inline]
    pub fn offset(mut self, x: f32, y: f32) -> Self {
        self.offset = [x, y];
        self
    }
}

/// Timer for tracking application and page runtimes.
///
/// 用于跟踪应用程序和页面运行时间的计时器。
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Timer {
    /// Time when the current page was entered, in milliseconds.
    ///
    /// 进入当前页面的时间（毫秒）。
    pub start_time: u128,

    /// Total runtime of the application since start, in milliseconds.
    ///
    /// 应用程序自启动以来的总运行时间（毫秒）。
    pub total_time: u128,

    /// Core timer instance for precise timing.
    ///
    /// 用于精确计时的核心计时器实例。
    pub timer: Instant,

    /// Runtime of the current page, in milliseconds.
    ///
    /// 当前页面的运行时间（毫秒）。
    pub now_time: u128,
}

impl Default for Timer {
    fn default() -> Self {
        Timer {
            start_time: 0,
            total_time: 0,
            timer: Instant::now(),
            now_time: 0,
        }
    }
}

/// Error type for Rust Constructor framework.
///
/// Rust Constructor框架的错误类型。
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct RustConstructorError {
    /// Identifier for the error type.
    ///
    /// 错误类型的标识符。
    pub error_id: String,

    /// Description of the error.
    ///
    /// 对此错误的描述。
    pub description: String,
}

impl Display for RustConstructorError {
    fn fmt(&self, f: &mut Formatter) -> std::fmt::Result {
        Debug::fmt(self, f)
    }
}

impl Error for RustConstructorError {}

/// Horizontal alignment options for UI elements.
///
/// UI元素的水平对齐选项。
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum HorizontalAlign {
    /// Align to the left.
    ///
    /// 左对齐。
    #[default]
    Left,
    /// Center align horizontally.
    ///
    /// 居中对齐。
    Center,
    /// Align to the right.
    ///
    /// 右对齐。
    Right,
}

/// Vertical alignment options for UI elements.
///
/// UI元素的垂直对齐选项。
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum VerticalAlign {
    /// Align to the top.
    ///
    /// 顶部对齐。
    #[default]
    Top,
    /// Center align vertically.
    ///
    /// 居中对齐。
    Center,
    /// Align to the bottom.
    ///
    /// 底部对齐。
    Bottom,
}

/// Defines the placement of borders relative to the element's bounds.
///
/// 定义边框相对于元素边界的放置方式。
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum BorderKind {
    /// Border is drawn inside the element's bounds, reducing the content area.
    ///
    /// 边框在元素边界内部绘制，减少内容区域。
    #[default]
    Inside,
    /// Border is centered on the element's bounds, half inside and half outside.
    ///
    /// 边框以元素边界为中心，一半在内部一半在外部。
    Middle,
    /// Border is drawn outside the element's bounds, preserving the content area.
    ///
    /// 边框在元素边界外部绘制，保持内容区域不变。
    Outside,
}

/// Config for rendering.
///
/// 渲染的配置。
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub enum RenderConfig {
    /// Line with width and color.
    ///
    /// 线段，包含宽度和颜色。
    Line(f32, [u8; 4]),
    /// Rectangle with corner radius, fill color, border color, border width, and border kind.
    ///
    /// 矩形，包含圆角半径，填充颜色，边框颜色，边框宽度，边框类型。
    Rect([u8; 4], [u8; 4], [u8; 4], f32, BorderKind),
}

/// Display config for resources, controlling visibility and rendering behavior.
///
/// 资源的显示配置，控制可见性和渲染行为。
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct DisplayInfo {
    /// Enables or disables the resource. If false, the resource is not processed.
    ///
    /// 启用或禁用资源。如果为false，资源不会被处理。
    pub enable: bool,

    /// Hides the resource visually but keeps it active for event handling.
    ///
    /// 隐藏资源视觉显示但保持其事件处理活性。
    pub hidden: bool,

    /// If true, the resource ignores the rendering layer and does not occupy the mouse focus.
    ///
    /// 如果为true，资源忽略渲染层，不占用鼠标焦点。
    pub ignore_render_layer: bool,
}

/// The lookup method for requesting resources to skip the rendering queue.
///
/// 请求资源跳过渲染队列的查找方法。
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum RequestMethod {
    /// Request by resource identifier.
    ///
    /// 按资源标识符请求。
    Id(RustConstructorId),
    /// Request by resource citer.
    ///
    /// 通过资源引用者请求。
    Citer(RustConstructorId),
}

/// Types of rendering layer requests.
///
/// 渲染层请求类型。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum RequestType {
    /// Move resource to the top layer.
    ///
    /// 移动资源到顶层。
    Top,
    /// Move resource up by specified number of layers.
    ///
    /// 按指定层数向上移动资源。
    Up(usize),
}

/// Methods for describing list information.
///
/// 用于描述列表信息的方法。
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum ListInfoDescribeMethod {
    /// Detailed display including resource and ID (with optional formatting).
    ///
    /// 详细显示，包括资源和ID（可选格式）。
    Detailed(bool),
    /// Simple display showing only resource IDs.
    ///
    /// 简单显示，只显示资源ID。
    #[default]
    Simple,
}

/// Methods for compatibility with different versions of egui.
///
/// 用于兼容不同版本egui的方法。
///
/// Use when you need to call egui::Context.
///
/// 需要调用egui::Context时使用。
///
/// # Arguments
///
/// * `ui` - The UI context for drawing
///
/// # Returns
///
/// Return Ui directly.
///
/// # 参数
///
/// * `ui` - 用于绘制的UI上下文
///
/// # 返回值
///
/// 直接返回Ui。
#[cfg(feature = "standard")]
pub fn ctx_adapter(ui: &mut Ui) -> &mut Ui {
    ui
}
/// Methods for compatibility with different versions of egui.
///
/// 用于兼容不同版本egui的方法。
///
/// Use when you need to call egui::Context.
///
/// 需要调用egui::Context时使用。
///
/// # Arguments
///
/// * `ui` - The UI context for drawing
///
/// # Returns
///
/// Return Context.
///
/// # 参数
///
/// * `ui` - 用于绘制的UI上下文
///
/// # 返回值
///
/// 返回Context。
#[cfg(feature = "bevy")]
pub fn ctx_adapter(ui: &mut Ui) -> &Context {
    ui.ctx()
}

/// Obtain the type name of the target resource.
///
/// 获取目标资源的类型名称。
///
/// # Arguments
///
/// * `target` - Target resource
///
/// # Returns
///
/// Returns the type name of the target resource.
///
/// # 参数
///
/// * `target` - 目标资源
///
/// # 返回值
///
/// 目标资源的类型名称。
pub fn type_processor(target: &impl RustConstructorResource) -> String {
    let result: Vec<_> = if let Some(list) = type_name_of_val(target).split_once("<") {
        list.0
    } else {
        type_name_of_val(&target)
    }
    .split("::")
    .collect();
    result[result.len() - 1].to_string()
}

/// Gets a tag value from the specified tag list by name.
///
/// 从指定标签列表中根据名称获取标签值。
///
/// # Arguments
///
/// * `tag_name` - The name of the tag to retrieve
/// * `target` - The list of tags to search through
///
/// # Returns
///
/// Returns `Some((index, value))` if the tag is found, or `None` if not found.
///
/// # 参数
///
/// * `tag_name` - 要检索的标签名称
/// * `target` - 要搜索的标签列表
///
/// # 返回值
///
/// 如果找到标签则返回`Some((索引, 值))`，否则返回`None`。
pub fn get_tag(tag_name: &str, target: &[[String; 2]]) -> Option<(usize, String)> {
    target
        .iter()
        .position(|x| x[0] == tag_name)
        .map(|index| (index, target[index][1].clone()))
}

/// Safely convert resource references to references of specific types of resources.
///
/// 安全地将资源引用转换为具体类型资源的引用。
///
/// When using the traversal method to retrieve resources, it should be combined with this method to obtain
/// the reference of the specific type of resource.
///
/// 当采用遍历的方式取出资源时，应和此方法配合来获取具体类型的资源引用。
///
/// # Arguments
///
/// * `resource` - Reference to resources
///
/// # Returns
///
/// Return a reference to the specific type of resource on success; otherwise, return `Err(RustConstructorError)`.
///
/// # 参数
///
/// * `resource` - 资源的引用
///
/// # 返回值
///
/// 成功时返回具体类型资源的引用，否则返回`Err(RustConstructorError)`。
pub fn downcast_resource<T: RustConstructorResource + 'static>(
    resource: &dyn RustConstructorResource,
) -> Result<&T, RustConstructorError> {
    if let Some(resource) = resource.as_any().downcast_ref::<T>() {
        Ok(resource)
    } else {
        Err(RustConstructorError {
            error_id: "ResourceDowncastTypeMismatch".to_string(),
            description: format!(
                "Failed to downcast resource to type '{}'.",
                type_name::<T>()
            ),
        })
    }
}

/// Safely convert mutable references to resources to mutable references to resources of specific types.
///
/// 安全地将资源可变引用转换为具体类型资源的可变引用。
///
/// When using the traversal method to retrieve resources, it should be combined with this method to obtain
/// the mutable reference of the specific type of resource.
///
/// 当采用遍历的方式取出资源时，应和此方法配合来获取具体类型的资源可变引用。
///
/// # Arguments
///
/// * `resource` - Mutable reference to resources
///
/// # Returns
///
/// Return a mutable reference to the specific type of resource on success; otherwise, return `Err(RustConstructorError)`.
///
/// # 参数
///
/// * `resource` - 资源的可变引用
///
/// # 返回值
///
/// 成功时返回具体类型资源的可变引用，否则返回`Err(RustConstructorError)`。
pub fn downcast_resource_mut<T: RustConstructorResource + 'static>(
    resource: &mut dyn RustConstructorResource,
) -> Result<&mut T, RustConstructorError> {
    if let Some(resource) = resource.as_any_mut().downcast_mut::<T>() {
        Ok(resource)
    } else {
        Err(RustConstructorError {
            error_id: "ResourceDowncastTypeMismatch".to_string(),
            description: format!(
                "Failed to downcast resource to type '{}'.",
                type_name::<T>()
            ),
        })
    }
}

/// Processes position and size calculations for resources.
///
/// 处理资源的最基本位置和尺寸计算。
///
/// This method handles the complex positioning logic including grid-based layout,
/// alignment, and offset calculations for UI resources.
///
/// 此方法处理复杂的定位逻辑，包括基于网格的布局、对齐方式和UI资源的偏移计算。
///
/// # Arguments
///
/// * `position_size_config` - The configuration for position and size
/// * `ui` - The UI context for drawing
///
/// # Returns
///
/// Returns `[position, size]` as computed from the configuration
///
/// # 参数
///
/// * `position_size_config` - 位置和尺寸的配置
/// * `ui` - 用于绘制的UI上下文
///
/// # 返回值
///
/// 返回根据配置计算出的 `[位置, 尺寸]`
pub fn position_size_processor(position_size_config: PositionSizeConfig, ui: &Ui) -> [[f32; 2]; 2] {
    let mut position = [0_f32, 0_f32];
    let mut size = [0_f32, 0_f32];
    size[0] = match position_size_config.x_size_grid[0] {
        0_f32 => position_size_config.origin_size[0],
        _ => {
            (ui.available_width() / position_size_config.x_size_grid[1]
                * position_size_config.x_size_grid[0])
                + position_size_config.origin_size[0]
        }
    };
    size[1] = match position_size_config.y_size_grid[0] {
        0_f32 => position_size_config.origin_size[1],
        _ => {
            (ui.available_height() / position_size_config.y_size_grid[1]
                * position_size_config.y_size_grid[0])
                + position_size_config.origin_size[1]
        }
    };
    position[0] = match position_size_config.x_location_grid[1] {
        0_f32 => position_size_config.origin_position[0],
        _ => {
            (ui.available_width() / position_size_config.x_location_grid[1]
                * position_size_config.x_location_grid[0])
                + position_size_config.origin_position[0]
        }
    };
    position[1] = match position_size_config.y_location_grid[1] {
        0_f32 => position_size_config.origin_position[1],
        _ => {
            (ui.available_height() / position_size_config.y_location_grid[1]
                * position_size_config.y_location_grid[0])
                + position_size_config.origin_position[1]
        }
    };
    match position_size_config.display_method.0 {
        HorizontalAlign::Left => {}
        HorizontalAlign::Center => position[0] -= size[0] / 2.0,
        HorizontalAlign::Right => position[0] -= size[0],
    };
    match position_size_config.display_method.1 {
        VerticalAlign::Top => {}
        VerticalAlign::Center => position[1] -= size[1] / 2.0,
        VerticalAlign::Bottom => position[1] -= size[1],
    };
    position[0] += position_size_config.offset[0];
    position[1] += position_size_config.offset[1];
    [position, size]
}

/// Map a [`BackgroundType`] to its discriminant string for resource lookups.
///
/// 将[`BackgroundType`]映射为其判别字符串，用于资源查找。
#[inline]
pub fn background_type_discern(background_type: &BackgroundType) -> &'static str {
    match background_type {
        BackgroundType::CustomRect(_) => "CustomRect",
        BackgroundType::Image(_) => "Image",
    }
}

/// Build a [`RustConstructorId`] from a name and discern type.
///
/// 从名称和辨别类型构建[`RustConstructorId`]。
#[inline]
pub fn build_id(name: impl Into<String>, discern_type: impl Into<String>) -> RustConstructorId {
    RustConstructorId {
        name: name.into(),
        discern_type: discern_type.into(),
    }
}