component

package
v0.23.0 Latest Latest
Warning

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

 Go to latest Published: Nov 25, 2025 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package component features a framework, inspired by React, that allows one to construct a user interface hierarchy through the usage of declarative DSL.

This package builds on top of the ui package and uses Elements as its foundation. The Elements are accessible only in some specific cases.

Index

Constants

This section is empty.

Variables

View Source 
var Element = Define[*elementComponent]()

Element represents the most basic component, which is translated to a UI Element. All higher-order components eventually boil down to an Element.

Functions

func After 

func After(scope Scope, duration time.Duration, fn func())

After will schedule a closure function to be run after the specified amount of time. The closure is guaranteed to run on the UI thread and the framework ensures that the closure will not be called if the component had been destroyed in the meantime.

It is safe to call this function from any thread.

func CloseOverlay added in v0.12.0 

func CloseOverlay(scope Scope)

CloseOverlay closes the Overlay associated with the specified scope.

func CreateFont added in v0.8.0 

func CreateFont(scope Scope, otFont *opentype.Font) *ui.Font

CreateFont uses the ui.Context from the specified scope to create a new ui.Font based on the passed opentype Font.

If creation of the font fails, this function logs an error and returns nil.

func CreateImage added in v0.3.0 

func CreateImage(scope Scope, img image.Image) *ui.Image

CreateImage uses the ui.Context from the specified scope to create a new image.

If the image could not be created for some reason, this function logs an error and returns nil.

func Every added in v0.14.0 

func Every(scope Scope, interval time.Duration, fn func())

Every will schedule a closure function to be run every interval amount of time. The closure is guaranteed to run on the UI thread and the framework ensures that the closure will not be called if the component had been destroyed in the meantime. In fact, the closure will stop being called only once the component has been destroyed.

It is safe to call this function from any thread.

func GetCallbackData added in v0.5.0 

func GetCallbackData[T any](props Properties) T

GetCallbackData returns the callback data stored in Properties as the specified type.

func GetData added in v0.5.0 

func GetData[T any](props Properties) T

GetData returns the data stored in Properties as the specified type.

func GetFont 

func GetFont(scope Scope, family, style string) *ui.Font

GetFont uses the ui.Context from the specified scope to retrieve the font with the specified family and style.

This function returns nil and logs a warning if it is unable to find the requested font (fonts need to have been loaded beforehand through one of the other Font functions).

func GetLayoutData added in v0.5.0 

func GetLayoutData[T any](props Properties) T

GetLayoutData returns the layout data stored in Properties as the specified type.

func GetOptionalCallbackData added in v0.5.0 

func GetOptionalCallbackData[T any](props Properties, defaultValue T) T

GetOptionalCallbackData returns the callback data stored in Properties as the specified type, unless there is no callback data, in which case the defaultValue is returned.

func GetOptionalData added in v0.5.0 

func GetOptionalData[T any](props Properties, defaultValue T) T

GetOptionalData returns the data stored in Properties as the specified type, unless there is no data, in which case the defaultValue is returned.

func GetOptionalLayoutData added in v0.5.0 

func GetOptionalLayoutData[T any](props Properties, defaultValue T) T

GetOptionalLayoutData returns the layout data stored in Properties as the specified type, unless there is no layout data, in which case the defaultValue is returned.

func Initialize 

func Initialize(scope Scope, instance Instance)

Initialize wires the framework using the specified root scope. The specified instance will be the root component used.

func Invalidate added in v0.11.0 

func Invalidate(scope Scope)

Invalidate causes the component that owns the specified scope to be reconciled.

This function should only be called from the UI thread.

func OpenFont added in v0.6.0 

func OpenFont(scope Scope, uri string) *ui.Font

OpenFont uses the ui.Context from the specified scope to load the font at the specified uri location.

If the font cannot be loaded for some reason, this function logs an error and returns nil.

func OpenFontCollection 

func OpenFontCollection(scope Scope, uri string) *ui.FontCollection

OpenFontCollection uses the ui.Context from the specified scope to load the font collection at the specified uri location.

If the collection cannot be loaded for some reason, this function logs an error and returns nil.

func OpenImage 

func OpenImage(scope Scope, uri string) *ui.Image

OpenImage uses the ui.Context from the specified scope to load image at the specified uri location.

If loading of the image fails for some reason, this function logs an error and returns nil.

func OpenSound added in v0.23.0 

func OpenSound(scope Scope, uri string) *ui.Sound

OpenSound uses the ui.Context from the specified scope to load the sound at the specified uri location.

If the sound cannot be loaded for some reason, this function logs an error and returns nil.

