README
¶
ui/core
所有界面模块的地基：
| 名字 | 作用 |
|---|---|
Widget |
接口：能 Layout 的东西。所有组件、容器都实现它 |
Func |
把一段 Gio 布局函数当组件用 |
DecodeImage(ctx, source) |
读取本地/HTTP/data 图片，限制编码大小与像素数；须在后台调用并管理超时 |
Update(fn) |
从任意 goroutine 修改界面：fn 在下一帧执行 |
Call(gtx, fn) |
给写组件的人用：执行用户回调并让所有窗口重绘 |
Semantic(gtx, w, ops...)、Role(...) |
给写组件的人用：声明组件的角色、名字、状态，让 Agent 看得见 |
WindowControls、CurrentWindow() |
组件拿到所在窗口的激活状态、标题区域登记、最小化、最大化、关闭能力，自定义标题栏用。ui/window 在布局期间登记当前窗口 |
- 依赖：只依赖 Gio，以及内部的
ui/internal/loop。 - 被谁依赖：
el、kit、window、markdown。
线程规则：回调里直接改组件；其他 goroutine 改组件包进 core.Update。原因见 架构 · 线程规则。
ClipboardData、ClipboardImage、ClipboardReader 定义富粘贴交换数据与异步读取接口；core 不读取系统剪贴板，不引用 native。应用适配平台读取结果，由输入组件调度回 UI 线程。
Documentation
¶
Overview ¶
Package core is the foundation every UI module builds on: what a Widget is, how a component runs a user callback, and how other goroutines change the UI.
Threading has one rule. All windows render, and all callbacks run, under one lock, so callbacks may change any component directly. Code on other goroutines (timers, network, hotkey callbacks) must wrap changes in Update.
Index ¶
- func Bind(action string, chords ...string) error
- func BindIn(context, action string, chords ...string) error
- func Bindings(action string) []string
- func BindingsIn(action string, contexts ...string) []string
- func Call(gtx C, fn func())
- func ClearBindingIn(context, action string)
- func DecodeImage(ctx context.Context, source string) (image.Image, error)
- func Keymap() map[string][]string
- func LoadKeymap(data []byte) error
- func OpenURL(raw string) error
- func ParseShortcut(s string) (key.Name, key.Modifiers, error)
- func Role(role string, value ...string) semantic.DescriptionOp
- func SetCurrentWindow(w WindowControls) (restore func())
- func ShortcutLabel(s, goos string) string
- func Update(fn func())
- type C
- type ClipboardData
- type ClipboardImage
- type ClipboardReader
- type D
- type Func
- type Widget
- type WindowControls
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bind ¶
Bind sets the chords that trigger action, replacing its earlier ones; no chords unbinds it. Chords use ParseShortcut's syntax, e.g. "mod+s". It returns an error, and changes nothing, if a chord is invalid. Every window redraws.
func BindIn ¶
BindIn sets action's chords in a named key context. No chords explicitly disables the action there, hiding outer/global bindings. Invalid chords leave the map unchanged. Contexts are exact names, not predicate expressions.
func Bindings ¶
Bindings returns the chords bound to action, the first being the one to show in hints; nil if it has none.
func BindingsIn ¶
BindingsIn resolves the nearest explicit binding, checking contexts in the supplied order (inner to outer), then the global keymap. The result is owned by the caller. An explicit empty binding prevents fallback.
func Call ¶
func Call(gtx C, fn func())
Call runs a user callback from inside Layout and redraws every window, because the callback may have changed components that were already drawn. Components must route every user callback through it.
func ClearBindingIn ¶
func ClearBindingIn(context, action string)
ClearBindingIn removes a contextual override, restoring inheritance.
func DecodeImage ¶
DecodeImage reads PNG, JPEG, GIF (first frame) and WebP. Size limits apply to encoded input and decoded dimensions, before allocating a pixel buffer. It blocks until completion; call from a worker with a deadline, not during layout.
func LoadKeymap ¶
LoadKeymap binds the actions in a JSON object such as {"editor.save": ["mod+s"], "app.quit": []} on top of the current keymap; an empty list unbinds. Nothing changes if any entry is invalid.
func OpenURL ¶
OpenURL opens an absolute HTTP, HTTPS or mailto URL using the platform handler. It reports launch errors, not whether the destination subsequently loaded.
func ParseShortcut ¶
ParseShortcut reads a key chord such as "mod+s", "ctrl+shift+k" or "esc" into a Gio key name and modifiers. "mod" is Cmd on macOS and Ctrl elsewhere.
func Role ¶
func Role(role string, value ...string) semantic.DescriptionOp
Role marks a node's role for agents, optionally with a value. The internal el-inert marker hides a background subtree from Agent snapshots while a modal el layer is active; it is not exposed as a component role. Automation reads it as "role" or "role:value" from the node's description. A button may carry "button:loading" while its action is unavailable. On a semantic.Button, automation keeps only link, tab, columnheader, select, image, disclosure and toggle; any other role is reported as given.
func SetCurrentWindow ¶
func SetCurrentWindow(w WindowControls) (restore func())
SetCurrentWindow marks w as the window being laid out and returns a func that restores the previous one. Only ui/window calls it.
func ShortcutLabel ¶
ShortcutLabel formats a ParseShortcut chord for goos (darwin, windows or linux). Invalid chords are returned unchanged. It does not register a shortcut.
Types ¶
type ClipboardData ¶
type ClipboardData struct {
Text string
Images []ClipboardImage
Files []string
}
ClipboardData holds the available text, images and file paths in one paste. Paths are references only; the UI does not open the files automatically.
type ClipboardImage ¶
ClipboardImage is owned encoded image data provided to a paste handler.
type ClipboardReader ¶
type ClipboardReader func(done func(ClipboardData, error))
ClipboardReader starts an asynchronous read. It must call done once, on any goroutine; input components marshal completion back to the UI loop. An error falls back to Gio text paste. Applications can adapt native/clipboard.Read.
type D ¶
type D = layout.Dimensions
func Semantic ¶
Semantic lays out w inside its own clip area and attaches semantic ops to it, so the component is one node in Gio's semantic tree with its real bounds. Agents (ui/window automation) and accessibility read that tree.
Gio's classes cover buttons, checkboxes, editors, radios and switches. Other roles go in a Role description, e.g. Role("row") or Role("select", value).
type WindowControls ¶
type WindowControls interface {
// Frameless reports whether the window draws its own title bar.
Frameless() bool
// Focused reports native window activation, not an individual control focus.
Focused() bool
// TitleBarArea registers the current draggable title region in window dp.
// The window clears it each frame; controls must be outside this rectangle.
TitleBarArea(x, y, width, height float32)
Minimize()
// ToggleMaximize maximizes the window, or restores it when maximized.
ToggleMaximize()
Maximized() bool
Close()
}
WindowControls is what UI code may ask of the window it is drawn in: a custom title bar uses it for its buttons. ui/window implements it.
func CurrentWindow ¶
func CurrentWindow() WindowControls
CurrentWindow returns the window being laid out, or nil outside one (a screenshot, a test harness). Read it in Render or Layout, under the frame lock, and keep it for callbacks; callbacks run within the same window.
Source Files