Documents
- 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” (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 following examples adds a document with the specified caption, float location, and size.
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);
Create and Delete Documents in Code
Use the following methods to create, delete, select documents:
- AddDocument
- RemoveDocument
- TabbedView.Controller.CreateNewDocumentGroup
- TabbedView.Controller.Close
- TabbedView.Controller.CloseAll
- TabbedView.Controller.Select
The following example demonstrates how to create and remove (delete) tabbed documents in code:
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();
}
}
}
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.
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;
}
}
}