Agregar controles a documentos de Office en tiempo de ejecución
Actualización: Julio de 2008
Se aplica a |
|---|
La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados. Proyectos de nivel de documento
Proyectos de nivel de aplicación
Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto. |
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. A partir de Visual Studio 2008 Service Pack 1 (SP1), puede agregar los controles dinámicos a los documentos y libros utilizando complementos en el nivel de la aplicación.
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
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 las clases Microsoft.Office.Tools.Excel.ControlCollection y Microsoft.Office.Tools.Word.ControlCollection.
La forma en que obtiene acceso a las colecciones de controles depende del tipo de proyecto que está desarrollando:
En un proyecto en el nivel del documento para Excel, utilice la propiedad Worksheet.Controls de las clases Sheet1, Sheet2 y Sheet3. Para obtener más información sobre estas clases, vea Elemento host Worksheet.
En un proyecto en el nivel del documento para Word, utilice la propiedad Document.Controls de la clase ThisDocument. Para obtener más información acerca de esta clase, vea Elemento host Document.
En un proyecto en el nivel de la aplicación para Excel o Word, utilice la propiedad Controls del objeto Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document que se genera en tiempo de ejecución. Para obtener más información sobre cómo generar estos objetos en tiempo de ejecución, vea Ampliar documentos de Word y libros de Excel en complementos en el nivel de la aplicación en tiempo de ejecución.
Agregar controles
Las clases 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.
.gif "Nota") 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. 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 específicas, 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:
En Excel, use uno de los métodos AddControl() de la clase Microsoft.Office.Tools.Excel.ControlCollection.
En Word, use uno de los métodos AddControl() de la clase Microsoft.Office.Tools.Word.ControlCollection.
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. En Excel, este método devuelve un objeto OLEObject. En Word, este método devuelve un objeto OLEControl. Estos objetos definen cómo interactúa el control con la hoja de cálculo o el documento.
En el ejemplo de código siguiente se muestra cómo utilizar el método AddControl(Control, Range, String) para agregar dinámicamente un control personalizado de usuario a una hoja de cálculo. En este ejemplo, el control de usuario se denomina UserControl1 y Range se denomina range1. En este ejemplo se supone que se ejecuta desde una de las clases Sheetn de un proyecto en el nivel del documento para Excel.
Dim customControl As New UserControl1()
Dim dynamicControl As Microsoft.Office.Tools.Excel.OLEObject = _
Me.Controls.AddControl(customControl, range1, "dynamic")
UserControl1 customControl = new UserControl1();
Microsoft.Office.Tools.Excel.OLEObject 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.
OLEObject o OLEControl, que representa el control una vez agregado a la hoja de cálculo o documento.
Muchas propiedades y métodos se comparten entre estos controles. Es importante que tenga acceso a estos métodos y propiedades a través del control adecuado:
Para tener acceso a las propiedades y métodos que sólo pertenecen al control personalizado, utilice System.Windows.Forms.Control.
Para tener acceso a las propiedades y los métodos compartidos por los controles, utilice OLEObject o OLEControl.
Si tiene acceso a un método compartido o una propiedad de System.Windows.Forms.Control, podría producirse un error sin advertencia o notificación, o generarse resultados no válidos. Siempre utilice métodos o propiedades de OLEObject o 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 OLEObject 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 OLEObject, 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
Referencia
Otros recursos
Controles en documentos de Office
Historial de cambios
Fecha |
Historial |
Motivo |
|---|---|---|
|
Julio de 2008 |
Se agrega información sobre cómo agregar controles a documentos utilizando complementos en el nivel de la aplicación. |
Cambio de características de SP1. |