Documentation ¶
Overview ¶
Package ki provides the base element of Goki Trees: Ki = Tree in Japanese, and "Key" in English -- powerful tree structures supporting scenegraphs, programs, parsing, etc.
The Node struct that implements the Ki interface, which can be used as an embedded type (or a struct field) in other structs to provide core tree functionality, including:
Parent / Child Tree structure -- each Node can ONLY have one parent. Node struct's can also have Node fields -- these are functionally like fixed auto-named children.
Paths for locating Nodes within the hierarchy -- key for many use-cases, including ability to convert pointers to/from strings for IO and robust deep copy and move functions. The path separator is / for children and . for fields.
Apply a function across nodes up or down a tree (natural "me first", breadth-first, depth-first) -- very flexible for tree walking.
Generalized I/O -- can Save and Load the Tree as JSON, XML, etc -- including pointers which are saved using paths and automatically cached-out after loading -- enums also bidirectionally convertable to strings using enum type registry in kit package.
Robust deep copy, clone, move of nodes.
Signal sending and receiving between Nodes (simlar to Qt Signals / Slots) -- setup connections once and then emit signals to all receivers when relevant event happens.
Robust state updating -- wrap updates in UpdateStart / End, and signals are blocked until the final end, at the highest affected level in the tree, at which point a single update signal is sent -- automatically gives the minimal update.
Properties (as a string-keyed map) with property inheritance, including type-level properties via kit type registry.
In general, the names of the children of a given node should all be unique. The following functions defined in ki package can be used:
* UniqueNameCheck(node) to check for unique names on node if uncertain. * UniqueNameCheckAll(node) to check entire tree under given node. * UniquifyNames(node) to add a suffix to name to ensure uniqueness. * UniquifyNamesAll(node) to to uniquify all names in entire tree.
The Ki interface is designed to support virtual method calling in Go and is only intended to be implemented once, by the ki.Node type (as opposed to interfaces that are used for hiding multiple different implementations of a common concept). Thus, all of the fields in ki.Node are exported (have captital names), to be accessed directly in types that embed and extend the ki.Node. The Ki interface has the "formal" name (e.g., Children) while the Node has the "nickname" (e.g., Kids). See the Naming Conventions on the Goki Wiki for more details.
Each Node stores the Ki interface version of itself, as This() / Ths which enables full virtual function calling by calling the method on that interface instead of directly on the receiver Node itself. This requires proper initialization via Init method of the Ki interface.
Index ¶
- Constants
- Variables
- func AsKi(v any) (Ki, *Node)
- func ChildByType[T Ki](k Ki, embeds bool, startIdx ...int) T
- func CopyFromRaw(kn, frm Ki) error
- func CopyProps(dest *map[string]any, src map[string]any, deepCopy bool)
- func DecodeXMLCharData(d *xml.Decoder) (val string, err error)
- func DecodeXMLCharEl(d *xml.Decoder) (name, val string, err error)
- func DecodeXMLEndEl(d *xml.Decoder, start xml.StartElement) error
- func DecodeXMLStartEl(d *xml.Decoder) (start xml.StartElement, err error)
- func DeleteFromParent(kid Ki)
- func DeletingChildren(k Ki)
- func Depth(kn Ki) int
- func EscapePathName(name string) string
- func InitNode(this Ki)
- func InsertNewChild[T Ki](par Ki, at int, name ...string) T
- func IsKi(typ reflect.Type) bool
- func IsRoot(k Ki) bool
- func MoveToParent(kid Ki, parent Ki)
- func New[T Ki](par Ki, name ...string) T
- func NewRoot[T Ki](name ...string) T
- func ParentAllChildren(kn Ki)
- func ParentByType[T Ki](k Ki, embeds bool) T
- func ReadRootTypeJSON(b []byte) (*gti.Type, []byte, error)
- func RootTypeJSON(k Ki) []byte
- func SaveNewJSON(k Ki, filename string) error
- func SetDepth(kn Ki, depth int)
- func SetParent(kid Ki, parent Ki)
- func SetPropStr(pr Props, key, val string)
- func SetSubProps(pr Props, key string, sp Props)
- func SliceDeleteAtIndex(sl *[]Ki, idx int) error
- func SliceIndexByFunc(sl *[]Ki, match func(k Ki) bool, startIdx ...int) (int, bool)
- func SliceIndexByName(sl *[]Ki, name string, startIdx ...int) (int, bool)
- func SliceIndexOf(sl *[]Ki, kid Ki, startIdx ...int) (int, bool)
- func SliceInsert(sl *[]Ki, k Ki, idx int)
- func SliceIsValidIndex(sl *[]Ki, idx int) error
- func SliceMove(sl *[]Ki, frm, to int) error
- func SliceSwap(sl *[]Ki, i, j int) error
- func ThisCheck(k Ki) error
- func UnescapePathName(name string) string
- func UniqueNameCheck(k Ki) bool
- func UniqueNameCheckAll(kn Ki) bool
- func UniquifyNames(kn Ki)
- func UniquifyNamesAddIndex(kn Ki)
- func UniquifyNamesAll(kn Ki)
- func UnmarshalPost(kn Ki)
- func UpdateReset(kn Ki)
- func WriteNewJSON(k Ki, writer io.Writer) error
- type BlankProp
- type Config
- type DeletedKi
- type Flags
- func (i Flags) BitIndexString() string
- func (i Flags) Desc() string
- func (i Flags) HasFlag(f enums.BitFlag) bool
- func (i Flags) Int64() int64
- func (i Flags) IsValid() bool
- func (i Flags) MarshalText() ([]byte, error)
- func (i *Flags) SetFlag(on bool, f ...enums.BitFlag)
- func (i *Flags) SetInt64(in int64)
- func (i *Flags) SetString(s string) error
- func (i *Flags) SetStringOr(s string) error
- func (i Flags) String() string
- func (i *Flags) UnmarshalText(text []byte) error
- func (i Flags) Values() []enums.Enum
- type Ki
- type Node
- func (n *Node) AddChild(kid Ki) error
- func (n *Node) AsKi() *Node
- func (n *Node) BaseType() *gti.Type
- func (n *Node) Child(idx int) Ki
- func (n *Node) ChildByName(name string, startIdx ...int) Ki
- func (n *Node) ChildByType(t *gti.Type, embeds bool, startIdx ...int) Ki
- func (n *Node) Children() *Slice
- func (n *Node) ClearUpdateFlags()
- func (n *Node) Clone() Ki
- func (n *Node) ConfigChildren(config Config) (mods, updt bool)
- func (n *Node) CopyFieldsFrom(frm any)
- func (n *Node) CopyFrom(frm Ki) error
- func (n *Node) Delete(destroy bool)
- func (n *Node) DeleteChild(child Ki, destroy bool) bool
- func (n *Node) DeleteChildAtIndex(idx int, destroy bool) bool
- func (n *Node) DeleteChildByName(name string, destroy bool) bool
- func (n *Node) DeleteChildren(destroy bool)
- func (n *Node) DeleteProp(key string)
- func (n *Node) Destroy()
- func (n *Node) FieldByName(field string) (Ki, error)
- func (n *Node) FindPath(path string) Ki
- func (n *Node) FlagType() enums.BitFlagSetter
- func (n *Node) HasChildren() bool
- func (n *Node) IndexInParent() int
- func (n *Node) InitName(k Ki, name ...string)
- func (n *Node) InsertChild(kid Ki, at int) error
- func (n *Node) InsertNewChild(typ *gti.Type, at int, name ...string) Ki
- func (n *Node) Is(f enums.BitFlag) bool
- func (t *Node) KiType() *gti.Type
- func (n *Node) Name() string
- func (t *Node) New() Ki
- func (n *Node) NewChild(typ *gti.Type, name ...string) Ki
- func (n *Node) NumChildren() int
- func (n *Node) NumLifetimeChildren() uint64
- func (n *Node) OnAdd()
- func (n *Node) OnChildAdded(child Ki)
- func (n *Node) OnChildDeleting(child Ki)
- func (n *Node) OnChildrenDeleting()
- func (n *Node) OnDelete()
- func (n *Node) OnInit()
- func (n *Node) OnUpdated()
- func (n *Node) Parent() Ki
- func (n *Node) ParentByName(name string) Ki
- func (n *Node) ParentByType(t *gti.Type, embeds bool) Ki
- func (n *Node) ParentLevel(par Ki) int
- func (n *Node) Path() string
- func (n *Node) PathFrom(par Ki) string
- func (n *Node) Prop(key string) any
- func (n *Node) PropInherit(key string, inherit bool) (any, bool)
- func (n *Node) PropTag() string
- func (n *Node) Properties() *Props
- func (n *Node) ReadXML(reader io.Reader) error
- func (n *Node) SetChild(kid Ki, idx int, name ...string) error
- func (n *Node) SetChildAdded()
- func (n *Node) SetFlag(on bool, f ...enums.BitFlag)
- func (n *Node) SetNChildren(trgn int, typ *gti.Type, nameStub ...string) (mods, updt bool)
- func (n *Node) SetName(name string)
- func (n *Node) SetProp(key string, val any)
- func (n *Node) SetProps(props Props)
- func (n *Node) String() string
- func (n *Node) This() Ki
- func (n *Node) UpdateEnd(updt bool)
- func (n *Node) UpdateStart() bool
- func (n *Node) WalkBreadth(fun func(k Ki) bool)
- func (n *Node) WalkPost(doChildTestFunc func(Ki) bool, fun func(Ki) bool)
- func (n *Node) WalkPre(fun func(Ki) bool)
- func (n *Node) WalkPreLevel(fun func(k Ki, level int) bool)
- func (n *Node) WalkPreNode(fun func(Ki) bool)
- func (n *Node) WalkUp(fun func(k Ki) bool) bool
- func (n *Node) WalkUpParent(fun func(k Ki) bool) bool
- func (n *Node) WriteXML(writer io.Writer, indent bool) error
- type PropSlice
- type PropStruct
- type Props
- type Slice
- func (sl *Slice) Config(n Ki, config Config) (mods, updt bool)
- func (sl *Slice) ConfigCopy(n Ki, frm Slice)
- func (sl *Slice) CopyFrom(frm Slice)
- func (sl *Slice) DeleteAtIndex(idx int) error
- func (sl *Slice) Elem(idx int) Ki
- func (sl *Slice) ElemByName(name string, startIdx ...int) Ki
- func (sl *Slice) ElemByNameTry(name string, startIdx ...int) (Ki, error)
- func (sl *Slice) ElemByType(t *gti.Type, embeds bool, startIdx ...int) Ki
- func (sl *Slice) ElemByTypeTry(t *gti.Type, embeds bool, startIdx ...int) (Ki, error)
- func (sl *Slice) ElemFromEnd(idx int) Ki
- func (sl *Slice) ElemFromEndTry(idx int) (Ki, error)
- func (sl *Slice) ElemTry(idx int) (Ki, error)
- func (sl *Slice) IndexByFunc(match func(k Ki) bool, startIdx ...int) (int, bool)
- func (sl *Slice) IndexByName(name string, startIdx ...int) (int, bool)
- func (sl *Slice) IndexByType(t *gti.Type, embeds bool, startIdx ...int) (int, bool)
- func (sl *Slice) IndexOf(kid Ki, startIdx ...int) (int, bool)
- func (sl *Slice) Insert(k Ki, idx int)
- func (sl *Slice) IsValidIndex(idx int) error
- func (sl Slice) MarshalJSON() ([]byte, error)
- func (sl Slice) MarshalXML(e *xml.Encoder, start xml.StartElement) error
- func (sl *Slice) Move(frm, to int) error
- func (sl *Slice) Swap(i, j int) error
- func (sl *Slice) UnmarshalJSON(b []byte) error
- func (sl *Slice) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
- type TravMap
- type TypeAndName
Constants ¶
const ( // Continue = true can be returned from tree iteration functions to continue // processing down the tree, as compared to Break = false which stops this branch. Continue = true // Break = false can be returned from tree iteration functions to stop processing // this branch of the tree. Break = false // Embeds is used for methods that look for children or parents of different types. // Passing this argument means to look for embedded types for matches. Embeds = true // NoEmbeds is used for methods that look for children or parents of different types. // Passing this argument means to NOT look for embedded types for matches. NoEmbeds = false // DestroyKids is used for Delete methods to indicate that deleted children // should be destroyed (else can be re-used somewhere else). DestroyKids = true // NoDestroyKids is used for Delete methods to indicate that deleted children // should NOT be destroyed, so they can be re-used somewhere else. NoDestroyKids = false // ShallowCopy is used for Props CopyFrom functions to indicate a shallow copy of // Props or PropSlice within Props (points to source props) ShallowCopy = true // DeepCopy is used for Props CopyFrom functions to indicate a deep copy of // Props or PropSlice within Props DeepCopy = true // Inherit is used for PropInherit to indicate that inherited properties // from parent objects should be checked as well. Otherwise not. Inherit = true // NoInherit is used for PropInherit to indicate that inherited properties // from parent objects should NOT be checked. NoInherit = false // Indent is used for Write methods to indicate that indenting should be done. Indent = true // NoIndent is used for Write methods to indicate that indenting should NOT be done. NoIndent = false )
Named consts for bool args
const ( // Version is the version of this package being used Version = "v2.0.0-dev0.0.33" // GitCommit is the commit just before the latest version commit GitCommit = "09088c3" // VersionDate is the date-time of the latest version commit in UTC (in the format 'YYYY-MM-DD HH:MM', which is the Go format '2006-01-02 15:04') VersionDate = "2023-12-26 23:30" )
const EnumTypeFlag string = "EnumType:Flag"
EnumTypeFlag is a Props property name that indicates what enum type to use as the type for the flags field in GUI views. Its value should be of the type reflect.Type
Variables ¶
var DelMgr = DeletedKi{}
DelMgr is the manager of all deleted items
var JSONTypePrefix = []byte("{\"ki.RootType\": ")
JSONTypePrefix is the first thing output in a ki tree JSON output file, specifying the type of the root node of the ki tree -- this info appears all on one { } bracketed line at the start of the file, and can also be used to identify the file as a ki tree JSON file
var JSONTypeSuffix = []byte("}\n")
JSONTypeSuffix is just the } and \n at the end of the prefix line
var KiType = reflect.TypeOf((*Ki)(nil)).Elem()
KiType is a Ki reflect.Type, suitable for checking for Type.Implements.
var NodeType = gti.AddType(>i.Type{ Name: "goki.dev/ki/v2.Node", ShortName: "ki.Node", IDName: "node", Doc: "The Node implements the Ki interface and provides the core functionality\nfor the Goki tree -- use the Node as an embedded struct or as a struct\nfield -- the embedded version supports full JSON save / load.\n\nThe desc: key for fields is used by the GoGi GUI viewer for help / tooltip\ninfo -- add these to all your derived struct's fields. See relevant docs\nfor other such tags controlling a wide range of GUI and other functionality\n-- Ki makes extensive use of such tags.", Directives: gti.Directives{}, Fields: ordmap.Make([]ordmap.KeyVal[string, *gti.Field]{ {"Nm", >i.Field{Name: "Nm", Type: "string", Doc: "Ki.Name() user-supplied name of this node -- can be empty or non-unique", Directives: gti.Directives{}}}, {"Flags", >i.Field{Name: "Flags", Type: "Flags", Doc: "[tableview: -] bit flags for internal node state -- can extend this using enums package", Directives: gti.Directives{}}}, {"Props", >i.Field{Name: "Props", Type: "Props", Doc: "[tableview: -] Ki.Properties() property map for arbitrary extensible properties, including style properties", Directives: gti.Directives{}}}, {"Par", >i.Field{Name: "Par", Type: "Ki", Doc: "[view: -] [tableview: -] Ki.Parent() parent of this node -- set automatically when this node is added as a child of parent", Directives: gti.Directives{}}}, {"Kids", >i.Field{Name: "Kids", Type: "Slice", Doc: "[tableview: -] Ki.Children() list of children of this node -- all are set to have this node as their parent -- can reorder etc but generally use Ki Node methods to Add / Delete to ensure proper usage", Directives: gti.Directives{}}}, {"Ths", >i.Field{Name: "Ths", Type: "Ki", Doc: "[view: -] we need a pointer to ourselves as a Ki, which can always be used to extract the true underlying type of object when Node is embedded in other structs -- function receivers do not have this ability so this is necessary. This is set to nil when deleted. Typically use This() convenience accessor which protects against concurrent access.", Directives: gti.Directives{}}}, {"NumLifetimeKids", >i.Field{Name: "NumLifetimeKids", Type: "uint64", Doc: "the number of children that have ever been added to this node, which is used for unique naming", Directives: gti.Directives{}}}, {"index", >i.Field{Name: "index", Type: "int", Doc: "[view: -] last value of our index -- used as a starting point for finding us in our parent next time -- is not guaranteed to be accurate! use IndexInParent() method", Directives: gti.Directives{}}}, {"depth", >i.Field{Name: "depth", Type: "int", Doc: "[view: -] optional depth parameter of this node -- only valid during specific contexts, not generally -- e.g., used in WalkBreadth function", Directives: gti.Directives{}}}, }), Embeds: ordmap.Make([]ordmap.KeyVal[string, *gti.Field]{}), Methods: ordmap.Make([]ordmap.KeyVal[string, *gti.Method]{}), Instance: &Node{}, })
NodeType is the gti.Type for Node
var PropsProps = Props{ "basic-type": true, }
var StringElideMax = 38
StringElideMax is the Max width for String() path printout of Ki nodes.
var UniquifyIndexAbove = 1000
UniquifyIndexAbove is the number of children above which UniquifyNamesAddIndex is called -- that is much faster for large numbers of children. Must be < 1000
Functions ¶
func AsKi ¶
AsKi returns the Ki interface and Node base type for any given object -- if not a Ki, return values are nil.
func ChildByType ¶
ChildByType is a generic helper function for [Ki.ChildByType]
func CopyFromRaw ¶
CopyFromRaw performs a raw copy that just does the deep copy of the bits and doesn't do anything with pointers.
func CopyProps ¶
CopyProps copies properties from source to destination map. If deepCopy is true, then any values that are Props or PropSlice are copied too *dest can be nil, in which case it is created.
func DecodeXMLCharData ¶
DecodeXMLCharData reads char data..
func DecodeXMLCharEl ¶
DecodeXMLCharEl reads a start / chardata / end sequence of 3 elements, returning name, val
func DecodeXMLEndEl ¶
func DecodeXMLEndEl(d *xml.Decoder, start xml.StartElement) error
DecodeXMLEndEl reads an end element
func DecodeXMLStartEl ¶
func DecodeXMLStartEl(d *xml.Decoder) (start xml.StartElement, err error)
DecodeXMLStartEl reads a start element token
func DeleteFromParent ¶
func DeleteFromParent(kid Ki)
DeleteFromParent calls OnChildDeleting on all parents of given node then calls OnDelete on the node, and finally sets the Parent to nil. Call this *before* deleting the child.
func DeletingChildren ¶
func DeletingChildren(k Ki)
DeletingChildren calls OnChildrenDeleting on given node and all parents thereof. Call this *before* deleting the children.
func Depth ¶
Depth returns the current depth of the node. This is only valid in a given context, not a stable property of the node (e.g., used in WalkBreadth).
func EscapePathName ¶
EscapePathName returns a name that replaces any path delimiter symbols . or / with \, and \\ escaped versions.
func InitNode ¶
func InitNode(this Ki)
InitNode initializes the node -- automatically called during Add/Insert Child -- sets the This pointer for this node as a Ki interface (pass pointer to node as this arg) -- Go cannot always access the true underlying type for structs using embedded Ki objects (when these objs are receivers to methods) so we need a This interface pointer that guarantees access to the Ki interface in a way that always reveals the underlying type (e.g., in reflect calls). Calls Init on Ki fields within struct, sets their names to the field name, and sets us as their parent.
func InsertNewChild ¶
InsertNewChild is a generic helper function for [Ki.InsertNewChild]
func IsKi ¶
IsKi returns true if the given type implements the Ki interface at any level of embedded structure.
func MoveToParent ¶
MoveToParent deletes given node from its current parent and adds it as a child of given new parent. Parents could be in different trees or not.
func New ¶
New adds a new child of the given the type with the given name to the given parent. If the name is unspecified, it defaults to the ID (kebab-case) name of the type, plus the [Ki.NumLifetimeChildren] of its parent. It is a helper function that calls [Ki.NewChild].
func NewRoot ¶
NewRoot returns a new root node of the given the type with the given name. If the name is unspecified, it defaults to the ID (kebab-case) name of the type. It is a helper function that calls [Ki.InitName].
func ParentAllChildren ¶
func ParentAllChildren(kn Ki)
ParentAllChildren walks the tree down from current node and call SetParent on all children -- needed after an Unmarshal.
func ParentByType ¶
ParentByType is a generic helper function for [Ki.ParentByType]
func ReadRootTypeJSON ¶
ReadRootTypeJSON reads the type of the root node as encoded by WriteRootTypeJSON, returning the gti.Type for the saved type name (error if not found), the remaining bytes to be decoded using a standard unmarshal, and an error.
func RootTypeJSON ¶
RootTypeJSON returns the JSON encoding of the type of the root node (this node) which is written first using our custom JSONEncoder type, to enable a file to be loaded de-novo and recreate the proper root type for the tree.
func SaveNewJSON ¶
SaveNewJSON writes JSON-encoded bytes to given writer including key type information at start of file so ReadNewJSON can create an object of the proper type.
func SetParent ¶
SetParent just sets parent of node (and inherits update count from parent, to keep consistent). Assumes not already in a tree or anything.
func SetPropStr ¶
SetPropStr is a convenience method for e.g., python wrapper that avoids need to deal directly with props interface{} type
func SetSubProps ¶
SetSubProps is a convenience method for e.g., python wrapper that avoids need to deal directly with props interface{} type
func SliceDeleteAtIndex ¶
SliceDeleteAtIndex deletes item at index; does not do any further management of deleted item. It is an optimized version for avoiding memory leaks. It returns an error if the index is invalid.
func SliceIndexByFunc ¶
SliceIndexByFunc finds index of item based on match function (which must return true for a find match, false for not). Returns false if not found. startIdx arg allows for optimized bidirectional find if you have an idea where it might be, which can be key speedup for large lists. If no value is specified for startIdx, it starts in the middle, which is a good default.
func SliceIndexByName ¶
SliceIndexByName returns index of first element that has given name, false if not found. See Slice.IndexOf for info on startIdx.
func SliceIndexOf ¶
SliceIndexOf returns index of element in list, false if not there. startIdx arg allows for optimized bidirectional find if you have an idea where it might be, which can be key speedup for large lists. If no value is specified for startIdx, it starts in the middle, which is a good default.
func SliceInsert ¶
SliceInsert item at index; does not do any parent updating etc; use the Ki or Node method unless you know what you are doing.
func SliceIsValidIndex ¶
SliceIsValidIndex checks whether the given index is a valid index into slice, within range of 0..len-1. Returns error if not.
func SliceMove ¶
SliceMove moves element from one position to another. Returns error if either index is invalid.
func SliceSwap ¶
SliceSwap swaps elements between positions. Returns error if either index is invalid
func ThisCheck ¶
ThisCheck checks that the This pointer is set and issues a warning to log if not -- returns error if not set -- called when nodes are added and inserted.
func UnescapePathName ¶
UnescapePathName returns a name that replaces any escaped path delimiter symbols \, or \\ with . and / unescaped versions.
func UniqueNameCheck ¶
UniqueNameCheck checks if all the children names are unique or not. returns true if all names are unique; false if not if not unique, call UniquifyNames or take other steps to ensure uniqueness.
func UniqueNameCheckAll ¶
UniqueNameCheckAll checks entire tree from given node, if all the children names are unique or not. returns true if all names are unique; false if not if not unique, call UniquifyNames or take other steps to ensure uniqueness.
func UniquifyNames ¶
func UniquifyNames(kn Ki)
UniquifyNames makes sure that the names are unique. If number of children >= UniquifyIndexAbove, then UniquifyNamesAddIndex is called, for faster performance. Otherwise, existing names are preserved if they are unique, and only duplicates are renamed. This is a bit slower.
func UniquifyNamesAddIndex ¶
func UniquifyNamesAddIndex(kn Ki)
UniquifyNamesAddIndex makes sure that the names are unique by automatically adding a suffix with index number, separated by underbar. Empty names get the parent name as a prefix. if there is an existing underbar, then whatever is after it is replaced with the unique index, ensuring that multiple calls are safe!
func UniquifyNamesAll ¶
func UniquifyNamesAll(kn Ki)
UniquifyNamesAll makes sure that the names are unique for entire tree If number of children >= UniquifyIndexAbove, then UniquifyNamesAddIndex is called, for faster performance. Otherwise, existing names are preserved if they are unique, and only duplicates are renamed. This is a bit slower.
func UnmarshalPost ¶
func UnmarshalPost(kn Ki)
UnmarshalPost must be called after an Unmarshal -- calls ParentAllChildren.
func UpdateReset ¶
func UpdateReset(kn Ki)
UpdateReset resets Updating flag for this node and all children -- in case they are out-of-sync due to more complex tree maninpulations -- only call at a known point of non-updating.
Types ¶
type BlankProp ¶
type BlankProp struct{}
BlankProp is an empty property, for when there isn't any need for the value
type DeletedKi ¶
DeletedKi manages all the deleted Ki elements, that are destined to then be destroyed, without having an additional pointer on the Ki object
func (*DeletedKi) DestroyDeleted ¶
func (dm *DeletedKi) DestroyDeleted()
DestroyDeleted destroys any deleted items in list
type Flags ¶
type Flags int64 //enums:bitflag
Flags are bit flags for efficient core state of nodes -- see bitflag package for using these ordinal values to manipulate bit flag field.
const ( // Field indicates a node is a field in its parent node, not a child in children. Field Flags = iota // Updating flag is set at UpdateStart and cleared if we were the first // updater at UpdateEnd. Updating // Deleted means this node has been deleted (removed from Parent) // Set just prior to calling OnDelete() Deleted // Destroyed means this node has been destroyed. // It should be skipped in all further processing, if there // are remaining pointers to it. Destroyed // ChildAdded means one or more new children were added to the node. ChildAdded // ChildDeleted means one or more children were deleted from the node. ChildDeleted // ChildrenDeleted means all children were deleted. ChildrenDeleted )
const FlagsN Flags = 7
FlagsN is the highest valid value for type Flags, plus one.
func FlagsValues ¶
func FlagsValues() []Flags
FlagsValues returns all possible values for the type Flags.
func (Flags) BitIndexString ¶
BitIndexString returns the string representation of this Flags value if it is a bit index value (typically an enum constant), and not an actual bit flag value.
func (Flags) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface.
func (*Flags) SetFlag ¶
SetFlag sets the value of the given flags in these flags to the given value.
func (*Flags) SetString ¶
SetString sets the Flags value from its string representation, and returns an error if the string is invalid.
func (*Flags) SetStringOr ¶
SetStringOr sets the Flags value from its string representation while preserving any bit flags already set, and returns an error if the string is invalid.
func (*Flags) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface.
type Ki ¶
type Ki interface { // InitName initializes this node to given actual object as a Ki interface // and sets its name. The names should be unique among children of a node. // This is needed for root nodes -- automatically done for other nodes // when they are added to the Ki tree. If the name is unspecified, it // defaults to the ID (kebab-case) name of the type. // Even though this is a method and gets the method receiver, it needs // an "external" version of itself passed as the first arg, from which // the proper Ki interface pointer will be obtained. This is the only // way to get virtual functional calling to work within the Go language. InitName(this Ki, name ...string) // This returns the Ki interface that guarantees access to the Ki // interface in a way that always reveals the underlying type // (e.g., in reflect calls). Returns nil if node is nil, // has been destroyed, or is improperly constructed. This() Ki // AsNode returns the *ki.Node base type for this node. AsKi() *Node // BaseType returns the base node type for all elements within this tree. // Used e.g., for determining what types of children can be created. BaseType() *gti.Type // Name returns the user-defined name of the object (Node.Nm), // for finding elements, generating paths, IO, etc. Name() string // SetName sets the name of this node. // Names should generally be unique across children of each node. // See Unique* functions to check / fix. // If node requires non-unique names, add a separate Label field. // Does NOT wrap in UpdateStart / End. SetName(name string) // KiType returns the gti Type record for this Ki node. // This is auto-generated by the gtigen generator for Ki types. KiType() *gti.Type // New returns a new token of this Ki node. // InitName _must_ still be called on this new token. // This is auto-generated by the gtigen generator for Ki types. New() Ki // Parent returns the parent of this Ki (Node.Par) -- Ki has strict // one-parent, no-cycles structure -- see SetParent. Parent() Ki // IndexInParent returns our index within our parent object. It caches the // last value and uses that for an optimized search so subsequent calls // are typically quite fast. Returns -1 if we don't have a parent. IndexInParent() int // ParentLevel finds a given potential parent node recursively up the // hierarchy, returning level above current node that the parent was // found, and -1 if not found. ParentLevel(par Ki) int // ParentByName finds first parent recursively up hierarchy that matches // given name. Returns nil if not found. ParentByName(name string) Ki // ParentByType finds parent recursively up hierarchy, by type, and // returns nil if not found. If embeds is true, then it looks for any // type that embeds the given type at any level of anonymous embedding. ParentByType(t *gti.Type, embeds bool) Ki // HasChildren tests whether this node has children (i.e., non-terminal). HasChildren() bool // NumChildren returns the number of children NumChildren() int // NumLifetimeChildren returns the number of children that this node // has ever had added to it (it is not decremented when a child is removed). // It is used for unique naming of children. NumLifetimeChildren() uint64 // Children returns a pointer to the slice of children (Node.Kids) -- use // methods on ki.Slice for further ways to access (ByName, ByType, etc). // Slice can be modified, deleted directly (e.g., sort, reorder) but Add // method on parent node should be used to ensure proper init. Children() *Slice // Child returns the child at given index and returns nil if // the index is out of range. Child(idx int) Ki // ChildByName returns the first element that has given name, and nil // if no such element is found. startIdx arg allows for optimized // bidirectional find if you have an idea where it might be, which // can be a key speedup for large lists. If no value is specified for // startIdx, it starts in the middle, which is a good default. ChildByName(name string, startIdx ...int) Ki // ChildByType returns the first element that has the given type, and nil // if not found. If embeds is true, then it also looks for any type that // embeds the given type at any level of anonymous embedding. // startIdx arg allows for optimized bidirectional find if you have an // idea where it might be, which can be a key speedup for large lists. If // no value is specified for startIdx, it starts in the middle, which is a // good default. ChildByType(t *gti.Type, embeds bool, startIdx ...int) Ki // Path returns path to this node from the tree root, using node Names // separated by / and fields by . // Node names escape any existing / and . characters to \\ and \, // Path is only valid when child names are unique (see Unique* functions) Path() string // PathFrom returns path to this node from given parent node, using // node Names separated by / and fields by . // Node names escape any existing / and . characters to \\ and \, // Path is only valid for finding items when child names are unique // (see Unique* functions). The paths that it returns exclude the // name of the parent and the leading slash; for example, in the tree // a/b/c/d/e, the result of d.PathFrom(b) would be c/d. PathFrom // automatically gets the [Ki.This] version of the given parent, // so a base type can be passed in without manually calling [Ki.This]. PathFrom(par Ki) string // FindPath returns Ki object at given path, starting from this node // (e.g., the root). If this node is not the root, then the path // to this node is subtracted from the start of the path if present there. // FindPath only works correctly when names are unique. // Path has node Names separated by / and fields by . // Node names escape any existing / and . characters to \\ and \, // There is also support for [idx] index-based access for any given path // element, for cases when indexes are more useful than names. // Returns nil if not found. FindPath(path string) Ki // FieldByName returns Ki object that is a direct field. // This must be implemented for any types that have Ki fields that // are processed as part of the overall Ki tree. This is only used // by FindPath. // Returns error if not found. FieldByName(field string) (Ki, error) // AddChild adds given child at end of children list. // The kid node is assumed to not be on another tree (see MoveToParent) // and the existing name should be unique among children. // No UpdateStart / End wrapping is done: do that externally as needed. // Can also call SetFlag(ki.ChildAdded) if notification is needed. AddChild(kid Ki) error // NewChild creates a new child of the given type and adds it at end // of children list. The name should be unique among children. If the // name is unspecified, it defaults to the ID (kebab-case) name of the // type, plus the [Ki.NumLifetimeChildren] of its parent. // No UpdateStart / End wrapping is done: do that externally as needed. // Can also call SetFlag(ki.ChildAdded) if notification is needed. NewChild(typ *gti.Type, name ...string) Ki // SetChild sets child at given index to be the given item; if it is passed // a name, then it sets the name of the child as well; just calls Init // (or InitName) on the child, and SetParent. Names should be unique // among children. No UpdateStart / End wrapping is done: do that // externally as needed. Can also call SetFlag(ki.ChildAdded) if // notification is needed. SetChild(kid Ki, idx int, name ...string) error // InsertChild adds given child at position in children list. // The kid node is assumed to not be on another tree (see MoveToParent) // and the existing name should be unique among children. // No UpdateStart / End wrapping is done: do that externally as needed. // Can also call SetFlag(ki.ChildAdded) if notification is needed. InsertChild(kid Ki, at int) error // InsertNewChild creates a new child of given type and add at position // in children list. The name should be unique among children. If the // name is unspecified, it defaults to the ID (kebab-case) name of the // type, plus the [Ki.NumLifetimeChildren] of its parent. No // UpdateStart / End wrapping is done: do that externally as needed. // Can also call SetFlag(ki.ChildAdded) if notification is needed. InsertNewChild(typ *gti.Type, at int, name ...string) Ki // SetNChildren ensures that there are exactly n children, deleting any // extra, and creating any new ones, using NewChild with given type and // naming according to nameStubX where X is the index of the child. // If nameStub is not specified, it defaults to the ID (kebab-case) // name of the type. // // IMPORTANT: returns whether any modifications were made (mods) AND if // that is true, the result from the corresponding UpdateStart call -- // UpdateEnd is NOT called, allowing for further subsequent updates before // you call UpdateEnd(updt) // // Note that this does not ensure existing children are of given type, or // change their names, or call UniquifyNames -- use ConfigChildren for // those cases -- this function is for simpler cases where a parent uses // this function consistently to manage children all of the same type. SetNChildren(n int, typ *gti.Type, nameStub ...string) (mods, updt bool) // ConfigChildren configures children according to given list of // type-and-name's -- attempts to have minimal impact relative to existing // items that fit the type and name constraints (they are moved into the // corresponding positions), and any extra children are removed, and new // ones added, to match the specified config. // It is important that names are unique! // // IMPORTANT: returns whether any modifications were made (mods) AND if // that is true, the result from the corresponding UpdateStart call -- // UpdateEnd is NOT called, allowing for further subsequent updates before // you call UpdateEnd(updt). ConfigChildren(config Config) (mods, updt bool) // DeleteChildAtIndex deletes child at given index. It returns false // if there is no child at the given index. Wraps delete in UpdateStart / End // and sets ChildDeleted flag. DeleteChildAtIndex(idx int, destroy bool) bool // DeleteChild deletes the given child node, returning false if // it can not find it. Wraps delete in UpdateStart / End and // sets ChildDeleted flag. DeleteChild(child Ki, destroy bool) bool // DeleteChildByName deletes child node by name, returning false // if it can not find it. Wraps delete in UpdateStart / End and // sets ChildDeleted flag. DeleteChildByName(name string, destroy bool) bool // DeleteChildren deletes all children nodes -- destroy will add removed // children to deleted list, to be destroyed later -- otherwise children // remain intact but parent is nil -- could be inserted elsewhere, but you // better have kept a slice of them before calling this. DeleteChildren(destroy bool) // Delete deletes this node from its parent children list -- destroy will // add removed child to deleted list, to be destroyed later -- otherwise // child remains intact but parent is nil -- could be inserted elsewhere. Delete(destroy bool) // Destroy calls DisconnectAll to cut all signal connections, // and remove all children and their childrens-children, etc. Destroy() // Is checks if flag is set, using atomic, safe for concurrent access Is(f enums.BitFlag) bool // SetFlag sets the given flag(s) to given state // using atomic, safe for concurrent access SetFlag(on bool, f ...enums.BitFlag) // SetChildAdded sets the ChildAdded flag -- set when notification is needed // for Add, Insert methods SetChildAdded() // ClearUpdateFlags resets all structure update related flags: // ChildAdded, ChildDeleted, ChildrenDeleted, Deleted // automatically called on StartUpdate to reset any old state. ClearUpdateFlags() // FlagType returns the flags of the node as the true flag type of the node, // which may be a type that extends the standard [Flags]. Each node type // that extends the flag type should define this method; for example: // func (wb *WidgetBase) FlagType() enums.BitFlagSetter { // return (*WidgetFlags)(&wb.Flags) // } FlagType() enums.BitFlagSetter // Properties (Node.Props) tell the GoGi GUI or other frameworks operating // on Trees about special features of each node -- functions below support // inheritance up Tree -- see kit convert.go for robust convenience // methods for converting interface{} values to standard types. Properties() *Props // SetProp sets given property key to value val -- initializes property // map if nil. SetProp(key string, val any) // Prop returns the property value for the given key. // It returns nil if it doesn't exist. Prop(key string) any // PropInherit gets property value from key with options for inheriting // property from parents. If inherit, then checks all parents. // Returns false if not set anywhere. PropInherit(key string, inherit bool) (any, bool) // DeleteProp deletes property key on this node. DeleteProp(key string) // PropTag returns the name to look for in type properties, for types // that are valid options for values that can be set in Props. For example // in GoGi, it is "style-props" which is then set for all types that can // be used in a style (colors, enum options, etc) PropTag() string // WalkUp calls function on given node and all the way up to its parents, // and so on -- sequentially all in current go routine (generally // necessary for going up, which is typically quite fast anyway) -- level // is incremented after each step (starts at 0, goes up), and passed to // function -- returns false if fun aborts with false, else true. WalkUp(fun func(k Ki) bool) bool // WalkUpParent calls function on parent of node and all the way up to its // parents, and so on -- sequentially all in current go routine (generally // necessary for going up, which is typically quite fast anyway) -- level // is incremented after each step (starts at 0, goes up), and passed to // function -- returns false if fun aborts with false, else true. WalkUpParent(fun func(k Ki) bool) bool // WalkPre calls function on this node (MeFirst) and then iterates // in a depth-first manner over all the children. // The [WalkPreNode] method is called for every node, after the given function, // which e.g., enables nodes to also traverse additional Ki Trees (e.g., Fields), // including for the basic UpdateStart / End and other such infrastructure calls // which use WalkPre (otherwise it could just be done in the given fun). // The node traversal is non-recursive and uses locally-allocated state -- safe // for concurrent calling (modulo conflict management in function call itself). // Function calls are sequential all in current go routine. // If fun returns false then any further traversal of that branch of the tree is // aborted, but other branches continue -- i.e., if fun on current node // returns false, children are not processed further. WalkPre(fun func(k Ki) bool) // WalkPreNode is called for every node during WalkPre with the function // passed to WalkPre. This e.g., enables nodes to also traverse additional // Ki Trees (e.g., Fields), including for the basic UpdateStart / End and // other such infrastructure calls. WalkPreNode(fun func(k Ki) bool) // WalkPreLevel calls function on this node (MeFirst) and then iterates // in a depth-first manner over all the children. // This version has a level var that tracks overall depth in the tree. // If fun returns false then any further traversal of that branch of the tree is // aborted, but other branches continue -- i.e., if fun on current node // returns false, children are not processed further. // Because WalkPreLevel is not used within Ki itself, it does not have its // own version of WalkPreNode -- that can be handled within the closure. WalkPreLevel(fun func(k Ki, level int) bool) // WalkPost iterates in a depth-first manner over the children, calling // doChildTestFunc on each node to test if processing should proceed (if // it returns false then that branch of the tree is not further processed), // and then calls given fun function after all of a node's children // have been iterated over ("Me Last"). // This uses node state information to manage the traversal and is very fast, // but can only be called by one thread at a time -- use a Mutex if there is // a chance of multiple threads running at the same time. // Function calls are sequential all in current go routine. // The level var tracks overall depth in the tree. WalkPost(doChildTestFunc func(k Ki) bool, fun func(k Ki) bool) // WalkBreadth calls function on all children in breadth-first order // using the standard queue strategy. This depends on and updates the // Depth parameter of the node. If fun returns false then any further // traversal of that branch of the tree is aborted, but other branches continue. WalkBreadth(fun func(k Ki) bool) // UpdateStart should be called when starting to modify the tree (state or // structure) -- returns whether this node was first to set the Updating // flag (if so, all children have their Updating flag set -- pass the // result to UpdateEnd -- automatically determines the highest level // updated, within the normal top-down updating sequence -- can be called // multiple times at multiple levels -- it is essential to ensure that all // such Start's have an End! Usage: // // updt := n.UpdateStart() // ... code // n.UpdateEnd(updt) // or // updt := n.UpdateStart() // defer n.UpdateEnd(updt) // ... code UpdateStart() bool // UpdateEnd should be called when done updating after an UpdateStart, // and passed the result of the UpdateStart call. // If this arg is true, the OnUpdated method will be called and the Updating // flag will be cleared. Also, if any ChildDeleted flags have been set, // the delete manager DestroyDeleted is called. // If the updt bool arg is false, this function is a no-op. UpdateEnd(updt bool) // CopyFrom another Ki node. It is essential that source has Unique names! // The Ki copy function recreates the entire tree in the copy, duplicating // children etc, copying Props too. It is very efficient by // using the ConfigChildren method which attempts to preserve any existing // nodes in the destination if they have the same name and type -- so a // copy from a source to a target that only differ minimally will be // minimally destructive. Only copies to same types are supported. // Signal connections are NOT copied. No other Ki pointers are copied, // and the field tag copy:"-" can be added for any other fields that // should not be copied (unexported, lower-case fields are not copyable). CopyFrom(frm Ki) error // Clone creates and returns a deep copy of the tree from this node down. // Any pointers within the cloned tree will correctly point within the new // cloned tree (see Copy info). Clone() Ki // CopyFieldsFrom is the base-level copy method that any copy-intensive // nodes should implement directly to explicitly copy relevant fields // that should be copied, avoiding any internal pointers etc. // Must explicitly call the CopyFieldsFrom method on any embedded // Ki types that you inherit from, and, critically, NONE of those // can rely on the generic Node-level version. CopyFieldsFrom(frm any) // OnInit is called when the node is // initialized (ie: through InitName). // It is called before the node is added to the tree, // so it will not have any parents or siblings. // It will be called only once in the lifetime of the node. // It does nothing by default, but it can be implemented // by higher-level types that want to do something. OnInit() // OnAdd is called when the node is added to a parent. // It will be called only once in the lifetime of the node, // unless the node is moved. It will not be called on root // nodes, as they are never added to a parent. // It does nothing by default, but it can be implemented // by higher-level types that want to do something. OnAdd() // OnChildAdded is called when a node is added to // this node or any of its children. When a node is added to // a tree, it calls [OnAdd] and then this function on each of its parents, // going in order from the closest parent to the furthest parent. // This function does nothing by default, but it can be // implemented by higher-level types that want to do something. OnChildAdded(child Ki) // OnDelete is called when the node is deleted from a parent. // It will be called only once in the lifetime of the node, // unless the node is moved. It will not be called on root // nodes, as they are never deleted from a parent. // It does nothing by default, but it can be implemented // by higher-level types that want to do something. OnDelete() // OnChildDeleting is called when a node is just about to be deleted from // this node or any of its children. When a node is deleted from // a tree, it calls this function on each of its parents, // going in order from the closest parent to the furthest parent, // and then [OnDelete]. // This function does nothing by default, but it can be // implemented by higher-level types that want to do something. OnChildDeleting(child Ki) // OnChildrenDeleting is called when all children are deleted from // this node or any of its children. // This function does nothing by default, but it can be // implemented by higher-level types that want to do something. OnChildrenDeleting() // OnUpdated is called during UpdateEnd if the updt flag is true, // indicating that this was the upper-most Ki node that was // updated in the latest round of updating. // This function does nothing by default, but it can be // implemented by higher-level types that want to do something. OnUpdated() }
The Ki interface provides the core functionality for a Goki tree. Each Ki is a node in the tree and can have child nodes, and no cycles are allowed (i.e., each node can only appear once in the tree). All the usual methods are included for accessing and managing Children, and efficiently traversing the tree and calling functions on the nodes. In addition, Ki nodes can have Fields that are also Ki nodes that are included in all the automatic tree traversal methods -- they are effectively named fixed children that are automatically present.
In general, the names of the children of a given node should all be unique. The following functions defined in ki package can be used: UniqueNameCheck(node) to check for unique names on node if uncertain. UniqueNameCheckAll(node) to check entire tree under given node. UniquifyNames(node) to add a suffix to name to ensure uniqueness. UniquifyNamesAll(node) to to uniquify all names in entire tree.
Use function MoveChild to move a node between trees or within a tree -- otherwise nodes are typically created and deleted but not moved.
The Ki interface is designed to support virtual method calling in Go and is only intended to be implemented once, by the ki.Node type (as opposed to interfaces that are used for hiding multiple different implementations of a common concept). Thus, all of the fields in ki.Node are exported (have captital names), to be accessed directly in types that embed and extend the ki.Node. The Ki interface has the "formal" name (e.g., Children) while the Node has the "nickname" (e.g., Kids). See the Naming Conventions on the Goki Wiki for more details.
Each Node stores the Ki interface version of itself, as This() / Ths which enables full virtual function calling by calling the method on that interface instead of directly on the receiver Node itself. This requires proper initialization via Init method of the Ki interface.
Ki nodes also support the following core functionality:
- UpdateStart() / UpdateEnd() to wrap around tree updating code, which then automatically triggers update signals at the highest level of the affected tree, resulting in efficient updating logic for arbitrary nested tree modifications.
- ConfigChildren system for minimally updating children to fit a given Name & Type template.
- Automatic JSON I/O of entire tree including type information.
func NewOfType ¶
NewOfType makes a new Ki struct of given type -- must be a Ki type -- will return nil if not.
func OpenNewJSON ¶
OpenNewJSON opens a new Ki tree from a JSON-encoded file, using type information at start of file to create an object of the proper type
func ReadNewJSON ¶
ReadNewJSON reads a new Ki tree from a JSON-encoded byte string, using type information at start of file to create an object of the proper type
type Node ¶
type Node struct { // Ki.Name() user-supplied name of this node -- can be empty or non-unique Nm string `copy:"-" set:"-" label:"Name"` // bit flags for internal node state -- can extend this using enums package Flags Flags `tableview:"-" copy:"-" json:"-" xml:"-" set:"-" max-width:"80" height:"3"` // Ki.Properties() property map for arbitrary extensible properties, including style properties Props Props `tableview:"-" xml:"-" copy:"-" set:"-" label:"Properties"` // Ki.Parent() parent of this node -- set automatically when this node is added as a child of parent Par Ki `tableview:"-" copy:"-" json:"-" xml:"-" view:"-" set:"-" label:"Parent"` // Ki.Children() list of children of this node -- all are set to have this node as their parent -- can reorder etc but generally use Ki Node methods to Add / Delete to ensure proper usage Kids Slice `tableview:"-" copy:"-" set:"-" label:"Children"` // we need a pointer to ourselves as a Ki, which can always be used to extract the true underlying type of object when Node is embedded in other structs -- function receivers do not have this ability so this is necessary. This is set to nil when deleted. Typically use This() convenience accessor which protects against concurrent access. Ths Ki `copy:"-" json:"-" xml:"-" view:"-" set:"-"` // the number of children that have ever been added to this node, which is used for unique naming NumLifetimeKids uint64 `copy:"-" json:"-" xml:"-" view:"-" set:"-"` // contains filtered or unexported fields }
The Node implements the Ki interface and provides the core functionality for the Goki tree -- use the Node as an embedded struct or as a struct field -- the embedded version supports full JSON save / load.
The desc: key for fields is used by the GoGi GUI viewer for help / tooltip info -- add these to all your derived struct's fields. See relevant docs for other such tags controlling a wide range of GUI and other functionality -- Ki makes extensive use of such tags.
func NewNode ¶
NewNode adds a new Node with the given name to the given parent. If the name is unspecified, it defaults to the ID (kebab-case) name of the type, plus the [Ki.NumLifetimeChildren] of the given parent.
func (*Node) AddChild ¶
AddChild adds given child at end of children list. The kid node is assumed to not be on another tree (see MoveToParent) and the existing name should be unique among children. No UpdateStart / End wrapping is done: do that externally as needed. Can also call SetFlag(ki.ChildAdded) if notification is needed.
func (*Node) BaseType ¶
BaseType returns the base node type for all elements within this tree. Used e.g., for determining what types of children can be created.
func (*Node) Child ¶
Child returns the child at given index and returns nil if the index is out of range.
func (*Node) ChildByName ¶
ChildByName returns the first element that has given name, and nil if no such element is found. startIdx arg allows for optimized bidirectional find if you have an idea where it might be, which can be a key speedup for large lists. If no value is specified for startIdx, it starts in the middle, which is a good default.
func (*Node) ChildByType ¶
ChildByType returns the first element that has the given type, and nil if not found. If embeds is true, then it also looks for any type that embeds the given type at any level of anonymous embedding. startIdx arg allows for optimized bidirectional find if you have an idea where it might be, which can be a key speedup for large lists. If no value is specified for startIdx, it starts in the middle, which is a good default.
func (*Node) Children ¶
Children returns a pointer to the slice of children (Node.Kids) -- use methods on ki.Slice for further ways to access (ByName, ByType, etc). Slice can be modified directly (e.g., sort, reorder) but Add* / Delete* methods on parent node should be used to ensure proper tracking.
func (*Node) ClearUpdateFlags ¶
func (n *Node) ClearUpdateFlags()
ClearUpdateFlags resets all structure update related flags: ChildAdded, ChildDeleted, ChildrenDeleted, Deleted automatically called on StartUpdate to reset any old state.
func (*Node) Clone ¶
Clone creates and returns a deep copy of the tree from this node down. Any pointers within the cloned tree will correctly point within the new cloned tree (see Copy info).
func (*Node) ConfigChildren ¶
ConfigChildren configures children according to given list of type-and-name's -- attempts to have minimal impact relative to existing items that fit the type and name constraints (they are moved into the corresponding positions), and any extra children are removed, and new ones added, to match the specified config. If uniqNm, then names represent UniqueNames (this results in Name == UniqueName for created children).
IMPORTANT: returns whether any modifications were made (mods) AND if that is true, the result from the corresponding UpdateStart call -- UpdateEnd is NOT called, allowing for further subsequent updates before you call UpdateEnd(updt).
func (*Node) CopyFieldsFrom ¶
CopyFieldsFrom copies from primary fields of source object, recursively following anonymous embedded structs
func (*Node) CopyFrom ¶
CopyFrom another Ki node. It is essential that source has Unique names! The Ki copy function recreates the entire tree in the copy, duplicating children etc, copying Props too. It is very efficient by using the ConfigChildren method which attempts to preserve any existing nodes in the destination if they have the same name and type -- so a copy from a source to a target that only differ minimally will be minimally destructive. Only copies to same types are supported. Signal connections are NOT copied. No other Ki pointers are copied, and the field tag copy:"-" can be added for any other fields that should not be copied (unexported, lower-case fields are not copyable).
func (*Node) Delete ¶
Delete deletes this node from its parent children list -- destroy will add removed child to deleted list, to be destroyed later -- otherwise child remains intact but parent is nil -- could be inserted elsewhere.
func (*Node) DeleteChild ¶
DeleteChild deletes the given child node, returning false if it can not find it. Wraps delete in UpdateStart / End and sets ChildDeleted flag.
func (*Node) DeleteChildAtIndex ¶
DeleteChildAtIndex deletes child at given index. It returns false if there is no child at the given index. Wraps delete in UpdateStart / End and sets ChildDeleted flag.
func (*Node) DeleteChildByName ¶
DeleteChildByName deletes child node by name, returning false if it can not find it. Wraps delete in UpdateStart / End and sets ChildDeleted flag.
func (*Node) DeleteChildren ¶
DeleteChildren deletes all children nodes -- destroy will add removed children to deleted list, to be destroyed later -- otherwise children remain intact but parent is nil -- could be inserted elsewhere, but you better have kept a slice of them before calling this.
func (*Node) DeleteProp ¶
DeleteProp deletes property key on this node.
func (*Node) Destroy ¶
func (n *Node) Destroy()
Destroy calls DisconnectAll to cut all pointers and signal connections, and remove all children and their childrens-children, etc.
func (*Node) FindPath ¶
FindPath returns Ki object at given path, starting from this node (e.g., the root). If this node is not the root, then the path to this node is subtracted from the start of the path if present there. FindPath only works correctly when names are unique. Path has node Names separated by / and fields by . Node names escape any existing / and . characters to \\ and \, There is also support for [idx] index-based access for any given path element, for cases when indexes are more useful than names. Returns nil if not found.
func (*Node) FlagType ¶
func (n *Node) FlagType() enums.BitFlagSetter
FlagType is the base implementation of [Ki.FlagType] that returns a value of type Flags.
func (*Node) HasChildren ¶
HasChildren tests whether this node has children (i.e., non-terminal).
func (*Node) IndexInParent ¶
IndexInParent returns our index within our parent object. It caches the last value and uses that for an optimized search so subsequent calls are typically quite fast. Returns -1 if we don't have a parent.
func (*Node) InitName ¶
InitName initializes this node to given actual object as a Ki interface and sets its name. The names should be unique among children of a node. This is needed for root nodes -- automatically done for other nodes when they are added to the Ki tree. If the name is unspecified, it defaults to the ID (kebab-case) name of the type. Even though this is a method and gets the method receiver, it needs an "external" version of itself passed as the first arg, from which the proper Ki interface pointer will be obtained. This is the only way to get virtual functional calling to work within the Go language.
func (*Node) InsertChild ¶
InsertChild adds given child at position in children list. The kid node is assumed to not be on another tree (see MoveToParent) and the existing name should be unique among children. No UpdateStart / End wrapping is done: do that externally as needed. Can also call SetChildAdded() if notification is needed.
func (*Node) InsertNewChild ¶
InsertNewChild creates a new child of given type and add at position in children list. The name should be unique among children. If the name is unspecified, it defaults to the ID (kebab-case) name of the type, plus the [Ki.NumLifetimeChildren] of its parent. No UpdateStart / End wrapping is done: do that externally as needed. Can also call SetFlag(ki.ChildAdded) if notification is needed.
func (*Node) Name ¶
Name returns the user-defined name of the object (Node.Nm), for finding elements, generating paths, IO, etc.
func (*Node) NewChild ¶
NewChild creates a new child of the given type and adds it at end of children list. The name should be unique among children. If the name is unspecified, it defaults to the ID (kebab-case) name of the type, plus the [Ki.NumLifetimeChildren] of its parent. No UpdateStart / End wrapping is done: do that externally as needed. Can also call SetFlag(ki.ChildAdded) if notification is needed.
func (*Node) NumChildren ¶
NumChildren returns the number of children of this node.
func (*Node) NumLifetimeChildren ¶
func (*Node) OnAdd ¶
func (n *Node) OnAdd()
OnAdd is a placeholder implementation of [Ki.OnAdd] that does nothing.
func (*Node) OnChildAdded ¶
OnChildAdded is a placeholder implementation of [Ki.OnChildAdded] that does nothing.
func (*Node) OnChildDeleting ¶
OnChildDeleting is a placeholder implementation of [Ki.OnChildDeleting] that does nothing.
func (*Node) OnChildrenDeleting ¶
func (n *Node) OnChildrenDeleting()
OnChildrenDeleting is a placeholder implementation of [Ki.OnChildrenDeleting] that does nothing.
func (*Node) OnDelete ¶
func (n *Node) OnDelete()
OnDelete is a placeholder implementation of [Ki.OnDelete] that does nothing.
func (*Node) OnInit ¶
func (n *Node) OnInit()
OnInit is a placeholder implementation of [Ki.OnInit] that does nothing.
func (*Node) OnUpdated ¶
func (n *Node) OnUpdated()
OnUpdated is a placeholder implementation of [Ki.OnUpdated] that does nothing.
func (*Node) Parent ¶
Parent returns the parent of this Ki (Node.Par) -- Ki has strict one-parent, no-cycles structure -- see SetParent.
func (*Node) ParentByName ¶
ParentByName finds first parent recursively up hierarchy that matches given name -- returns nil if not found.
func (*Node) ParentByType ¶
ParentByType finds parent recursively up hierarchy, by type, and returns nil if not found. If embeds is true, then it looks for any type that embeds the given type at any level of anonymous embedding.
func (*Node) ParentLevel ¶
ParentLevel finds a given potential parent node recursively up the hierarchy, returning level above current node that the parent was found, and -1 if not found.
func (*Node) Path ¶
Path returns path to this node from the tree root, using node Names separated by / and fields by . Node names escape any existing / and . characters to \\ and \, Path is only valid when child names are unique (see Unique* functions)
func (*Node) PathFrom ¶
PathFrom returns path to this node from given parent node, using node Names separated by / and fields by . Node names escape any existing / and . characters to \\ and \, Path is only valid for finding items when child names are unique (see Unique* functions). The paths that it returns exclude the name of the parent and the leading slash; for example, in the tree a/b/c/d/e, the result of d.PathFrom(b) would be c/d. PathFrom automatically gets the [Ki.This] version of the given parent, so a base type can be passed in without manually calling [Ki.This].
func (*Node) Prop ¶
Prop returns the property value for the given key. It returns nil if it doesn't exist.
func (*Node) PropInherit ¶
PropInherit gets property value from key with options for inheriting property from parents. If inherit, then checks all parents. Returns false if not set anywhere.
func (*Node) PropTag ¶
PropTag returns the name to look for in type properties, for types that are valid options for values that can be set in Props. For example in GoGi, it is "style-props" which is then set for all types that can be used in a style (colors, enum options, etc)
func (*Node) Properties ¶
Properties (Node.Props) tell the GoGi GUI or other frameworks operating on Trees about special features of each node -- functions below support inheritance up Tree.
func (*Node) ReadXML ¶
ReadXML reads the tree from an XML-encoded byte string over io.Reader, calls UnmarshalPost to recover pointers from paths.
func (*Node) SetChild ¶
SetChild sets child at given index to be the given item; if it is passed a name, then it sets the name of the child as well; just calls Init (or InitName) on the child, and SetParent. Names should be unique among children. No UpdateStart / End wrapping is done: do that externally as needed. Can also call SetFlag(ki.ChildAdded) if notification is needed.
func (*Node) SetChildAdded ¶
func (n *Node) SetChildAdded()
SetChildAdded sets the ChildAdded flag -- set when notification is needed for Add, Insert methods
func (*Node) SetFlag ¶
SetFlag sets the given flag(s) to given state using atomic, safe for concurrent access
func (*Node) SetNChildren ¶
SetNChildren ensures that there are exactly n children, deleting any extra, and creating any new ones, using NewChild with given type and naming according to nameStubX where X is the index of the child. If nameStub is not specified, it defaults to the ID (kebab-case) name of the type.
IMPORTANT: returns whether any modifications were made (mods) AND if that is true, the result from the corresponding UpdateStart call -- UpdateEnd is NOT called, allowing for further subsequent updates before you call UpdateEnd(updt)
Note that this does not ensure existing children are of given type, or change their names, or call UniquifyNames -- use ConfigChildren for those cases -- this function is for simpler cases where a parent uses this function consistently to manage children all of the same type.
func (*Node) SetName ¶
SetName sets the name of this node. Names should generally be unique across children of each node. See Unique* functions to check / fix. If node requires non-unique names, add a separate Label field. Does NOT wrap in UpdateStart / End.
func (*Node) SetProp ¶
SetProp sets given property key to value val. initializes property map if nil.
func (*Node) This ¶
This returns the Ki interface that guarantees access to the Ki interface in a way that always reveals the underlying type (e.g., in reflect calls). Returns nil if node is nil, has been destroyed, or is improperly constructed.
func (*Node) UpdateEnd ¶
UpdateEnd should be called when done updating after an UpdateStart, and passed the result of the UpdateStart call. If this arg is true, the OnUpdated method will be called and the Updating flag will be cleared. Also, if any ChildDeleted flags have been set, the delete manager DestroyDeleted is called. If the updt bool arg is false, this function is a no-op.
func (*Node) UpdateStart ¶
UpdateStart should be called when starting to modify the tree (state or structure) -- returns whether this node was first to set the Updating flag (if so, all children have their Updating flag set -- pass the result to UpdateEnd -- automatically determines the highest level updated, within the normal top-down updating sequence -- can be called multiple times at multiple levels -- it is essential to ensure that all such Start's have an End! Usage:
updt := n.UpdateStart() ... code n.UpdateEnd(updt)
or
updt := n.UpdateStart() defer n.UpdateEnd(updt) ... code
func (*Node) WalkBreadth ¶
WalkBreadth calls function on all children in breadth-first order using the standard queue strategy. This depends on and updates the Depth parameter of the node. If fun returns false then any further traversal of that branch of the tree is aborted, but other branches continue.
func (*Node) WalkPost ¶
WalkPost iterates in a depth-first manner over the children, calling doChildTestFunc on each node to test if processing should proceed (if it returns false then that branch of the tree is not further processed), and then calls given fun function after all of a node's children. have been iterated over ("Me Last"). The node traversal is non-recursive and uses locally-allocated state -- safe for concurrent calling (modulo conflict management in function call itself). Function calls are sequential all in current go routine. The level var tracks overall depth in the tree.
func (*Node) WalkPre ¶
WalkPre calls function on this node (MeFirst) and then iterates in a depth-first manner over all the children. The [WalkPreNode] method is called for every node, after the given function, which e.g., enables nodes to also traverse additional Ki Trees (e.g., Fields), including for the basic UpdateStart / End and other such infrastructure calls which use WalkPre (otherwise it could just be done in the given fun). The node traversal is non-recursive and uses locally-allocated state -- safe for concurrent calling (modulo conflict management in function call itself). Function calls are sequential all in current go routine. If fun returns false then any further traversal of that branch of the tree is aborted, but other branches continue -- i.e., if fun on current node returns false, children are not processed further.
func (*Node) WalkPreLevel ¶
WalkPreLevel calls function on this node (MeFirst) and then iterates in a depth-first manner over all the children. This version has a level var that tracks overall depth in the tree. If fun returns false then any further traversal of that branch of the tree is aborted, but other branches continue -- i.e., if fun on current node returns false, children are not processed further. Because WalkPreLevel is not used within Ki itself, it does not have its own version of WalkPreNode -- that can be handled within the closure.
func (*Node) WalkPreNode ¶
WalkPreNode is called for every node during WalkPre with the function passed to WalkPre. This e.g., enables nodes to also traverse additional Ki Trees (e.g., Fields), including for the basic UpdateStart / End and other such infrastructure calls.
func (*Node) WalkUp ¶
WalkUp calls function on given node and all the way up to its parents, and so on -- sequentially all in current go routine (generally necessary for going up, which is typically quite fast anyway) -- level is incremented after each step (starts at 0, goes up), and passed to function -- returns false if fun aborts with false, else true.
func (*Node) WalkUpParent ¶
WalkUpParent calls function on parent of node and all the way up to its parents, and so on -- sequentially all in current go routine (generally necessary for going up, which is typically quite fast anyway) -- level is incremented after each step (starts at 0, goes up), and passed to function -- returns false if fun aborts with false, else true.
type PropSlice ¶
type PropSlice []PropStruct
PropSlice is a slice of PropStruct, for when order is important within a subset of properties (maps do not retain order) -- can set the value of a property to a PropSlice to create an ordered list of property values.
func SliceProps ¶
SliceProps returns a value that contains a PropSlice, or nil and false if it doesn't exist or isn't a PropSlice
type PropStruct ¶
PropStruct is a struct of Name and Value, for use in a PropSlice to hold properties that require order information (maps do not retain any order)
type Props ¶
Props is the type used for holding generic properties -- the actual Go type is a mouthful and not very gui-friendly, and we need some special json methods
func SubProps ¶
SubProps returns a value that contains another props, or nil and false if it doesn't exist or isn't a Props
func (*Props) CopyFrom ¶
CopyFrom copies properties from source to receiver destination map. If deepCopy is true, then any values that are Props or PropSlice are copied too *dest can be nil, in which case it is created.
func (Props) MarshalJSON ¶
MarshalJSON saves the type information for each struct used in props, as a separate key with the __type: prefix -- this allows the Unmarshal to create actual types
func (*Props) UnmarshalJSON ¶
UnmarshalJSON parses the type information in the map to restore actual objects -- this is super inefficient and really needs a native parser, but props are likely to be relatively small
type Slice ¶
type Slice []Ki
Slice is just a slice of ki elements: []Ki, providing methods for accessing elements in the slice, and JSON marshal / unmarshal with encoding of underlying types
func (*Slice) Config ¶
Config is a major work-horse routine for minimally-destructive reshaping of a tree structure to fit a target configuration, specified in terms of a type-and-name list. If the node is != nil, then it has UpdateStart / End logic applied to it, only if necessary, as indicated by mods, updt return values.
func (*Slice) ConfigCopy ¶
ConfigCopy uses Config method to copy name / type config of Slice from source If n is != nil then Update etc is called properly. it is essential that child names are unique.
func (*Slice) CopyFrom ¶
CopyFrom another Slice. It is efficient by using the Config method which attempts to preserve any existing nodes in the destination if they have the same name and type -- so a copy from a source to a target that only differ minimally will be minimally destructive. it is essential that child names are unique.
func (*Slice) DeleteAtIndex ¶
DeleteAtIndex deletes item at index; does not do any further management of deleted item. It is an optimized version for avoiding memory leaks. It returns an error if the index is invalid.
func (*Slice) ElemByName ¶
ElemByName returns first element that has given name, nil if not found. See Slice.IndexOf for info on startIdx.
func (*Slice) ElemByNameTry ¶
ElemByNameTry returns first element that has given name, error if not found. See Slice.IndexOf for info on startIdx.
func (*Slice) ElemByType ¶
ElemByType returns index of element that either is that type or embeds that type, nil if not found. See Slice.IndexOf for info on startIdx.
func (*Slice) ElemByTypeTry ¶
ElemByTypeTry returns index of element that either is that type or embeds that type, error if not found. See Slice.IndexOf for info on startIdx.
func (*Slice) ElemFromEnd ¶
ElemFromEnd returns element at index from end of slice (0 = last element, 1 = 2nd to last, etc). Panics if invalid index.
func (*Slice) ElemFromEndTry ¶
ElemFromEndTry returns element at index from end of slice (0 = last element, 1 = 2nd to last, etc). Try version returns error on invalid index.
func (*Slice) ElemTry ¶
ElemTry returns element at index -- Try version returns error if index is invalid.
func (*Slice) IndexByFunc ¶
IndexByFunc finds index of item based on match function (which must return true for a find match, false for not). Returns false if not found. startIdx arg allows for optimized bidirectional find if you have an idea where it might be, which can be key speedup for large lists. If no value is specified for startIdx, it starts in the middle, which is a good default.
func (*Slice) IndexByName ¶
IndexByName returns index of first element that has given name, false if not found. See Slice.IndexOf for info on startIdx.
func (*Slice) IndexByType ¶
IndexByType returns index of element that either is that type or embeds that type, false if not found. See Slice.IndexOf for info on startIdx.
func (*Slice) IndexOf ¶
IndexOf returns index of element in list, false if not there. startIdx arg allows for optimized bidirectional find if you have an idea where it might be, which can be key speedup for large lists. If no value is specified for startIdx, it starts in the middle, which is a good default.
func (*Slice) Insert ¶
Insert item at index; does not do any parent updating etc; use the Ki or Node method unless you know what you are doing.
func (*Slice) IsValidIndex ¶
IsValidIndex checks whether the given index is a valid index into slice, within range of 0..len-1. Returns error if not.
func (Slice) MarshalJSON ¶
MarshalJSON saves the length and type, name information for each object in a slice, as a separate struct-like record at the start, followed by the structs for each element in the slice -- this allows the Unmarshal to first create all the elements and then load them
func (Slice) MarshalXML ¶
MarshalXML saves the length and type information for each object in a slice, as a separate struct-like record at the start, followed by the structs for each element in the slice -- this allows the Unmarshal to first create all the elements and then load them
func (*Slice) Move ¶
Move element from one position to another. Returns error if either index is invalid.
func (*Slice) UnmarshalJSON ¶
UnmarshalJSON parses the length and type information for each object in the slice, creates the new slice with those elements, and then loads based on the remaining bytes which represent each element
func (*Slice) UnmarshalXML ¶
UnmarshalXML parses the length and type information for each object in the slice, creates the new slice with those elements, and then loads based on the remaining bytes which represent each element
type TypeAndName ¶
TypeAndName holds a type and a name. Used for specifying configurations of children in Ki, for efficiently configuring the chilren.