Documents

Apr 19, 2024
6 minutes to read

Documents are content wrappers that feature different appearance and behavior depending on their parent View.

Parent Classes

Each View manages Documents of different classes, which all derive from the base BaseDocument class.

Document (the DevExpress.XtraBars.Docking2010.Views.NativeMdi namespace)
Document (the DevExpress.XtraBars.Docking2010.Views.Tabbed namespace)
Document (the DevExpress.XtraBars.Docking2010.Views.Widget namespace)
Document (the DevExpress.XtraBars.Docking2010.Views.WindowsUI namespace)

Content Types

Documents can wrap the following content:

UserControls and XtraUserControls;
standard and DevExpress forms when you use NativeMdiView or TabbedView in MDI mode (set the DocumentManager.MdiParent property to enable MDI mode);
any standard, DevExpress, or third-party visual control;
dock panels.

Add and Populate Documents

There are several ways to add a Document to a View.

Invoke the Designer dialog, switch to its Documents tab and click Add New Document to create an empty Document:
Invoke the Designer dialog, switch to its “Documents” tab and click “Populate” (see the figure below). The DocumentManager will scan your project and create a Document for each UserControl/XtraUserControl found. Before the application form is displayed, call the BaseView.AddDocument for each Document created. Use instances of your User Controls to pass to these methods as parameters. See the BaseDocument.ControlName and/or BaseDocument.ControlTypeName properties for details.
Call the BaseView.AddDocument method overload that takes a control as a parameter.
Call the IBaseViewController.AddDocument method of a controller, associated with the View. To retrieve this controller, use the BaseView.Controller property.
Create a new instance of a Document class, then add it to the BaseView.Documents collection. To supply this Document with content, set its BaseDocument.ControlName and BaseDocument.ControlTypeName properties or handle the BaseView.QueryControl event.

Important

The Document Manager identifies its child documents by the names of controls hosted within these documents. Thus, it is recommended that you set unique names for these controls. Failure to comply with this recommendation results in an exception for certain scenarios (e.g., saving and restoring a View layout).
Do not modify the BaseView.Documents collection to add and\or remove Documents to\from this collection. Instead, use approaches described in this article: call the View’s or the related Controller’s methods.

Pre-Customize Documents

Most Document Manager Views provide the DocumentSettings class that allows you to customize the document before it is created and shown. To do so, use the static Attach method to attach an instance of the DocumentSettings class to document content.

The following examples adds a document with the specified caption, float location, and size.

C#
VB.NET

csharp

Form floatForm = new Form();
DevExpress.XtraBars.Docking2010.Views.Tabbed.DocumentSettings.Attach(floatForm, new DocumentSettings() {
    Caption = "Float Tab",
    FloatLocation = new System.Drawing.Point(100, 100),
    FloatSize = new System.Drawing.Size(600, 400)
});
tabbedView1.AddFloatDocument(floatForm);

Dim floatForm As New Form()
DevExpress.XtraBars.Docking2010.Views.Tabbed.DocumentSettings.Attach(floatForm, New DocumentSettings() With {
    .Caption = "Float Tab",
    .FloatLocation = New System.Drawing.Point(100, 100),
    .FloatSize = New System.Drawing.Size(600, 400)})
tabbedView1.AddFloatDocument(floatForm)

Create and Delete Documents in Code

Use the following methods to create, delete, select documents:

The following example demonstrates how to create and remove (delete) tabbed documents in code:

C#
VB.NET

csharp

using DevExpress.XtraBars;
using DevExpress.XtraEditors;
using DevExpress.XtraBars.Ribbon;

namespace DXApplication {
    public partial class Form1 : RibbonForm {
        public Form1() {
            InitializeComponent();
            this.addDocument.ItemClick += new ItemClickEventHandler(this.addDocument_ItemClick);
            this.removeDocument.ItemClick += new ItemClickEventHandler(this.removeDocument_ItemClick);
            this.clearAll.ItemClick += new ItemClickEventHandler(this.clearAll_ItemClick);
        }
        int i = 0;
        private void addDocument_ItemClick(object sender, ItemClickEventArgs e) {
            // Creates a document.
            documentManager1.View.AddDocument(new XtraUserControl(), string.Format("New Document {0}", i++));
        }
        private void removeDocument_ItemClick(object sender, ItemClickEventArgs e) {
            // Closes the selected document.
            tabbedView1.Controller.Close(tabbedView1.DocumentGroups[0].SelectedDocument);
        }
        private void clearAll_ItemClick(object sender, ItemClickEventArgs e) {
            tabbedView1.Controller.CloseAll();
        }
    }
}

Imports DevExpress.XtraBars
Imports DevExpress.XtraEditors
Imports DevExpress.XtraBars.Ribbon

Namespace DXApplication
    Partial Public Class Form1
        Inherits RibbonForm

        Public Sub New()
            InitializeComponent()
            AddHandler addDocument.ItemClick, AddressOf addDocument_ItemClick
            AddHandler removeDocument.ItemClick, AddressOf removeDocument_ItemClick
            AddHandler clearAll.ItemClick, AddressOf clearAll_ItemClick
        End Sub
        Private i As Integer = 0
        Private Sub addDocument_ItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
            ' Creates a document.
            documentManager1.View.AddDocument([New] XtraUserControl(), String.Format("New Document {0}", i))
            i += 1
        End Sub
        Private Sub removeDocument_ItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
            ' Closes the selected document.
            tabbedView1.Controller.Close(tabbedView1.DocumentGroups(0).SelectedDocument)
        End Sub
        Private Sub clearAll_ItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
            tabbedView1.Controller.CloseAll()
        End Sub
    End Class
