rotor-framework 0.3.2

package/src/source/engine/builder/Builder.bs

@@ -0,0 +1,213 @@
+import "Processor.bs"
+import "PostProcessor.bs"
+import "NodePool.bs"
+import "Tree.bs"
+import "../../base/BaseWidget.bs"
+import "WidgetCreate.bs"
+import "WidgetUpdate.bs"
+import "WidgetRemove.bs"
+import "PluginAdapter.bs"
+
+namespace Rotor.ViewBuilder
+
+    ' =====================================================================
+    ' Builder - Core ViewBuilder engine that orchestrates widget lifecycle operations
+    '
+    ' Manages widget tree, node pool, plugin adapter, and rendering queue.
+    ' Handles create, update, and remove operations with post-processing support.
+    ' =====================================================================
+    class Builder
+
+        widgetTree = new Rotor.ViewBuilder.WidgetTree()
+
+        pluginAdapter = new Rotor.ViewBuilder.pluginAdapter()
+
+        processor = new Rotor.ViewBuilder.Processor()
+        postProcessor = new Rotor.ViewBuilder.PostProcessor()
+        postProcessBuffer = new Rotor.ViewBuilder.postProcessBuffer()
+
+        nodePool = new Rotor.ViewBuilder.NodePool()
+
+        frameworkInstance as Rotor.Framework
+
+        isRenderProcessing = false
+        renderQueue = []
+        callbackQueue = []
+
+        ' ---------------------------------------------------------------------
+        ' init - Initializes the builder and all its subsystems
+        '
+        ' @param {object} frameworkInstance - Reference to the framework instance
+        '
+        sub init(frameworkInstance as object)
+            m.frameworkInstance = frameworkInstance
+            m.nodePool.init(frameworkInstance)
+            m.widgetTree.init()
+            m.pluginAdapter.init(frameworkInstance)
+            m.processor.init(frameworkInstance)
+            m.postProcessor.init(frameworkInstance)
+            m.postProcessBuffer.init(frameworkInstance)
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Destroys the builder and cleans up all resources
+        '
+        sub destroy()
+            ' remove all widgets
+            rootKeys = m.widgetTree.tree.children.Keys()
+            m.erase(rootKeys, true)
+            ' destroy builder engine
+            m.pluginAdapter.destroy()
+            m.processor.destroy()
+            m.postProcessor.destroy()
+            m.postProcessBuffer.destroy()
+            m.widgetTree.destroy()
+            m.nodePool.destroy()
+            ' remove references
+            m.frameworkInstance = invalid
+        end sub
+
+        timer = CreateObject("roTimespan")
+
+        ' ---------------------------------------------------------------------
+        ' renderQueueFlush - Flushes the render queue and processes next queued render
+        '
+        sub renderQueueFlush()
+            if m.renderQueue.Count() > 0
+                nextQueuedConfig = m.renderQueue.shift()
+                m.renderProcessor(nextQueuedConfig.payload, nextQueuedConfig.params, true)
+            end if
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' render - Public render method that processes payloads through the render processor
+        '
+        ' @param {dynamic} payloads - Widget configuration payload(s) to render
+        ' @param {object} params - Optional rendering parameters (default: {})
+        '
+        sub render(payloads as dynamic, params = {} as object)
+            ' for each payload in Rotor.Utils.ensureArray(payloads)
+            ' m.renderProcessor(payload, params)
+            m.renderProcessor(payloads, params)
+            ' end for
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' renderProcessor - Core rendering processor that handles queuing and execution
+        '
+        ' @param {dynamic} payload - Widget configuration payload to process
+        ' @param {object} params - Rendering parameters (default: {})
+        ' @param {boolean} isNextProcess - Whether this is next in queue (default: false)
+        '
+        sub renderProcessor(payload as dynamic, params = {} as object, isNextProcess = false as boolean)
+            ' call custom callback
+            if Rotor.Utils.isValid(params.callback)
+                m.callbackQueue.push({
+                    callback: params.callback,
+                    callbackScope: params.callbackScope
+                })
+                params.delete("callback")
+                params.delete("callbackScope")
+            end if
+
+            renderingDisabled = m.frameworkInstance.enableRendering = false and not(params?.enableRenderBeforeReady ?? false)
+            if (m.isRenderProcessing = true and isNextProcess = false) or renderingDisabled
+                m.renderQueue.push({
+                    payload: payload,
+                    params: params
+                })
+                return
+            end if
+            m.isRenderProcessing = true
+
+            m.timer.Mark()
+            m.processor.run(m.postProcessBuffer, "0", payload, params)
+            m.timer.Mark()
+            m.postProcessor.run(m.postProcessBuffer)
+            m.postProcessBuffer.clearLifeCycleBuffers()
+
+            if m.renderQueue.Count() > 0
+                nextQueuedConfig = m.renderQueue.shift()
+                m.renderProcessor(nextQueuedConfig.payload, nextQueuedConfig.params, true)
+            else
+
+                m.isRenderProcessing = false
+
+                while m.callbackQueue.Count() > 0
+                    callbackObj = m.callbackQueue.shift()
+                    Rotor.Utils.callbackScoped(callbackObj.callback, callbackObj.callbackScope)
+                    callbackObj.callbackScope = invalid
+                end while
+
+            end if
+
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' erase - Erases widgets from the tree by ID or configuration
+        '
+        ' @param {dynamic} payload - Widget ID(s) or configuration object(s) to erase
+        ' @param {boolean} shouldSkipNodePool - Whether to skip returning nodes to pool (default: false)
+        ' @param {string} HID - Hierarchical ID context for search (default: "0")
+        '
+        sub erase (payload as dynamic, shouldSkipNodePool = false as boolean, HID = "0" as string)
+
+            ' normalize shortcuts
+
+            identifiersToErase = []
+            if Rotor.Utils.isString(payload)
+                identifiersToErase.push(payload)
+            else if Rotor.Utils.isArray(payload)
+                for each item in payload
+                    if Rotor.Utils.isString(item)
+                        identifiersToErase.push(item)
+                    else if Rotor.Utils.isAssociativeArray(item)
+                        identifiersToErase.push(item?.id)
+                    end if
+                end for
+            else if Rotor.Utils.isAssociativeArray(payload)
+                for each key in payload
+                    if key = "id"
+                        identifiersToErase.push(key)
+                    else
+                        identifiersToErase.push(payload[key])
+                    end if
+                end for
+            end if
+
+            widgetsToRemove = []
+
+            for each id in identifiersToErase
+                result = m.widgetTree.find(id, HID)
+                if result <> invalid
+                    widgetsToRemove.append(result)
+                end if
+            end for
+
+            if widgetsToRemove.Count() > 0
+
+                renderObject = []
+
+                for each widget in widgetsToRemove
+
+                    if m.widgetTree.hasByHID(widget.HID)
+                        renderObject.push({
+                            HID: widget.HID,
+                            parentHID: widget.parentHID,
+                            id: widget.id,
+                            markedToRemove: true,
+                            shouldSkipNodePool: shouldSkipNodePool
+                        })
+                    end if
+
+                end for
+                ' renderObject.Clear()
+                m.render(renderObject)
+
+            end if
+
+        end sub
+
+    end class
+
+end namespace