func Schedule 

func Schedule(scope Scope, fn func())

Schedule will schedule a closure function to run as soon as possible on the UI thread. It is safe to call this function from any thread.

Normally this would be used when a certain processing is being performed on a separate go routine and the result needs to be passed back to the UI thread.

The framework ensures that the closure will not be called if the component had been destroyed in the meantime.

func TypedValue added in v0.11.0 

func TypedValue[T any](scope Scope) T

TypedValue returns the value in the specified scope associated with the generic type.

If there is no value with the specified type in the Scope then the zero value for that type is returned.

func Value added in v0.23.0 

func Value[T any](scope Scope, key any) T

Value is a helper function that retrieves the value as the specified generic param type from the specified scope using the provided key.

If there is no value with the specified key in the Scope or if the value is not of the correct type then the zero value for that type is returned.

func Window 

func Window(scope Scope) *ui.Window

Window uses the specified scope to retrieve the Window that owns that particular scope.

func WithCallbackData 

func WithCallbackData(callbackData any)

WithCallbackData specifies the callback data to be passed to the component instance during instantiation.

Callback data is a mechanism for one component to listen for events on instanced components.

As callback data is expected to be a struct of function fields, they are not comparable in Go and as such cannot follow the lifecycle of data or layout data.

func WithChild 

func WithChild(key string, instance Instance)

WithChild adds a child to the given component instance. The child is appended to all previously registered children via the same method.

The key property is important. If in a subsequent render a component's child changes key or component type, the old one will be destroyed and a new one will be created. As such, to maintain a more optimized rendering and to prevent state loss, children should have a key assigned to them.

func WithChildren 

func WithChildren(children []Instance)

WithChildren sets the children for the given component instance. Keep in mind that any former children assigned via WithChild are replaced.

func WithData 

func WithData(data any)

WithData specifies the data to be passed to the component instance during instantiation.

Your data should be comparable in order to enable optimizations done by the framework. If you'd like to pass functions, in case of callbacks, they can be passed through the callback data.

func WithID added in v0.23.0 

func WithID(id string)

WithID assigns an ID to the element of the component instance.

func WithLayoutData 

func WithLayoutData(layoutData any)

WithLayoutData specifies the layout data to be passed to the component instance during instantiation.

LayoutData is kept separate by the framework as it is expected to have a different lifecycle (changes might be rare) and as such can be optimized.

Your layout data should be comparable in order to enable optimizations done by the framework.

func WithName added in v0.23.0 

func WithName(name string)

WithName assigns a name to the component instance. This is useful for debugging purposes.

func WithScopeValue added in v0.23.0 

func WithScopeValue(key, value any)

WithScopeValue modifies the scope to be passed to the component instance by assigning the specified value to the specified key.

func WithTypedScopeValue added in v0.23.0 

func WithTypedScopeValue[T any](value T)

WithTypedScopeValue is a helper function that adds a value to the scope using the value's type as the key.

func XWithCallbackData added in v0.8.0 

func XWithCallbackData(callbackData any)

XWithCallbackData is a helper function that resembles WithCallbackData but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

func XWithChild added in v0.8.0 

func XWithChild(key string, instance Instance)

XWithChild is a helper function that resembles WithChild but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

func XWithChildren added in v0.8.0 

func XWithChildren(children []Instance)

XWithChildren is a helper function that resembles WithChildren but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

func XWithData added in v0.8.0 

func XWithData(data any)

XWithData is a helper function that resembles WithData but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

func XWithID added in v0.23.0 

func XWithID(id string)

XWithID is a helper function that resembles WithID but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

func XWithLayoutData added in v0.8.0 

func XWithLayoutData(layoutData any)

XWithLayoutData is a helper function that resembles WithLayoutData but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

func XWithName added in v0.23.0 

func XWithName(name string)

XWithName is a helper function that resembles WithName but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

func XWithScopeValue added in v0.23.0 

func XWithScopeValue(key, value any)

XWithScopeValue is a helper function that resembles WithScopeValue but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

func XWithTypedScopeValue added in v0.23.0 

func XWithTypedScopeValue[T any](value T)

XWithTypedScopeValue is a helper function that resembles WithTypedScopeValue but does nothing. This allows one to experiment during development without having to comment out large sections of code and deal with compilation issues.

Types

type BaseComponent added in v0.11.0 

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

BaseComponent contains the basic functionality needed to implement a Renderable component. All component implementations should embed this struct.

func (*BaseComponent) Element added in v0.23.0 

func (c *BaseComponent) Element() *ui.Element

