client

package
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

README

Protocol client

github.com/moriyoshi/gpui-go/client owns the transport-independent Go protocol API: session negotiation, request correlation, windows, snapshot revisions, events, resources, observable models and platform commands. Importing it does not initialize Sable or lock an OS thread.

Use NewClient(ctx, transport) when supplying a Transport. Standalone applications use host.Run, which creates the client. Construct views with scene, or use ui for persistent reactive components.

Use public aliases for callback and service values: Event, TextChanged, ModelState, Menu, MenuItem, PathPrompt, SavePathPrompt, PathResult, Capabilities and their related enums. Constants include ResourceImage, ResourceSVG, ResourceFont, MouseLeft, WindowActivate and ErrorStaleHandle. Event oneof cases use names such as EventClick and EventTextChanged. See types.go for the full set. These are aliases of the wire types, preserving methods and identity with generated callers.

handler := app.OnTextChange(func(ctx context.Context, event *client.Event) error {
    if value.Accept(event.GetTextChanged()) {
        return window.Set(ctx, render())
    }
    return nil
})

Handles and geometry in client signatures use scene.Handle, scene.FocusTarget and scene.Size. Generated RPC envelopes and the low-level tagged automation protocol remain available for transport/test adapters; normal application code does not need to import those bindings.

Client commands support concurrent callers. Event pulls have one ordered consumer; dispatch callbacks sequentially on the application state goroutine. Window.Set installs a whole snapshot, and consumes a revision even when cancellation races commitment. Successful installation does not prove presentation. Mutations are not automatically retried.

Resource handles and model handles belong to the negotiated session. Release resources only after installed references are removed; close observer subscriptions explicitly. Generic events retain their existing acknowledgement/replay contract. The root gpui.Client, Window, Resource, Model, errors and operation types are aliases of these canonical types.

The Automate method remains available only with the gpui_e2e build tag, and the backend must separately advertise automation capabilities. uitest/gpui adapts that method to the shared test harness. See the main guide for the complete feature APIs and limits.

Documentation

Overview

Package client implements the transport-independent GPUI protocol client.

Index

Constants

MouseButton values use concise application-facing names.

ResourceKind values use concise application-facing names.

WindowOperation values use concise application-facing names.

ErrorCode values use concise application-facing names.

Variables

This section is empty.

Functions

This section is empty.

Types

type Capabilities

type Capabilities = pb.Capabilities

Client service values retain their generated accessors and protobuf identity.

type Click

type Click = pb.Click

Events and payloads are shared with existing protobuf callers without conversion.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is safe for concurrent commands. NextEvents and DispatchEvents share one ordered event consumer. Application state mutated by callbacks should remain on that event goroutine, or use the application's own synchronization.

func NewClient

func NewClient(ctx context.Context, transport Transport) (*Client, error)

func (*Client) Capabilities

func (c *Client) Capabilities() *Capabilities

func (*Client) ClipboardText

func (c *Client) ClipboardText(ctx context.Context) (string, error)

func (*Client) CreateModel

func (c *Client) CreateModel(ctx context.Context, value []byte) (*Model, error)

func (*Client) Dispatch

func (c *Client) Dispatch(ctx context.Context, event *Event) error

Dispatch invokes the registered callback for a received event. Use it with NextEvents to combine UI input and background results on one state-owning goroutine. It does not commit or acknowledge an event by itself.

func (*Client) DispatchEvents

func (c *Client) DispatchEvents(ctx context.Context) error

DispatchEvents runs handlers sequentially until canceled or a handler fails. Window lifecycle events can be consumed directly with NextEvents instead.

func (*Client) NextEvents

func (c *Client) NextEvents(ctx context.Context) ([]*Event, error)

NextEvents acknowledges the preceding received batch. Cancellation can be retried: Rust retains unacknowledged events. Use one consumer per Client.

func (*Client) OnClick

func (c *Client) OnClick(handler func(context.Context, *Event) error) uint64

OnClick registers a handler without exposing a Go pointer to Rust. IDs are never reused. Call RemoveHandler when the application no longer needs one.

