Compartir a través de

Extender un área de formulario con un complemento

  • Artículo

Si bien puede crear y ejecutar formularios con áreas del formulario sin un complemento COM, el uso de un complemento COM permitirá que las áreas del formulario incluyan lógica empresarial personalizada o funcionalidad avanzada. A diferencia de la personalización de páginas de formulario en un formulario estándar, no se usa VBScript para escribir código detrás de un formulario; en su lugar, se programan regiones de formulario con un complemento COM. El complemento implementará una nueva interfaz FormRegionStartup. Los complementos podrán usar controles de Microsoft Forms 2.0 y controles de Microsoft Outlook en un área del formulario. En este tema se describe de qué manera se puede implementar FormRegionStartup y obtener acceso a los controles de Outlook en un área del formulario.

Especificar el uso de un complemento

Al registrar el área de formulario de una clase de mensaje, cree una clave en el Registro de Windows para esa clase de mensaje (si la clave aún no existe) y especifique como datos, un signo igual (=) seguido del ProgID del complemento. Para obtener más información sobre cómo registrar un área de formulario en el Registro de Windows, vea Especificar regiones de formulario en el Registro de Windows.

Implementar FormRegionStartup

En la misma clase que implementa la interfaz IDTExtensibility2 del complemento COM, implemente la interfaz Outlook.FormRegionStartup, que se define en la biblioteca de tipos de Outlook. Outlook llamará a los cuatro métodos que componen esta interfaz:

GetFormRegionStorage

Cuando Outlook esté a punto de mostrar un área del formulario controlada por un complemento, llamará al método GetFormRegionStorage. Cuando el complemento reciba una llamada desde Outlook al método GetFormRegionStorage especificando información para un área del formulario, el complemento devolverá información para el diseño. Esta información puede ser una ruta de acceso local al archivo de diseño (. Archivo OFS), un objeto IStorage de Microsoft Windows o una matriz de bytes con el contenido del archivo OFS, lo que permite a un complemento almacenar el OFS como un recurso. Outlook usará la información devuelta para crear instancias de los controles y calcular el diseño para el área del formulario. Outlook también creará instancias de un objeto FormRegion para el área del formulario. A continuación se muestran los prototipos de métodos para GetFormRegionStorage en Microsoft Visual Basic y Microsoft C#.

En Visual Basic:

Public Function GetFormRegionStorage(ByVal FormRegionName As String,
    ByVal Item As Object, 
    ByVal LCID As Integer, 
    _ ByVal FormRegionMode As Outlook.OlFormRegionMode, 
    ByVal FormRegionSize As Outlook.OlFormRegionSize) _ 
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionStorage

En C#:

public object GetFormRegionStorage(string FormRegionName, 
    object Item, 
    int LCID,
    Outlook.OlFormRegionMode FormRegionMode, 
    Outlook.OlFormRegionSize FormRegionSize)

BeforeFormRegionShow

Si GetFormRegionStorage finaliza correctamente, justo antes de mostrar el área del formulario en una ventana del inspector o en el panel de lectura, Outlook llamará a BeforeFormRegionShow y pasará el objeto FormRegion al complemento. El complemento usará esta oportunidad antes de que se muestre el área de formulario para actualizar cualquier elemento de la interfaz de usuario, como cambiar los títulos de etiqueta, como se describe en la sección Acceso a los controles de Outlook a continuación, y suprimir contenido irrelevante. A continuación se muestran los prototipos de método de Visual Basic o C#, para BeforeFormRegionShow.

En Visual Basic:

Public Sub BeforeFormRegionShow(ByVal Item As Object, 
    ByVal FormRegion As Microsoft.Office.Interop.Outlook.FormRegion) _ 
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.BeforeFormRegionShow

En C#:

public void BeforeFormRegionShow(object Item, Outlook.FormRegion FormRegion)

Tener acceso a los controles de Outlook

Al usar un complemento COM para extender un área del formulario, es habitual escuchar los eventos de los controles, llamar a los métodos de los controles o leer y establecer las propiedades de los controles. Para obtener acceso a controles de Microsoft Forms 2.0, controles de Outlook o al objeto de lienzo de formulario desde un complemento, debe agregar una referencia a la biblioteca de objetos de Microsoft Forms 2.0. Al agregar esta referencia obtendrá acceso al espacio de nombres Microsoft.Vbe.Interop.Forms en el proyecto del complemento.

Después de agregar la referencia, también puede crear un alias para el espacio de nombres de la biblioteca de tipos para facilitar el uso de los tipos incluidos. Para crear un alias, escriba el código siguiente al principio del archivo de código. Los siguientes ejemplos muestran cómo hacerlo si está escribiendo el complemento en Visual Basic o en C#. Estos alias también se emplearán en los ejemplos de código del final de este tema:

En Visual Basic:

Imports Outlook = Microsoft.Office.Interop.Outlook 
Imports Office = Microsoft.Office.Core  
Imports MSForms = Microsoft.Vbe.Interop.Forms

En C#:

using Outlook = Microsoft.Office.Interop.Outlook; 
using Office = Microsoft.Office.Core; 
using MSForms = Microsoft.Vbe.Interop.Forms;

