Documentation
¶
Index ¶
- Constants
- func MakeIndexValid(slice []Element, index int) int
- func SliceFilter(s *[]Element, predicate func(elem Element) bool)
- func SliceRemove(s *[]Element, index int)
- type Allocator
- type Compact
- type Comparator
- type Direction
- type Element
- type End
- type Hooks
- type Loader
- type Manager
- func (m *Manager) InPlace(updateOnly []Element)
- func (m *Manager) Layout(gtx layout.Context, index int) layout.Dimensions
- func (m *Manager) ManagedElements(gtx layout.Context) []Element
- func (m *Manager) ManagedState(gtx layout.Context) map[Serial]interface{}
- func (m *Manager) Modify(newOrUpdated []Element, updateOnly []Element, remove []Serial)
- func (m *Manager) Remove(remove []Serial)
- func (m *Manager) Shutdown()
- func (m *Manager) Update(newOrUpdated []Element)
- func (m *Manager) UpdatedLen(list *layout.List) int
- type Presenter
- type Serial
- type Start
- type Synthesis
- type Synthesizer
Constants ¶
const DefaultPrefetch = 0.15
DefaultPrefetch is the default prefetching threshold.
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 ¶
MakeIndexValid forces the given index to be in bounds for given slice.
func SliceFilter ¶
SliceFilter removes elements for which the predicate returns false from the slice.
func SliceRemove ¶
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 ¶
Apply inserts, updates, and removes elements from within the contents of the compact.
func (*Compact) Compact ¶
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 ¶
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 )
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.
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.
type Loader ¶
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 ¶
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 ¶
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) ManagedElements ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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.
type Synthesizer ¶
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.
Source Files