Document Properties

Title, author, subject and keywords, the creation date, the application that created a document and any properties you add yourself are stored inside the document file. They let a document management system find and sort documents without opening them, and they stay with a document when it is sent on. The WPF TextControl exposes them for the document the user is editing, a sidebar panel lets users change them, and the save settings decide what ends up in the file.

The code below belongs in MainWindow.xaml.cs of a window with a TextControl named textControl1, as built in Load and Save Documents, and uses using TXTextControl;.

What Document Properties Are

DocumentSettings of the WPF TextControl returns a DocumentSettings object for the current document. Loading a document fills it, and saving stores all of its values automatically. The class was introduced in version 29.0.

The three properties that can be null need a check before your code uses them.

Show the Document Settings Panel

The WPF Sidebar has a panel for managing the settings of a document. In XAML, name the editor in the sidebar's TextControl attribute and set ContentLayout to DocumentSettings:

<Window x:Class="SampleApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:WPF="clr-namespace:TXTextControl.WPF;assembly=TXTextControl.WPF"
        Title="MainWindow" Height="450" Width="800">
    <DockPanel>
        <WPF:Sidebar x:Name="sidebar1"
                    DockPanel.Dock="Right"
                    HorizontalAlignment="Right"
                    TextControl="textControl1"
                    ContentLayout="DocumentSettings" />
        <WPF:TextControl x:Name="textControl1" />
    </DockPanel>
</Window>

The panel has text boxes for the title, author, subject and keywords (Tags), shows the creation date and lists user-defined properties, which Add... and Delete change. The creation date is set to the current date when the content of the editor is reset; for a loaded document, the panel shows the date stored in it. A further category lists the attachments of a PDF document, described in Attachments.

As with the toolbars, the sidebar refers to the TextControl by its name. The reference shows TextControl of the sidebar with the type TextControl, but in version 34.0 the property is a string: in code, assign "textControl1", not the object. Sidebar and Panels describes the other panels.

Set the Properties in Code

The following Click handler sets the standard properties and three user-defined properties of the document in the editor:

private void setPropertiesButton_Click(object sender, RoutedEventArgs e)
{
    DocumentSettings settings = textControl1.DocumentSettings;

    settings.DocumentTitle = "Quarterly Report";
    settings.Author = "Sales Department";
    settings.DocumentSubject = "Results of the third quarter";
    settings.DocumentKeywords = new string[] { "sales", "report", "Q3" };

    // null if the document has no user-defined properties yet
    UserDefinedPropertyDictionary properties =
        settings.UserDefinedDocumentProperties ?? new UserDefinedPropertyDictionary();

    SetProperty(properties, "Department", "Sales");
    SetProperty(properties, "Revision", 3);
    SetProperty(properties, "Approved", false);

    settings.UserDefinedDocumentProperties = properties;
}

private static void SetProperty(UserDefinedPropertyDictionary properties, string name, object value)
{
    if (properties.Contains(name))
    {
        properties.Remove(name);
    }

    properties.Add(name, value);
}

The code works as follows:

• Standard properties are plain assignments and are written to the file with the next save.
• User-defined properties live in a UserDefinedPropertyDictionary. Each name is a string of up to 255 characters, and each value a string, bool, int or double.
• Replacing a value. SetProperty checks with Contains, removes the old entry with Remove and stores the new one with Add.

Read the Properties After Loading

DocumentLoaded occurs when a new document has been loaded, and DocumentSettings then holds its values. Connect the handler in the constructor of the window, after InitializeComponent, with textControl1.DocumentLoaded += textControl1_DocumentLoaded;. The handler needs using System.Collections; and using System.Diagnostics;:

private void textControl1_DocumentLoaded(object sender, EventArgs e)
{
    DocumentSettings settings = textControl1.DocumentSettings;

    Debug.WriteLine("Title: " + settings.DocumentTitle);
    Debug.WriteLine("Author: " + settings.Author);

    // null if the document has no keywords
    if (settings.DocumentKeywords != null)
    {
        Debug.WriteLine("Keywords: " + string.Join(", ", settings.DocumentKeywords));
    }

    if (settings.UserDefinedDocumentProperties != null)
    {
        foreach (DictionaryEntry property in settings.UserDefinedDocumentProperties)
        {
            Debug.WriteLine(property.Key + " = " + property.Value);
        }
    }
}

The dictionary enumerates DictionaryEntry objects with the name in Key and the value in Value; Names returns just the names. The read-only properties of LoadSettings, such as DocumentTitle and UserDefinedDocumentProperties, return the values of a single load operation, which is useful with a ServerTextControl that has no editor.

Override Values When Saving

Values passed in a SaveSettings object take precedence over DocumentSettings when the document is saved. SaveSettings has Author, DocumentTitle, DocumentSubject, DocumentKeywords, CreationDate, LastModificationDate, CreatorApplication and UserDefinedDocumentProperties:

SaveSettings saveSettings = new SaveSettings()
{
    CreatorApplication = "My Editor",
    LastModificationDate = DateTime.Now
};

textControl1.Save("report.docx", StreamType.WordprocessingML, saveSettings);

The blog article Maintaining Custom Document Properties from 2020 passes user-defined properties with SaveSettings on every save, because they weren't kept otherwise. Since DocumentSettings arrived in version 29.0, the editor keeps them, and SaveSettings only replaces them.

Which Formats Store the Properties

• Title, author, subject, keywords, dates and creator application can be saved with all supported text formats since version 23.0.
• User-defined properties are saved and loaded with the TX Text Control format, RTF, DOC and DOCX.
• PDF documents keep the standard properties as metadata; see Document Metadata.
• Embedded files exist only in PDF and PDF/A documents; see Attachments.

Next Steps

• Loading and Saving Documents: the load and save options around the properties.
• Sidebar and Panels: the sidebar and its panels.
• Document Metadata: properties of PDF documents.