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 ¶
- Constants
- 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 DecodeImageBytes(data []byte) (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 ReadImageSource(ctx context.Context, source string) ([]byte, error)
- func ReportScrollGesture(device ScrollDevice, active, momentum, ended bool)
- 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 ScrollDevice
- type ScrollGesture
- type Widget
- type WindowControls
Constants ¶
const MaxImagePixels = 32_000_000
MaxImagePixels is the largest image, in pixels, that decoding accepts.
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 where a key context predicate holds: a name such as "Editor", or an expression such as "Editor && !ReadOnly" or "Pane > Editor" (see keymap_predicate.go). No chords explicitly disables the action there, hiding outer and global bindings. An invalid chord or predicate leaves the map unchanged.
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 action along a focus path of KeyContext names, inner to outer: the innermost level where some binding's predicate holds wins, and among bindings matching at that level, the one bound last. With none, the global keymap applies. 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 DecodeImageBytes ¶ added in v0.0.4
DecodeImageBytes decodes PNG, JPEG, GIF (first frame) or WebP bytes, refusing images larger than DecodeImage allows before allocating them.
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 ReadImageSource ¶ added in v0.0.4
ReadImageSource returns the encoded bytes of an image source, as DecodeImage reads it: a local path, a file URL, an HTTP(S) URL or a data URL, up to 16MiB. Use it to decode formats DecodeImage does not, such as SVG or every frame of a GIF. It blocks; call it from a worker.
func ReportScrollGesture ¶ added in v0.0.4
func ReportScrollGesture(device ScrollDevice, active, momentum, ended bool)
ReportScrollGesture records platform scroll state; window backends call it for each native scroll event; ScrollDeviceUnknown clears what earlier reports established. A finished gesture redraws every window so components waiting on it can settle. Safe from any goroutine.
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 ScrollDevice ¶ added in v0.0.4
type ScrollDevice uint8
ScrollDevice is the kind of device behind scroll input.
const ( // ScrollDeviceUnknown: the platform does not say. ScrollDeviceUnknown ScrollDevice = iota // ScrollDeviceWheel scrolls in notches. ScrollDeviceWheel // ScrollDeviceTrackpad scrolls continuously, with gesture phases. ScrollDeviceTrackpad )
type ScrollGesture ¶ added in v0.0.4
type ScrollGesture struct {
Device ScrollDevice
// Phases is true once the platform has reported gesture phases, so
// Active and Ended can be trusted.
Phases bool
// Active is true while fingers are on the trackpad.
Active bool
// Momentum is true while inertial scrolling continues after a lift.
Momentum bool
// Ended counts finished gestures; a change means the fingers lifted.
Ended uint64
}
ScrollGesture is what the platform reports about scroll input beyond the deltas Gio delivers. Only macOS reports it today; elsewhere Phases is false and components fall back to timing.
func CurrentScrollGesture ¶ added in v0.0.4
func CurrentScrollGesture() ScrollGesture
CurrentScrollGesture returns the latest platform scroll state.
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