package/src/source/engine/builder/NodePool.bs

@@ -0,0 +1,236 @@
+' ===== NODE POOL =====
+namespace Rotor.ViewBuilder
+
+    ' =====================================================================
+    ' NodePool - Manages reusable pools of SceneGraph nodes to improve performance. Optimized for pooling Group nodes and types extending Group (like Poster), as well as other common nodes (e.g., Rectangle, Label). Includes node reset logic upon release.
+    ' =====================================================================
+    class NodePool
+
+        frameworkInstance as Rotor.Framework
+
+        config = {
+            nodePool: [{
+                    nodeType: "Group",
+                    amount: 1
+                }, {
+                    nodeType: "Rectangle",
+                    amount: 1
+                }, {
+                    nodeType: "Poster",
+                    amount: 1
+                }, {
+                    nodeType: "Label",
+                    amount: 1
+                }
+            ]
+        }
+
+        pools = {}
+        poolInfo = {
+            totalAcquiredNodes: 0, ' Configured and acquired nodes from pools
+            totalReleasedNodes: 0, ' Released nodes back to pools
+            outOfStockNodes: {}, ' Nodes that out of stock
+            poolFulness: {} ' Current amount of nodes in each pool
+        }
+
+        ' ---------------------------------------------------------------------
+        ' new - Initializes the instance
+        '
+        ' @description Initializes the node pool
+        ' ---------------------------------------------------------------------
+        sub new()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' init - Initializes the pool with framework instance reference
+        '
+
+        ' @param {Rotor.Framework} frameworkInstance - Framework instance reference
+        ' ---------------------------------------------------------------------
+        sub init(frameworkInstance as Rotor.Framework)
+            m.frameworkInstance = frameworkInstance
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Cleans up framework instance reference and pools
+        ' ---------------------------------------------------------------------
+        sub destroy()
+            m.frameworkInstance = invalid
+            m.pools.Clear()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        '
+
+        ' presetNodePool - Presets node pools with specified amounts of each node type
+        '
+        ' @param {object} config - Configuration with nodePool array
+        ' ---------------------------------------------------------------------
+        sub presetNodePool(config)
+            Rotor.Utils.deepExtendAA(m.config, config)
+            for each thisPool in m.config.nodePool
+                for index = 0 to thisPool.amount - 1
+                    if not m.pools.doesExist(thisPool.nodeType)
+                        m.pools[thisPool.nodeType] = []
+                        #if debug
+                            m.poolInfo.outOfStockNodes[thisPool.nodeType] = 0
+                        #end if
+                    end if
+                    node = CreateObject("roSGNode", thisPool.nodeType)
+                    m.pools[thisPool.nodeType].push(node)
+                end for
+            end for
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' acquireNode - Acquires a node from the pool or creates a new one
+        '
+
+        ' @param {string} nodeType - Type of SceneGraph node to acquire
+        ' @returns {object} SceneGraph node instance
+        ' ---------------------------------------------------------------------
+        function acquireNode(nodeType)
+            if m.pools.doesExist(nodeType) and m.pools[nodeType].Count() > 0
+                node = m.pools[nodeType].pop()
+                #if debug
+                    m.poolInfo.totalAcquiredNodes++
+                #end if
+            else
+                node = CreateObject("roSGNode", nodeType)
+                #if debug
+                    if m.pools.doesExist(nodeType)
+                        m.poolInfo.outOfStockNodes[nodeType]++
+                    end if
+                #end if
+            end if
+
+            return node
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' releaseNodeBranch - Recursively releases a node and its children back to pools
+        '
+
+        ' @param {object} node - SceneGraph node to release
+        ' @param {object} parent - Parent node for removal (default: invalid)
+        ' ---------------------------------------------------------------------
+        sub releaseNodeBranch(node as object, parent = invalid as object)
+
+            children = node.getChildren(-1, 0)
+
+            if children <> invalid and children.count() > 0
+                for each child in children
+                    m.releaseNodeBranch(child, node)
+                end for
+            end if
+
+            nodeType = node.subtype()
+
+            if m.pools.doesExist(nodeType)
+                if parent <> invalid
+                    parent.removeChild(node)
+                end if
+                m.resetNode(node)
+                m.pools[nodeType].push(node)
+
+                #if debug
+                    m.poolInfo.totalReleasedNodes++
+                #end if
+            end if
+
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' resetNode - Resets a node's properties to default values before returning to pool
+        '
+
+        ' @param {object} node - SceneGraph node to reset
+        ' @private
+        ' ---------------------------------------------------------------------
+        private sub resetNode(node as object)
+            if node = invalid then return
+
+            nodeType = node.subtype()
+
+            node.visible = true
+            node.opacity = 1.0
+            node.translation = [0.0, 0.0]
+            node.rotation = 0.0
+            node.scale = [1.0, 1.0]
+            node.scaleRotateCenter = [0.0, 0.0]
+            node.inheritParentTransform = true
+            node.inheritParentOpacity = true
+            node.muteAudioGuide = false
+            node.renderPass = 0
+            node.enableRenderTracking = false
+            ' TODO: test below properties to reset
+            ' node.childRenderOrder = "renderLast"
+            ' node.clippingRect = [0.0, 0.0, 0.0, 0.0]
+
+            if nodeType = "Rectangle"
+                node.setFields({
+                    color: "#FFFFFFFF",
+                    width: 0,
+                    height: 0,
+                    blendingEnabled: true
+                })
+
+            else if nodeType = "Poster"
+                node.setFields({
+                    uri: "",
+                    width: 0,
+                    height: 0,
+                    loadWidth: 0,
+                    loadHeight: 0,
+                    blendColor: "#FFFFFFFF",
+                    loadDisplayMode: "noScale",
+                    loadSync: false,
+                    loadingBitmapUri: "",
+                    failedBitmapUri: "",
+                    loadingBitmapOpacity: 1.0,
+                    failedBitmapOpacity: 1.0
+                })
+
+            else if nodeType = "Label"
+                node.setFields({
+                    text: "",
+                    color: "#FFFFFFFF",
+                    horizAlign: "left",
+                    vertAlign: "top",
+                    width: 0,
+                    height: 0,
+                    wrap: false,
+                    numLines: 0,
+                    lineSpacing: 0.0,
+                    maxLines: 0,
+                    ellipsisText: "",
+                    font: "font:MediumSystemFont"
+                })
+
+            end if
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' getNodePoolInfo - Gets node pool statistics (debug mode only)
+        '
+
+        ' @returns {object} Pool information with counts and stats
+        ' ---------------------------------------------------------------------
+        function getNodePoolInfo()
+            info = {}
+            #if debug
+                for each nodeType in m.pools
+                    m.poolInfo.poolFulness[nodeType] = m.pools[nodeType].Count()
+                end for
+                info = m.poolInfo
+            #end if
+            return info
+        end function
+
+
+    end class
+
+
+
+
+end namespace