func (*Client) OnEvent

func (c *Client) OnEvent(handler func(context.Context, *Event) error) uint64

OnEvent registers a native interaction/action callback. Callbacks run only when the application dispatches events, never synchronously during painting.

func (*Client) OnTextChange

func (c *Client) OnTextChange(handler func(context.Context, *Event) error) uint64

OnTextChange registers a callback for native text edits, including IME composition. Use InputState.Accept to ignore obsolete edits after a reset.

func (*Client) OpenURL

func (c *Client) OpenURL(ctx context.Context, url string) error

func (*Client) OpenWindow

func (c *Client) OpenWindow(ctx context.Context, options WindowOptions, root *scene.Node) (*Window, error)

func (*Client) PromptPaths

func (c *Client) PromptPaths(ctx context.Context, options *PathPrompt, callback func(context.Context, *PathResult) error) (func(), error)

PromptPaths displays an asynchronous OS picker. The callback runs through Dispatch/DispatchEvents. The returned function detaches the callback; it does not dismiss an already displayed OS dialog. No file contents are read.

func (*Client) PromptSavePath

func (c *Client) PromptSavePath(ctx context.Context, options *SavePathPrompt, callback func(context.Context, *PathResult) error) (func(), error)

func (*Client) Quit

func (c *Client) Quit(ctx context.Context) error

func (*Client) RemoveHandler

func (c *Client) RemoveHandler(id uint64)

func (*Client) SetMenus

func (c *Client) SetMenus(ctx context.Context, menus ...*Menu) error

SetMenus replaces the application menu bar. Menu actions target stable nodes and logical actions; closed/removed/unbound targets are ignored on dispatch.

func (*Client) Supports

func (c *Client) Supports(feature string) bool

func (*Client) UploadResource

func (c *Client) UploadResource(ctx context.Context, kind ResourceKind, mediaType string, data []byte) (*Resource, error)

func (*Client) WriteClipboardText

func (c *Client) WriteClipboardText(ctx context.Context, text string) error

type ColorSchemeChanged added in v0.0.2

type ColorSchemeChanged = pb.ColorSchemeChanged

Events and payloads are shared with existing protobuf callers without conversion.

type ErrorCode

type ErrorCode = pb.ErrorCode

Client service values retain their generated accessors and protobuf identity.

type Event

type Event = pb.Event

Events and payloads are shared with existing protobuf callers without conversion.

type EventAction

type EventAction = pb.Event_Action

Event kinds expose the wire oneof cases without generated underscore names.

type EventClick

type EventClick = pb.Event_Click

Event kinds expose the wire oneof cases without generated underscore names.

type EventColorSchemeChanged added in v0.0.2

type EventColorSchemeChanged = pb.Event_ColorSchemeChanged

Event kinds expose the wire oneof cases without generated underscore names.

type EventDataDrop

type EventDataDrop = pb.Event_DataDrop

Event kinds expose the wire oneof cases without generated underscore names.

type EventFileDrop

type EventFileDrop = pb.Event_FileDrop

Event kinds expose the wire oneof cases without generated underscore names.

type EventFocusChanged

type EventFocusChanged = pb.Event_FocusChanged

Event kinds expose the wire oneof cases without generated underscore names.

type EventKeyDown

type EventKeyDown = pb.Event_KeyDown

Event kinds expose the wire oneof cases without generated underscore names.

type EventKeyUp

type EventKeyUp = pb.Event_KeyUp

Event kinds expose the wire oneof cases without generated underscore names.

type EventModelChanged

type EventModelChanged = pb.Event_ModelChanged

Event kinds expose the wire oneof cases without generated underscore names.

type EventMouseDown

type EventMouseDown = pb.Event_MouseDown

Event kinds expose the wire oneof cases without generated underscore names.

type EventMouseMove

type EventMouseMove = pb.Event_MouseMove

Event kinds expose the wire oneof cases without generated underscore names.

type EventMouseUp

type EventMouseUp = pb.Event_MouseUp

Event kinds expose the wire oneof cases without generated underscore names.

type EventPathResult

