Built-In Dialog Boxes

TX Text Control .NET for Windows Forms brings the dialog boxes of a word processor with it: font, paragraph, tabs, lists, styles, page setup, tables, images, find and replace and more. The ribbon tabs open them for the user, and your code opens each one with a single method call. Here you find which dialog boxes exist, how to open them on a certain tab, how to tell whether the user clicked OK, and how to change the separate dialog classes for bookmarks, hyperlinks and comments.

How Built-In Dialog Boxes Work

Most dialog boxes are methods of the TextControl whose names end in Dialog, such as FontDialog. A dialog box works on the current selection or input position of the control and applies the user's settings when the user clicks OK. The method returns a System.Windows.Forms.DialogResult: DialogResult.Cancel when the user left with Cancel, otherwise DialogResult.OK.

The following screenshot shows the Tabs dialog box, which TabDialog opens, in the TX Words sample:

In the ribbon, groups such as Font and Paragraph show a small button in their lower right corner, visible in the screenshot. It is the dialog box launcher of the group, a DialogBoxLauncher object with a Click event. Built-in Ribbon Tabs describes the tabs.

Dialog Boxes of the TextControl

A few methods don't follow this pattern or return something else:

• AddSymbolDialog and SpellCheckDialog return nothing.
• LanguageDialog returns DialogResult.None when the selected language could not be set.
• The two conditional instruction methods return DialogResult.Abort when the dialog box could not be opened because a condition of the table above isn't met.
• ListFormatDialog also returns DialogResult.Cancel when nothing was changed.

Find, Replace, Open, Save and Print

Other methods open dialog boxes when they are called without the parameters that would otherwise do the work:

Search and Replace, Loading and Saving and Printing cover these tasks in full.

Open a Dialog Box From Code

The following handlers open the Font dialog box on its second tab and the table dialog box only when the input position is in a table. Connect them to the Click event of two buttons or menu items in Form1.cs:

using System;
using System.Windows.Forms;
using TXTextControl;

public partial class Form1 : Form
{
    public Form1()
    {
        InitializeComponent();
    }

    private void FontButton_Click(object sender, EventArgs e)
    {
        // Open the tab for baseline position and text effects
        if (textControl1.FontDialog(1) == DialogResult.OK)
        {
            // Return the keyboard focus to the editor
            textControl1.Focus();
        }
    }

    private void TableButton_Click(object sender, EventArgs e)
    {
        // The table dialog box needs a table at the input position
        if (textControl1.Tables.GetItem() != null)
        {
            textControl1.TableFormatDialog(2);
        }
        else
        {
            MessageBox.Show("Place the input position in a table first.");
        }
    }
}

The code works as follows:

• FontDialog(1) opens the dialog box on the tab with index 1. Without a parameter, a tabbed dialog box opens on the tab that was open last.
• The result is compared with DialogResult.OK, which means the user confirmed the changes.
• TableCollection.GetItem without parameters returns the table at the input position, or null. ImageCollection.GetItem and TextFrameCollection.GetItem test the same way whether an image or a text frame is selected.
• TableFormatDialog(2) opens the tab for formulas and number formats.

Tabs of the Tabbed Dialog Boxes

The activeTab parameter is the zero-based index of the tab:

SectionFormatDialog(1) opens the page setup on the Headers and Footers tab:

Measuring Units

The DialogUnit property sets the unit for sizes and distances in all dialog boxes: Auto, Centimeter, Inch or Millimeter. With Auto, the unit depends on the culture of the current thread.

// Show sizes and distances in millimeters
textControl1.DialogUnit = DialogUnit.Millimeter;

Options in the Save As Dialog Box

An overload of Save takes a SaveSettings.DialogSettings value that adds options to the Save As dialog box, such as a password button for Adobe PDF, stylesheet options for HTML or a check box that saves only the selected text. Loading and Saving Documents shows the options and the code.

Dialog Classes

Some dialog boxes are classes of their own that inherit from System.Windows.Forms.Form. You create them for a TextControl and show them modally with ShowDialog or modelessly with Show:

This is the hyperlink dialog box, opened for an existing link:

BookmarkDialog and HyperlinkDialog throw an exception if nothing can be inserted or edited at the input position. The reference names the checks: DocumentTargets.CanAdd or a target at the input position for bookmarks, and HypertextLinks.CanAdd or a link at the input position for hyperlinks.

Each item of these dialog boxes has a name from the class's DialogItem enumeration, and FindItem returns the item as a System.Windows.Forms.Control so that you can move, change or remove it. The following code removes the check box that lets users mark a bookmark as deletable, then shows the dialog box:

BookmarkDialog dialog = new BookmarkDialog(textControl1);

// Remove the check box before the dialog box is shown
Control deletable = dialog.FindItem(BookmarkDialog.DialogItem.TXITEM_Deletable);
deletable.Parent.Controls.Remove(deletable);

dialog.ShowDialog(this);

BookmarkDialog.FindItem and BookmarkDialog.DialogItem list the items of this dialog box; the other classes have their own enumerations.

Adapt the Comments and Tracked Changes Dialog Boxes

The two modeless dialog boxes work the same way. CommentsDialog.FindItem takes a value of CommentsDialog.DialogItem, and TrackedChangesDialog.FindItem a value of TrackedChangesDialog.DialogItem. Both return null when the item isn't found:

The following handler opens the tracked changes dialog box for a reviewer who may accept single changes but not accept or reject all of them at once:

private void reviewButton_Click(object sender, EventArgs e)
{
    TrackedChangesDialog dialog = new TrackedChangesDialog(textControl1);

    // Hide the buttons that act on all tracked changes
    Control acceptAll = dialog.FindItem(TrackedChangesDialog.DialogItem.TXITEM_AcceptAllTrackedChanges);
    Control rejectAll = dialog.FindItem(TrackedChangesDialog.DialogItem.TXITEM_RejectAllTrackedChanges);

    if (acceptAll != null) acceptAll.Visible = false;
    if (rejectAll != null) rejectAll.Visible = false;

    // Modeless: the user goes on working in the document
    dialog.Show(this);
}

The name of each DialogItem value is the Name of the control it identifies. For comments, CommentsDialog.DialogItem.TXITEM_DeleteAllComments finds the button that deletes every comment, which you hide the same way.

Dialog Boxes of Fields

Two field classes open their own dialog boxes, which return a Selection.DialogResult:

• FormField.FormFieldDialog changes the formatting attributes of a form field.
• PageNumberField.PageNumberDialog changes the format and numbering of a page number field.

Next Steps

• Context Menus: open dialog boxes from the right-click menu.
• Localization and Resource Kit: the language of the dialog boxes.
• Right-to-Left UI: dialog boxes in a right-to-left layout.
• Custom Tabs and Commands: ribbon buttons that open dialog boxes.