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

Artículo
05/15/2013

Agrega el control especificado a la colección ControlCollection en el intervalo especificado y con el tamaño especificado.

Espacio de nombres: Microsoft.Office.Tools.Word
Ensamblados: Microsoft.Office.Tools.Word (en Microsoft.Office.Tools.Word.dll)
Microsoft.Office.Tools.Word.v4.0.Utilities (en Microsoft.Office.Tools.Word.v4.0.Utilities.dll)

Sintaxis

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

ControlSite AddControl(
    Control control,
    Range range,
    float width,
    float height,
    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.Word.Range
Range que proporciona la ubicación del control.

width
Tipo: System.Single
Ancho del control, expresado en puntos.

height
Tipo: System.Single
Alto del control, expresado en puntos.

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

Valor devuelto

Tipo: Microsoft.Office.Tools.Word.ControlSite
Objeto que representa el control que contiene el control especificado en el documento.

Excepciones

Excepción	Condición
ArgumentNullException	name, o argumento de range es nullreferencia null (Nothing en Visual Basic), o argumento de name tiene longitud cero.
ControlNameAlreadyExistsException	Ya existe un control con el mismo nombre en la instancia de ControlCollection.
ControlCouldNotBeInitializedException	El argumento control es nullreferencia null (Nothing en Visual Basic).

Comentarios

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

Ejemplos

En el ejemplo de código siguiente se agregan dos controles de usuario personalizados al documento mediante el método AddControl.El primer control se agrega a Range.El segundo control se agrega a una ubicación específica.El código cambia la propiedad Top del primer control de usuario personalizado, que sólo mueve el control con respecto al ControlSite que contiene el control en el documento.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 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

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;
}

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.