Puede obtener acceso a los controles a través del objeto FormRegion obtenido a partir de BeforeFormRegionShow. La propiedad FormRegion.Form devuelve un objeto que representa un formulario; es posible convertir este objeto en la clase MSForms.UserForm (que se expone en la biblioteca de objetos de Microsoft Forms 2.0) para obtener acceso al lienzo de formulario para el área del formulario.

Cada instancia del objeto UserForm tiene una colección Controls que puede usarse para obtener acceso a cada uno de los controles del objeto UserForm usando sus nombres. Un gran número de los controles de Microsoft Forms 2.0 tienen homólogos con temas que son controles de Outlook. En un área del formulario, Outlook reemplaza dichos controles de Forms 2.0 que tienen controles homólogos de Outlook por los homólogos con temas correspondientes. Una vez que haya obtenido una referencia a un control con temas de la colección Controls puede convertirla en el tipo apropiado de la biblioteca de tipos de Outlook. A continuación, podrá acceder a todas las propiedades, métodos y eventos expuestos para estos controles en la biblioteca de tipos de Outlook. A diferencia de la personalización de formularios con VBScript, podrá escuchar todos los eventos de control y no solo el evento Click . Para obtener más información sobre los controles, consulte el tema sobre los controles en un formulario personalizado.

En los ejemplos de código siguientes se muestra cómo el método BeforeFormRegionShow usa el parámetro de entradaFormRegion de Outlook para obtener un objeto de formulario y, a continuación, lo convierte en una clase MSForms.UserForm y obtiene acceso a la colección de controles del objeto UserForm . El lienzo de formulario representado por este objeto UserForm tiene dos controles de Outlook: un cuadro de texto denominado OlkTextBox1 y una casilla denominada OlkCheckBox1. Los convierte en los tipos de controles de Outlook apropiados y establece valores predeterminados para estos controles de la siguiente manera.

En Visual Basic:

Dim UserForm As MSForms.UserForm 
Dim FormControls As MSForms.Controls 
Dim TextBox1 As Outlook.OlkTextBox 
Dim CheckBox1 As Outlook.OlkCheckBox 
 
UserForm = FormRegion.Form 
FormControls = UserForm.Controls 
 
TextBox1 = FormControls.Item("OlkTextBox1") 
TextBox1.Text = "Sample Form Region" 
CheckBox1 = FormControls.Item("OlkCheckBox1") 
CheckBox1.Value = True

En C#:

MSForms.UserForm userForm = (MSForms.UserForm)FormRegion.Form; 
MSForms.Controls formControls = userForm.Controls; 
 
Outlook.OlkTextBox textBox1 =  
   (Outlook.OlkTextBox)formControls.Item("OlkTextBox1"); 
textBox1.Text = "Sample Form Region"; 
 
Outlook.OlkCheckBox checkBox1 =  
   (Outlook.OlkCheckBox)formControls.Item("OlkCheckBox1"); 
checkBox1.Value = true;

GetFormRegionManifest

Cuando se inicia, Outlook lee la lista de áreas del formulario desde el Registro de Windows y copia los datos en caché. Sobre la base de estos datos, si Outlook nota que un complemento va a proporcionar el manifiesto XML a un área del formulario, usará el ProgID proporcionado en los datos en caché y llamará al método GetFormRegionManifest implementado por este complemento para obtener el XML que necesita para mostrar el área del formulario. Si el manifiesto XML no es válido y no cumple con el esquema XML del área del formulario, Outlook no podrá cargar el área del formulario.

Para obtener más información sobre cómo especificar un ProgID cuando se registra un área del formulario, consulte el tema sobre cómo especificar áreas del formulario en el Registro de Windows.

A continuación se muestran los prototipos de método de Visual Basic o C# para GetFormRegionManifest.

En Visual Basic:

Public Function GetFormRegionManifest(ByVal FormRegionName As String, 
    ByVal LCID As Integer) _
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionManifest

En C#:

public object GetFormRegionManifest(string FormRegionName, int LCID)

GetFormRegionIcon

Cuando se inicia Outlook, lee la lista de áreas de formulario en el registro de Windows y almacena en caché los datos asociados con las áreas de formulario. Si un área de formulario se ha registrado con un ProgID, Outlook recurrirá llamando a su implementación de GetFormRegionIcon para cualquier icono en el manifiesto XML que tiene addin como el valor de un elemento secundario del elemento de iconos para el complemento correspondiente. Si desea obtener más información sobre el modo de usar un complemento para especificar iconos, consulte el tema sobre los procedimientos para usar un complemento para especificar iconos para un área del formulario.

A continuación se muestran los prototipos de método de Visual Basic o C# para GetFormRegionIcon.

En Visual Basic:

Public Function GetFormRegionIcon(ByVal FormRegionName As String, 
    ByVal LCID As Integer, _ 
    ByVal Icon As Outlook.OlFormRegionIcon) _ 
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionManifest

En C#:

public object GetFormRegionIcon(string FormRegionName, int LCID, Outlook.OlFormRegionIcon Icon)

Soporte técnico y comentarios

¿Tiene preguntas o comentarios sobre VBA para Office o esta documentación? Vea Soporte técnico y comentarios sobre VBA para Office para obtener ayuda sobre las formas en las que puede recibir soporte técnico y enviar comentarios.