Document Properties
- 4 minutes to read
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 Properties
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 collection of document properties. |
| SubDocument.EndUpdate | Finishes document update. |
This code snippet demonstrates how to set standard document properties and show them in a document using specific fields. Calling the FieldCollection.Update updates all property fields in the document body.
Note
If the DOCPROPERTY fields are located in the text box, header or footer, they should be updated separately. Use the Section.BeginUpdateHeader - Section.EndUpdateHeader or Section.BeginUpdateFooter - Section.EndUpdateFooter paired methods to obtain the header or footer. The TextBox.Document property allows you to retrieve the text box content and update the corresponding fields.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/winforms-richedit-document-api-e5219
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();
Built-in Properties in Different Formats
The table below highlights what built-in document properties supported in different formats.
| DOCX | RTF | DOC | WordML | ODT | HTML | |
|---|---|---|---|---|---|---|
| Category |  |
|
|
|
 |
|
| ContentStatus | |
|
|
|
|
|
| ContentType | |
|
|
|
|
|
| Created | |
|
|
|
|
|
| Creator | |
|
|
|
|
|
| Description | |
|
|
|
|
|
| Identifier | |
|
|
|
|
|
| Keywords | |
|
|
|
|
|
| Language | |
|
|
|
|
|
| LastModifiedBy | |
|
|
|
|
|
| LastPrinted | |
|
|
|
|
|
| Modified | |
|
|
|
|
|
| Revision | |
|
|
|
|
|
| Subject | |
|
|
|
|
|
| Title | |
|
|
|
|
|
| Version | |
|
|
|
|
|
Custom Properties
Custom properties in the RichEditControl document are represented by the DocumentCustomProperties instance. The API from the table below allows you to set 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 a new custom property with a given name and value to the document collection. |
| DocumentCustomProperties.Item | Sets a value of a 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 DOCPROPERTY field is used to display property values in the document. Calling the FieldCollection.Update updates all property fields in the document body.
Note
If the DOCPROPERTY fields are located in the text box, header or footer, they should be updated separately. Use the Section.BeginUpdateHeader - Section.EndUpdateHeader or Section.BeginUpdateFooter - Section.EndUpdateFooter paired methods to obtain the header or footer. The TextBox.Document property allows you to retrieve the text box content and update the corresponding fields.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/winforms-richedit-document-api-e5219
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, @"DOCPROPERTY ""MyNumericProperty""");
document.AppendText("\nMyStringProperty: ");
document.Fields.Create(document.Range.End, @"DOCPROPERTY ""MyStringProperty""");
document.AppendText("\nMyBooleanProperty: ");
document.Fields.Create(document.Range.End, @"DOCPROPERTY ""MyBooleanProperty""");
document.AppendText("\nMyBookmarkProperty: ");
document.Fields.Create(document.Range.End, @"DOCPROPERTY ""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.Fields.Update();
Tip
To set what document properties are going to be exported, use the DocumentExporterOptions.ExportedDocumentProperties property.
Document Properties in the User Interface
End-users can specify both built-in and custom properties using the Document Properties Dialog (invoked from the File ribbon tab). To learn how to provide the application with the Ribbon UI, refer to the How to: Create the RichEditControl with a Ribbon UI topic.
The Statistics dialog tab displays document properties that are updated automatically. You can specify the RichEditBehaviorOptions.DocumentPropertiesAutoUpdate property to control these properties’ update.
To display document properties in the document, use special fields, the DOCPROPERTY field or a combination of the DOCVARIABLE field and the RichEditControl.CalculateDocumentVariable event handler.