# 如何显示 Hint（toast）

> 显示自动出现、自动消失的非模态短暂反馈，不打断用户当前正在做的事。

Source: https://crossfly.dev/zh/docs/cookbook/ui/mostrar-um-hint — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 如何显示 Hint（toast）

**目的。** 显示一条短暂的临时消息（「toast」风格），它出现在
屏幕之上，不阻塞交互，并在一段时间后自行消失。用于快速
确认（「已保存」、「已复制」）、轻量提示和状态。它替代了旧的
`Toast` 概念。

## 所用 API
- `Hint.show(String message, int delay)` — 以淡入淡出显示 toast，持续 `delay` 毫秒。**静态**方法（不需要实例化 `Hint`）。
- `Hint.show(message, delay, Window parentWindow)` — 同上，锚定到指定窗口（默认：栈顶窗口）。
- `Hint.show(message, delay, parentWindow, Relative at, Gap innerGap)` — 完全控制垂直位置和内边距。
- `Hint.show(null, delay)` — 传入 `message == null` 会立即**隐藏**当前 toast。
- `Hint.INFINITE` — 常量 `Integer.MAX_VALUE`：保持可见（带淡入），直到你手动隐藏。
- `Hint.INFINITE_NOANIM` — 常量 `Integer.MIN_VALUE`：**不带**动画保持可见。

> 全局配置（公开静态字段）：`Hint.backColor`、`Hint.foreColor`、
> `Hint.position`（默认 `Relative.ofScreen(0.85f)`，靠近底部）、`Hint.fade`、
> `Hint.font`。修改这些字段会影响之后的所有 toast。

## 完整示例（复制、粘贴即可运行）
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // 一个点击时触发 toast 的按钮
      Button btn = new Button("Salvar");
      btn.onAction(origin ->
      {
         // 简单 Toast：显示 2 秒后淡出消失
         Hint.show("Registro salvo", 2000);
      });
      add(LAY_FILL, btn);
   }
}
```

> 下面的片段只展示**核心部分**。要运行它，请把它放进上面的 `MainWindow` 骨架中。

## 最小片段
```java
// 简单 Toast：显示 2 秒后淡出消失
Hint.show("Registro salvo", 2000);

// 无限 Toast（停留在屏幕上直到你让它消失）
Hint.show("Sincronizando...", Hint.INFINITE);
// ... 完成后：
Hint.show(null, 0);   // message == null 隐藏当前 toast

// 顶部位置，带自定义内边距
Hint.show("No topo", 1500, null, Relative.START, Gap.ofFont(1f, 0.5f, 1f, 0.5f));
```

> **验证说明（2026 代码）。** 源码中真实的签名为
> `Hint.show(String, int)` 及其重载 —— **不存在** `hide()` 方法；要
> 隐藏，请调用 `Hint.show(null, ...)`。toast 由一个内部的 `ToastWindow`
> （`Window` 的子类）渲染，显示在 `EventsProcessor` 的栈上，因此它
> 会出现在当前屏幕之上而无需你管理任何东西。

## 深入了解
- 控件页面：[Hint](/docs/ui/widgets/hint) · 权威来源：第 16 章
- 姊妹模态对话框：[用 Alert 进行确认](/docs/cookbook/ui/confirmar-com-alert) · [操作菜单](/docs/cookbook/ui/menu-de-acoes)