Version

Working with Snapshots (xamSyntaxEditor)

Topic Overview

Purpose

This topic describes features provided by the TextDocumentSnapshot and the TextDocumentSnapshotScanner classes.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

In this topic, you will find information to help you better understand the xamSyntaxEditor’s functions.

This topic covers the text editing capabilities of the xamSyntaxEditor control from both the developer and user’s perspective.

Snapshots

Overview

Snapshots are immutable objects that represent the entire state of a document at a specific point in time. Snapshots are created whenever changes are made to the document’s content (for example, when typing in the xamSyntaxEditor’s editing area). The TextDocument’s CurrentSnapshot property contains the most recent snapshot, which returns an object of type TextDocumentSnapshot.

The snapshots are thread-safe, so they can be used for longer running operations, without having to worry about dealing with any changes made to the document during the process.

Terms:

Term Description

Offset

This is a zero-based index of a character in a document starting from the beginning.

Text Location

This is a structure, which contains zero-based line and character offset that uniquely identify a character location in a document.

Token

Produced during the lexical analysis of the document tokens represent sections of the text (for example, keyword, punctuations characters, whitespace, etc…​). By concatenating the text of all of its tokens, you can reconstruct the entire text of a document.

Word

Unlike the token, the Word structure can only represent a word (not punctuation characters, whitespace or delimiters).

Properties summary

The following table lists the available read-only properties for obtaining document information:

Property Description

The length of a snapshot measured in characters.

The number of lines contained in the snapshot.

The number of tokens contained in the snapshot.

Methods summary

The following table lists the public methods exposed by the snapshot.

Method Description

Returns part or the entire content of the snapshot.

Returns either a forward or a backward token enumerator with an optional filter callback.

Returns either a forward or a backward line enumerator.

Obtains a line by it zero-based index.

Obtains a line from a character offset within the document.

Obtains a line index from a character offset within the document.

Obtains a location from an offset.

Obtains an offset from a location.

Obtains a token from an offset.

Obtains a word from an offset.

Note
Note

You can use the indexer of the TextDocumentSnapshot class to access the characters at a zero-based offset.

Note
Note

You can also use the Find and FindAll methods of the snapshots to find single or multiple occurrences of a text by using search criteria similar to the one explained in the Find / Replace topic.

Snapshot Scanner

Overview

The snapshot’s CreateScanner method creates a TextDocumentSnapshotScanner class targeting a specific instance of a TextDocumentSnaphot. It is useful for efficiently scanning through the snapshot’s lines, tokens and words.

Note
Note

Even though the snapshot that it targets is thread-safe, the scanner is not. Create the scanner on the same thread that uses it. Creating a scanner on one thread and trying to access the properties and methods of a scanner created on another thread raises an InvalidOperationException.

When first creating the scanner its current scan position initializes to zero. The scan position can be explicitly set (via the CurrentOffset property) or manipulated by calling any of the following “seek” methods. There are also several “peek” methods, which are useful in obtain Tokens or Words surrounding the current scan position, without changing the current scan position.

Properties summary

You can use the following properties to obtain different information regarding the current scan position:

Property Description

Returns or sets the current offset from the beginning of the document.

Returns the character at the CurrentOffset.

Returns the line containing the CurrentOffset.

Returns the token containing the CurrentOffset.

Note
Note

Setting the CurrentOffset to the snapshot’s length returns the end-of-stream (EOS) token.

Returns either the word containing the CurrentOffset or null in the event that the CurrentOffset is not within a word.

Methods summary

You can use the following methods to move back and forth the current scan position:

Method Description

Move the scan position to the end of the snapshot content.

Move the scan position to a specific line in the snapshot content.

Move the scan position to the start of the snapshot content.

Move the scan position to the next/previous start/end token.

Move the scan position to the next/previous start/end word.

You can use the following methods to peek the surrounding documents parts without moving the current scan position:

Method Description

Obtain the next token.

Obtain the next word.

Obtain the previous token.

Obtain the previous word.

Related Topics

The following topics provide additional information related to this topic.

Topic Purpose

This topic provides an overview of the xamSyntaxEditor control’s error reporting functionality and shows how to configure and work with the control.

This topic explains the TextDocument’s Find, Replace and ReplaceAll operations.