Información general sobre elementos y controles Host
Actualización: Julio de 2008
Se aplica a |
|---|
La información de este tema sólo se aplica a los proyectos y versiones especificados de Visual Studio Tools para Office de Microsoft Office. Proyectos de nivel de documento
Proyectos de nivel de aplicación
Para obtener más información, consulte Características disponibles por aplicación y tipo de proyecto. |
Los elementos y los controles host son clases que proporcionan el modelo de programación para las soluciones en el nivel del documento de Visual Studio Tools para Office. Interactúan con los modelos de objetos de Microsoft Office Word y Microsoft Office Excel, que están basados en COM, más que con objetos administrados, como los controles de formularios Windows Forms.
Elementos host
Los elementos host son clases que están en la parte superior de las jerarquías del modelo de objetos en proyectos de Visual Studio Tools para Office. Visual Studio Tools para Office define los elementos host siguientes para soluciones de Word y Excel:
Cada una de estas clases extiende una clase que existe de manera nativa en el modelo de objetos de Word o Excel (denominado objeto de Office nativo). Por ejemplo, el elemento host Microsoft.Office.Tools.Word.Document extiende la clase Microsoft.Office.Interop.Word.Document, que se define en el ensamblado de interoperabilidad primario para Word.
Los elementos host tienen, generalmente, la misma funcionalidad básica que los objetos de Office correspondientes, pero están mejorados con las características siguientes:
Capacidad de hospedar controles host administrados, incluidos los controles host y los controles de formularios Windows Forms.
Modelos de eventos más completos. Algunos eventos de documento, libro y hoja de cálculo de los modelos de objetos nativos de Word y de Excel solo se provocan en el nivel de la aplicación. Los elementos host proporcionan estos eventos en el nivel del documento, para que sea más fácil controlar los eventos para un documento concreto.
Comprender los elementos host de proyectos en el nivel del documento
En los proyectos en el nivel del documento, los elementos host proporcionan un punto de entrada para el código y tienen diseñadores que ayudan a desarrollar la solución.
Los elementos host Microsoft.Office.Tools.Word.Document y Microsoft.Office.Tools.Excel.Worksheet tienen diseñadores que son la representación visual del documento o de la hoja, igual que un diseñador de formularios Windows Forms. Puede utilizar este diseñador para modificar directamente el contenido del documento en Word o de la hoja de cálculo en Excel, y para arrastrar los controles a la superficie de diseño. Para obtener más información, consulte Elemento host Document y Elemento host Worksheet.
El elemento host Microsoft.Office.Tools.Excel.Workbook no actúa como un contenedor para los controles que tienen interfaz de usuario. En cambio, el diseñador de este elemento host funciona como una bandeja de componentes que permite arrastrar un componente, como DataSet, a la superficie de diseño. Para obtener más información, consulte Elemento host Workbook.
No pueden crearse elementos host mediante programación en los proyectos en el nivel del documento. En su lugar, utilice las clases ThisDocument, ThisWorkbook o Sheetn que Visual Studio Tools para Office genera automáticamente en tiempo de diseño en el proyecto. Estas clases generadas derivan de las clases del elemento host y proporcionan un punto de entrada para el código. Para obtener más información, vea Limitaciones de programación de elementos y controles Host.
Comprender los elementos host de proyectos en el nivel de la aplicación
Al crear un complemento en el nivel de la aplicación, no tiene acceso a los elementos host de forma predeterminada. Sin embargo, a partir de Visual Studio 2008 Service Pack 1 (SP1), puede generar elementos host Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbooky Microsoft.Office.Tools.Excel.Worksheet en los complementos en tiempo de ejecución.
Después de generar un elemento host, puede hacer tareas como agregar controles a los documentos y crear etiquetas inteligentes que se reconocen en un documento concreto. Para obtener más información, vea Ampliar documentos de Word y libros de Excel en complementos en el nivel de la aplicación en tiempo de ejecución.
Controles de host
Los controles host amplían varios objetos de la interfaz de usuario en los modelos de objetos de Excel y Word, como los objetos Microsoft.Office.Interop.Excel.Range y Microsoft.Office.Interop.Word.ContentControl.
Los controles host siguientes están disponibles con proyectos de Excel:
Los controles host siguientes están disponibles con proyectos de Word:
Los controles host agregados a los documentos de Office se comportan como los objetos nativos de Office; sin embargo, los controles host poseen funcionalidad adicional que incluye eventos y capacidades de enlace a datos. Por ejemplo, cuando desea capturar los eventos de un objeto Microsoft.Office.Interop.Excel.Range nativo en Excel, en primer lugar debe administrar el evento de cambio de la hoja de cálculo. A continuación debe determinar si el cambio se produjo dentro de los intervalos Microsoft.Office.Interop.Excel.Range. En cambio, el control host Microsoft.Office.Tools.Excel.NamedRange tiene un evento Change que se puede administrar directamente.
La relación entre un elemento host y los controles host es muy parecida a la relación entre un formulario Windows Forms y los controles de formularios Windows Forms. Igual que colocaría un control de cuadro de texto en un formulario Windows Forms, puede colocar un control Microsoft.Office.Tools.Excel.NamedRange en un elemento host Microsoft.Office.Tools.Excel.Worksheet. En la ilustración siguiente se muestra la relación entre los elementos host y los controles host.
.png)
Además, Visual Studio Tools para Office permite utilizar controles de formularios Windows Forms en las soluciones de Office si se agregan directamente en la superficie del documento de Word y Excel. Para obtener más información, consulte Información general sobre controles de formularios Windows Forms en documentos de Office.
.gif "Nota") Nota: |
|---|
No se pueden agregar controles host ni controles de formularios Windows Forms a un subdocumento de Word. |
Agregar controles host a sus documentos
En proyectos en el nivel del documento, puede agregar en tiempo de diseño los controles host a los documentos de Word o a las hojas de cálculo de Excel de las maneras siguientes:
Agregue los controles host al documento en tiempo de diseño de la misma manera que agregaría un objeto nativo.
Arrastre los controles host desde el Cuadro de herramientas hasta los documentos y hojas de cálculo. Los controles host de Excel están disponibles en la ficha Controles de Excel en los proyectos de Excel, mientras que los controles host de Word se encuentran en la ficha Controles de Word en los proyectos de Word.
Arrastre los controles host desde la ventana Orígenes de datos hasta los documentos y hojas de cálculo. Esto permite agregar controles ya enlazados a datos. Para obtener más información, vea Enlazar datos a controles.
A partir del SP1, en proyectos en el nivel del documento y en proyectos en el nivel de la aplicación puede agregar también controles host a los documentos en tiempo de ejecución. Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.
Para obtener más información sobre cómo agregar controles host a los documentos, vea los temas siguientes:
Nombres de los controles host
Si arrastra un control host desde el Cuadro de herramientas hasta el documento, se asignará automáticamente al control un nombre en el que se utiliza el tipo de control y un número incremental al final. Por ejemplo, los marcadores se denominan bookmark1, bookmark2, etc. Si utiliza la funcionalidad nativa de Word o Excel para agregar el control, puede darle un nombre específico en el momento de crearlo. También es posible cambiar el nombre de los controles cambiando el valor de la propiedad Name en la ventana Propiedades.
| Nota: |
|---|
No puede utilizar palabras reservadas como nombre de los controles host. Por ejemplo, si agrega un control NamedRange a una hoja de cálculo y le cambia el nombre a System, se producirán errores cuando genere el proyecto. |
Eliminar controles host
En la mayoría de los proyectos en el nivel del documento, los controles host se pueden eliminar en tiempo de diseño seleccionando el control en la hoja de cálculo de Excel o en el documento de Word y presionando la tecla SUPR. Sin embargo, se debe utilizar el cuadro de diálogo Definir nombre en Excel para eliminar controles NamedRange. Para obtener más información, consulte Cómo: Eliminar controles NamedRange en tiempo de diseño.
Si agrega un control host a un documento en tiempo de diseño, no debe quitarlo mediante programación en tiempo de ejecución porque la próxima vez que intente utilizar el control en el código, se produce una excepción. El método Delete de un control host sólo quita controles host agregados al documento en tiempo de ejecución. Si llama al método Delete de un control host creado en tiempo de diseño, se produce una excepción.
Por ejemplo, el método Delete de una NamedRange solo elimina correctamente el NamedRange si se agregó mediante programación a la hoja de cálculo, lo que se conoce como crear controles host dinámicamente. Los controles host creados dinámicamente también pueden quitarse pasando el nombre del control al método Remove de la propiedad Worksheet.Controls o Document.Controls. Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.
Si los usuarios finales eliminan un control host del documento en tiempo de ejecución, se podrían producir errores inesperados en la solución. Es posible utilizar las características de protección de documentos de Word y Excel para evitar que se eliminen los controles host. Para obtener más información, vea Ejemplo Word Document Protection Techniques y Ejemplo Excel Document Protection Techniques.
| Nota: |
|---|
No quite controles mediante programación durante el funcionamiento del controlador de eventos Shutdown del documento o de la hoja de cálculo. Los elementos de la interfaz de usuario dejan de estar disponibles cuando se produce el evento Shutdown. Si desea quitar controles antes de que se cierre la aplicación, agregue su código a otro controlador de eventos como BeforeClose o BeforeSave. |
Programar basándose en eventos de controles host
Una manera en que los controles host extienden los objetos de Office es agregando eventos. Por ejemplo, el objeto Microsoft.Office.Interop.Excel.Range de Excel y el objeto Microsoft.Office.Interop.Word.Bookmark de Word no tienen eventos, pero Visual Studio Tools para Office extiende estos objetos agregándoles eventos programables. Puede obtener acceso a estos eventos y escribir código basado en ellos de la misma manera que tiene acceso a los eventos de controles de formularios Windows Forms: a través de la lista desplegable de eventos en Visual Basic y la página de propiedades de eventos en C#. Para obtener más información, vea Tutorial: Programar basándose en los eventos de un control NamedRange.
| Nota: |
|---|
No debe establecer la propiedad EnableEvents del objeto Application de Excel en false. Establecer esta propiedad en false impide que Excel active cualquier evento, incluidos los evento de los controles host. |
Vea también
Conceptos
Limitaciones de programación de elementos y controles Host
Otros recursos
Controles en documentos de Office
Historial de cambios
Fecha |
Historial |
Motivo |
|---|---|---|
|
Julio de 2008 |
100% 92%> SP1_Conceptual_Review maborrachero 8/11/2008 12:04:08 PM Added information about using host items and host controls in application-level add-ins. Different match in memory: Se agrega información sobre el uso de elementos y controles host en los complementos en el nivel de la aplicación. Added information about using host items and host controls in application-level add-ins. Se agrega información sobre el uso de elementos y controles host en los complementos en el nivel de la aplicación. |
Cambio de características de SP1. |