novelWriter 2.6b1__py3-none-any.whl → 2.6rc1__py3-none-any.whl

novelwriter/core/tree.py

@@ -3,10 +3,11 @@ novelWriter – Project Tree Class
 ================================
 
 File History:
-Created: 2020-05-07 [0.4.5] NWTree
+Created:   2020-05-07 [0.4.5] NWTree
+Rewritten: 2024-11-16 [2.6b2] NWTree
 
 This file is a part of novelWriter
-Copyright 2018–2024, Veronica Berglyd Olsen
+Copyright (C) 2020 Veronica Berglyd Olsen and novelWriter contributors
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -30,10 +31,13 @@ from collections.abc import Iterable, Iterator
 from pathlib import Path
 from typing import TYPE_CHECKING, Literal, overload
 
-from novelwriter.common import isHandle
-from novelwriter.constants import nwFiles
+from PyQt5.QtCore import QModelIndex
+
+from novelwriter import SHARED
+from novelwriter.constants import nwFiles, nwLabels, trConst
 from novelwriter.core.item import NWItem
-from novelwriter.enum import nwItemClass, nwItemLayout, nwItemType
+from novelwriter.core.itemmodel import ProjectModel, ProjectNode
+from novelwriter.enum import nwChange, nwItemClass, nwItemLayout, nwItemType
 from novelwriter.error import logException
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -41,7 +45,7 @@ if TYPE_CHECKING:  # pragma: no cover
 
 logger = logging.getLogger(__name__)
 
-MAX_DEPTH = 1000  # Cap of tree traversing for loops (recursion limit)
+MAX_DEPTH = 999  # Cap of tree traversing for loops (recursion limit)
 
 
 class NWTree:
@@ -51,30 +55,51 @@ class NWTree:
     This class holds all the project items of the project as instances
     of NWItem.
 