End Namespace

Example: Adding Documents at Runtime

This example shows how a control can be added to the DocumentManager as a document. The application creates a new RichEditControl and docks it as a tab to DocumentManager each time the ‘Add Tabbed Document’ button is clicked. A click on the ‘Add Float Document’ button results in adding a floating document that contains a new RichEditControl object. For every RichEditControl a Document object is created. The figure below shows the result:

A click on the ‘Remove All’ button closes all documents within the view.

The DocumentManager uses the Tabbed View UI.

View Example

Form1.cs
Form1.vb

csharp

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using DevExpress.XtraBars;
using DevExpress.XtraRichEdit;
using DevExpress.XtraBars.Docking2010.Views.Tabbed;
using DevExpress.XtraBars.Docking2010.Views.NativeMdi;
using DevExpress.XtraBars.Docking2010.Views;

namespace DcoumentManagerContentGenerator {
    public partial class Form1 : Form {
        int index = 1;
        public Form1() {
            InitializeComponent();
            documentManager2.View.DocumentProperties.UseFormIconAsDocumentImage = false;
            documentManager2.View.UseDocumentSelector = DevExpress.Utils.DefaultBoolean.True;
            tabbedView1.FloatingDocumentContainer = FloatingDocumentContainer.DocumentsHost;
        }
        void AddNewTextDoc(string s, bool tabbed) {
            RichEditControl newTB = new RichEditControl();
            newTB.Size = new Size(400, 170);
            newTB.BorderStyle = DevExpress.XtraEditors.Controls.BorderStyles.NoBorder;
            newTB.ActiveViewType = DevExpress.XtraRichEdit.RichEditViewType.PrintLayout;
            newTB.Views.PrintLayoutView.ZoomFactor = 0.7f;
            newTB.Name = s + index.ToString();
            newTB.Text = s + " " + index.ToString();
            documentManager2.View.BeginUpdate();
            if (tabbed == true) {
                documentManager2.View.AddDocument(newTB);
            }
            else documentManager2.View.AddFloatDocument(newTB);
            documentManager2.View.EndUpdate();
            index++;
        }

        private void addTabbedDoc(object sender, ItemClickEventArgs e) {
            AddNewTextDoc("Document", true);
        }

        private void addFloatDoc(object sender, ItemClickEventArgs e) {
            AddNewTextDoc("Document", false);
        }

        private void closeAllDocs(object sender, ItemClickEventArgs e) {
            documentManager2.View.Controller.CloseAll();
            index = 1;
        }
    }
}

Imports Microsoft.VisualBasic
Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Linq
Imports System.Text
Imports System.Windows.Forms
Imports DevExpress.XtraBars
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraBars.Docking2010.Views.Tabbed
Imports DevExpress.XtraBars.Docking2010.Views.NativeMdi
Imports DevExpress.XtraBars.Docking2010.Views

Namespace DcoumentManagerContentGenerator
    Partial Public Class Form1
        Inherits Form
        Private index As Integer = 1
        Public Sub New()
            InitializeComponent()
            documentManager2.View.DocumentProperties.UseFormIconAsDocumentImage = False
            documentManager2.View.UseDocumentSelector = DevExpress.Utils.DefaultBoolean.True
            tabbedView1.FloatingDocumentContainer = FloatingDocumentContainer.DocumentsHost
        End Sub
        Private Sub AddNewTextDoc(ByVal s As String, ByVal tabbed As Boolean)
            Dim newTB As New RichEditControl()
            newTB.Size = New Size(400, 170)
            newTB.BorderStyle = DevExpress.XtraEditors.Controls.BorderStyles.NoBorder
            newTB.ActiveViewType = DevExpress.XtraRichEdit.RichEditViewType.PrintLayout
            newTB.Views.PrintLayoutView.ZoomFactor = 0.7f
            newTB.Name = s & index.ToString()
            newTB.Text = s & " " & index.ToString()
            documentManager2.View.BeginUpdate()
            If tabbed = True Then
                documentManager2.View.AddDocument(newTB)
            Else
                documentManager2.View.AddFloatDocument(newTB)
            End If
            documentManager2.View.EndUpdate()
            index += 1
        End Sub

        Private Sub addTabbedDoc(ByVal sender As Object, ByVal e As ItemClickEventArgs) Handles barButtonItem1.ItemClick
            AddNewTextDoc("Document", True)
        End Sub

        Private Sub addFloatDoc(ByVal sender As Object, ByVal e As ItemClickEventArgs) Handles barButtonItem3.ItemClick
            AddNewTextDoc("Document", False)
        End Sub

        Private Sub closeAllDocs(ByVal sender As Object, ByVal e As ItemClickEventArgs) Handles barButtonItem2.ItemClick
            documentManager2.View.Controller.CloseAll()
            index = 1
        End Sub
    End Class
End Namespace