How to: Attach Views to Document Data Objects

  • Article

If you have a new document view (or simply, view), you may be able to attach it to an existing document data object. For an overview of the process, see Robust Programming below.

For an example implementation of this, see the Microsoft.Samples.VisualStudio.SynchronousXmlDesigner namespace in the EditorFactory.cs file, located in the Visual C# version of the Example.XMLDesigner sample. By default, this sample is located in <Visual Studio SDK installation path>\VisualStudioIntegration\Samples\IDE\CSharp\Example.XmlDesigner\.

To determine if you can attach a view to an existing document data object

  1. Implement CreateEditorInstance.

  2. In your implementation of IVsEditorFactory::CreateEditorInstance, call QueryInterface on the existing document data object when the IDE calls your CreateEditorInstance implementation.

    Calling QueryInterface enables you to examine the existing document data object, which is specified in the punkDocDataExisting parameter.

    The exact interfaces you must query, however, depends upon the editor that is opening the document, as outlined in step 4.

  3. If you do not find the appropriate interfaces on the existing document data object, then return an error code to your editor indicating that the document data object is incompatible with your editor.

    In the IDE's implementation of OpenStandardEditor, a message box notifies you that the document is open in another editor and asks if you want to close it.

  4. If you close this document, then the IDE calls your editor factory for a second time. On this call, the DocDataExisting parameter is equal to NULL. Your editor factory implementation can then open the document data object in your own editor.

    Note

    To determine whether you can work with an existing document data object, you can also use private knowledge of the interface implementation by casting a pointer to the actual Visual C++ class of your private implementation. For example, all standard editors implement IVsPersistFileFormat, which inherits from IPersist. Thus, you can call QueryInterface for GetClassID, and if the class ID on the existing document data object matches your implementation's class ID, then you can work with the document data object.

Robust Programming

When the IDE calls your implementation of the CreateEditorInstance method, it passes back a pointer to the existing document data object in the punkDocDataExisting parameter, if one exists. Examine the document data object returned in punkDocDataExisting to determine if the document data object is appropriate for your editor as outlined in the note in step 4 of the procedure in this topic. If it is appropriate, then your editor factory should provide a second view for the data as outlined in Supporting Multiple Document Views. If not, then it should display an appropriate error message.

See Also

Concepts

Supporting Multiple Document Views

Document Data and Document View Objects

Other Resources

Editors