One of the key design goals for VSTO was to keep the design experience as close to existing Windows Forms development as possible, and adding Windows Forms controls to the document is a key tenet of this goal. The great thing about adding controls to the document or spreadsheet is that you really do not have to think about it because most of the design experience is almost identical to that of creating a Windows Forms form. However, there are some differences in the experience that we examine in this section.
When you create a new project based on an Excel workbook or Word document, VSTO creates a project and automatically loads the Excel or Word document surface into Visual Studio to provide a design surface for you to drag and drop controls onto. In the C# profile, the toolbox is set to auto hide by default. It is easier to pin the toolbox to make it dock to the side of Visual Studio window because it is difficult to drag and drop from the toolbox onto Word or Excel when it is in its default auto hide mode. Why? When the toolbox shows itself, it obscures quite a bit of the left side of the document or spreadsheet. When you drag and drop a control onto the document surface, the toolbox does not auto hide and get out of the way until the drag and drop is over.
Modes for Adding Controls
VSTO provides three modes for adding controls to the document surface:
Figure 14-5. Drag and drop of a Button control from the toolbox to an Excel worksheet.
Figure 14-6. Drawing a PictureBox control on a Word document.
Controls That Are Not in the Control Toolbox
A number of Windows Forms controls do not show up in the controls toolbox for Excel and Word projects. These controls were purposely excluded because of known issues in using them on the document surface. Some of these issues are purely design-time related in that the design-time representation of the control does not work well. This does not mean that the control cannot be used, but it might mean that the only way that you can use it on a document is by adding it programmatically at runtime or by using the control in a user control that you then add to the document.
A good example of such a control is the group box. The design-time experience of the group box does not work well in Excel or Word because the group box designer requires the container to support container drag and drop, which the Excel and Word designer does not support. You have two options to work around this limitation:
Some other controls are excluded from the toolbox because of the following reasons.
Control Insertion Behavior in Word
A control added to Word is affected by the insertion settings set in Word's Options dialog. A control can be inserted "in line with text," which means the control is inserted into the text flow of the document and moves as the text flow changes. It can also be inserted "in front of text," which means that the control is positioned at an absolute position in the document that does not change when the text flow changes.
The default insertion behavior in Word can be changed to be exact-position based rather than flow based by changing the insert/paste pictures setting in Word's Option dialog from the default In line with text to In front of text. After you change this setting, all controls will be positioned where you want them instead of having to be in line with the text. To change this setting, choose Options from the Tools menu and click the Edit tab of the Options dialog. Figure 14-7 shows the Insert/paste pictures setting.
Figure 14-7. Changing the default insertion behavior in Word's Options dialog.
You can also change the way a control in Word is wrapped with the text by right-clicking the control in the designer and selecting the Format Control menu option. Doing so brings up Word's Format Object dialog shown in Figure 14-8. Changing the wrapping style from in line with text to in front of text provides exact positioning.
Figure 14-8. Changing the wrapping style for a control with Word's Format Object dialog.
From the standpoint of the Word object model, a control whose wrapping style is set to In line with text, Square, or Tight is represented by the InlineShape object in Word's object model and found in the Document object's InlineShapes collection. A control whose wrapping style is set to Behind text or In front of text is represented by the Shape object in Word's object model and found in the Document object's Shapes collection.
Control Insertion Behavior in Excel
Excel also provides options for positioning a control on the worksheet surface, with the default being to move the control relative to the cell but not to size with the cell. This setting means that when you put a control onto the worksheet surface, it is linked to the cell that you dropped it on; so if you insert or delete cells around that cell, the control will stay positioned relative to the cell it was dropped on. However, if you resize the cell you dropped, the size of the control stays the same. This is usually the behavior that you would expect when adding a control. If you want your control to resize with the cell, you can either draw the control over the cell so that it exactly matches the size of the cell (not for the faint of heart) or right-click the control inside of Visual Studio and select Format Control, which brings up the Format Control dialog shown in Figure 14-9. Click the Properties tab and select one of three options:
Figure 14-9. Setting object positioning options for a control in Excel.
Layout of Controls on the Document or Worksheet Surface
The Windows Forms editor in Visual Studio has some great alignment tools that make it much simpler to design professional-looking forms without having to resort to per-pixel tweaks on each control. Unfortunately, the alignment tools do not work on documents because the display surface is very different from a form. In the place of these tools, a new toolbar provides easy access to the alignment functionality in Word and Excel. Figure 14-10 shows the toolbar. To align controls, just select the controls you want to align, and then click the button that represents the alignment option you want.
Figure 14-10. The control positioning toolbar in VSTO.
Part One. An Introduction to VSTO
An Introduction to Office Programming
Introduction to Office Solutions
Part Two. Office Programming in .NET
Working with Excel Events
Working with Excel Objects
Working with Word Events
Working with Word Objects
Working with Outlook Events
Working with Outlook Objects
Introduction to InfoPath
Part Three. Office Programming in VSTO
The VSTO Programming Model
Using Windows Forms in VSTO
Working with Actions Pane
Working with Smart Tags in VSTO
VSTO Data Programming
Server Data Scenarios
.NET Code Security
Part Four. Advanced Office Programming
Working with XML in Excel
Working with XML in Word
Developing COM Add-Ins for Word and Excel
Creating Outlook Add-Ins with VSTO