SuperAPI AI 工具集

makepad-2.0-events

编程与开发

查看项目

更新于 10-16 02:03

技能介绍

用途

本技能用于 Makepad 2.0 的事件与动作处理。Makepad 2.0 采用双层事件系统,本技能说明如何在这两层中编写事件处理逻辑,并通过桥接宏让两层互通。适合在使用 Makepad 2.0 构建界面时处理点击、渲染、输入、定时器、网络响应等事件。

主要能力

双层事件系统

Splash 层:直接在 script_mod! Splash 代码中编写内联事件处理器(on_click、on_render、on_return、on_startup),以声明式方式处理 UI 交互,位置靠近控件定义。

Rust 层:通过 MatchEvent trait 及 handle_actions、handle_timer、handle_http_response 等方法处理业务逻辑、外部 I/O 以及需要完整 Rust 能力的逻辑。

两层通过两个桥接宏通信:

  • script_eval!(cx, { ... }) —— 从 Rust 执行 Splash 代码(更新状态、触发渲染)。
  • script_apply_eval!(cx, widget_ref, { ... }) —— 从 Rust 在运行时补丁控件属性。

Splash 内联事件处理器

  • on_click:按钮或可点击控件被点击时触发。普通按钮无参数;CheckBox 通过 |checked| 传入新的布尔状态。
  • on_render:调用目标视图的 .render() 时触发,是动态内容的主要机制,其主体替换视图上一次的绘制内容。关键点:on_render 不会自动调用,必须显式调用 ui.widget_name.render();视图上的 new_batch: true 表示重新渲染前清除先前的绘制内容。
  • on_return:用户在 TextInput 中按下 Enter/Return 时触发,常用于提交表单。
  • on_startup:应用启动时触发一次,定义在 Root 层,常用于触发初始渲染。

在事件处理器内可调用 Splash 函数、读取/设置控件值、触发重新渲染、触发其他控件的点击、修改状态变量、使用数组方法和控制流。

Rust 事件处理 —— MatchEvent trait

MatchEvent trait 是 Rust 侧的事件分发器,接收平台事件和控件动作,包含以下处理函数:生命周期(handle_startup、handle_shutdown、handle_foreground、handle_background、handle_pause、handle_resume)、窗口焦点(handle_window_got_focus、handle_window_lost_focus)、帧(handle_next_frame)、控件动作(handle_action、handle_actions)、输入(handle_key_down、handle_key_up、handle_back_pressed)、定时器(handle_timer)、绘制(handle_draw、handle_draw_2d)、网络(handle_http_response、handle_http_request_error、handle_http_progress、handle_http_stream、handle_http_stream_complete)、信号(handle_signal)、媒体设备(handle_audio_devices、handle_midi_ports、handle_video_inputs)。

每个 Makepad 2.0 应用需要标准 Rust 结构:app_main!(App)、script_mod!、impl App::run、带 #[derive(Script, ScriptHook)] 的 App 结构体、impl MatchEvent、impl AppMain。关键点:handle_event 必须同时调用 self.match_event(cx, event)(分发到 MatchEvent 处理器)和 self.ui.handle_event(cx, event, &mut Scope::empty())(将事件传播给控件)。

控件 Action API

从 Rust 用 self.ui.widget_type(cx, ids!(name)) 访问控件,再传入 &Actions 引用查询其动作状态:

  • Button:clicked、pressed、long_pressed、released、clicked_modifiers、pressed_modifiers、released_modifiers。
  • TextInput:changed、returned、escaped、key_down_unhandled、selected_text。
  • CheckBox:changed。
  • DropDown:selected、changed、changed_label、selected_item、selected_label。
  • Slider:slided、end_slide、value。
  • RadioButton / RadioButtonGroup:clicked;组的 selected。
  • LinkLabel:clicked、clicked_modifiers。

script_eval! 宏

从 Rust 处理器内执行 Splash 代码,是更新 Splash 状态并触发 UI 重新渲染的主要桥梁。签名为 script_eval!(cx_or_vm, { splash_code }),第一个参数在事件处理器内可为 &mut Cx,初始化期间可为 &mut ScriptVm。用 #(expr) 插值将 Rust 值注入 Splash。

script_apply_eval! 宏

从 Rust 在运行时补丁控件属性,针对特定控件引用直接应用属性变更。签名为 script_apply_eval!(cx, widget_ref, { property_patches }),可补丁单个属性、margin、width 以及嵌套的绘制着色器属性。

控件引用访问与设置

用 self.ui.widget_type(cx, ids!(name)) 获取类型化引用(button、label、text_input、check_box、drop_down、slider、view、radio_button),用点号访问嵌套控件,用 self.ui.widget(cx, ids!(my_widget)) 获取非类型化引用。常用 setter 包括 Label 的 set_text、TextInput 的 set_text、CheckBox 的 set_active、DropDown 的 set_selected_item 和 set_labels、Slider 的 set_value,以及任意控件的 redraw 和 set_visible。

从 Splash 访问控件方法

在 script_mod! 中通过 ui 前缀访问控件:ui.main_view.render() 触发重新渲染、ui.todo_input.text() 读取文本、ui.todo_input.set_text("") 设置文本、ui.add_button.on_click() 触发其他控件点击。

底层 Hit 事件

供需要原始输入处理的自定义控件使用,通过 event.hits(cx, area) 访问。Hit 枚举包含键盘焦点(KeyFocus、KeyFocusLost)、键盘输入(KeyDown、KeyUp)、文本输入(TextInput、TextRangeReplace、TextCopy、TextCut、ImeAction)、指针/手指事件(FingerDown、FingerMove、FingerUp、FingerScroll、FingerLongPress)、悬停事件(FingerHoverIn、FingerHoverOver、FingerHoverOut)、触发器(Trigger)和 Nothing。

使用方式

按照上述分层结构编写代码:在 script_mod! 中为控件附加内联事件处理器,在 Rust 侧实现 MatchEvent trait 处理业务逻辑,需要跨层调用时使用 script_eval! 与 script_apply_eval! 宏,查询控件动作时传入 &Actions 引用,访问控件时使用 ids! 宏。

适用场景

适用于使用 Makepad 2.0 构建 UI 的所有事件处理开发,包括按钮点击、动态列表渲染、表单提交与回车、应用启动初始化、按键输入、定时器、HTTP 网络响应与进度、音频/MIDI/视频设备事件,以及自定义控件的底层输入处理。

限制

资料未提供该技能的收费、价格、平台支持范围、版本兼容性、性能指标等具体信息。