wpf-118378-controls-and-libraries-rich-text-editor-rich-edit-control-document-document-properties.md
RichEditControl allows you to provide a document with additional information about its author, title, editor, etc. These details are represented by document properties - metadata stored with the document.
Standard ECMA-376 (Edition 1) divides document properties into three categories: Core, Extended, and Custom. Rich Text Editor recognizes Core properties as the document’s built-in properties, and both Extended and Custom properties - as custom properties. Document metadata is accessible both in code and in the User Interface.
Built-in document properties are represented by the DocumentProperties instance. To set these attributes, use the following API.
| Member | Description |
|---|---|
| SubDocument.BeginUpdate | Enables document modification. |
| Document.DocumentProperties | Provides access to the document properties collection. |
| SubDocument.EndUpdate | Finishes the document update. |
This code snippet demonstrates how to set standard document properties with the Document.DocumentProperties property and show them in a document using specific fields.
document.BeginUpdate();
document.DocumentProperties.Creator = "John Doe";
document.DocumentProperties.Title = "Inserting Custom Properties";
document.DocumentProperties.Category = "TestDoc";
document.DocumentProperties.Description = "This code demonstrates API to modify and display standard document properties.";
document.Fields.Create(document.AppendText("\nAUTHOR: ").End, "AUTHOR");
document.Fields.Create(document.AppendText("\nTITLE: ").End, "TITLE");
document.Fields.Create(document.AppendText("\nCOMMENTS: ").End, "COMMENTS");
document.Fields.Create(document.AppendText("\nCREATEDATE: ").End, "CREATEDATE");
document.Fields.Create(document.AppendText("\nCategory: ").End, "DOCPROPERTY Category");
document.Fields.Update();
document.EndUpdate();
document.BeginUpdate()
document.DocumentProperties.Creator = "John Doe"
document.DocumentProperties.Title = "Inserting Custom Properties"
document.DocumentProperties.Category = "TestDoc"
document.DocumentProperties.Description = "This code demonstrates API to modify and display standard document properties."
document.Fields.Create(document.AppendText(vbLf & "AUTHOR: ").End, "AUTHOR")
document.Fields.Create(document.AppendText(vbLf & "TITLE: ").End, "TITLE")
document.Fields.Create(document.AppendText(vbLf & "COMMENTS: ").End, "COMMENTS")
document.Fields.Create(document.AppendText(vbLf & "CREATEDATE: ").End, "CREATEDATE")
document.Fields.Create(document.AppendText(vbLf & "Category: ").End, "DOCPROPERTY Category")
document.Fields.Update()
document.EndUpdate()
The following table lists the built-in document properties supported in different formats:
| DOCX | DOTX | DOCM | DOTM | RTF | DOC | DOT | WordML | ODT | HTML | XML | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Application | |||||||||||
| AppVersion | |||||||||||
| Category | |||||||||||
| ContentStatus | |||||||||||
| ContentType | |||||||||||
| Company | |||||||||||
| Created | |||||||||||
| Creator | |||||||||||
| Description | |||||||||||
| Identifier | |||||||||||
| Keywords | |||||||||||
| Language | |||||||||||
| LastModifiedBy | |||||||||||
| LastPrinted | |||||||||||
| Manager | |||||||||||
| Modified | |||||||||||
| Revision | |||||||||||
| Subject | |||||||||||
| Template | |||||||||||
| Title | |||||||||||
| Version |
Custom properties in the RichEditControl document are represented by the DocumentCustomProperties instance. The API from the table below allows you to set the custom properties for your document.
| Member | Description |
|---|---|
| SubDocument.BeginUpdate | Enables document modification. |
| Document.CustomProperties | Provides access to the collection of custom document properties. |
| DocumentCustomProperties.Add | Adds new custom property with the given name and value to the document collection. |
| DocumentCustomProperties.Item | Sets the value of the custom property. If the property with the specified name does not exist, RichEditControl creates it automatically. |
| SubDocument.EndUpdate | Finishes the document update. |
The following code illustrates how to create custom document properties and place them in the document’s storage. The DOCVARIABLE field is used to display property values in the document. The DocumentPropertyDisplayHelper is a custom class that helps to obtain a property value.
document.BeginUpdate();
document.AppendText("A new value of MyBookmarkProperty is obtained from here: NEWVALUE!\n");
document.Bookmarks.Create(document.FindAll("NEWVALUE!", SearchOptions.CaseSensitive)[0], "bmOne");
document.AppendText("\nMyNumericProperty: ");
document.Fields.Create(document.Range.End, "DOCVARIABLE CustomProperty MyNumericProperty");
document.AppendText("\nMyStringProperty: ");
document.Fields.Create(document.Range.End, "DOCVARIABLE CustomProperty MyStringProperty");
document.AppendText("\nMyBooleanProperty: ");
document.Fields.Create(document.Range.End, "DOCVARIABLE CustomProperty MyBooleanProperty");
document.AppendText("\nMyBookmarkProperty: ");
document.Fields.Create(document.Range.End, "DOCVARIABLE CustomProperty MyBookmarkProperty");
document.EndUpdate();
document.CustomProperties["MyNumericProperty"] = 123.45;
document.CustomProperties["MyStringProperty"] = "The Final Answer";
document.CustomProperties["MyBookmarkProperty"] = document.Bookmarks[0];
document.CustomProperties["MyBooleanProperty"] = true;
document.CalculateDocumentVariable += DocumentPropertyDisplayHelper.OnCalculateDocumentVariable;
document.Fields.Update();
class DocumentPropertyDisplayHelper
{
public static void OnCalculateDocumentVariable(object sender, DevExpress.XtraRichEdit.CalculateDocumentVariableEventArgs e)
{
if (e.Arguments.Count == 0 || e.VariableName != "CustomProperty")
return;
string name = e.Arguments[0].Value;
var customProperty = ((DevExpress.Xpf.RichEdit.RichEditControl)sender).Document.CustomProperties[name];
if (customProperty != null)
e.Value = customProperty.ToString();
e.Handled = true;
}
}
document.BeginUpdate()
document.AppendText("A new value of MyBookmarkProperty is obtained from here: NEWVALUE!" & vbLf)
document.Bookmarks.Create(document.FindAll("NEWVALUE!", SearchOptions.CaseSensitive)(0), "bmOne")
document.AppendText(vbLf & "MyNumericProperty: ")
document.Fields.Create(document.Range.End, "DOCVARIABLE CustomProperty MyNumericProperty")
document.AppendText(vbLf & "MyStringProperty: ")
document.Fields.Create(document.Range.End, "DOCVARIABLE CustomProperty MyStringProperty")
document.AppendText(vbLf & "MyBooleanProperty: ")
document.Fields.Create(document.Range.End, "DOCVARIABLE CustomProperty MyBooleanProperty")
document.AppendText(vbLf & "MyBookmarkProperty: ")
document.Fields.Create(document.Range.End, "DOCVARIABLE CustomProperty MyBookmarkProperty")
document.EndUpdate()
document.CustomProperties("MyNumericProperty") = 123.45
document.CustomProperties("MyStringProperty") = "The Final Answer"
document.CustomProperties("MyBookmarkProperty") = document.Bookmarks(0)
document.CustomProperties("MyBooleanProperty") = True
AddHandler document.CalculateDocumentVariable, AddressOf DocumentPropertyDisplayHelper.OnCalculateDocumentVariable
document.Fields.Update()
Private Class DocumentPropertyDisplayHelper
Public Shared Sub OnCalculateDocumentVariable(ByVal sender As Object, ByVal e As DevExpress.XtraRichEdit.CalculateDocumentVariableEventArgs)
If e.Arguments.Count = 0 OrElse e.VariableName <> "CustomProperty" Then
Return
End If
Dim name As String = e.Arguments(0).Value
Dim customProperty = DirectCast(sender, DevExpress.Xpf.RichEdit.RichEditControl).Document.CustomProperties(name)
If customProperty IsNot Nothing Then
e.Value = customProperty.ToString()
End If
e.Handled = True
End Sub
End Class
Tip
To check what document properties are going to be exported, use the ExportedDocumentProperties property.
End-users can specify both built-in and custom properties using the Document Properties Dialog (invoked from the File ribbon tab). To provide the application with the Ribbon UI, refer to the Lesson 5 - Create Separate Ribbon Pages for a Rich Text Editor topic.
The Statistics dialog tab displays document properties that are updated automatically. You can specify the DXRichEditBehaviorOptions.DocumentPropertiesAutoUpdate property to control these properties’ update.