How to: Attach views to document data

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

If you have a new document view, you may be able to attach it to an existing document data object.

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 Visual Studio 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 Visual Studio 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 Support multiple document views. If not, then it should display an appropriate error message.

See also