ControlCollection.AddControl (Método) (Control, Range, String)

Artículo
08/10/2011

Agrega el objeto Control especificado a ControlCollection en el rango especificado.

Espacio de nombres: Microsoft.Office.Tools.Excel
Ensamblado: Microsoft.Office.Tools.Excel (en Microsoft.Office.Tools.Excel.dll)

Sintaxis

'Declaración
Function AddControl ( _
    control As Control, _
    range As Range, _
    name As String _
) As ControlSite

ControlSite AddControl(
    Control control,
    Range range,
    string name
)

Parámetros

control
Tipo: System.Windows.Forms.Control
Control que se va a agregar a la instancia de ControlCollection.

range
Tipo: Microsoft.Office.Interop.Excel.Range
Objeto Range que proporciona los límites del control.

name
Tipo: System.String
Nombre del control que puede usarse para indizar el control en la instancia de ControlCollection.

Valor devuelto

Tipo: Microsoft.Office.Tools.Excel.ControlSite
Objeto que representa el control que contiene el control especificado en la hoja de cálculo.

Excepciones

Excepción	Condición
ArgumentNullException	El argumento de nombre, rango o control es nullreferencia null (Nothing en Visual Basic), o el argumento de nombre tiene longitud cero.
ControlNameAlreadyExistsException	Ya existe un control con el mismo nombre en la instancia de ControlCollection.
InvalidRangeException	El intervalo especificado no es válido. No pueden utilizarse rangos multiárea. El rango debe estar en la misma hoja de cálculo que la instancia de ControlCollection.

Comentarios

Este método se puede utilizar para agregar cualquier control en tiempo de ejecución al objeto ControlCollection. Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.

Ejemplos

En el siguiente ejemplo de código se agregan dos controles de usuario personalizados a la hoja de cálculo con el método AddControl. El primer control se agrega a un rango de celdas. El segundo control se agrega a una ubicación específica. Mediante el código se cambia la propiedad Top del primer control de usuario personalizado, con lo que sólo se mueve el control en relación al objeto ControlSite que contiene el control en la hoja de cálculo. A continuación, el código establece la propiedad Top del objeto ControlSite que devuelve el segundo control de usuario para ilustrar la manera correcta de establecer la propiedad Top del control.

    Private Sub ExcelRangeAddControl()

        Dim CustomUserControl As New UserControl1()
        Dim CustomUserControl2 As New UserControl2()

        Dim DynamicControl As Microsoft.Office.Tools.Excel.ListObject = Me.Controls.AddControl( _
            CustomUserControl, 0, 0, 150, 150, _
            "DynamicControl")

        Dim DynamicControl2 As Microsoft.Office.Tools.Excel. _
            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

private void ExcelRangeAddControl()
{

    UserControl1 customUserControl = new UserControl1();
    UserControl2 customUserControl2 = new UserControl2();

    Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
        this.Controls.AddControl(customUserControl,
        0, 0, 150, 150, "dynamicControl");

    Microsoft.Office.Tools.Excel.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;
}

Seguridad de .NET Framework

Plena confianza para el llamador inmediato. Un código de confianza parcial no puede utilizar este miembro. Para obtener más información, vea Utilizar bibliotecas de código que no es de plena confianza.