Extending Keel
Before adding something, determine which existing module it belongs to. In most cases, a file is added to an existing module; for the standards for creating new modules, see Architecture · When to create a new module.
| What you want to add | Where to put | Examples |
|---|---|---|
| Interfaces and business components in applications | Not included in the library: Use ui/el to write functions or views, see Elements and Views |
Order cards, toolbars |
| Generic element capabilities | ui/el |
New styling methods, layout properties, element types |
| Common components | ui/kit/ New files |
select.go, chart.go, dock.go |
| Adjustable parameters such as color, font size, etc. | ui/theme/theme.go |
Value used by more than two components |
| Related to the window itself | ui/window/ |
Window position, pinned |
| System capabilities, useful even without opening a window | New module under native/ |
native/clipboard, native/notify, native/tray |
| There is only one interface fragment used on the page | Not included in the library, the business code is written as a function that returns el.Element |
Consider moving it in after using it for the second time |
Add new components
Common components are placed in ui/kit, one component is a file, and views are written in ui/el. The complete specification and acceptance list are in Component Development Specification, here we only go through the skeleton. Take a counter as an example (the kit already has NumberInput, this is just to illustrate the structure):
// CounterView shows a number between − and + buttons.
type CounterView struct {
value int
disabled bool
onChange func(int)
}
func Counter(value int) *CounterView { return &CounterView{value: value} }
func (v *CounterView) Value() int { return v.value }
func (v *CounterView) SetValue(n int) { v.value = n } // Program assignment does not trigger callback
func (v *CounterView) SetDisabled(d bool) { v.disabled = d }
func (v *CounterView) OnChange(fn func(int)) *CounterView {
v.onChange = fn
return v
}
func (v *CounterView) set(n int) {
v.value = n
if v.onChange != nil {
v.onChange(n) // Only triggered by user actions
}
}
func (v *CounterView) Render(cx *el.Context) el.Element {
minus := Button("−", func() { v.set(v.value - 1) }).Variant(ButtonSecondary)
plus := Button("+", func() { v.set(v.value + 1) }).Variant(ButtonSecondary)
minus.SetDisabled(v.disabled)
plus.SetDisabled(v.disabled)
return el.Div().Row().Gap(8).Items(el.Center).Child(
minus.Render(cx),
el.Text(strconv.Itoa(v.value)).TextColor(theme.Text), // Color is read at Render time
plus.Render(cx),
)
}
Key points:
- **Constructor
Xxx(...)returns*XxxView. ** Business status is stored in the structure; interaction status such as hover, press, and focus are saved by el according to the element position without declaration. - Value components are provided
Value,SetValue,OnChange,SetDisabled. Programmatic assignment does not trigger callbacks. - The color and framework text are read from
themeandlocaleduring Render, and are not saved during construction, nor hard-coded Chinese. - The capabilities that el lacks are added to el first (focus, timing, overlay, dragging), and the Gio input routing is not written directly in the component.
Then complete the supporting files, ui/kit/conventions_test.go will check which one is missing:
ui/kit/counter_test.go: Usepage(v),click(t, h, "name")and other auxiliary functions (inkit_test.go) to take the real input route;ui/window/kit_*_test.go: The role, name, value, and status in the Agent snapshot are correct; the container role that needs to list the sub-elements separately is added tocontainerRoles, and the table of Agent end-to-end test is added;docs/kit/counter.md, and registered in the corresponding category of component reference;examples/components/counter.go, sign up for-section counter.
Add native capabilities
Take "Read Clipboard Text" as an example and walk through it. The macOS step was compiled against the current helpers when writing the document; the example is not in the repository.
Step one: Call AppKit from Go. macOS code is Go too: objc_darwin.go drives the Objective-C runtime through purego, without cgo. Append to native/internal/sys/sys_darwin.go:
func ClipboardText() (string, error) {
var text string
onMain(func() { // AppKit's pasteboard belongs to the main thread
board := send(class("NSPasteboard"), "generalPasteboard")
text = goString(send(board, "stringForType:", uintptr(constant("NSPasteboardTypeString"))))
})
return text, nil
}
send sends a message with integer or pointer arguments; floats and structs (NSRect, CGPoint) need a function registered once with purego.RegisterFunc. onMain and mainAsync run code on the main queue inside an autorelease pool; withPool does the same on the current thread. Objects from alloc/init/new/copy are yours to release.
Errors use one convention: 0 is success, 1 no permission, 2 unsupported, 3 invalid argument, 4 wrong thread, 5 timeout, 6 conflict, other values are failures. status() in sys_darwin.go converts them to native.Err*; add both sides together when a new category is needed.
Step 2: Callbacks. A system that answers later (a completion handler, a notification) calls a block or a method of a class registered at run time. purego never frees callbacks, so create them once per signature (objc.NewBlock reuses one per function type) and find the Go state through a token or the object pointer; never hand a Go pointer to native code that keeps it.
Step 3: Other platforms. sys_windows.go (Win32) and sys_linux.go (X11) must also have functions with the same name. If it cannot be done temporarily, it will return to native.ErrUnsupported first. sys_other.go covers the rest of the platforms:
func ClipboardText() (string, error) { return "", native.ErrUnsupported }
If any file is missing, the platform will not be able to compile it. Check one by one:
GOOS=windows go vet ./native/...
CGO_ENABLED=0 GOOS=linux go vet ./native/...
CGO_ENABLED=0 GOOS=freebsd go vet ./native/...
Step 4: Make the package public. Create a new native/clipboard/clipboard.go. Parameter verification is placed in this layer. The sys layer only does translation:
// Package clipboard reads the system clipboard.
package clipboard
import "github.com/dyike/keel/native/internal/sys"
// Text returns the clipboard's plain text, or "" when it holds none.
func Text() (string, error) { return sys.ClipboardText() }
Step 5: Register module boundaries. Add a row to the allowed table of internal/deps/deps_test.go:
"native/clipboard": {"native", "native/internal/sys"},
Without registration, TestEveryModuleIsListed will fail. This step forces you to think clearly: who the new module depends on, and whether it is really independent.
Step 6: Write the document. Write clearly in native/clipboard/README.md what it does, what it depends on, and how to use it alone (copy the README format of other modules); add a section each in the table of native/README.md and native capability to clearly indicate what permissions are required, whether it will block, and which thread it can be called from.
For system APIs involving the main thread (most UI classes in AppKit), please note: Gio's event loop occupies the main thread, and dispatch_sync(dispatch_get_main_queue(), ...) is used to cut through it in C code (refer to the existing onMain). But if the caller itself is on the main thread, dispatch_sync will deadlock, so [NSThread isMainThread] is judged first.
New example
examples/<name>/main.go, an example demonstrates one thing. To be able to produce screenshots, please refer to examples/hello to support the -screenshot parameter.
Check before submission
gofmt -l . # Expect no output
go vet ./...
CGO_ENABLED=0 GOOS=linux go vet ./native/... ./cmd/... # Verify platform stubs
go test -race ./... # Includes module boundary checks
go run ./examples/hello -screenshot /tmp/after.png # Compare screenshots after style changes