list

package
v0.0.0-...-6dca35c Latest Latest
Warning

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

Go to latest
Published: May 15, 2024 License: MIT, Unlicense Imports: 7 Imported by: 3

Documentation

Index

Constants

View Source
const DefaultPrefetch = 0.15

DefaultPrefetch is the default prefetching threshold.

View Source
const NoSerial = Serial("")

NoSerial is a special serial that can be used by Elements that do not require a unique identifier. Only stateless elements may go without a unique identifier.

Variables

This section is empty.

Functions

func MakeIndexValid

func MakeIndexValid(slice []Element, index int) int

MakeIndexValid forces the given index to be in bounds for given slice.

func SliceFilter

func SliceFilter(s *[]Element, predicate func(elem Element) bool)

SliceFilter removes elements for which the predicate returns false from the slice.

func SliceRemove

func SliceRemove(s *[]Element, index int)

SliceRemove takes the given index of a slice and swaps it with the final index in the slice, then shortens the slice by one element. This hides the element at index from the slice, though it does not erase its data.

Types

type Allocator

type Allocator func(current Element) (state interface{})

Allocator is a function that can allocate the appropriate state type for a given Element. It will only be invoked for Elements that return a serial from their Serial() method. It may return nil, indicating that the element in question does not need any persistent state.

type Compact

type Compact struct {
	Size int
	Comparator
	// contains filtered or unexported fields
}

Compact is a list of sorted Elements with a specific maximum size. It supports insertion, updating elements in place, and removing elements.

func NewCompact

func NewCompact(size int, comp Comparator) *Compact

NewCompact returns a Compact with the given maximum size and using the given Comparator to sort its contents.

func (*Compact) Apply

func (c *Compact) Apply(insertOrUpdate []Element, updateOnly []Element, remove []Serial)

Apply inserts, updates, and removes elements from within the contents of the compact.

func (*Compact) Compact

func (c *Compact) Compact(keepStart, keepEnd Serial) (contents []Element, compacted []Serial)

Compact returns a compacted slice of the elements managed by the Compact. The resulting elements are garanteed to be sorted using the Compact's Comparator and there will usually be no more than c.Size elements. The exception is when c.Size is smaller than 3 times the distance between keepStart and keepEnd. In that case, Compact will attempt to return a slice containing the region described by [keepStart,keepEnd] with the same number of elements on either side.

type Comparator

type Comparator func(a, b Element) bool

Comparator returns whether element a sorts before element b in the list.

type Direction

type Direction uint8

Direction indicates a direction relative to the viewport of a list.

const (
	// NoDirection refers to no specific direction.
	NoDirection Direction = iota
	// Before refers to serial values earlier than a reference value
	// (usually the beginning of the viewport).
	Before
	// After refers to serial values after a reference value
	// (usually the end of the viewport).
	After
	// Both indicates the Before and After Directions simultaneously.
	Both
)

func (*Direction) Add

func (d *Direction) Add(other Direction)

Add combines the receiving direction with the parameter.

func (Direction) Contains

func (d Direction) Contains(other Direction) bool

Contains returns whether the receiver direction logically includes the provided direction.

func (Direction) String

func (d Direction) String() string

String converts a direction into a printable representation.

type Element

type Element interface {
	// Serial returns a unique identifier for the Element, if it has one.
	// In order for an Element to be stateful, it _must_ return a unique
	// Serial. Elements that are not stateful may return the special Serial
	// NoSerial to indicate that they do not need any state allocated
	// for them.
	Serial() Serial
}

Element is a type that can be presented by a Manager.

type End

type End struct{}

End is a psuedo Element that indicates the end of the list view, that is, the end of the elements currently loaded in memory. Type assert inside Synthesizer to check for list boundary.

func (End) Serial

func (End) Serial() Serial

type Hooks

type Hooks struct {
	Synthesizer
	Comparator
	Loader
	Presenter
	Allocator
	// Invalidator triggers a new frame in the window displaying the managed
	// list.
	Invalidator func()
}

Hooks provides the lifecycle hooks necessary for a Manager to orchestrate the state of all its managed elements. See the documentation of each function type for details.

func DefaultHooks

