Documentation
¶
Overview ¶
Package darwin implements the macOS AXUIElement core.Backend ("ax") for the Pando Desktop Controller, described in Phase 5 of pando/plans/desktop_controller_uiauto_plan.md.
No cgo is used anywhere in this package. The real Accessibility/ CoreFoundation bridging (dlopen + purego.RegisterLibFunc against ApplicationServices.framework and CoreFoundation.framework) lives in ax_darwin.go, built only for GOOS=darwin. Every other file in this package contains platform-INDEPENDENT logic — selector-driven traversal, AXError -> core.DesktopError mapping, Element construction from a decoded attribute map, action-kind dispatch — written against the small axConn interface (conn.go) instead of calling AX functions directly, so it compiles and its unit tests run on any GOOS (in particular, on this Linux development machine) against a fake axConn.
Element identity: an AXUIElementRef is a live CoreFoundation object. axRef{PID, Handle} identifies one within the current process; Handle is only meaningful for the lifetime of the *DarwinBackend that produced it (its handle table CFRetains every ref it hands out and CFReleases them all in Close()). Because a raw pointer cannot safely be reused across snapshots or after Close(), every Element this backend builds also stashes the durable (pid, AXIdentifier, role, index-path) tuple described by the plan in Element.Native.Data — see element.go's nativeIndexPathKey et al. — as the re-resolution key a future Find/Observe can use to recover an equivalent node even if the live handle went stale.
CoreFoundation memory-management discipline: every CFRelease-able object this package creates or copies (CFStringRef, CFArrayRef, AXUIElementRef, CFNumberRef is read in place and never retained) is released exactly once, either immediately after use (attribute value decode) or is retained into the backend's handle table and released in Close(). The fixed, small vocabulary of attribute-name and action-name CFStrings is interned once (created, never released) since the process lives for the lifetime of the backend; see ax_darwin.go's cfStringIntern.
Index ¶
- type AXError
- type DarwinBackend
- func (b *DarwinBackend) Apps(ctx context.Context) ([]core.AppInfo, error)
- func (b *DarwinBackend) Available(ctx context.Context) (core.Capabilities, error)
- func (b *DarwinBackend) Children(ctx context.Context, el *core.Element) ([]*core.Element, error)
- func (b *DarwinBackend) Close() error
- func (b *DarwinBackend) Find(ctx context.Context, scope core.Scope, sel *core.Selector, limit int) ([]*core.Element, error)
- func (b *DarwinBackend) Name() string
- func (b *DarwinBackend) Perform(ctx context.Context, el *core.Element, action core.Action) error
- func (b *DarwinBackend) Properties(ctx context.Context, el *core.Element, props []string) (map[string]any, error)
- func (b *DarwinBackend) Windows(ctx context.Context, appID string) ([]core.WindowInfo, error)
- type Point
- type Size
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AXError ¶
type AXError int32
AXError mirrors the AXError codes documented in <ApplicationServices/HIServices/AXError.h>. Only the codes the plan calls out explicitly get a name; anything else maps generically.
const ( AXErrorSuccess AXError = 0 AXErrorFailure AXError = -25200 AXErrorIllegalArgument AXError = -25201 AXErrorInvalidUIElement AXError = -25202 AXErrorInvalidUIElementObserver AXError = -25203 AXErrorCannotComplete AXError = -25204 AXErrorAttributeUnsupported AXError = -25205 AXErrorActionUnsupported AXError = -25206 AXErrorNotificationUnsupported AXError = -25207 AXErrorNotImplemented AXError = -25208 AXErrorNotificationAlreadyRegistered AXError = -25209 AXErrorNotificationNotRegistered AXError = -25210 AXErrorAPIDisabled AXError = -25211 AXErrorNoValue AXError = -25212 AXErrorParameterizedAttributeUnsupport AXError = -25213 AXErrorNotEnoughPrecision AXError = -25214 )
type DarwinBackend ¶
type DarwinBackend struct {
// contains filtered or unexported fields
}
DarwinBackend implements core.Backend against the macOS Accessibility API via the axConn seam (conn.go). The real, purego-backed axConn is constructed only by NewBackend (ax_darwin.go, "//go:build darwin"); newBackendWithConn lets tests substitute a fake for every other file in this package.
func (*DarwinBackend) Apps ¶
Apps implements core.Backend by enumerating running processes and building an AXUIElementRef application object for each.
func (*DarwinBackend) Available ¶
func (b *DarwinBackend) Available(ctx context.Context) (core.Capabilities, error)
Available implements core.Backend. Per the plan this checks AXIsProcessTrusted and returns a PERM_DENIED error (not just an all-false Capabilities) when untrusted, so the Manager/tool layer surfaces the actionable suggestion directly instead of silently degrading to PLATFORM_NOT_SUPPORTED on the first real call.
func (*DarwinBackend) Find ¶
func (b *DarwinBackend) Find(ctx context.Context, scope core.Scope, sel *core.Selector, limit int) ([]*core.Element, error)
Find implements core.Backend with the selector-driven, depth-capped, limit-capped, ctx-aware traversal in traverse.go — it never walks the whole tree.
func (*DarwinBackend) Properties ¶
func (b *DarwinBackend) Properties(ctx context.Context, el *core.Element, props []string) (map[string]any, error)
Properties implements core.Backend. When props is empty it returns the cheap extras already gathered by a normal node fetch (help/selected/ main/subrole); "actions" is only fetched on request since it costs an extra round trip.
func (*DarwinBackend) Windows ¶
func (b *DarwinBackend) Windows(ctx context.Context, appID string) ([]core.WindowInfo, error)
Windows implements core.Backend by reading AXWindows off the matching application(s).
Source Files