package/src/source/engine/builder/PluginAdapter.bs

@@ -0,0 +1,139 @@
+namespace Rotor.ViewBuilder
+
+    ' =====================================================================
+    ' PluginHookClass - Container for plugin hook metadata and handler function
+    ' =====================================================================
+    class PluginHookClass
+
+        pluginKey as string
+        handlerFn as function
+
+        ' ---------------------------------------------------------------------
+        ' new - Initializes the instance
+        '
+        ' @description Initializes plugin hook with key and handler
+        ' @param {object} config - Configuration with pluginKey and handlerFn
+        ' ---------------------------------------------------------------------
+        sub new(config)
+            m.pluginKey = config.pluginKey
+            m.handlerFn = config.handlerFn
+        end sub
+
+    end class
+
+    ' =====================================================================
+    ' pluginAdapter - Manages plugin registration and lifecycle hook integration. Maintains plugin instances and maps lifecycle hooks to plugin handlers.
+    ' =====================================================================
+    class pluginAdapter
+
+        plugins as object
+
+        ' ---------------------------------------------------------------------
+        ' new - Initializes the instance
+        '
+        ' @description Initializes plugin hook storage for all lifecycle types
+        ' ---------------------------------------------------------------------
+        sub new()
+
+            ' dedicated plugin lifecycle hooks
+            for each hookType in [
+                    Rotor.Const.LifeCycleHookType.BEFORE_MOUNT,
+                    Rotor.Const.LifeCycleHookType.AFTER_MOUNTED,
+                    Rotor.Const.LifeCycleHookType.BEFORE_UPDATE,
+                    Rotor.Const.LifeCycleHookType.AFTER_UPDATED,
+                    Rotor.Const.LifeCycleHookType.BEFORE_DESTROY
+                ]
+                m.pluginHooks[hookType] = {}
+            end for
+
+        end sub
+
+        ' Plugins has limited type of hooks to lifecycle (check the list below)
+        pluginHooks = {}
+        pluginKeyList = CreateObject("roList")
+
+        frameworkInstance as Rotor.Framework
+
+        ' ---------------------------------------------------------------------
+        ' registerPlugins - Registers plugins and their lifecycle hooks with the framework
+        '
+
+        ' @param {object} pluginConfig - Plugin configuration object or array
+        ' ---------------------------------------------------------------------
+        sub registerPlugins (pluginConfig as object)
+
+            plugins = Rotor.Utils.ensureArray(pluginConfig)
+
+            for each plugin in plugins
+
+                ' Plugin key
+                pluginKey = plugin.key
+
+                ' add plugin key to tree viewModelState
+                ' obj = Rotor.Utils.wrapObject(pluginKey, {})
+
+                ' create workspace for plugin in root of widget tree
+                ' m.frameworkInstance.builder.widgetTree.tree.extendContext(obj)
+
+                ' Setup hooks
+                hooks = plugin.hooks
+                if Rotor.Utils.isValid(hooks) and hooks.Count() > 0
+
+                    for each hook in hooks
+                        pluginHook = new PluginHookClass({
+                            pluginKey: pluginKey,
+                            handlerFn: hooks[hook]
+                        })
+                        m.pluginHooks[hook][pluginKey] = pluginHook
+                    end for
+
+                end if
+
+                ' add plugin instance to viewBuilder
+                m.pluginKeyList.AddTail(pluginKey)
+                m.frameworkInstance.plugins[pluginKey] = plugin
+                m.frameworkInstance.plugins[pluginKey].frameworkInstance = m.frameworkInstance
+                if Rotor.Utils.isFunction(m.frameworkInstance.plugins[pluginKey].init)
+                    m.frameworkInstance.plugins[pluginKey].init()
+                end if
+            end for
+
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' destroyPlugins - Destroys all registered plugins
+        ' ---------------------------------------------------------------------
+        sub destroyPlugins()
+            if m.plugins.Count() > 0
+                for each plugin in m.plugins
+                    plugin.frameworkInstance = invalid
+                    destroy = plugin.destroy
+                    if Rotor.Utils.isFunction(plugin.destroy)
+                        destroy()
+                    end if
+                end for
+            end if
+        end sub
+
+        ' ---------------------------------------------------------------------
+        '
+
+        ' init - Initializes the adapter with framework instance reference
+        '
+        ' @param {object} frameworkInstance - Framework instance reference
+        ' ---------------------------------------------------------------------
+        sub init(frameworkInstance as object)
+            m.frameworkInstance = frameworkInstance
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Cleans up framework instance reference
+        '
+        ' ---------------------------------------------------------------------
+        sub destroy()
+            m.frameworkInstance = invalid
+        end sub
+
+    end class
+
+end namespace