We just published WPF Studio 2009.2 build 514 and some of its new features are the culmination of over a month of work on the SyntaxEditor product. We’ve mentioned some of the new feature areas in our previous blog posts, but here is the list again:
- Collapsed text
- Intra-text spacers and intra-text adornment managers
- Code outlining
Build 514 includes 7 new samples specifically related to the features mentioned above. That brings our grand total to over 60 samples just for the SyntaxEditor product!
Our last blog post focused on a QuickStart included with build 514 that showed how to implement code reviewing right within the editor, via the use of intra-text adornments. Today I’d like to discuss code outlining.
What is code outlining?
Code outlining, also known as code folding, is the ability for an outlining node hierarchy to be constructed based on the contents of the document. The outlining node hierarchy is rendered visually within the new outlining margin as seen in the screenshot below:
A “+” or “-“ box in the margin shows where nodes start. Clicking those boxes toggles the collapsed state of the node. When a node is collapsed, its text is hidden and boxed-in collapsed text adornment is rendered in place of the hidden text. In the screenshot above, the boxed-in “/**/” is a collapsed multi-line comment node.
When a node is expanded, a vertical line in the outlining margin extends downward to show the lines that are encompassed by the node. A small horizontal offshoot line indicates when the node ends. You can double-click on the vertical line to collapse the node.
A neat feature added to Visual Studio 2010 is collapsed region highlights that render when moving the mouse over nodes in the outlining margin. This feature is now in SyntaxEditor as well. In the screenshot above, the mouse is over the outlining node that covers lines 7-14. Thus a highlight visually shows the end user the line range that is covered by the node. This is especially useful when there are multiple nested nodes since the highlight will show innermost node that the mouse is over.
An optional built-in service is provided that will show quick info tips when you hover over collapsed text adornments. By double-clicking a collapsed text adornment, the related collapsed node expands.
Automatic and manual outlining modes
There are two main outlining modes that SyntaxEditor can be in: automatic and manual.
In automatic mode, a language defines a service that is capable of telling the SyntaxEditor outlining manager where nodes are within the document. We include two built-in base classes to make it easy to add this functionality. One simply generates nodes based on tokens, such as start/end curly brace tokens and executes in the main thread. This is a good way to get started and works well for small to medium size documents. The second way is a little more advanced and is where your outlining data is constructed in your language’s parser. A lot of times you’ll want to use an AST (abstract syntax tree) to build the outlining data in this case. But since the parser is executed in a worker thread, there is no real performance impact to supporting outlining with this way, even with relatively large documents.
Manual mode on the other hand leaves it up to the end user to define the outlining nodes. The end user can make a selection and choose to collapse it. They can also choose to remove existing nodes.
Built-in commands
We include built-in edit actions and WPF commands that tie directly to the common outlining functionality you’ll find in products like Visual Studio, such as:
- Collapse to Definitions
- Hide Selection
- Toggle Outlining Expansion
- Toggle All Outlining
- Stop Outlining
- Stop Hiding Current
- Start Automatic Outlining
To allow your end users to access this functionality just wire up the commands we provide to your WPF buttons or menu items.
Outlining nodes and definitions
The entire outlining node hierarchy can be navigated through programmatically via the root node in the document’s outlining manager. Each node tells you whether it is collapsed, its text snapshot range (which gives access to text content), and its node definition.
The node definition is an object the provides some characteristics about the node. A node definition can be shared by multiple nodes. The node definition has these capabilities:
- Provide default content to display when the node is collapsed (instead of the standard “…” text)
- Whether to collapse the node by default when the document is loaded, such as for #region nodes
- Whether the node is an implementation, which when true will collapse the node when Collapse to Definitions is executed
- Whether the node is collapsible and is rendered in the UI
We even allow collapsed text to be easily customized based on the nodes content.
This screenshot shows how a collapsed multi-line comment node did an examination of its contained text and rendered the first line of text in the collapsed text adornment.
Summary
All of this functionality, along with collapsed regions independent of outlining, and intra-text adornments, is now available in the build 514 that was just released. Head over to our main site and download an evaluation if you are not already a customer. If you are a WPF Studio customer you can grab build 514 from your account.