TX Text Control .NET for Windows Forms

Visual Studio Designer Integration

Topic

In a Windows Forms project, most of the work of putting TX Text Control on a form happens in the Visual Studio designer: smart tags add and connect the bars, the ribbon and the sidebars, and the Properties window sets everything else. What each designer feature does, and what it leaves behind in your project, is described below, so that you can rely on the designer for the layout and know where to continue in code.

The toolbox tab TX Text Control 34.0 and its items are covered by Visual Studio Toolbox and Designer. The designer needs the setup of TX Text Control on the development machine; the package from the Text Control Private NuGet Feed is meant for build servers.

What the Designer Writes

Everything you do in the designer is stored as C# code in the file Form1.Designer.cs, in the method InitializeComponent, which the constructor of the form calls. When you drop a TextControl on the form, Visual Studio adds a field textControl1 and the statements that create it, set its properties and add it to the form's Controls collection. A smart tag that connects a ruler to the editor writes the same assignment you would write yourself, such as textControl1.RulerBar = rulerBar1.

  • Don't edit Form1.Designer.cs by hand. Visual Studio rewrites it whenever the form changes in the designer. Put your own code in Form1.cs, after InitializeComponent.
  • The designer doesn't need code to run. The editor, its bars and its ribbon work as soon as the form opens. Code is needed only for what happens at run time: loading a document, reacting to events, changing the ribbon for a user.
  • The same result in code. Everything the designer does can be written in code instead, for example for forms that are built at run time. See Creating and Configuring Controls in Code.

The Smart Tag of the TextControl

Select the TextControl on the form and click the small arrow in its upper right corner. The TextControl Tasks panel opens:

The TextControl Tasks smart tag of a TextControl on a form, with the Appearance section for ViewMode, Dock and Text, the Information section with the version, and the Wizards section with links such as Add a Ribbon, Add a Ruler and Arrange Controls Automatically.

The panel has three sections:

SectionEntriesWhat they do
AppearanceViewMode, Dock, TextSet the ViewMode of the editor, such as PageView, its docking in the form and the text it starts with
InformationStart TXTextControlWords, Open the Help and Support Center, the versionStart the TX Words sample, open the Help and Support Center and show the version and edition of the installed product
WizardsAdd a Ribbon, Add a ButtonBar, Add a StatusBar, Add a Ruler, Add a Vertical Ruler, Add a Bottom Sidebar, Add a Left Sidebar, Add a Right Sidebar, Arrange Controls AutomaticallyAdd a control and connect it to the editor, and dock all controls so that they fill the form

Each Add wizard creates the control and sets the matching property of the TextControl: ButtonBar, RulerBar, VerticalRulerBar, StatusBar or Ribbon. A sidebar is connected the other way round: its TextControl property names the editor. Click Arrange Controls Automatically after adding controls, so that the new ones get their place around the editor.

The Smart Tags of the Ribbon and the Sidebar

The ribbon and the sidebars have smart tags of their own:

  • Ribbon. Select the ribbon by clicking its blue File tab title and open its smart tag. It adds the nine main predefined tabs, such as Add a RibbonFormattingTab, adds an empty RibbonTab, removes the selected tab and converts the form to a RibbonForm. The four contextual tabs, such as Table Layout, go into contextual tab groups instead. Built-in Ribbon Tabs describes the tabs.

    The Ribbon Tasks smart tag of a ribbon on a form, with the links Add a RibbonFormattingTab to Add a RibbonReferencesTab, Add a RibbonTab, Remove RibbonTab and Add a TextControl.

  • Predefined tabs. The smart tag of a tab such as the RibbonFormattingTab lists its Connected Sidebars: which sidebar opens when the user clicks Find, Go To, Replace or the dialog box launcher of the Styles group.

    The RibbonFormattingTab Tasks smart tag with the Connected Sidebars section, where drop-down lists assign a horizontal and a vertical sidebar to Find, Go To and Replace and a sidebar to the Styles dialog box launcher.

  • Sidebar. The smart tag of a Sidebar sets its ContentLayout, such as Styles or TrackedChanges, its docking, the connected TextControl and options such as IsShown and ShowPinButton. Sidebar and Panels shows the panel.

    The Sidebar Tasks smart tag with the ContentLayout drop-down open, listing None, Custom, Goto, FieldNavigator, TrackedChanges, Styles, Find, Replace, ConditionalInstructions, DocumentSettings, Comments and About, next to a Styles sidebar on the form.

The Properties Window

Every property the smart tags set is also in the Properties window, together with the ones they don't cover, such as the items of the ribbon's Application Menu in ApplicationMenuItems and its contextual tab groups in ContextualTabGroups. Properties that connect one component to another show a drop-down list of the matching components on the form. The MailMerge component, for example, which the designer places in the component tray below the form, lists the TextControl in its TextComponent property, as Where the Merge Runs shows.

Connections you make in the Properties window:

ComponentPropertyConnects
TextControlButtonBar, RulerBar, VerticalRulerBar, StatusBar, RibbonThe bars and the ribbon, if the smart tag didn't connect them
TextControlSpellCheckerThe TXSpellChecker of TX Spell .NET; see Integrating TX Spell .NET for Windows Forms
SidebarTextControlThe editor whose content the sidebar shows
Predefined ribbon tabsSidebar properties, such as StylesSidebarThe sidebar a ribbon button opens
MailMergeTextComponentThe editor that shows the template and the result of the merge

Some properties of the TextControl exist only at run time, such as Selection: they describe the document, not the control, and are not listed in the Properties window.

Events in the Designer

The Events page of the Properties window, the button with the lightning bolt, lists the events of the selected control. Double-click an event, such as Changed of the TextControl, and Visual Studio creates a handler in Form1.cs and connects it in Form1.Designer.cs. Events lists the events of the editor by subject.

Licensing in the Designer

The designer also takes care of the development license:

  • .NET Framework. Dropping a TextControl on a form adds an entry to the project's licenses.licx file, from which the license compiler embeds the license into your assembly when you build. Since version 30.0, the entries contain the full assembly version.
  • .NET 8 or higher. The NuGet package TXTextControl.TextControl.WinForms.SDK embeds its license file into your assembly, and no licenses.licx entry is needed.

A TextControl in a user control of a control library needs one more line of code; see Embedding the Editor in Forms and UserControls. Development Licenses covers the details.

When the Designer Doesn't Cooperate

When the toolbox tab is missing, a control can't be dropped on the form or a smart tag can't be found, Toolbox and Designer in Troubleshooting lists the causes. The most frequent one in a .NET project: the package must be installed and the form opened in the designer before the tab appears.

Next Steps