-    For historical reasons, the order of the items is saved in a
-    separate list from the items themselves, which are stored in a
-    dictionary. This is somewhat redundant with the newer versions of
-    Python, but is still practical as it's easier to update the item
-    order as a list.
-
     Each item has a handle, which is a random hex string of length 13.
     The handle is the name of the item everywhere in novelWriter, and is
     also used for file names.
     """
 
-    __slots__ = ("_project", "_tree", "_order", "_roots", "_trash", "_changed")
+    __slots__ = ("_project", "_model", "_items", "_nodes", "_trash")
 
     def __init__(self, project: NWProject) -> None:
-
         self._project = project
+        self._model = ProjectModel(self)
+        self._items: dict[str, NWItem] = {}
+        self._nodes: dict[str, ProjectNode] = {}
+        self._trash = None
+        logger.debug("Ready: NWTree")
+        return
 
-        self._tree: dict[str, NWItem] = {}   # Holds all the items of the project
-        self._order: list[str] = []          # The order of the tree items in the tree view
-        self._roots: dict[str, NWItem] = {}  # The root items of the tree
+    def __del__(self) -> None:  # pragma: no cover
+        logger.debug("Delete: NWTree")
+        return
+
+    def __len__(self) -> int:
+        """The number of items in the project."""
+        return len(self._items)
 
-        self._trash = None     # The handle of the trash root folder
-        self._changed = False  # True if tree structure has changed
+    def __bool__(self) -> bool:
+        """True if there are any items in the project."""
+        return bool(self._items)
 
+    def __getitem__(self, tHandle: str | None) -> NWItem | None:
+        """Return a project item based on its handle. Returns None if
+        the handle doesn't exist in the project.
+        """
+        if tHandle and tHandle in self._items:
+            return self._items[tHandle]
+        logger.error("No tree item with handle '%s'", str(tHandle))
+        return None
+
+    def __contains__(self, tHandle: str) -> bool:
+        """Checks if a handle exists in the tree."""
+        return tHandle in self._items
+
+    def __iter__(self) -> Iterator[NWItem]:
+        """Iterate through project items."""
+        for node in self._model.root.allChildren():
+            yield node.item
         return
 
     ##
@@ -82,9 +107,19 @@ class NWTree:
     ##
 
     @property
-    def trashRoot(self) -> str | None:
-        """Return the handle of the trash folder, or None."""
-        return self._trash
+    def trash(self) -> ProjectNode | None:
+        """Return trash node, if it exists."""
+        if self._trash:
+            return self._trash
+        return self._getTrashNode()
+
+    @property
+    def model(self) -> ProjectModel:
+        return self._model
+
+    @property
+    def nodes(self) -> dict[str, ProjectNode]:
+        return self._nodes
 
     ##
     #  Class Methods
@@ -92,83 +127,91 @@ class NWTree:
 
     def clear(self) -> None:
         """Clear the item tree entirely."""
-        self._tree    = {}
-        self._order   = []
-        self._roots   = {}
-        self._trash   = None
-        self._changed = False
+        oldModel = self._model
+        oldModel.clear()
+        self._model = ProjectModel(self)
+        self._items.clear()
+        self._nodes.clear()
+        self._trash = None
+        oldModel.deleteLater()
+        del oldModel
         return
 
-    def handles(self) -> list[str]:
-        """Returns a copy of the list of all the active handles."""
-        return self._order.copy()
+    def add(self, item: NWItem, pos: int = -1) -> bool:
+        """Add a project item into the project tree."""
+        if pHandle := item.itemParent:
+            if parent := self._nodes.get(pHandle):
+                node = ProjectNode(item)
+                index = self._model.indexFromNode(parent)
+                self._model.insertChild(node, index, pos)
+                self._nodes[item.itemHandle] = node
+                self._items[item.itemHandle] = item
+                self._itemChange(item, nwChange.CREATE)
+            else:
+                logger.error("Could not locate parent of '%s'", item.itemHandle)
+                return False
+        elif item.isRootType():
+            node = ProjectNode(item)
+            self._model.insertChild(node, QModelIndex(), pos)
+            self._nodes[item.itemHandle] = node
+            self._items[item.itemHandle] = item
+            self._itemChange(item, nwChange.CREATE)
+        else:
+            logger.error("Invalid project item '%s'", item.itemHandle)
+            return False
+        return True
+
+    def remove(self, tHandle: str) -> bool:
+        """Remove an item from the project tree."""
+        if (node := self._nodes.get(tHandle)) and tHandle in self._items:
+            index = self._model.indexFromNode(node)
+            if index.isValid() and self._model.removeChild(index.parent(), index.row()):
+                self._itemChange(node.item, nwChange.DELETE)
+                del self._nodes[tHandle]
+                del self._items[tHandle]
+                return True
+        return False
 
     @overload  # pragma: no cover
-    def create(self, label: str, parent: None, itemType: Literal[nwItemType.ROOT],
-               itemClass: nwItemClass) -> str:
+    def create(
+        self, label: str, parent: None, itemType: Literal[nwItemType.ROOT],
+        itemClass: nwItemClass, pos: int = -1
+    ) -> str:
         pass
 
     @overload  # pragma: no cover
-    def create(self, label: str, parent: str | None, itemType: nwItemType,
-               itemClass: nwItemClass = nwItemClass.NO_CLASS) -> str | None:
+    def create(
+        self, label: str, parent: str | None, itemType: nwItemType,
+        itemClass: nwItemClass = nwItemClass.NO_CLASS, pos: int = -1
+    ) -> str | None:
         pass
 
-    def create(self, label, parent, itemType, itemClass=nwItemClass.NO_CLASS):
+    def create(
+        self, label: str, parent: str | None, itemType: nwItemType,
+        itemClass: nwItemClass = nwItemClass.NO_CLASS, pos: int = -1,
+    ) -> str | None:
         """Create a new item in the project tree, and return its handle.
         If the item cannot be added to the project because of an invalid
         parent, None is returned. For root elements, this cannot occur.
         """
         parent = None if itemType == nwItemType.ROOT else parent
-        if parent is None or parent in self._order:
+        if parent is None or parent in self._nodes:
             tHandle = self._makeHandle()
-            newItem = NWItem(self._project, tHandle)
-            newItem.setName(label)
-            newItem.setParent(parent)
-            newItem.setType(itemType)
-            newItem.setClass(itemClass)
-            self.append(newItem)
-            self.updateItemData(tHandle)
-            return tHandle
+            nwItem = NWItem(self._project, tHandle)
+            nwItem.setName(label)
+            nwItem.setParent(parent)
+            nwItem.setType(itemType)
+            nwItem.setClass(itemClass)
+            if self.add(nwItem, pos):
+                return tHandle
         return None
 
-    def append(self, nwItem: NWItem) -> bool:
-        """Add a new item to the end of the tree."""
-        tHandle = nwItem.itemHandle
-        pHandle = nwItem.itemParent
-
-        if not isHandle(tHandle):
-            logger.warning("Invalid item handle '%s' detected, skipping", tHandle)
-            return False
-
-        if tHandle in self._tree:
-            logger.warning("Duplicate handle '%s' detected, skipping", tHandle)
-            return False
-
-        logger.debug("Adding item '%s' with parent '%s'", str(tHandle), str(pHandle))
-
-        if nwItem.isRootType():
-            logger.debug("Item '%s' is a root item", str(tHandle))
-            self._roots[tHandle] = nwItem
-            if nwItem.itemClass == nwItemClass.TRASH:
-                if self._trash is None:
-                    logger.debug("Item '%s' is the trash folder", str(tHandle))
-                    self._trash = tHandle
-                else:
-                    logger.error("Only one trash folder allowed")
-                    return False
-
-        self._tree[tHandle] = nwItem
-        self._order.append(tHandle)
-        self._setTreeChanged(True)
-
-        return True
-
-    def duplicate(self, sHandle: str) -> NWItem | None:
+    def duplicate(self, sHandle: str, pHandle: str | None, putAfter: bool) -> NWItem | None:
         """Duplicate an item and set a new handle."""
-        sItem = self.__getitem__(sHandle)
-        if isinstance(sItem, NWItem):
-            nItem = NWItem.duplicate(sItem, self._makeHandle())
-            if self.append(nItem):
+        if sNode := self._nodes.get(sHandle):
+            nItem = NWItem.duplicate(sNode.item, self._makeHandle())
+            nItem.setParent(pHandle)
+            if self.add(nItem, (sNode.row() + 1) if putAfter else -1):
                 logger.info("Duplicated item '%s' -> '%s'", sHandle, nItem.itemHandle)
                 return nItem
         return None
@@ -177,23 +220,62 @@ class NWTree:
         """Pack the content of the tree into a list of dictionaries of
         items. In the order defined by the _treeOrder list.
         """
-        tree = []
-        for tHandle in self._order:
-            tItem = self.__getitem__(tHandle)
-            if tItem:
-                tree.append(tItem.pack())
-        return tree
+        nodes = self._model.root.allChildren()
+        if len(nodes) != len(self._nodes):
+            logger.warning(
+                "Model tree is inconsitent with nodes map, %d != %d",
+                len(nodes), len(self._nodes)
+            )
+        return [node.item.pack() for node in nodes]
 
     def unpack(self, data: list[dict]) -> None:
         """Iterate through all items of a list and add them to the
         project tree.
         """
         self.clear()
+        items: dict[str, NWItem] = self._items.copy()
         for item in data:
-            nwItem = NWItem(self._project, "")  # Handle is set by unpack()
+            nwItem = NWItem(self._project, "")
             if nwItem.unpack(item):
-                self.append(nwItem)
-                nwItem.saveInitialCount()
+                items[nwItem.itemHandle] = nwItem
+
+        later = items
+        self._model.beginInsertRows(self._model.index(0, 0), 0, 0)
+        for _ in range(MAX_DEPTH):
+            later = self._addItems(later)
+            if len(later) == 0:
+                break
+        else:
+            logger.error("Not all items could be added to project tree")
+
+        self._trash = self._getTrashNode()
+        self._model.endInsertRows()
+        self._model.layoutChanged.emit()
+
+        return
+
+    def refreshItems(self, items: list[str]) -> None:
+        """Refresh these items on the GUI. If they are an ordered range,
+        also set the isRange flag to True.
+        """
+        for tHandle in items:
+            if node := self._nodes.get(tHandle):
+                node.refresh()
+                node.updateCount()
+                indexS = self._model.indexFromNode(node, 0)
+                indexE = self._model.indexFromNode(node, 3)
+                self._model.dataChanged.emit(indexS, indexE)
+                self._itemChange(node.item, nwChange.UPDATE)
+        return
+
+    def refreshAllItems(self) -> None:
+        """Refresh all items in the tree."""
+        for node in reversed(self._model.root.allChildren()):
+            node.refresh()
+            node.updateCount(propagate=False)
+        self._model.root.refresh()
+        self._model.root.updateCount(propagate=False)
+        self._model.layoutChanged.emit()
         return
 
     def checkConsistency(self, prefix: str) -> tuple[int, int]:
@@ -205,29 +287,21 @@ class NWTree:
         mark recovered files.
         """
         storage = self._project.storage