Element returns the underlying UI element of this component.

func (*BaseComponent) Invalidate added in v0.11.0 

func (c *BaseComponent) Invalidate()

Invalidate marks this component as needing to be reconciled.

func (*BaseComponent) Name added in v0.23.0 

func (c *BaseComponent) Name() string

Name returns the name of this component. This is mostly useful for debugging purposes.

func (*BaseComponent) Properties added in v0.11.0 

func (c *BaseComponent) Properties() Properties

Properties returns the properties with which this component was rendered.

func (*BaseComponent) Scope added in v0.11.0 

func (c *BaseComponent) Scope() Scope

Scope returns the scope in which this component is rendered.

type Component 

type Component interface {

	// TypeName returns the name of this component type.
	TypeName() string

	// Allocate allocates a new instance of this component type.
	Allocate(element *ui.Element, invalidate InvalidateFunc) Renderable

	// Release releases the specified component instance.
	Release(ref Renderable)

	// HandleCreate is called when the component is first created.
	HandleCreate(ref Renderable, scope Scope, properties Properties)

	// HandleUpdate is called when the component is about to be updated
	// with new properties.
	HandleUpdate(ref Renderable, scope Scope, properties Properties)

	// HandleDelete is called when the component is about to be deleted.
	HandleDelete(ref Renderable)
}

Component represents the definition of a component.

func ContextScoped added in v0.8.0 

func ContextScoped(delegate Component) Component

ContextScoped will cause a wrapped component to receive a Scope that has a dedicated ui.Context with a lifecycle equal to the lifecycle of the component instance.

func Define 

func Define[T Renderable]() Component

Define defines a new component using the specified Go type as template.

type CreateNotifiable added in v0.10.0 

type CreateNotifiable interface {

	// OnCreate is called when a component is first instantiated.
	//
	// When called, an Element is already assigned to the component
	// and the Scope and Properties are also set.
	//
	// The Render call has not yet been called, however, as usually a component
	// would fetch data during this call that is later usind during rendering.
	// As such, no children are yet created as well.
	OnCreate()
}

CreateNotifiable should be implemented by component types that want to be notified of component creation.

type DeleteNotifiable added in v0.10.0 

type DeleteNotifiable interface {

	// OnDelete is called just before a component is destroyed.
	//
	// No rendering is performed after this call.
	OnDelete()
}

DeleteNotifiable should be implemented by component types that want to be notified of component deletion.

type ElementData 

type ElementData struct {

	// Essence is a mechanism to register hooks for various Element events.
	Essence ui.Essence

	// Bounds, if specified, forces the Element to have the specified bounds.
	// This should only be used when a layout system is not in place.
	Bounds opt.T[ui.Bounds]

	// IdealSize is a hint to the layout system about the ideal size of
	// the Element.
	IdealSize opt.T[ui.Size]

	// Padding specifies the spacing between the Element's border and its
	// content.
	Padding ui.Spacing

	// Layout specifies how children of the Element should be laid out.
	Layout ui.Layout

	// Enabled, if specified, controls whether the Element is enabled
	// or disabled.
	Enabled opt.T[bool]

	// Visible, if specified, controls whether the Element is visible
	// or hidden. A visible element still takes space in the layout.
	Visible opt.T[bool]

	// CanAutoFocus, if specified, controls whether the Element can
	// automatically receive focus when clicked or touched.
	CanAutoFocus opt.T[bool]

	// CanAutoUnfocus, if specified, controls whether the Element can
	// automatically lose focus when another Element is clicked or touched.
	CanAutoUnfocus opt.T[bool]

	// Focused, if specified, controls whether the Element should have focus.
	Focused opt.T[bool]

	// CreateFocused controls whether the Element should request focus when
	// created.
	CreateFocused bool
}

ElementData is the struct that should be used when configuring an Element component's data.

type Instance 

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

Instance represents the instantiation of a given Component chain.

func New 

func New(component Component, setupFn func()) Instance

New instantiates the specified component. The setupFn function is used to apply configurations to the component in a DSL manner.

NOTE: Creating an instance with New does not necessarily mean that a component will be freshly instantiated. If this occurs during re-rendering the framework will reuse former instances when possible.

func (Instance) Key added in v0.3.0 

func (i Instance) Key() string

Key returns the child key that is registered for this Instance in case the Instance was created as part of a WithChild directive.

func (*Instance) Properties added in v0.11.0 

func (i *Instance) Properties() Properties

Properties returns the properties assigned to this instance.

type InvalidateFunc added in v0.11.0 

type InvalidateFunc func()

