Custom Document Properties (Managed Package Framework)
Document properties are displayed when the user selects Property Window from the View menu. Typically, programming languages do not have any properties associated with individual source files so the Property Window is empty. However, some languages do support source file level properties. For example, XML supports document properties that affect the encoding, schema, and stylesheet.
Discussion
If your language needs custom document properties, you must derive a class from the DocumentProperties class and implement the necessary C#/Visual Basic properties on your derived class.
In addition, document properties are typically stored in the source file itself. This requires the language service to parse the property information from the source file to display in the Properties window and to update the source file when a change is made to the document properties in the Properties window.
Customizing the DocumentProperties Class
To support custom document properties, you must derive a class from the DocumentProperties class and implement public properties on your class. You can add as many properties as needed and you supply user attributes to organize them in the Properties window display. If a property has only a get operator, it is shown as read-only in the Properties window. If a property has both get and set operators, the property can be both viewed and updated in the Properties window.
Example
Here is an example class derived from DocumentProperties, showing two properties for a filename and a description. When a property is updated, a custom method on the LanguageService class is called to put the property back into the source file. See "Instantiating the Custom DocumentProperties Class" section in this topic to see how to use this class.
using System.ComponentModel;
using Microsoft.VisualStudio.Package;
namespace MyLanguagePackage
{
class MyDocumentProperties : DocumentProperties
{
private string m_filename;
private string m_description;
public MyDocumentProperties(CodeWindowManager mgr)
: base(mgr)
{
}
// Helper function to initialize this property without
// going through the FileName property (which does a lot
// more than what we need when the filename is set).
public void SetFileName(string filename)
{
m_filename = filename;
}
// Helper function to initialize this property without
// going through the Description property (which does a lot
// more than what we need when the description is set).
public void SetDescription(string description)
{
m_description = description;
}
////////////////////////////////////////////////////////////
// The document properties
[CategoryAttribute("General")]
[DescriptionAttribute("Name of the file")]
[DisplayNameAttribute("Filename")]
public string FileName
{
get { return m_filename; }
set
{
if (value != m_filename)
{
m_filename = value;
SetPropertyValue("Filename", m_filename);
}
}
}
[CategoryAttribute("General")]
[DescriptionAttribute("Description of the file")]
[DisplayNameAttribute("Description")]
public string Description
{
get { return m_description; }
set
{
if (value != m_description)
{
m_description = value;
SetPropertyValue("Description", m_description);
}
}
}
///////////////////////////////////////////////////////////
// Private methods.
private void SetPropertyValue(string propertyName, string propertyValue)
{
Source src = this.GetSource();
if (src != null)
{
MyLanguageService service = src.LanguageService as MyLanguageService;
if (service != null)
{
// Set the property in to the source file.
service.SetPropertyValue(src, propertyName, propertyValue);
}
}
}
}
}
Instantiating the Custom DocumentProperties class
To instantiate your custom document properties class, you must override the CreateDocumentProperties method in your version of the LanguageService class to return a single instance of your DocumentProperties class. There should be only one instance of your DocumentProperties class in your language service.
Example
using System.ComponentModel;
using Microsoft.VisualStudio.Package;
namespace MyLanguagePackage
{
class MyLanguageService : LanguageService
{
private MyDocumentProperties m_documentProperties;
public override DocumentProperties CreateDocumentProperties(CodeWindowManager mgr)
{
if (m_documentProperties == null)
{
m_documentProperties = new MyDocumentProperties(mgr);
}
return m_documentProperties;
}
}
}
Properties in the Source File
Since document properties are usually very specific to the source file being viewed, the property values are typically stored in the source file itself. This requires support from the language parser or scanner to parse out these properties. In XML, for example, the ParseSource method breaks the entire XML document into a tree structure and the properties that are shown in the Properties window are then easily obtained from the root node. Updating the properties is also straightforward: the values in the root node are set based on the Properties window values and the root node is updated in the view to reflect the new values.
Example
This somewhat contrived example stores the properties "Filename" and "Description" in the first two lines of the source file, embedded in a special comment header. In the final source file, these properties appear as
//!Filename = file.myext
//!Description = A sample file
The characters "//!" denote the start of a property and are followed by the name of the property, an equals sign, and the value of the property.
This example shows the two methods needed to get and set the document properties from the first two lines of the source file as well as how the properties are updated if the user modifies the source file directly. The SetPropertyValue method in the example shown here is the same one called from the MyDocumentProperties class as shown in the "Customizing the DocumentProperties class" section.
This example uses the scanner to determine the type of tokens in the first two lines. This example is for illustrative purposes only. A more typical approach to this situation is to parse the source file into what is called a parse tree where each node of the tree contains information about a particular token. The root node would contain the document properties.
using System.ComponentModel;
using Microsoft.VisualStudio.Package;
namespace MyLanguagePackage
{
// TokenType.Comment is the last item in that enumeration.
public enum MyTokenTypes
{
DocPropertyLine = TokenType.Comment + 1,
DocPropertyName,
DocPropertyAssign,
DocPropertyValue
}
class MyLanguageService : LanguageService
{
// Search this many lines from the beginning for properties.
private static int maxLinesToSearch = 2;
private MyDocumentProperties m_documentProperties;
// Called whenever a full parsing operation has completed.
public override void OnParseComplete(ParseRequest req)
{
if (m_documentProperties != null)
{
Source src = GetSource(req.View);
if (src != null)
{
string value = GetPropertyValue(src, "Filename");
m_documentProperties.SetFileName(value);
value = GetPropertyValue(src, "Description");
m_documentProperties.SetDescription(value);
// Update the Properties Window.
m_documentProperties.Refresh();
}
}
}
// Retrieves the specified property value from the given source.
public string GetPropertyValue(Source src, string propertyName)
{
string propertyValue = "";
if (src != null)
{
IVsTextColorState colorState = src.ColorState;
if (colorState != null)
{
string line;
TokenInfo[] lineInfo = null;
int i;
for (i = 0; i < maxLinesToSearch; i++)
{
line = src.GetLine(i);
lineInfo = src.GetColorizer().GetLineInfo(
src.GetTextLines(),
i,
colorState);
if (lineInfo == null)
{
continue;
}
if (lineInfo[0].Type != (TokenType)MyTokenTypes.DocPropertyLine)
{
// Not a property line.
continue;
}
TokenInfo valueInfo = new TokenInfo();
int tokenIndex = -1;
for (tokenIndex = 0;
tokenIndex < lineInfo.Length;
tokenIndex++)
{
if (lineInfo[tokenIndex].Type == (TokenType)MyTokenTypes.DocPropertyName)
{
break;
}
}
if (tokenIndex >= lineInfo.Length)
{
// No property name on the line.
continue;
}
string name = src.GetText(i,
lineInfo[tokenIndex].StartIndex,
i,
lineInfo[tokenIndex].EndIndex + 1);
if (name != null)
{
if (String.Compare(name, propertyName, true) == 0)
{
for ( ;
tokenIndex < lineInfo.Length;
tokenIndex++)
{
if (lineInfo[tokenIndex].Type == (TokenType)MyTokenTypes.DocPropertyValue)
{
break;
}
}
if (tokenIndex < lineInfo.Length)
{
propertyValue = src.GetText(i,
lineInfo[tokenIndex].StartIndex,
i,
lineInfo[tokenIndex].EndIndex + 1);
}
break;
}
}
}
}
}
return propertyValue;
}
// Sets the specified property into the given source file.
// Called from the MyDocumentProperties class.
public void SetPropertyValue(Source src, string propertyName, string propertyValue)
{
string newLine;
if (propertyName == null || propertyName == "")
{
// No property name, so nothing to do
return;
}
if (propertyValue == null)
{
propertyValue = "";
}
// This is the line to be inserted.
newLine = String.Format("//!{0} = {1}", propertyName, propertyValue);
// First, find the line on which the property belongs.
// If line is found, replace it.
// Otherwise, insert the line at the beginning of the file.
if (src != null)
{
IVsTextColorState colorState = src.ColorState;
if (colorState != null)
{
int lineNumber = -1;
string line;
TokenInfo[] lineInfo = null;
int i;
for (i = 0; i < maxLinesToSearch; i++)
{
line = src.GetLine(i);
lineInfo = src.GetColorizer().GetLineInfo(
src.GetTextLines(),
i,
colorState);
if (lineInfo == null)
{
continue;
}
if (lineInfo[0].Type != (TokenType)MyTokenTypes.DocPropertyLine)
{
// Not a property line
continue;
}
TokenInfo valueInfo = new TokenInfo();
int tokenIndex = -1;
for (tokenIndex = 0;
tokenIndex < lineInfo.Length;
tokenIndex++)
{
if (lineInfo[tokenIndex].Type == (TokenType)MyTokenTypes.DocPropertyName)
{
break;
}
}
if (tokenIndex >= lineInfo.Length)
{
// No property name on the line.
continue;
}
string name = src.GetText(i,
lineInfo[tokenIndex].StartIndex,
i,
lineInfo[tokenIndex].EndIndex + 1);
if (name != null)
{
if (String.Compare(name, propertyName, true) == 0)
{
lineNumber = i;
break;
}
}
}
// Set up an undo context that also handles the insert/replace.
EditArray editArray = new EditArray(src,
true,
"Update Property");
if (editArray != null)
{
TextSpan span = new TextSpan();
if (lineNumber != -1)
{
// Replace line.
int lineLength = 0;
src.GetTextLines().GetLengthOfLine(lineNumber,
out lineLength);
span.iStartLine = lineNumber;
span.iStartIndex = 0;
span.iEndLine = lineNumber;
span.iEndIndex = lineLength;
}
else
{
// Insert new line.
span.iStartLine = 0;
span.iStartIndex = 0;
span.iEndLine = 0;
span.iEndIndex = 0;
newLine += "\n";
}
editArray.Add(new EditSpan(span, newLine));
editArray.ApplyEdits();
}
}
}
}
}
}