-        files = set(storage.scanContent())
-        for tHandle in self._order:
-            if self.updateItemData(tHandle):
-                logger.debug("Checking item '%s' ... OK", tHandle)
-                files.discard(tHandle)  # Remove it from the record
-            else:
-                logger.error("Checking item '%s' ... ERROR", tHandle)
-                self.__delitem__(tHandle)  # The file will be re-added as orphaned
-
-        orphans = len(files)
+        remains = set(storage.scanContent()).difference(set(self._nodes.keys()))
+        orphans = len(remains)
         if orphans == 0:
             logger.info("Checked project files: OK")
             return 0, 0
 
         logger.warning("Found %d file(s) not tracked in project", orphans)
         recovered = 0
-        for cHandle in files:
+        for cHandle in remains:
             aDoc = storage.getDocument(cHandle)
             aDoc.readDocument(isOrphan=True)
             oName, oParent, oClass, oLayout = aDoc.getMeta()
 
             oName = oName or cHandle
-            oParent = oParent if oParent in self._order else None
+            oParent = oParent if oParent in self._nodes else None
             oClass = oClass or nwItemClass.NOVEL
             oLayout = oLayout or nwItemLayout.NOTE
 
@@ -248,8 +322,7 @@ class NWTree:
             newItem.setType(nwItemType.FILE)
             newItem.setClass(oClass)
             newItem.setLayout(oLayout)