type EventPathResult = pb.Event_PathResult

Event kinds expose the wire oneof cases without generated underscore names.

type EventScroll

type EventScroll = pb.Event_Scroll

Event kinds expose the wire oneof cases without generated underscore names.

type EventTextChanged

type EventTextChanged = pb.Event_TextChanged

Event kinds expose the wire oneof cases without generated underscore names.

type EventViewUpdated

type EventViewUpdated = pb.Event_ViewUpdated

Event kinds expose the wire oneof cases without generated underscore names.

type EventWindowClosed

type EventWindowClosed = pb.Event_WindowClosed

Event kinds expose the wire oneof cases without generated underscore names.

type EventWindowResized added in v0.0.2

type EventWindowResized = pb.Event_WindowResized

Event kinds expose the wire oneof cases without generated underscore names.

type FileDrop

type FileDrop = pb.FileDrop

Events and payloads are shared with existing protobuf callers without conversion.

type FocusChanged

type FocusChanged = pb.FocusChanged

Events and payloads are shared with existing protobuf callers without conversion.

type KeyEvent

type KeyEvent = pb.KeyEvent

Events and payloads are shared with existing protobuf callers without conversion.

type Menu = pb.Menu

Client service values retain their generated accessors and protobuf identity.

type MenuItem = pb.MenuItem

Client service values retain their generated accessors and protobuf identity.

type Model

type Model struct {
	// contains filtered or unexported fields
}

Model is a session-owned serializable entity, backed by a GPUI Entity on the native backend. Values are opaque bytes (for example, an application protobuf). Updates use compare-and-swap revisions; canceled writes are never retried.

func (*Model) Handle

func (m *Model) Handle() *scene.Handle

func (*Model) Observe

func (m *Model) Observe(ctx context.Context, handler func(context.Context, *ModelState) error) (*Subscription, error)

func (*Model) Read

func (m *Model) Read(ctx context.Context) (*ModelState, error)

func (*Model) Release

func (m *Model) Release(ctx context.Context) error

func (*Model) Update

func (m *Model) Update(ctx context.Context, expectedRevision uint64, value []byte) (*ModelState, error)

type ModelState

type ModelState = pb.ModelState

Client service values retain their generated accessors and protobuf identity.

type MouseButton

type MouseButton = pb.MouseButton

Events and payloads are shared with existing protobuf callers without conversion.

type Operation

type Operation uint32
const (
	OperationRequest Operation = 0x47505501
	OperationEvents  Operation = 0x47505502
	MaxMessageBytes            = 4 << 20
)

type PathPrompt

type PathPrompt = pb.PathPrompt

Client service values retain their generated accessors and protobuf identity.

type PathResult

type PathResult = pb.PathResult

Client service values retain their generated accessors and protobuf identity.

type PointerEvent

type PointerEvent = pb.PointerEvent

Events and payloads are shared with existing protobuf callers without conversion.

type ProtocolError

type ProtocolError struct {
	Code    ErrorCode
	Message string
}

func (*ProtocolError) Error

func (e *ProtocolError) Error() string

type Resource

type Resource struct {
	// contains filtered or unexported fields
}

Resource is a session-owned uploaded asset. Release rejects assets still referenced by an installed view. Font faces remain installed until app exit.

func (*Resource) Handle

func (r *Resource) Handle() *scene.Handle

func (*Resource) Release

func (r *Resource) Release(ctx context.Context) error

type ResourceKind

type ResourceKind = pb.ResourceKind

Client service values retain their generated accessors and protobuf identity.

type SavePathPrompt

type SavePathPrompt = pb.SavePathPrompt

Client service values retain their generated accessors and protobuf identity.

type Subscription

type Subscription struct {
	// contains filtered or unexported fields
}

Subscription owns an observer callback. Close it when finished. Delivery uses the client's ordinary acknowledged event stream and requires event dispatch.

func (*Subscription) Close

func (s *Subscription) Close(ctx context.Context) error

type TextChanged

type TextChanged = pb.TextChanged

Events and payloads are shared with existing protobuf callers without conversion.

type Transport

