Classification is the process that determines the attributes and structure of Nodes
in the Tree
.
Overview:
-
Changes are made in the Tree.
-
The changed parts of the tree are marked invalid.
-
A "worker" is scheduled to reclassify those invalid regions making sure that all nodes have correct type, structure and other attributes.
Notes
This process is incremental. You don't need to wait for your entire document to get parsed and classified before it's displayed and you can start editing it. It's also efficient at handling changes, if you edit some text only that text and a few lines surrounding it need to be reclassified, not the entire Tree.
Incremental classification leads to some complexities. Nodes might not be classified as you would expect. For example you might have a node with text content # my heading
, but that node may have the type body
instead of heading
. This can happen when the classification process hasn't yet caught up with changes in the Tree.
A common case where this can be a problem is when you perform a node path query immediately after a document is loaded. You might not get the matches that you expect, because the classification process hasn't yet set the correct Node types and structures. There are two ways to deal with this problem:
-
The best way is to listen for TreeChangedEvents and re-run your query after each change event. Anytime the tree changes, including the classification system changing node types and structure (not necessarily only when text is inserted) TreeChangedEvents get fired. So as long as you listen for TreeChangedEvents you will get notified as the classification process incrementally proceeds.
-
If it's not possible to structure your code this way another alternative is to call
tree.ensureClassified()
before you run your query. This forces the classification process to run, but defeats its incremental nature. So if you call it on a large document just after startup, it will cause the entire load process to pause while waiting for classification to finish.The
ensureClassified
method takes optionalfromNode
andtoNode
parameters which can be used to just force classification of a certain range of nodes. For instance on each display cycle FoldingText callsensureClassified
on the nodes in the visible viewport to make sure that the visual display is always up-to-date.