-            if self.append(newItem):
-                self.updateItemData(cHandle)
+            if self.add(newItem):
                 recovered += 1
 
         return orphans, recovered
@@ -263,38 +336,33 @@ class NWTree:
         if not (isinstance(contentPath, Path) and isinstance(runtimePath, Path)):
             return False
 
-        tocList = []
-        tocLen = 0
-        for tHandle in self._order:
-            tItem = self.__getitem__(tHandle)
-            if tItem is None:
-                continue
-
-            tFile = tHandle+".nwd"
-            if (contentPath / tFile).is_file():
+        entries = []
+        maxLen = 0
+        for node in self._model.root.allChildren():
+            item = node.item
+            file = f"{item.itemHandle}.nwd"
+            if (contentPath / file).is_file():
                 tocLine = "{0:<25s}  {1:<9s}  {2:<8s}  {3:s}".format(
-                    str(Path("content") / tFile),
-                    tItem.itemClass.name,
-                    tItem.itemLayout.name,
-                    tItem.itemName,
+                    f"content/{file}",
+                    item.itemClass.name,
+                    item.itemLayout.name,
+                    item.itemName,
                 )
-                tocList.append(tocLine)
-                tocLen = max(tocLen, len(tocLine))
+                entries.append(tocLine)
+                maxLen = max(maxLen, len(tocLine))
 
         try:
-            # Dump the text
-            tocText = runtimePath / nwFiles.TOC_TXT
-            with open(tocText, mode="w", encoding="utf-8") as outFile:
-                outFile.write("\n")
-                outFile.write("Table of Contents\n")
-                outFile.write("=================\n")
-                outFile.write("\n")
-                outFile.write("{0:<25s}  {1:<9s}  {2:<8s}  {3:s}\n".format(
+            with open(runtimePath / nwFiles.TOC_TXT, mode="w", encoding="utf-8") as toc:
+                toc.write("\n")
+                toc.write("Table of Contents\n")
+                toc.write("=================\n")
+                toc.write("\n")
+                toc.write("{0:<25s}  {1:<9s}  {2:<8s}  {3:s}\n".format(
                     "File Name", "Class", "Layout", "Document Label"
                 ))
-                outFile.write("-"*max(tocLen, 62) + "\n")
-                outFile.write("\n".join(tocList))
-                outFile.write("\n")
+                toc.write("-"*max(maxLen, 62) + "\n")
+                toc.write("\n".join(entries))
+                toc.write("\n")
 
         except Exception:
             logger.error("Could not write ToC file")
@@ -307,74 +375,46 @@ class NWTree:
         """Loop over all entries and add up the word counts."""
         noteWords = 0
         novelWords = 0
-        for tHandle in self._order:
-            tItem = self.__getitem__(tHandle)
-            if tItem is None:
-                continue
-            if tItem.itemLayout == nwItemLayout.NO_LAYOUT:
-                pass
-            elif tItem.itemLayout == nwItemLayout.NOTE:
-                noteWords += tItem.wordCount
-            else:
-                novelWords += tItem.wordCount
+        for item in self._items.values():
+            if item.itemLayout == nwItemLayout.NOTE:
+                noteWords += item.wordCount
+            elif item.itemLayout == nwItemLayout.DOCUMENT:
+                novelWords += item.wordCount
         return novelWords, noteWords
 
     ##
     #  Tree Item Methods
     ##
 
-    def updateItemData(self, tHandle: str) -> bool:
-        """Update the root item handle of a given item. Returns True if
-        a root was found and data updated, otherwise False.
-        """
-        tItem = self.__getitem__(tHandle)
-        if tItem is None:
-            return False
-
-        iItem = tItem
-        for _ in range(MAX_DEPTH):
-            if iItem.itemParent is None:
-                tItem.setRoot(iItem.itemHandle)
-                tItem.setClassDefaults(iItem.itemClass)
-                return True
-            else:
-                iItem = self.__getitem__(iItem.itemParent)
-                if iItem is None:
-                    return False
-        else:
-            raise RecursionError("Critical internal error")
-
     def checkType(self, tHandle: str, itemType: nwItemType) -> bool:
         """Check if item exists and is of the specified item type."""
-        tItem = self.__getitem__(tHandle)
-        if not tItem:
-            return False
-        return tItem.itemType == itemType
+        if tItem := self.__getitem__(tHandle):
+            return tItem.itemType == itemType
+        return False
 
-    def getItemPath(self, tHandle: str, asName: bool = False) -> list[str]:
+    def itemPath(self, tHandle: str, asName: bool = False) -> list[str]:
         """Iterate upwards in the tree until we find the item with
         parent None, the root item, and return the list of handles, or
         alternatively item names. We do this with a for loop with a
         maximum depth to make infinite loops impossible.
         """
-        tTree = []
-        tItem = self.__getitem__(tHandle)
-        if tItem is not None:
-            tTree.append(tItem.itemName if asName else tHandle)
+        path = []
+        if node := self._nodes.get(tHandle):
             for _ in range(MAX_DEPTH):
-                if tItem.itemParent is None:
-                    return tTree
+                if parent := node.parent():
+                    path.append(node.item.itemName if asName else tHandle)
+                    node = parent
                 else:
-                    tHandle = tItem.itemParent
-                    tItem = self.__getitem__(tHandle)
-                    if tItem is None:
-                        return tTree
-                    else:
-                        tTree.append(tItem.itemName if asName else tHandle)
+                    return path
             else:
-                raise RecursionError("Critical internal error")
+                logger.error("Max project tree depth reached")
+        return path
 
-        return tTree
+    def subTree(self, tHandle: str) -> list[str]:
+        """Get the subtree from a given handle."""
+        if node := self._nodes.get(tHandle):
+            return [child.item.itemHandle for child in node.allChildren()]
+        return []
 
     ##
     #  Tree Root Methods
@@ -383,131 +423,72 @@ class NWTree:
     def rootClasses(self) -> set[nwItemClass]:
         """Return a set of all root classes in use by the project."""
         rootClasses = set()
-        for nwItem in self._roots.values():
-            rootClasses.add(nwItem.itemClass)
+        for node in self._model.root.children:
+            rootClasses.add(node.item.itemClass)
         return rootClasses
 
     def iterRoots(self, itemClass: nwItemClass | None) -> Iterable[tuple[str, NWItem]]:
         """Iterate over all root items of a given class in order."""
-        for tHandle in self._order:
-            nwItem = self.__getitem__(tHandle)
-            if isinstance(nwItem, NWItem) and nwItem.isRootType():
-                if itemClass is None or nwItem.itemClass == itemClass:
-                    yield tHandle, nwItem
+        for node in self._model.root.children:
+            if node.item.isRootType():
+                if itemClass is None or node.item.itemClass == itemClass:
+                    yield node.item.itemHandle, node.item
         return
 
-    def isTrash(self, tHandle: str) -> bool:
-        """Check if an item is in or is the trash folder."""
-        tItem = self.__getitem__(tHandle)
-        if tItem is None:
-            return True
-        if tItem.itemClass == nwItemClass.TRASH:
-            return True
-        if self._trash is not None:
-            if tHandle == self._trash:
-                return True
-            elif tItem.itemParent == self._trash:
-                return True
-            elif tItem.itemRoot == self._trash:
-                return True
-        return False
-
     def findRoot(self, itemClass: nwItemClass | None) -> str | None:
         """Find the first root item for a given class."""
-        for aRoot in self._roots:
-            tItem = self.__getitem__(aRoot)
-            if tItem is None:
-                continue
-            if itemClass == tItem.itemClass:
-                return tItem.itemHandle
+        for node in self._model.root.children:
+            if node.item.itemClass == itemClass:
+                return node.item.itemHandle
         return None
 
     ##
-    #  Setters
+    #  Internal Functions
     ##
 
-    def setOrder(self, newOrder: list[str]) -> None:
-        """Reorders the tree based on a list of items."""
-        tmpOrder = [tHandle for tHandle in newOrder if tHandle in self._tree]
-        if not (len(tmpOrder) == len(newOrder) == len(self._order)):
-            # Something is wrong, so let's debug it
-            for tHandle in newOrder:
-                if tHandle not in self._tree:
-                    logger.error("Handle '%s' in new tree order is not in old order", tHandle)
-            for tHandle in self._order:
-                if tHandle not in tmpOrder:
-                    logger.warning("Handle '%s' in old tree order is not in new order", tHandle)
-
-        # Save the temp list
-        self._order = tmpOrder
-        self._setTreeChanged(True)
-        logger.debug("Project tree order updated")
-
+    def _itemChange(self, item: NWItem, change: nwChange) -> None:
+        """Signal item change and notify project."""
+        tHandle = item.itemHandle
+        logger.debug("Item change: %s -> %s", tHandle, change.name)
+        self._project.setProjectChanged(True)
+        SHARED.emitProjectItemChanged(self._project, tHandle, change)
+        if item.isRootType():
+            SHARED.emitRootFolderChanged(self._project, tHandle, change)
         return
 
-    ##
-    #  Special Methods
-    ##
-
-    def __len__(self) -> int:
-        """The number of items in the project."""
-        return len(self._order)
-
-    def __bool__(self) -> bool:
-        """True if there are any items in the project."""
-        return bool(self._order)
-
-    def __getitem__(self, tHandle: str | None) -> NWItem | None:
-        """Return a project item based on its handle. Returns None if
-        the handle doesn't exist in the project.
-        """
-        if tHandle and tHandle in self._tree:
-            return self._tree[tHandle]
-        logger.error("No tree item with handle '%s'", str(tHandle))
+    def _getTrashNode(self) -> ProjectNode | None:
+        """Get the trash node. If it doesn't exist, create it."""
+        for node in self._model.root.children:
+            if node.item.itemClass == nwItemClass.TRASH:
+                return node
+        label = trConst(nwLabels.CLASS_NAME[nwItemClass.TRASH])
+        if handle := self.create(label, None, nwItemType.ROOT, nwItemClass.TRASH):
+            return self._nodes.get(handle)
         return None
 
-    def __delitem__(self, tHandle: str) -> None:
-        """Remove an item from the internal lists and dictionaries."""
-        if tHandle in self._order and tHandle in self._tree:
-            self._order.remove(tHandle)
-            del self._tree[tHandle]
-        else:
-            logger.warning("Failed to delete item '%s': item not found", tHandle)
-            return
-
-        if tHandle in self._roots:
-            del self._roots[tHandle]
-        if tHandle == self._trash:
-            self._trash = None
-
-        self._setTreeChanged(True)
-
-        return
-
-    def __contains__(self, tHandle: str) -> bool:
-        """Checks if a handle exists in the tree."""
-        return tHandle in self._order
-
-    def __iter__(self) -> Iterator[NWItem]:
-        """Iterate through project items."""
-        for tHandle in self._order:
-            tItem = self._tree.get(tHandle)
-            if isinstance(tItem, NWItem):
-                yield tItem
-        return
-
-    ##
-    #  Internal Functions
-    ##
-
-    def _setTreeChanged(self, state: bool) -> None:
-        """Set the changed flag to state, and if being set to True,
-        propagate that state change to the parent NWProject class.
+    def _addItems(self, items: dict[str, NWItem]) -> dict[str, NWItem]:
+        """Add a dictionary of items to the project tree. Returns a new
+        dictionary of items that could not be added yet, but can be.
         """
-        self._changed = state
-        if state:
-            self._project.setProjectChanged(True)
-        return
+        remains: dict[str, NWItem] = {}
+        for handle, item in items.items():
+            if pHandle := item.itemParent:
+                if parent := self._nodes.get(pHandle):
+                    node = ProjectNode(item)
+                    parent.addChild(node)
+                    parent.updateCount()
+                    self._items[handle] = item
+                    self._nodes[handle] = node
+                elif pHandle in items:
+                    remains[handle] = item
+                    logger.warning("Item '%s' found before its parent", handle)
+            elif item.isRootType():
+                node = ProjectNode(item)
+                self._model.root.addChild(node)
+                self._model.root.updateCount()
+                self._items[handle] = item
+                self._nodes[handle] = node
+        return remains
 
     def _makeHandle(self) -> str:
         """Generate a unique item handle. In the event that the key
@@ -515,7 +496,7 @@ class NWTree:
         """
         logger.debug("Generating new handle")
         handle = f"{random.getrandbits(52):013x}"
-        if handle in self._tree:
+        if handle in self._items:
             logger.warning("Duplicate handle encountered! Retrying ...")
             handle = self._makeHandle()