func DefaultHooks(w *app.Window, th *material.Theme) Hooks

DefaultHooks returns a Hooks instance with most fields defined as no-ops. It does populate the Invalidator field with w.Invalidate.

type Loader

type Loader func(direction Direction, relativeTo Serial) (elems []Element, more bool)

Loader is a function that can fulfill load requests. If it returns a response with no elements in a given direction or false as its second return value, the manager will not invoke the loader in that direction again until the manager loads data from the other end of the list or another manger state update occurs.

Loader implements pull modifications. When the manager wants more data it will invoke the Loader hook to get more.

type Manager

type Manager struct {
	// Prefetch specifies a minimum threshold at which to start prefetching more
	// data (in either direction), as a percentage in the range [0,1] of the
	// total number of elements present in the list.
	//
	// In other words, a prefetch of 0.15 ensures load will be invoked if the
	// viewport is laying out the first or final 15% of elements.
	//
	// Defaults to '0.15' (15%), clamped to '1.0' (100%).
	Prefetch float32

	// Stickiness specifies direction(s) in which the list is "sticky". If the list
	// reaches the end of loaded content in a sticky direction, it will latch onto
	// the end of the list and remain there when new content loads at that end of
	// the list. The user can scroll away from the end of the list, which will
	// break the latch on that end of the list until they scroll back to the end.
	//
	// The default of NoDirection will cause no ends to be sticky. Setting
	// This field to "Before" will make the beginning of the list sticky. Setting this
	// field to "After" will make the end of the list sticky. Setting it to "Both"
	// will make both ends sticky.
	Stickiness Direction
	// contains filtered or unexported fields
}

Manager presents heterogenous Element data. Each element could represent any element of an interface with a list.

State is updated with two strategies, push and pull:

Pull updates occur when the list has scrolled to the end of it's current data and needs to ask for more. In this case, the Loader hook will be invoked concurrently to get the data, if any.

Push updates occur when the data source changes outside of the list. The application can push those changes into the list with a call to `Modify`.

Any changes that fall outside the bounds of the data will be ignored and expected to be Loaded appropriately when scrolled into view.

func NewManager

func NewManager(maxSize int, hooks Hooks) *Manager

NewManager constructs a manager. maxSize defines the number of raw elements that the list will manage simultaneously. If the list grows beyond this, it will automatically discard some elements to stay beneath this limit. The provided hooks implement application-specific logic necessary for the Manager to do its job. This constructor will panic if any hooks are not defined.

func (*Manager) InPlace

func (m *Manager) InPlace(updateOnly []Element)

InPlace atomically modifies the Manager to update from the provided elements.

Elements provided that exist in the Manager will be updated in-place, and those that do not will be ignored.

func (*Manager) Layout

func (m *Manager) Layout(gtx layout.Context, index int) layout.Dimensions

Layout the element at the given index.

func (*Manager) ManagedElements

func (m *Manager) ManagedElements(gtx layout.Context) []Element

ManagedElements returns the slice of elements managed by the manager during the current frame. This MUST be called from the layout goroutine, and callers must not insert, remove, or reorder elements.

This method is useful for checking the relative positions of managed elements during layout. Many applications will never need this functionality.

func (*Manager) ManagedState

func (m *Manager) ManagedState(gtx layout.Context) map[Serial]interface{}

ManagedState returns the map of widget state managed by the manager during the current frame. This MUST be called from the layout goroutine, and callers must not insert or remove elements from the returned map.

This method is useful for checking for events on all managed widgets in a single loop ahead of laying each element out, rather than checking each element during layout. Many applications will never need this functionality.

func (*Manager) Modify

func (m *Manager) Modify(newOrUpdated []Element, updateOnly []Element, remove []Serial)

Modify is a thread-safe means of atomically pushing modifications to the Manager: inserting elements into, updating elements within, or removing elements from the managed list state.

Elements in the newOrUpdated parameter will be inserted into the managed state, and any pre-existing element with the same serial will be removed. Elements in the updateOnly parameter will replace any elements in the managed list with the same serial, but otherwise will not be inserted. Elements with a serial in the remove parameter will be removed from the managed list.

Elements that sort outside of the view will be ignored. In that case the loader hook should load it when scrolled into view.