InvalidateFunc can be used to indicate that the component's data has been internally modified and it needs to be reconciled.

type Overlay added in v0.3.0 

type Overlay interface {

	// Close closes this Overlay.
	Close()
}

Overlay represents a UI Element that stays on top of all existing elements and is first to receive events.

func OpenOverlay added in v0.3.0 

func OpenOverlay(scope Scope, instance Instance) Overlay

OpenOverlay opens a new Overlay that will take the appearance described in the specified instance.

type Properties 

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

Properties is a holder for all user-specified data necessary to render a component.

func (Properties) CallbackData 

func (p Properties) CallbackData() any

CallbackData returns the callback data that can be used by the component to notify its owner regarding key events.

func (Properties) Children 

func (p Properties) Children() []Instance

Children returns all the child instances that this component should host.

func (Properties) Data 

func (p Properties) Data() any

Data returns the configuration data needed to render the component.

func (Properties) LayoutData 

func (p Properties) LayoutData() any

LayoutData returns the layout data needed to layout the component.

type Renderable added in v0.11.0 

type Renderable interface {

	// Render should produce the component hierarchy for this component.
	Render() Instance
	// contains filtered or unexported methods
}

Renderable is a component instance.

type Scope added in v0.8.0 

type Scope interface {

	// Context returns the ui.Context that is applicable for this component scope.
	Context() *ui.Context

	// Value returns the stored arbitrary value for the specified arbitrary key.
	// This is a mechanism through which external frameworks can attach metadata
	// to scopes.
	Value(key any) any
}

Scope represents a component sub-hierarchy region.

func ContextScope added in v0.8.0 

func ContextScope(parent Scope, ctx *ui.Context) Scope

ContextScope returns a new Scope that extends the specified parent scope but uses a different ui.Context. This can be used to have sections of the UI use a dedicated resource set.

NOTE: The returned scope is NOT responsible for managing the lifecycle of the provided ui.Context. The caller is responsible for ensuring that the context remains valid for the duration of the scope's usage and is properly released afterwards.

func RootScope added in v0.8.0 

func RootScope(window *ui.Window) Scope

RootScope initializes a new scope associated with the specified window.

One would usually use this method to acquire a root scope to be later used in Initialize to bootstrap the framework.

func TypedValueScope added in v0.11.0 

func TypedValueScope[T any](parent Scope, value T) Scope

TypedValueScope returns a ValueScope that uses the value's type as the key.

This makes it easier to store and retrieve values without having to define custom keys.

func ValueScope added in v0.8.0 

func ValueScope(parent Scope, key, value any) Scope

ValueScope creates a new Scope that extends the specified parent scope by adding the specified key-value pair.

This function would not typically be used directly. Instead, use one of the rendering functions to modify the scope of a component instance.

type ScopeModifier added in v0.23.0 

type ScopeModifier func(Scope) Scope

ScopeModifier represents a function that takes a scope and returns a modified version of it.

Modifiers are not usually applied directly but rather through helper render functions.

func ChainScopeModifier added in v0.23.0 

func ChainScopeModifier(parent, current ScopeModifier) ScopeModifier

ChainScopeModifier creates a new ScopeModifier that applies the parent modifier first and then the current modifier. If the parent modifier is nil, only the current modifier is used.

This function would normally not be used by user code, instead a rendering function would be used to chain scope modifications.

func ScopeValueModifier added in v0.23.0 

func ScopeValueModifier(key, value any) ScopeModifier

ScopeValueModifier creates a ScopeModifier that adds a value to the scope it is applied to using the specified key.

This function would normally not be used by user code, instead a rendering function such as WithScopeValue would be used.

func TypedScopeValueModifier added in v0.23.0 

func TypedScopeValueModifier[T any](value T) ScopeModifier

TypedScopeValueModifier creates a ScopeModifier that adds a value to the scope it is applied to using the value's type as the key.

This function would normally not be used by user code, instead a rendering function such as WithTypedScopeValue would be used.

type UpdateNotifiable added in v0.10.0 

type UpdateNotifiable interface {

	// OnUpdate is called whenever a component's properties have changed.
	//
	// This method is called prior to rendering the component again.
	OnUpdate()
}

UpdateNotifiable should be implemented by component types that want to be notified of component updates.

type UpsertNotifiable added in v0.11.0 

type UpsertNotifiable interface {

	// OnUpsert is called whenever a component's properties have changed.
	//
	// This method is called prior to rendering the component and updating
	// or initializing any children.
	OnUpsert()
}

UpsertNotifiable should be implemented by component types that want to be notified of both component creations and updates.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.