type Transport interface {
	Call(context.Context, Operation, []byte) ([]byte, error)
}

Transport owns the byte boundary. Implementations must copy requests before retaining them and return independently owned response bytes.

type ViewUpdated

type ViewUpdated = pb.ViewUpdated

Events and payloads are shared with existing protobuf callers without conversion.

type Window

type Window struct {
	// contains filtered or unexported fields
}

Window owns its root view. Its references become invalid when it closes.

func (*Window) ActionTarget

func (w *Window) ActionTarget(element uint64) *scene.FocusTarget

ActionTarget returns the serializable target used in native menu items.

func (*Window) Activate

func (w *Window) Activate(ctx context.Context) error

func (*Window) Close

func (w *Window) Close(ctx context.Context) error

func (*Window) ColorScheme added in v0.0.2

func (w *Window) ColorScheme() (scheme scene.ColorScheme, ok bool)

ColorScheme returns whether the window is drawn light or dark, as reported when it opened and updated as Dispatch receives changes. ok is false when the backend lacks the window-color-scheme capability.

func (*Window) Command

func (w *Window) Command(ctx context.Context, operation WindowOperation, title string, size *scene.Size) error

func (*Window) DispatchAction

func (w *Window) DispatchAction(ctx context.Context, element uint64, name string, payload []byte) error

func (*Window) EmbedTarget

func (w *Window) EmbedTarget() (uint64, uint32)

EmbedTarget identifies this window's view to a host extension that creates embedded views in it.

func (*Window) Focus

func (w *Window) Focus(ctx context.Context, element uint64) error

func (*Window) Handle

func (w *Window) Handle() *scene.Handle

func (*Window) Minimize

func (w *Window) Minimize(ctx context.Context) error

func (*Window) OnColorSchemeChanged added in v0.0.2

func (w *Window) OnColorSchemeChanged(handler func(context.Context, scene.ColorScheme) error) (remove func())

OnColorSchemeChanged registers a callback that Dispatch runs, on the dispatching goroutine, after the window switches between the light and dark color schemes. The returned function removes the callback.

func (*Window) OnResized added in v0.0.2

func (w *Window) OnResized(handler func(context.Context, WindowSize) error) (remove func())

OnResized registers a callback that Dispatch runs, on the dispatching goroutine, after the window's drawable area changes. A live resize is coalesced, so the callback sees the latest size rather than every step. The returned function removes the callback.

func (*Window) Resize

func (w *Window) Resize(ctx context.Context, width, height float32) error

func (*Window) ScrollTo

func (w *Window) ScrollTo(ctx context.Context, element uint64, item uint32) error

func (*Window) Set

func (w *Window) Set(ctx context.Context, root *scene.Node) error

Set replaces a complete view. A successful response means installed, not necessarily painted. Revisions are consumed even on cancellation because an operation may commit immediately before cancellation wins the response race.

func (*Window) SetTitle

func (w *Window) SetTitle(ctx context.Context, title string) error

func (*Window) Size added in v0.0.2

func (w *Window) Size() (size WindowSize, ok bool)

Size returns the window's drawable area, as reported when it opened and updated as Dispatch receives resizes. ok is false when the backend lacks the window-size capability.

func (*Window) ToggleFullscreen

func (w *Window) ToggleFullscreen(ctx context.Context) error

func (*Window) ViewHandle

func (w *Window) ViewHandle() *scene.Handle

func (*Window) Zoom

func (w *Window) Zoom(ctx context.Context) error

type WindowClosed

type WindowClosed = pb.WindowClosed

Events and payloads are shared with existing protobuf callers without conversion.

type WindowOperation

type WindowOperation = pb.WindowOperation

Client service values retain their generated accessors and protobuf identity.

type WindowOptions

type WindowOptions struct {
	Title         string
	Width, Height float32
}

type WindowResized added in v0.0.2

type WindowResized = pb.WindowResized

Events and payloads are shared with existing protobuf callers without conversion.

type WindowSize added in v0.0.2

type WindowSize struct{ Width, Height float32 }

WindowSize is a window's drawable area in logical pixels.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL