component

package
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Jan 25, 2024 License: MIT Imports: 10 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.

func CloseOverlay added in v0.12.0 

func CloseOverlay(scope 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.

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 GetScopeValue added in v0.8.0 

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

GetScopeValue 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 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 recalculated.

func IsEqualData added in v0.3.0 

func IsEqualData(old, new any) bool

IsEqualData compares if the two data objects are equal

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 Schedule 

func Schedule(scope Scope, fn func())

Schedule will schedule a closure function to run as soon as possible on the UI 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 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 interface{})

WithCallbackData specifies the callback data to be passed to the component 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. 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. Keep in mind that any former children assigned via WithChild are replaced.

func WithData 

func WithData(data interface{})

WithData specifies the data to be passed to the component 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 WithLayoutData 

func WithLayoutData(layoutData interface{})

WithLayoutData specifies the layout data to be passed to the component 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 WithScope added in v0.8.0 

func WithScope(scope Scope)

WithScope attaches a custom Scope to this component. Any child components will inherit the Scope unless overridden by another call to WithScope.

func XWithCallbackData added in v0.8.0 

func XWithCallbackData(callbackData interface{})

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 interface{})

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 XWithLayoutData added in v0.8.0 

func XWithLayoutData(layoutData interface{})

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 XWithScope added in v0.8.0 

func XWithScope(scope Scope)

XWithScope is a helper function that resembles WithScope 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
}

func (*BaseComponent) Invalidate added in v0.11.0 

func (c *BaseComponent) Invalidate()

func (*BaseComponent) Properties added in v0.11.0 

func (c *BaseComponent) Properties() Properties

func (*BaseComponent) Scope added in v0.11.0 

func (c *BaseComponent) Scope() Scope

type Component 

type Component interface {
	TypeName() string

	Allocate(scope Scope, invalidate InvalidateFunc) Renderable
	Release(ref Renderable)

	NotifyCreate(ref Renderable, properties Properties)
	NotifyUpdate(ref Renderable, properties Properties)
	NotifyDelete(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(template 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.
	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.
	OnDelete()
}

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

type ElementData 

type ElementData struct {
	Reference **ui.Element
	Essence   ui.Essence
	Enabled   opt.T[bool]
	Visible   opt.T[bool]
	Focusable opt.T[bool]
	Focused   opt.T[bool]
	Bounds    opt.T[ui.Bounds]
	IdealSize opt.T[ui.Size]
	Padding   ui.Spacing
	Layout    ui.Layout
}

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() interface{}

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() interface{}

Data returns the configuration data needed to render the component.

func (Properties) LayoutData 

func (p Properties) LayoutData() interface{}

LayoutData returns the layout data needed to layout the component.

type Renderable added in v0.11.0 

type Renderable interface {

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

Renderable is a component that is implemented through a Go type.

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 that will be freed once the hierarchy is destroyed.

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.

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.

type UpdateNotifiable added in v0.10.0 

type UpdateNotifiable interface {

	// OnUpdate is called whenever a component's properties have changed.
	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.
	OnUpsert()
}

UpsertNotifiable should be implemented by component types that want to be notified of 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.