Completor Class

Wraps and applies multiple changes to a text view as a single operation.

This API is not CLS-compliant. The CLS-compliant alternative is [None].

Inheritance Hierarchy

System.Object
  Microsoft.VisualStudio.Package.Completor

Namespace:  Microsoft.VisualStudio.Package
Assemblies:   Microsoft.VisualStudio.Package.LanguageService.11.0 (in Microsoft.VisualStudio.Package.LanguageService.11.0.dll)
  Microsoft.VisualStudio.Package.LanguageService.10.0 (in Microsoft.VisualStudio.Package.LanguageService.10.0.dll)
  Microsoft.VisualStudio.Package.LanguageService.9.0 (in Microsoft.VisualStudio.Package.LanguageService.9.0.dll)
  Microsoft.VisualStudio.Package.LanguageService (in Microsoft.VisualStudio.Package.LanguageService.dll)

Syntax

'Declaration
<CLSCompliantAttribute(False)> _
Public Class Completor _
    Implements IDisposable
[CLSCompliantAttribute(false)]
public class Completor : IDisposable
[CLSCompliantAttribute(false)]
public ref class Completor : IDisposable
[<CLSCompliantAttribute(false)>]
type Completor =  
    class 
        interface IDisposable 
    end
public class Completor implements IDisposable

The Completor type exposes the following members.

Constructors

  Name Description
Public method Completor Initializes a new instance of the Completor class.

Top

Properties

  Name Description
Public property AtEndOfLine Determines if the internal caret position is at the end of the current line.
Public property IsExpansionActive Determines if a code snippet is being edited.

Top

Methods

  Name Description
Public method Apply Applies all changes made through the Completor object.
Public method Dispose Cleans up any allocations made just before the object is destroyed.
Public method Equals Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected method Finalize Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public method GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public method GetType Gets the Type of the current instance. (Inherited from Object.)
Protected method MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public method RefreshLine Obtains the current line of text from the Source object.
Public method ToString Returns a string that represents the current object. (Inherited from Object.)
Public method TypeBackspace Performs the specified number of backspaces on the line being edited and updates the internal caret position.
Public method TypeChar Inserts the specified character and updates the internal caret position.
Public method TypeChars Inserts the specified string of characters and updates internal caret position.
Public method TypeDelete Performs the specified number of delete operations on the line being edited.
Public method TypeLeft Moves the internal caret position the specified number of positions to the left.
Public method TypeRight Moves the internal caret position the specified number of positions to the right.

Top

Remarks

This helper class is used to manage changes to the current line due to completion actions; that is, actions that result in the automatic insertion of text.

This class gathers characters and cursor actions and applies them to the current caret position as a single compound action. This allows all of the characters to be undone in a single operation. This class supports inserting any text character, moving the caret left and right as well as Delete and Backspace (each of these is applied by calling a different method on this class).

In addition, all inserted characters and cursor movements are added to a macro recorder if such a recorder is turned on.

This class maintains an internal buffer that contains all the characters to be inserted. This buffer is treated as a stream of characters; any character can be inserted into this buffer, even control characters such as newline. Only after the characters are inserted are any control characters handled. For example, if you use this class to insert the string "Hello\nThere" into an empty source file, the source file will contain two lines. However, the caret is positioned six characters after the word "Hello" on the first line (five letters in "There" and one newline character for a total of six characters). This class does not understand multiple lines in this situation; all it sees is a stream of characters to insert.

Notes to Implementers

This class is self-contained and there is typically no reason to derive from this class.

Notes to Callers

Instantiate and use this class when you need to wrap a set of character-oriented insertions at the current caret position.

Note

Since this class is typically used in a completion operation, the commit or completion character may have already been added to the line before this class applies any changes. If you need to replace the commit character, you need to call the TypeBackspace method as the first operation to delete the commit character from the line.

Examples

This example shows a simple completion operation using the Completor class in a derived version of the Declarations class. This operation wraps in quotes whatever text was committed.

namespace MyLanguagePackage
{
    class MyDeclarations : Declarations
    {
        LanguageService m_languageService;

        MyDeclarations(LanguageService service) : base()
        {
            m_languageService = service;
        }

        public override char OnAutoComplete(IVsTextView view,
                                            string committedText,
                                            char commitChar,
                                            int index)
        {
            if (committedText != null && view != null && m_languageService != null)
            {
                bool fHasCommitChar = commitChar != '\0' && commitChar != '\r';
                // If user completes word with single quotes, use single quotes;
                // Otherwise, always use double quotes.
                char quoteChar = (commitChar == '\'') ? '\'' : '"';

                Completor completor = new Completor(m_languageService,
                                                    view,
                                                    "Add Quotes");
                // All edits are applied when the completor object is disposed off.
                using (completor)
                {
                    int delta = fHasCommitChar ? 1 : 0;
                    completor.TypeLeft(committedText.Length + delta);
                    completor.TypeChar(quoteChar);
                    completor.TypeRight(committedText.Length + delta);
                    if (commitChar != quoteChar)
                    {
                        completor.TypeChar(quoteChar);
                    }
                }
            }

            return '\0';    // No further operations needed
        }
    }
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

Microsoft.VisualStudio.Package Namespace