# ColorPicker

> 通过色相×饱和度矩阵加亮度滑块选择颜色，并回传所选的色值。

Source: https://crossfly.dev/zh/docs/ui/widgets/colorpicker — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# ColorPicker

`ColorPicker` 通过一个色相×饱和度的二维矩阵加上一个亮度滑块来选择一种**颜色**。它遵循 picker 模式（见 [`Picker`](/docs/ui/widgets/picker)），返回一个**不带 alpha 通道**的 ARGB `Integer`。

> 🟡 · **包：** `dev.crossfly.ui.picker` · **继承：** `Picker` · **选择：** 内部 `ColorMatrix`

## 何时使用
- 让用户选择一种颜色（主题、强调色、标签）。

## 外观
窗口占屏幕的 80%×80%，色相×饱和度矩阵填充主体，一个亮度滑块，以及 **Cancel** 和 **Select** 按钮（Select 显示十六进制值，并用所选颜色自身着色）。

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

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

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

      Button abrir = new Button("Escolher cor");
      // 用所选颜色本身作为按钮背景
      abrir.onAction(c ->
      {
         ColorPicker cp = new ColorPicker(0xFF3366CC);
         cp.show(answer ->
         {
            int argb = 0xFF000000 | (Integer) answer;  // 添加 alpha（无 alpha 的颜色）
            abrir.style(abrir.getStyle().copy().backColor(argb));
         });
      });
      add(LAY_AUTO, abrir);
   }
}
```

> 下面的代码片段只展示**核心部分**（放进 `onShow()` 内的内容）。要运行它们，请把它们放入上面的 `MainWindow` 骨架中。

## 基本用法
```java
ColorPicker cp = new ColorPicker(0xFF3366CC);
cp.show(answer ->
{
   int rgb = (Integer) answer;    // 0x00RRGGBB（无 alpha）
   int argb = 0xFF000000 | rgb;   // 添加 alpha 以作为不透明颜色使用
   botao.style(botao.getStyle().copy().backColor(argb));
});
```

## 构造函数
| 构造函数 | 描述 |
|---|---|
| `ColorPicker(int defaultColor)` | 打开时显示的初始 ARGB 颜色。 |

## 属性与自定义
| 成员 | 类型 | 作用 |
|---|---|---|
| `choosenColor` | `int`（公有） | 当前颜色（RGB 无 alpha）；取消时为 `-1`。 |
| `ColorPicker.selectStr`（静态） | `String` | Select 按钮标签的前缀（`"Select color "`）。 |

## 回调与事件
| 回调 | 触发时机 |
|---|---|
| `show(onAnswer)` | 确认（Select）时，传递 `Integer`（RGB 无 alpha）。 |

## 结果（重要）
`getAnswer()` 返回 `Integer`（RGB 颜色，**无 alpha**，已用 `& 0x00FFFFFF` 掩码），若取消则返回 `null`。类型为 `Integer`（而非 `int`）正是为了能够为 `null`。

> ⚠️ **该颜色没有 alpha 通道。** 若需要不透明颜色，请应用 `0xFF000000 |`。

## 状态
- **Select** → `answer = choosenColor` 并关闭。
- **Cancel** → `answer = null`，`choosenColor = -1` 并关闭（`onAnswer` **不会**触发）。

### 将所选颜色用作按钮背景
```java
ColorPicker cp = new ColorPicker(0xFF3366CC);
cp.show(answer ->
{
   int argb = 0xFF000000 | (Integer) answer;
   botao.style(botao.getStyle().copy().backColor(argb));
});
```

## 最佳实践
- 记得在把结果用作不透明颜色时**添加 alpha**（`0xFF000000 |`）。
- 转换为 `Integer`（而非 `int`），以免在取消时丢失 `null` 语义。

## 常见错误
- **使用不带 alpha 的结果** —— 会显示为透明（`0x00RRGGBB`）。
- **期望取消时触发 `onAnswer`** —— 不会触发（`answer = null`）。

## 另见
- 该领域指南：[`ui/`](/docs/ui) · 食谱：[`cookbook/`](/docs/cookbook)
- 模式基类：[`Picker`](/docs/ui/widgets/picker)