Skip to main content
All docs
V24.1

Get Started

  • 6 minutes to read

This topic introduces major Document Manager concepts. We also recommend that you review these help articles that demonstrate how the Document Manager component can help you build different UI types:

Create a Sample Project

  • Create a blank Windows Forms project (you can use the “Blank Application” template from the Template Gallery) and drop a DocumentManager component on a form.

  • Document Manager includes multiple Views. The default View is “Tabbed”. Use the component smart tag menu to switch to another View.

    Document Manager smart tag menu

    Tip

    Each View creates a unique UI type and operates its own type of Documents. If you populate a View with Documents, and then change the Document Manager View (for instance, from NativeMDI to WindowsUI), documents from the previous View will be lost.

    For the purpose of this tutorial, leave the default Tabbed View active.

  • Use the same smart tag menu to open the Designer dialog. Go to the Documents tab and click Add New Document.

    Document Manager Designer

    You now have a blank Document. Try to run the application and notice that it crashes with the DevExpress.XtraBars.Docking2010.Views.DeferredLoadingException. This happens because Documents are content wrappers and cannot be empty.

    Click the Assign Control button and specify the BaseDocument.ControlType property in the opened window:

    Document Manager Designer - Assign Control

    Alternatively, you can handle the View.QueryControl event. It fires repeatedly for every blank document that is about to be shown, and allows you to assign document content to the e.Control property.

    void TabbedView1_QueryControl(object sender, QueryControlEventArgs e) {
        if (e.Document == document1)
            e.Control = new UserControl1();
    }
    

    Document populated on Query Control event

    Tip

    You can assign any control to the e.Control property, but we recommend that you assign forms or user controls.

  • Create another User Control, rebuild the solution, and go back to the “Documents” tab of the Document Manager Designer. Notice that the “Populate” button is now enabled - you can click it to add a new Document for every UserControl in your app. Created documents refer to their content by ControlName and ControlTypeName properties.

    Auto-generated documents

    When you click “Populate”, the component handles the QueryControl event (if it is not handled yet) and adds code that populates auto-generated documents. Since you already have the event handler, add the following code:

    void tabbedView1_QueryControl(object sender, QueryControlEventArgs e) {
        //...
        if (e.Document.ControlName == "UserControl2")
            e.Control = new UserControl2();
    }
    
  • Another option to add and populate documents is to call View.AddDocument method overloads. You do not need to handle QueryControl for Documents added in this manner.

    void Form1_Load(object sender, EventArgs e) {
        var newDoc = tabbedView1.AddDocument(new ucRichEditControl(), "Document3");
    }
    

    Tip

    This technique allows you to load all Documents at once, which degrades the application start-up performance, but eliminates the need to load Documents when users select them. In contrast, the QueryControl event allows you to delay Document load up until it is selected for the first time - the application starts faster, but navigation between Documents takes time. See this help article for more information: Deferred Load.

  • You now have three Documents docked as tabs. To move and select them, use View controller methods. You can access the View controller with the BaseView.Controller property.

    //place a document in another spot
    tabbedView1.Controller.Move(document3, 0);
    //select a document
    tabbedView1.Controller.Select(document2);
    //undock a Document and make it float
    tabbedView1.Controller.Float(document1,
        new Point(this.Location.X + 150, this.Location.Y + 150), //or set Document.FloatLocation
        new Size(600, 300)); //or set Document.FloatSize
    //dock a floating Document as a tab
    tabbedView1.Controller.Dock(document1);
    

Document Groups

Tabbed Documents are not hosted directly inside the View; they must be placed in DocumentGroup containers. All Documents you create are first placed into a default Group. When you or your users dock a Document to either side of another Document, the View creates new groups for these Documents. The figure below illustrates three side-by-side Documents. Each document resides in its own Group.

Horizontally oriented documents

If you need to rearrange Documents in code, create Document Groups and use View.Controller.Dock method overloads to place Documents into these Groups.

DocumentGroup group2 = new DocumentGroup();
DocumentGroup group3 = new DocumentGroup();
tabbedView1.DocumentGroups.AddRange(new DocumentGroup[] { group2, group3 });
tabbedView1.Controller.Dock((Document)tabbedView1.Documents[1], group2);
tabbedView1.Controller.Dock((Document)tabbedView1.Documents[2], group3);

The code above arranges all three documents side-by-side in a horizontal line. If you need to arrange groups in a column (one below another), change the View’s orientation.

tabbedView1.Orientation = Orientation.Vertical;

With default View settings, all groups can be arranged either vertically (in a column) or horizontally (in a row). If you need to mix vertically and horizontally oriented groups and allow users to freely arrange Documents across the View surface, enable Free Layout Mode.

Free layout mode

tabbedView1.EnableFreeLayoutMode = DevExpress.Utils.DefaultBoolean.True;

DocumentGroup group2 = new DocumentGroup();
DocumentGroup group3 = new DocumentGroup();
tabbedView1.DocumentGroups.AddRange(new DocumentGroup[] { group2, group3 });

group2.DockTo(tabbedView1.DocumentGroups[0], Orientation.Vertical);
group3.DockTo(group2, Orientation.Horizontal);

tabbedView1.Controller.Dock((Document)tabbedView1.Documents[1], group2);
tabbedView1.Controller.Dock((Document)tabbedView1.Documents[2], group3);

Customize Document Properties

Use properties from the TabbedView.DocumentProperties section to specify additional document settings. For example, you can disable the AllowClose property to remove a close button from document headers.

All Boolean properties from the DocumentProperties group are also available for individual documents. Individual document properties are of the DefaultBoolean type: the DefaultBoolean.Default value means this document should act according to the global View setting, and DefaultBoolean.True/DefaultBoolean.False values override it.

//only document2 can float
tabbedView1.DocumentProperties.AllowFloat = false;
document2.Properties.AllowFloat = DevExpress.Utils.DefaultBoolean.True;

Floating Document Host

You can allow floating Documents to be placed into containers that contain their own document manager components. Such containers can host multiple documents, which allow you and your users to group floating documents rather than keep each of them as a separate window.

Float Host

To enable this behavior, set the FloatingDocumentContainer property to DocumentsHost.

tabbedView1.FloatingDocumentContainer = FloatingDocumentContainer.DocumentsHost;

Document Manager in MVVM Applications

DevExpress MVVM Framework allows you to build applications that follow a Model-View-ViewModel concept. This concept implies that data, UI, and application logic are split into independent layers.

To manage a Document UI from a ViewModel layer, register a DocumentManagerService or a WindowedDocumentManagerService in the View layer, and call its public methods from a ViewModel to create, dock and select documents.

//View
mvvmContext1.RegisterService(DocumentManagerService.Create(tabbedView1));

//ViewModel
public void ShowDocument(){
    var dms = this.GetService<IDocumentManagerService>();
    var doc = dms.CreateDocument(...);
    doc.Show();
}

See this help article for details: Standard DevExpress Services.