This method may block, and should not be called from the goroutine that is performing layout.

Use this method to push modifications from the data source.

For "pull" modifications, see the Loader hook.

func (*Manager) Remove

func (m *Manager) Remove(remove []Serial)

Remove atomically modifies the Manager to remove elements based on a Serial.

Elements in the Manager that are specified in the remove list will be deleted. Serials that map to non-existant elements will be ignored.

func (*Manager) Shutdown

func (m *Manager) Shutdown()

Shutdown kills the asynchronous goroutine powering the list. After this, the Manager can no longer be used.

func (*Manager) Update

func (m *Manager) Update(newOrUpdated []Element)

Update atomically modifies the Manager to insert or update from the provided elements.

Elements provided that exist in the Manager will be updated in-place, and those that do not will be inserted as new elements.

func (*Manager) UpdatedLen

func (m *Manager) UpdatedLen(list *layout.List) int

UpdatedLen returns the number of elements managed by this manager, and also updates the state of the ListManager and List prior to layout. This method should be called to provide a layout.List with the length of the underlying list, and the layout.List should be passed in as a parameter. If the provided layout.List has its ScrollToEnd field set to true, the Manager will attempt to respect that when handling content inserted asynchronously with Modify() (and similar methods).

type Presenter

type Presenter func(current Element, state interface{}) layout.Widget

Presenter is a function that can transform the data for an Element into a widget to be laid out in the user interface. It must not return nil. The state parameter may be nil if the Element either has no Serial or if the Allocator function returned nil for the element.

type Serial

type Serial string

Serial uniquely identifies a list element.

func SerialAtOrAfter

func SerialAtOrAfter(list []Element, index int) Serial

SerialAtOrAfter returns the serial of the element at the given index if it is not NoSerial. If it is NoSerial, this method iterates forwards towards the end of the list, searching for the nearest element with a serial. If no serial is found before the end of the list, NoSerial is returned.

func SerialAtOrBefore

func SerialAtOrBefore(list []Element, index int) Serial

SerialAtOrBefore returns the serial of the element at the given index if it is not NoSerial. If it is NoSerial, this method iterates backwards towards the beginning of the list, searching for the nearest element with a serial. If no serial is found before the beginning of the list, NoSerial is returned.

type Start

type Start struct{}

Start is a psuedo Element that indicates the beginning of the list view, that is, the beginning of the elements currently loaded in memory. Type assert inside Synthesizer to check for list boundary.

func (Start) Serial

func (Start) Serial() Serial

type Synthesis

type Synthesis struct {
	// Elements holds the resulting elements.
	Elements []Element
	// SerialToIndex maps the serial of an element to the index it
	// occupies within the Elements slice.
	SerialToIndex map[Serial]int
	// ToSourceIndicies maps each index in Elements to the index of
	// the element that generated it when given to the Synthesizer.
	// It is always true that Elements[i] was synthesized from
	// Source[ToSourceIndicies[i]].
	ToSourceIndicies []int
	// The source elements.
	Source []Element
}

Synthesis holds the results of transforming a slice of Elements with a Synthesizer hook.

func Synthesize

func Synthesize(elements []Element, synth Synthesizer) Synthesis

Synthesize applies a Synthesizer to a slice of elements, returning the resulting slice of elements as well as a mapping from the index of each resulting element to the input element that generated it.

func (Synthesis) SerialAt

func (s Synthesis) SerialAt(index int) Serial

SerialAt returns the serial at the given index within the Source slice, if there is one.

func (Synthesis) String

func (s Synthesis) String() string

func (Synthesis) ViewportToSerials

func (s Synthesis) ViewportToSerials(viewport layout.Position) (Serial, Serial)

ViewportToSerials converts the First and Count fields of the provided viewport into a pair of serials representing the range of elements visible within that viewport.

type Synthesizer

type Synthesizer func(previous, current, next Element) []Element

Synthesizer is a function that can insert synthetic elements into a list of elements. The most common use case for this is to insert separators between elements indicating the passage of time or some other logical transition between them. previous may be nil if the Synthesizer is invoked at the beginning of the list. This function may choose to return nil to prevent current from being shown.

Jump to

Keyboard shortcuts

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