ControlCollection.AddControl Method (Control, , String) (2007 System)
Adds the specified Control to the ControlCollection at the specified range.
Namespace: Microsoft.Office.Tools.Excel
Assembly: Microsoft.Office.Tools.Excel.v9.0 (in Microsoft.Office.Tools.Excel.v9.0.dll)
Syntax
'Declaration
Public Function AddControl ( _
control As Control, _
range As Range, _
name As String _
) As OLEObject
'Usage
Dim instance As ControlCollection
Dim control As Control
Dim range As Range
Dim name As String
Dim returnValue As OLEObject
returnValue = instance.AddControl(control, _
range, name)
public OLEObject AddControl(
Control control,
Range range,
string name
)
public:
OLEObject^ AddControl(
Control^ control,
Range^ range,
String^ name
)
public function AddControl(
control : Control,
range : Range,
name : String
) : OLEObject
Parameters
control
Type: System.Windows.Forms.ControlThe control to be added to the ControlCollection instance.
range
Type: RangeA Range that provides the bounds for the control.
name
Type: System.StringThe name of the control that can be used to index the control in the ControlCollection instance.
Return Value
Type: Microsoft.Office.Tools.Excel.OLEObject
An OLEObject instance that represents the container created for the control.
Exceptions
Exception | Condition |
---|---|
ArgumentNullException | The control, name or range argument is nulla null reference (Nothing in Visual Basic), or the name argument has zero length. |
ControlNameAlreadyExistsException | A control with the same name is already in the ControlCollection instance. |
InvalidRangeException | The range that was specified is not valid. Multi-area ranges cannot be used. The range should be on the same worksheet as the ControlCollection instance. |
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.
Examples
The following code example adds two custom user controls to the worksheet using the AddControl method. The first control is added to a range of cells. 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 OLEObject that contains the control on the worksheet. The code then sets the Top property of the OLEObject returned by the second user control to illustrate the correct way to set the Top property of the control.
Private Sub ExcelRangeAddControl()
Dim CustomUserControl As New UserControl1()
Dim CustomUserControl2 As New UserControl2()
Dim DynamicControl As Microsoft.Office.Tools.Excel. _
OLEObject = Me.Controls.AddControl( _
customUserControl, 0, 0, 150, 150, _
"DynamicControl")
Dim DynamicControl2 As Microsoft.Office.Tools.Excel. _
OLEObject = 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
private void ExcelRangeAddControl()
{
UserControl1 customUserControl = new UserControl1();
UserControl2 customUserControl2 = new UserControl2();
Microsoft.Office.Tools.Excel.OLEObject dynamicControl =
this.Controls.AddControl(customUserControl,
0, 0, 150, 150, "dynamicControl");
Microsoft.Office.Tools.Excel.OLEObject dynamicControl2 =
this.Controls.AddControl(customUserControl2, 200, 0,
150, 150, "dynamicControl2");
customUserControl.BackColor = Color.Blue;
customUserControl2.BackColor = Color.Green;
customUserControl.Top = 100;
dynamicControl2.Top = 100;
}
.NET Framework Security
- Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.