github.com/goki/ki@v1.1.11/ki/doc.go (about)

     1  // Copyright (c) 2018, The GoKi Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package ki provides the base element of GoKi Trees: Ki = Tree in Japanese, and
     7  "Key" in English -- powerful tree structures supporting scenegraphs, programs,
     8  parsing, etc.
     9  
    10  The Node struct that implements the Ki interface, which can be used as an
    11  embedded type (or a struct field) in other structs to provide core tree
    12  functionality, including:
    13  
    14  	* Parent / Child Tree structure -- each Node can ONLY have one parent.
    15        Node struct's can also have Node fields -- these are functionally like
    16        fixed auto-named children.
    17  
    18  	* Paths for locating Nodes within the hierarchy -- key for many use-cases,
    19        including ability to convert pointers to/from strings for IO and robust
    20        deep copy and move functions.  The path separator is / for children and
    21        . for fields.
    22  
    23  	* Apply a function across nodes up or down a tree (natural "me first",
    24        breadth-first, depth-first) -- very flexible for tree walking.
    25  
    26  	* Generalized I/O -- can Save and Load the Tree as JSON, XML, etc --
    27        including pointers which are saved using paths and automatically
    28        cached-out after loading -- enums also bidirectionally convertable to
    29        strings using enum type registry in kit package.
    30  
    31  	* Robust deep copy, clone, move of nodes, with automatic pointer updating.
    32  
    33  	* Signal sending and receiving between Nodes (simlar to Qt Signals /
    34        Slots) -- setup connections once and then emit signals to all receivers
    35        when relevant event happens.
    36  
    37  	* Robust state updating -- wrap updates in UpdateStart / End, and signals
    38        are blocked until the final end, at the highest affected level in the
    39        tree, at which point a single update signal is sent -- automatically
    40        gives the minimal update.
    41  
    42  	* Properties (as a string-keyed map) with property inheritance, including
    43        type-level properties via kit type registry.
    44  
    45  In general, the names of the children of a given node should all be unique.
    46  The following functions defined in ki package can be used:
    47  
    48  * UniqueNameCheck(node) to check for unique names on node if uncertain.
    49  * UniqueNameCheckAll(node) to check entire tree under given node.
    50  * UniquifyNames(node) to add a suffix to name to ensure uniqueness.
    51  * UniquifyNamesAll(node) to to uniquify all names in entire tree.
    52  
    53  The Ki interface is designed to support virtual method calling in Go
    54  and is only intended to be implemented once, by the ki.Node type
    55  (as opposed to interfaces that are used for hiding multiple different
    56  implementations of a common concept).  Thus, all of the fields in ki.Node
    57  are exported (have captital names), to be accessed directly in types
    58  that embed and extend the ki.Node. The Ki interface has the "formal" name
    59  (e.g., Children) while the Node has the "nickname" (e.g., Kids).  See the
    60  Naming Conventions on the GoKi Wiki for more details.
    61  
    62  Each Node stores the Ki interface version of itself, as This() / Ths
    63  which enables full virtual function calling by calling the method
    64  on that interface instead of directly on the receiver Node itself.
    65  This requires proper initialization via Init method of the Ki interface.
    66  
    67  */
    68  package ki