Agregar controles a documentos de Office en tiempo de ejecución

  • Artículo

Puede agregar controles a documentos de Microsoft Office Word 2003 y a libros de Microsoft Office Excel 2003, y también quitarlos, en tiempo de ejecución. Los controles que se agregan a los documentos en tiempo de ejecución se denominan controles dinámicos.

Se aplica a: la información de este tema se aplica a los proyectos de nivel de documento y los proyectos de nivel de aplicación para las siguientes aplicaciones: Excel 2007 y Excel 2010; Word 2007 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

En este tema se proporciona la información siguiente:

  • Administrar controles en tiempo de ejecución con colecciones de controles

  • Agregar controles host a documentos

  • Agregar controles de formularios Windows Forms a documentos

vínculo a vídeo Dispone de una demostración en vídeo relacionada en How Do I: Add Controls to a Document Surface at Runtime?.

Administrar controles en tiempo de ejecución con colecciones de controles

Para agregar, obtener o quitar controles de un documento en tiempo de ejecución, use métodos auxiliares de los objetos Microsoft.Office.Tools.Excel.ControlCollection y Microsoft.Office.Tools.Word.ControlCollection.

La forma en que se obtiene acceso a estos objetos depende del tipo de proyecto que se está desarrollando:

Agregar controles

Los tipos Microsoft.Office.Tools.Excel.ControlCollection y Microsoft.Office.Tools.Word.ControlCollection incluyen métodos auxiliares que puede utilizar para agregar controles host y controles de Windows Forms comunes a los documentos y las hojas de cálculo. Cada nombre de método tiene el formato Add<clase del control>, donde clase del control es el nombre de clase del control que desea agregar. Por ejemplo, para agregar un control NamedRange al documento, se utiliza el método AddNamedRange. Para obtener una lista completa de métodos auxiliares, vea Métodos auxiliares para controles host y Métodos auxiliares para controles de formularios Windows Forms.

En el siguiente ejemplo de código se agrega un NamedRange al objeto Sheet1 en un proyecto en el nivel del documento para Excel.

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Obtener acceso a los controles y eliminarlos

Puede utilizar la propiedad Controls de un objeto Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document para recorrer en iteración todos los controles del documento, incluso los que agregó en tiempo de diseño. Los controles que agrega en tiempo de diseño también se denominan controles estáticos.

Puede quitar los controles dinámicos llamando al método Delete del control o llamando al método Remove de cada colección Controls. En el siguiente ejemplo de código se utiliza el método Remove para quitar NamedRange de Sheet1 en un proyecto en el nivel del documento para Excel.

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

Los controles estáticos no se pueden quitar en tiempo de ejecución. Si intenta utilizar el método Remove o Delete para quitar un control estático, se iniciará una excepción CannotRemoveControlException.

Nota

No quite controles mediante programación en el controlador de eventos Shutdown del documento. Los elementos de la interfaz de usuario del documento dejan de estar disponibles cuando se provoca el evento Shutdown. Si desea quitar controles antes de que se cierre el documento, agregue su código al controlador de eventos de otro evento, como Document.BeforeClose o Document.BeforeSave para Word, o bien Workbook.BeforeClose o Workbook.BeforeSave para Excel.

Agregar controles host a documentos

Cuando agregue un control host a un documentos mediante programación, es preciso proporcionar un nombre que singularmente identifique ese control y, además, especificar dónde se agregará el control en el documento. Para obtener instrucciones concretas, consulte los temas siguientes:

Para obtener más información acerca de los controles de host, vea Información general sobre elementos y controles Host.

Cuando se guarda y cierra un documento, todos los controles host creados dinámicamente se desconectan de sus eventos y pierden la funcionalidad de enlace de datos. Puede agregar código a la solución para crear de nuevo los controles host cuando se vuelva a abrir el documento. Para obtener más información, vea Guardar controles dinámicos en documentos de Office.

Nota

No se proporcionan métodos auxiliares para los controles host siguientes, ya que estos controles no se pueden agregar a los documentos mediante programación: XmlMappedRange, XMLNode y XMLNodes.

Agregar controles de formularios Windows Forms a documentos

Cuando agrega un control de formularios Windows Forms a un documento mediante programación, debe proporcionar la ubicación del control y un nombre que lo identifique de forma única. El Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office proporciona métodos auxiliares para cada control. Estos métodos se sobrecargan, de modo que puede pasar un intervalo o coordenadas específicas para la ubicación del control. Para obtener instrucciones concretas, vea Cómo: Agregar controles de Windows Forms a documentos de Office.

