Keypad

Keypad 是一个带数字键盘的窗口（Window），它锚定在获得焦点的文本字段的上方或下方。当处于计算器模式（isCalculator）时，它会增加第 4 列 + − × ÷ =，解算输入的算式，并将结果写回字段。

其用法几乎总是间接的：你在 TextField 上配置 Keyboard.KEYPAD/CALCULATOR（或 EditMode.CURRENCY），字段本身会在获得焦点时实例化并显示 Keypad。手动实例化它的情况很少见。

🔴 · 包： dev.crossfly.ui · 继承： Window · 样式： KeypadStyle

何时使用

• 内嵌的数字输入（不依赖原生键盘），包括在桌面端。
• 计算器模式：允许用户在货币/数字字段内进行计算。

何时不要使用

• 自由文本输入 → 使用原生键盘（Keyboard.DEFAULT）。
• 你很少直接实例化 Keypad —— 请在 TextField 上配置键盘。

外观

按钮网格（GridLayout）：3 列（0–9、退格、回车）或计算器模式下 4 列（带运算符）。按钮使用 keyWidth/keyHeight（× 字体高度）和四角圆角。窗口在能容纳时定位于字段下方，否则位于上方（会考虑浮动的 caption）。

``

完整示例（复制、粘贴并运行）

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());

      // 接收 Keypad 按键的数字字段
      TextField valor = new TextField().caption("Quantidade");
      add(LAY_AUTO, valor);

      // 输出 Label
      Label saida = new Label("Digite no keypad e toque em Confirmar");
      add(LAY_AUTO, saida);

      // 打开锚定到该字段的 Keypad 的按钮（直接使用）
      Button abrir = new Button("Abrir keypad").onAction(c -> {
         Keypad kp = new Keypad(valor);   // target 是上面的 TextField
         kp.show();
      });
      add(LAY_AUTO, abrir);

      // Keypad 写入该字段；提交时读取 getText()
      Button confirmar = new Button("Confirmar")
         .onAction(c -> saida.setText("Valor: " + valor.getText()));
      add(LAY_AUTO, confirmar);
   }
}

下面的片段只展示核心部分（放入 onShow() 内的内容）。要运行它们，请将其放入上面的 MainWindow 骨架中。

基本用法（间接，通过 TextField）

// TextField 在聚焦时自动显示 Keypad：
TextField valor = new TextField().caption("Quantidade");
valor.setKeyboard(Keyboard.KEYPAD);      // 内置数字键盘
container.add(LAY_AUTO, valor);

// 计算器模式 — CURRENCY 默认已使用 CALCULATOR：
TextField preco = new TextField().caption("Preço");
preco.setMode(EditMode.CURRENCY, true);
container.add(LAY_AUTO, preco);

直接使用（高级）

// 手动将 Keypad 锚定到某个字段：
Keypad kp = new Keypad(campo);   // 字段是一个 TextInput (TextField/TextArea)
kp.show();

// 在计算器模式下：
Keypad calc = new Keypad(campo);
calc.<KeypadStyle>getStyle().isCalculator(true);
calc.show();

构造函数

属性与自定义（通过 KeypadStyle）

回调与事件

Keypad 不暴露自己的 onAction。它将按键发送给 target：

• 数字 → target.onKeyTyped(c)。
• 退格 / 回车 → target.onKeyDown(Input.Keys.BACKSPACE / ENTER)。
• 在计算器模式下，= 会计算并通过 target.setText(...) 写入结果。
• 关闭时（onRemove），焦点通过 restoreFocusAtEnd() 返回字段。

要作出响应，请观察字段（getText()），而不是 Keypad。

状态

• Enter ↔ Equals： 在计算器模式下，底部按钮会根据是否有待处理的运算，在 Enter（图标）和 =（文本）之间切换。
• 点击外部或确认（Enter）时窗口关闭。

带内嵌计算器的货币字段

TextField total = new TextField().caption("Total");
total.setMode(EditMode.CURRENCY, true);   // 以计算器模式打开 Keypad
container.add(LAY_AUTO, total);
// 用户输入 "10 + 5 ="，字段随后显示 15,00。

在桌面端强制使用 Keypad

// NUMERIC 在桌面端调用 showInput() 时会自动降级为 KEYPAD；
// 要在任意平台上确保使用 Keypad，请显式使用 KEYPAD：
TextField codigo = new TextField().caption("Código");
codigo.setKeyboard(Keyboard.KEYPAD);
container.add(LAY_AUTO, codigo);

最佳实践

• 优先在 TextField 上配置键盘（setKeyboard/setMode），而不是直接实例化 Keypad。
• 对于货币输入，EditMode.CURRENCY 已自带计算器 —— 无需额外配置任何东西。

常见错误

• 在 Keypad 上注册 onAction： 它不会触发自己的动作；请观察目标字段。
• 在没有可聚焦 target 的情况下实例化 Keypad： 它需要一个 TextInput 来发送按键。

另请参阅

• 领域指南：ui/ · 食谱：cookbook/
• 概念（虚拟键盘、焦点）：concepts/
• 相关组件：TextField · TextInput · TextArea