ControlCollection.AddControl Method

Definition

Namespace:

Microsoft.Office.Tools.Word

Assemblies:

Microsoft.Office.Tools.Word.dll, Microsoft.Office.Tools.Word.v4.0.Utilities.dll

Overloads

AddControl(Control, Single, Single, Single, Single, String)	Adds the specified control to the ControlCollection at the specified location, with the specified size.
AddControl(Control, Range, Single, Single, String)	Adds the specified control to the ControlCollection at the specified range, with the specified size.

AddControl(Control, Single, Single, Single, Single, String)

Adds the specified control to the ControlCollection at the specified location, with the specified size.

public:
 Microsoft::Office::Tools::Word::ControlSite ^ AddControl(System::Windows::Forms::Control ^ control, float left, float top, float width, float height, System::String ^ name);

public Microsoft.Office.Tools.Word.ControlSite AddControl (System.Windows.Forms.Control control, float left, float top, float width, float height, string name);

abstract member AddControl : System.Windows.Forms.Control * single * single * single * single * string -> Microsoft.Office.Tools.Word.ControlSite

Public Function AddControl (control As Control, left As Single, top As Single, width As Single, height As Single, name As String) As ControlSite

Parameters

control

Control

The control to be added to the ControlCollection instance.

left

Single

The distance in points between the left edge of the control and the left edge of the document.

top

Single

The distance in points between the top edge of the control and the top edge of the document.

width

Single

The width of the control in points.

height

Single

The height of the control in points.

name

String

The name of the control.

Returns

ControlSite

An object that represents the control that contains the specified control on the document.

Exceptions

ArgumentNullException

The name argument is null, or the name argument has zero length.

ControlNameAlreadyExistsException

A control with the same name is already in the ControlCollection instance.

ControlCouldNotBeInitializedException

The control argument is null.

Examples

The following code example adds two custom user controls to the document using the AddControl method. The first control is added to a Range. The second control is added to a specific location. The code changes the Top property of the first custom user control, which only moves the control relative to the ControlSite that contains the control on the document. The code then sets the Top property of the ControlSite returned by the second user control to illustrate the correct way to set the Top property of the control.

private void WordRangeAddControl()
{
    this.Paragraphs[1].Range.InsertParagraphBefore();
    UserControl1 customUserControl = new UserControl1();
    UserControl2 customUserControl2 = new UserControl2();

    Microsoft.Office.Tools.Word.ControlSite dynamicControl =
        this.Controls.AddControl(customUserControl, 
        this.Paragraphs[1].Range, 150, 150, "dynamicControl");

    Microsoft.Office.Tools.Word.ControlSite dynamicControl2 =
        this.Controls.AddControl(customUserControl2, 200, 0,
        150, 150, "dynamicControl2");

    customUserControl.BackColor = Color.Blue;
    customUserControl2.BackColor = Color.Green;
    
    customUserControl.Top = 100;
    dynamicControl2.Top = 100;
}

Private Sub WordRangeAddControl()
    Me.Paragraphs(1).Range.InsertParagraphBefore()
    Dim CustomUserControl As New UserControl1()
    Dim CustomUserControl2 As New UserControl2()

    Dim DynamicControl As Microsoft.Office.Tools.Word.ControlSite = _
        Me.Controls.AddControl(CustomUserControl, _
        Me.Paragraphs(1).Range, 150, 150, "DynamicControl")

    Dim DynamicControl2 As Microsoft.Office.Tools.Word.ControlSite = _
        Me.Controls.AddControl(CustomUserControl2, _
        200, 0, 150, 150, "DynamicControl2")

    CustomUserControl.BackColor = Color.Blue
    CustomUserControl2.BackColor = Color.Green

    CustomUserControl.Top = 100
    dynamicControl2.Top = 100
End Sub 

Remarks

This method can be used to add any control to the ControlCollection at run time. For more information, see Adding Controls to Office Documents at Run Time.

AddControl(Control, Range, Single, Single, String)

Adds the specified control to the ControlCollection at the specified range, with the specified size.

public:
 Microsoft::Office::Tools::Word::ControlSite ^ AddControl(System::Windows::Forms::Control ^ control, Microsoft::Office::Interop::Word::Range ^ range, float width, float height, System::String ^ name);

public Microsoft.Office.Tools.Word.ControlSite AddControl (System.Windows.Forms.Control control, Microsoft.Office.Interop.Word.Range range, float width, float height, string name);

abstract member AddControl : System.Windows.Forms.Control * Microsoft.Office.Interop.Word.Range * single * single * string -> Microsoft.Office.Tools.Word.ControlSite

Public Function AddControl (control As Control, range As Range, width As Single, height As Single, name As String) As ControlSite

Parameters

control

Control

The control to be added to the ControlCollection instance.

range

Range

A Range that provides the location for the control.

width

Single

The width of the control in points.

height

Single

The height of the control in points.

name

String

The name that can be used to index the control in the ControlCollection instance.

Returns

ControlSite

An object that represents the control that contains the specified control on the document.

Exceptions

ArgumentNullException

The name, or range argument is null, or the name argument has zero length.

ControlNameAlreadyExistsException

A control with the same name is already in the ControlCollection instance.

Microsoft.VisualStudio.Tools.Applications.Runtime.ControlCouldNotBeInitializedException

The control argument is null.

Examples

The following code example adds two custom user controls to the document using the AddControl method. The first control is added to a Range. The second control is added to a specific location. The code changes the Top property of the first custom user control, which only moves the control relative to the ControlSite that contains the control on the document. The code then sets the Top property of the ControlSite returned by the second user control to illustrate the correct way to set the Top property of the control.

private void WordRangeAddControl()
{
    this.Paragraphs[1].Range.InsertParagraphBefore();
    UserControl1 customUserControl = new UserControl1();
    UserControl2 customUserControl2 = new UserControl2();

    Microsoft.Office.Tools.Word.ControlSite dynamicControl =
        this.Controls.AddControl(customUserControl, 
        this.Paragraphs[1].Range, 150, 150, "dynamicControl");

    Microsoft.Office.Tools.Word.ControlSite dynamicControl2 =
        this.Controls.AddControl(customUserControl2, 200, 0,
        150, 150, "dynamicControl2");

    customUserControl.BackColor = Color.Blue;
    customUserControl2.BackColor = Color.Green;
    
    customUserControl.Top = 100;
    dynamicControl2.Top = 100;
}

Private Sub WordRangeAddControl()
    Me.Paragraphs(1).Range.InsertParagraphBefore()
    Dim CustomUserControl As New UserControl1()
    Dim CustomUserControl2 As New UserControl2()

    Dim DynamicControl As Microsoft.Office.Tools.Word.ControlSite = _
        Me.Controls.AddControl(CustomUserControl, _
        Me.Paragraphs(1).Range, 150, 150, "DynamicControl")

    Dim DynamicControl2 As Microsoft.Office.Tools.Word.ControlSite = _
        Me.Controls.AddControl(CustomUserControl2, _
        200, 0, 150, 150, "DynamicControl2")

    CustomUserControl.BackColor = Color.Blue
    CustomUserControl2.BackColor = Color.Green

    CustomUserControl.Top = 100
    dynamicControl2.Top = 100
End Sub 

Remarks

This method can be used to add any control to the ControlCollection at run time. For more information, see Adding Controls to Office Documents at Run Time.