Cuando un documento se guarda y, a continuación, se cierra, todos los controles de Windows Forms creados dinámicamente se quitan del documento. Puede agregar código a la solución para crear de nuevo los controles cuando se vuelva a abrir el documento. Si crea controles dinámicos de Windows Forms utilizando un complemento en el nivel de la aplicación, los contenedores de ActiveX para los controles permanecen en el documento. Para obtener más información, vea Guardar controles dinámicos en documentos de Office.

Nota

Los controles de formularios Windows Forms no se pueden agregar mediante programación a los documentos protegidos. Si anula la protección de un documento de Word o una hoja de cálculo de Excel mediante programación para agregar un control, debe escribir código adicional para quitar el contenedor de ActiveX del control cuando se cierre el documento. El contenedor de ActiveX del control no se elimina automáticamente de los documentos protegidos.

Agregar controles personalizados

Si desea agregar un control System.Windows.Forms.Control no admitido por los métodos auxiliares disponibles (por ejemplo, un control de usuario personalizado), use los métodos siguientes:

Para agregar el control, pase al método AddControl el control System.Windows.Forms.Control, una ubicación para el control y un nombre que lo identifique de forma única. El método AddControl devuelve un objeto que define cómo el control interactúa con la hoja de cálculo o el documento. El tipo del objeto devuelto depende del proyecto:

  • Para los proyectos destinados a .NET Framework 4, este método devuelve un objeto Microsoft.Office.Tools.Word.ControlSite (para Excel) o un objeto Microsoft.Office.Tools.Excel.ControlSite (para Word).

  • Para los proyectos destinados a .NET Framework 3.5, este método devuelve un objeto Microsoft.Office.Tools.Word.OLEControl (para Excel) o un objeto Microsoft.Office.Tools.Excel.OLEObject (para Word).

En el siguiente ejemplo de código, se muestra cómo utilizar el método AddControl(Control, Range, String) para agregar dinámicamente un control de usuario personalizado a una hoja de cálculo en un proyecto de nivel de documento de Excel destinado a .NET Framework 4. En este ejemplo, el control de usuario se denomina UserControl1, y el Range se denomina range1. Para usar este ejemplo, ejecútelo desde una clase Sheetn en el proyecto.

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.ControlSite = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Utilizar miembros de controles personalizados

Después de utilizar uno de los métodos AddControl para agregar un control a una hoja de cálculo o un documento, ahora tiene dos objetos de control diferentes:

  • System.Windows.Forms.Control, que representa el control personalizado.

  • Objeto ControlSite, OLEObject u OLEControl que representa el control una vez agregado a la hoja de cálculo o el documento.

Muchas propiedades y métodos se comparten entre estos controles. Es importante que obtenga acceso a estos miembros a través del control adecuado:

  • Para obtener acceso a los miembros que solo pertenecen al control personalizado, utilice System.Windows.Forms.Control.

  • Para obtener acceso a los miembros compartidos por los controles, use el objeto ControlSite, OLEObject u OLEControl.

Si obtiene acceso a un miembro compartido de System.Windows.Forms.Control, podría producirse un error sin advertencia o notificación, o podrían generarse resultados no válidos. Siempre utilice métodos o propiedades del objeto ControlSite, OLEObject u OLEControl, a menos que el método o la propiedad que se necesite no esté disponible; únicamente en este caso se debe hacer referencia a System.Windows.Forms.Control.

Por ejemplo, las clases ControlSite y System.Windows.Forms.Control tienen una propiedad Top. Para obtener o establecer la distancia entre la parte superior del control y la parte superior del documento, utilice la propiedad Top de ControlSite, no la propiedad Top de System.Windows.Forms.Control.

' Property is set in relation to the document.
dynamicControl.Top = 100

' Property is set in relation to the container control.
customControl.Top = 100

// Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Vea también

Tareas

Cómo: Agregar controles ListObject a hojas de cálculo

Cómo: Agregar controles NamedRange a hojas de cálculo

Cómo: Agregar controles Chart a hojas de cálculo

Cómo: Agregar controles de contenido a documentos de Word

Cómo: Agregar controles Bookmark a documentos de Word

Cómo: Agregar controles de Windows Forms a documentos de Office

Conceptos

Guardar controles dinámicos en documentos de Office

Métodos auxiliares para controles host

Métodos auxiliares para controles de formularios Windows Forms

Información general sobre controles de formularios Windows Forms en documentos de Office

Otros recursos

Controles en documentos de Office