Documents
- 5 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;
- 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” (see the figure below). By doing so, you will create an empty Document, which requires you to handle the BaseView.QueryControl event and dynamically populate your Documents with content. See the Deferred Load article to learn more.
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 code snippet below illustrates an example.
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);
This code will result in adding a document that has a ready-set caption, float location and size.
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.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/how-to-add-a-control-based-document-e3912
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;
}
}
}