DocumentProperties Class

Provides support for document-specific properties associated with a language service.

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

Inheritance Hierarchy

Object
  Microsoft.VisualStudio.Shell.LocalizableProperties
    Microsoft.VisualStudio.Package.DocumentProperties

Namespace:  Microsoft.VisualStudio.Package
Assemblies:   Microsoft.VisualStudio.Package.LanguageService.10.0 (in Microsoft.VisualStudio.Package.LanguageService.10.0.dll)
  Microsoft.VisualStudio.Package.LanguageService.12.0 (in Microsoft.VisualStudio.Package.LanguageService.12.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)
  Microsoft.VisualStudio.Package.LanguageService.11.0 (in Microsoft.VisualStudio.Package.LanguageService.11.0.dll)

Syntax

'Declaration
<CLSCompliantAttribute(False)> _
Public MustInherit Class DocumentProperties _
    Inherits LocalizableProperties _
    Implements ISelectionContainer, IDisposable
[CLSCompliantAttribute(false)]
public abstract class DocumentProperties : LocalizableProperties, 
    ISelectionContainer, IDisposable
[CLSCompliantAttribute(false)]
public ref class DocumentProperties abstract : public LocalizableProperties, 
    ISelectionContainer, IDisposable
[<AbstractClass>]
[<CLSCompliantAttribute(false)>]
type DocumentProperties =  
    class 
        inherit LocalizableProperties 
        interface ISelectionContainer 
        interface IDisposable 
    end
public abstract class DocumentProperties extends LocalizableProperties implements ISelectionContainer, IDisposable

The DocumentProperties type exposes the following members.

Constructors

  Name Description
Protected method DocumentProperties Initializes a new instance of the DocumentProperties class.

Top

Properties

  Name Description
Public property Visible Determines if the DocumentProperties object is visible in the Properties window.

Top

Methods

  Name Description
Public method Close Closes down the DocumentProperties object so that its properties are no longer visible in the Properties window.
Public method CountObjects Returns the number of objects managed by this DocumentProperties object.
Public method CreateDesignPropertyDescriptor Returns a DesignPropertyDescriptor wrapper on the given property descriptor. (Inherited from LocalizableProperties.)
Public method Dispose() Cleans up the object.
Protected method Dispose(Boolean) Cleans up the object and its resources.
Public method Equals Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected method Finalize Does final cleanup of the object. (Overrides Object.Finalize.)
Public method GetAttributes Gets a collection of attributes for this component. (Inherited from LocalizableProperties.)
Public method GetClassName Returns the class name of this object. (Inherited from LocalizableProperties.)
Public method GetCodeWindowManager Retrieves the code window manager associated with this DocumentProperties object.
Public method GetComponentName Returns the name of this object. (Inherited from LocalizableProperties.)
Public method GetConverter Returns a type converter for this object. (Inherited from LocalizableProperties.)
Public method GetDefaultEvent Returns the default event for this object. (Inherited from LocalizableProperties.)
Public method GetDefaultProperty Gets the default property for a component. (Inherited from LocalizableProperties.)
Public method GetEditor Retrieves the editor for this object. (Inherited from LocalizableProperties.)
Public method GetEvents() Gets the collection of events for a specified component. (Inherited from LocalizableProperties.)
Public method GetEvents(array<Attribute[]) Gets the collection of events for a specified component using a specified array of attributes as a filter. (Inherited from LocalizableProperties.)
Public method GetHashCode Serves as the default hash function. (Inherited from Object.)
Public method GetObjects Returns a list of objects managed by this DocumentProperties object.
Public method GetProperties() Gets the collection of properties. (Inherited from LocalizableProperties.)
Public method GetProperties(array<Attribute[]) Returns the properties for selected object using the attribute array as a filter. (Inherited from LocalizableProperties.)
Public method GetPropertyOwner Returns the brows-able object. (Inherited from LocalizableProperties.)
Public method GetSource Returns a Source object associated with this DocumentProperties 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 Refresh Updates the Properties window with the latest property values.
Public method SelectObjects Called to manage the selection of multiple objects in the Properties window.
Public method ToString Returns a string that represents the current object. (Inherited from Object.)

Top

Remarks

Document properties appear in the Properties window when that document is opened in Visual Studio. Normally, source file documents do not have properties and so the Properties window is empty. However, a language service can supply properties that can be associated with any document type supported by that language service. For example, if your language service supports embedding an encoding scheme in the source file, this could be displayed as a document property. When the property is changed, the source file is updated.

It is up to the language service to determine how document-specific properties are persisted or saved. Typically, the properties are loaded from and saved to the source file itself. The properties can be obtained when the document is parsed. When a property is updated, the value can be inserted immediately into the source file so when the source file is saved, the property is saved with it.

Notes to Implementers

If you need to support document-specific properties in your language service, you need to derive a class from the DocumentProperties class and add public properties representing the properties that can be viewed and changed. See the example in this topic to see how this is typically implemented. You must override the CreateDocumentProperties method in the LanguageService class to return an instance of your DocumentProperties object.

Notes to Callers

Visual Studio manages the Properties window. The default implementation of the CreateDocumentProperties method returns a DocumentProperties object that has no viewable properties so the Properties window shows nothing. If you implement your own version of the DocumentProperties class with public properties that have the correct attributes, those properties automatically appear in the Properties window. Changes made to a property in the Properties window affect your DocumentProperties object immediately. See the example to see which attributes need to be applied to a property.

Examples

The following example shows a DocumentProperties object with one visible property.

using Microsoft.VisualStudio.Package;
using System.ComponentModel;

namespace MyLanguagePackage
{
    class MyDocumentProperties : DocumentProperties
    {
        private string m_encoding;

        public MyDocumentProperties(CodeWindowManager mgr) : base(mgr)
        {
        }

        [DisplayNameAttribute("Encoding")]
        [CategoryAttribute("General")]
        [DescriptionAttribute("Changes encoding scheme")]
        public string Encoding
        {
            get
            {
                return m_encoding;
            }
            set
            {
                m_encoding = value;
                // Write value to source text.
                // This can be done through a custom method
                // (called SetProperyValue in this example) on your
                // language service class like this:
                Source src = this.GetSource();
                if (src != null)
                {
                    MyLanguageService service = src.LanguageService as MyLanguageService;
                    if (service != null)
                    {
                        service.SetPropertyValue(src, "Encoding", m_encoding);
                    }
                }
            }
        }
    }
}

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