Estendendo uma área de formulário com um suplemento
Embora você possa criar e executar formulário com áreas de formulário sem um suplemento COM, o uso de um suplemento COM permitirá que as áreas de formulário incluam lógica de negócios personalizada ou funcionalidade avançada. Ao contrário de personalizar páginas de formulário em um formulário padrão, você não usa o VBScript para gravar código atrás de um formulário; Em vez disso, você programa regiões de formulário com um suplemento COM. Seu suplemento implementará uma nova interface, FormRegionStartup. Os suplementos poderão usar Microsoft Forms controles 2.0 e controles do Microsoft Outlook em uma região de formulário. Este tópico descreve como implementar FormRegionStartup e acessar os controles do Outlook em uma área de formulário.
Especificando o uso de um suplemento
Ao registrar a região do formulário para uma classe de mensagem, crie uma chave no registro do Windows para essa classe de mensagem (se a chave ainda não existir) e especifique como dados, um sinal igual (=) seguido pelo ProgID do suplemento. Para obter mais informações sobre como registrar uma região de formulário no registro do Windows, consulte Especificando regiões de formulário no Registro do Windows.
Implementando FormRegionStartup
Na mesma classe que implementa a interface IDTExtensibility2 do suplemento COM, implemente a interface Outlook.FormRegionStartup , que é definida na biblioteca de tipos do Outlook. O Outlook chamará os quatro métodos nesta interface:
GetFormRegionStorage
Quando o Outlook estiver prestes a exibir uma região de formulário controlada por um suplemento, o Outlook chamará o método GetFormRegionStorage . Quando o suplemento recebe uma chamada do Outlook para GetFormRegionStorage especificando informações para uma região de formulário, o suplemento retornará informações para o layout. Essas informações podem ser um caminho local para o arquivo de layout (. Arquivo OFS), um objeto IStorage do Microsoft Windows ou uma matriz de bytes com o conteúdo do arquivo OFS, que permite que um suplemento armazene o OFS como um recurso. O Outlook usará as informações retornadas para instanciar controles e calcular o layout para a região do formulário. O Outlook também instanciará um objeto FormRegion para a região do formulário. O protótipo do método getFormRegionStorage no Microsoft Visual Basic e microsoft C# é mostrado abaixo.
No 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
No C#:
public object GetFormRegionStorage(string FormRegionName,
object Item,
int LCID,
Outlook.OlFormRegionMode FormRegionMode,
Outlook.OlFormRegionSize FormRegionSize)
BeforeFormRegionShow
Se GetFormRegionStorage for bem-sucedido, pouco antes da região do formulário ser exibida em uma janela inspetor ou no Painel de Leitura, o Outlook chamará BeforeFormRegionShow, passando o objeto FormRegion para o suplemento. O suplemento usará essa chance antes que a região do formulário seja exibida para atualizar qualquer coisa na interface do usuário, como alterar legendas de rótulo, conforme descrito na seção Acessar controles do Outlook abaixo e suprimir conteúdo irrelevante. Os protótipos do método Visual Basic e C# para BeforeFormRegionShow são mostrados abaixo.
No Visual Basic:
Public Sub BeforeFormRegionShow(ByVal Item As Object,
ByVal FormRegion As Microsoft.Office.Interop.Outlook.FormRegion) _
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.BeforeFormRegionShow
No C#:
public void BeforeFormRegionShow(object Item, Outlook.FormRegion FormRegion)
Acessando controles do Outlook
Ao usar um suplemento de COM para estender uma área de formulário, você normalmente atende a eventos de controle, chama métodos de controle ou lê e define propriedades de controle. Para acessar Microsoft Forms controles 2.0, controles do Outlook ou o objeto de tela de formulário em um suplemento, você deve adicionar uma referência à biblioteca de objetos Microsoft Forms 2.0. Adicionar essa referência permitirá o acesso ao namespace Microsoft.Vbe.Interop.Forms de seu projeto de suplemento.
Depois de adicionar a referência, como opção, você pode criar um alias para o namespace da biblioteca de tipos para facilitar o uso dos tipos incluídos. Para criar um alias, insira o código a seguir na parte superior do arquivo de código. Seguem exemplos de como fazer isso se você estiver criando seu suplemento em Visual Basic ou C#. Esses aliases também serão usados nos exemplos de código logo a seguir:
No Visual Basic:
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports Office = Microsoft.Office.Core
Imports MSForms = Microsoft.Vbe.Interop.Forms
No C#:
using Outlook = Microsoft.Office.Interop.Outlook;
using Office = Microsoft.Office.Core;
using MSForms = Microsoft.Vbe.Interop.Forms;
Você pode acessar controles por meio do objeto FormRegion obtido de BeforeFormRegionShow. A propriedade FormRegion.Form retorna um objeto que representa um formulário; você pode lançar esse objeto para a classe MSForms.UserForm (exposta na Microsoft Forms biblioteca de objetos 2.0) para acessar a tela do formulário para a região do formulário.
Cada instância do objeto UserForm tem uma coleção Controls que pode ser usada para acessar os controles individuais do objeto UserForm pelo nome do controle. Muitos controles do Microsoft Forms 2.0 têm equivalentes com tema que são controles do Outlook. Em uma área de formulário, o Outlook substitui os controles do Forms 2.0 que tenham controles equivalentes do Outlook pelos equivalentes com tema correspondentes. Depois de obter uma referência a um controle temático da coleção Controls , você pode lancá-la para o tipo adequado na biblioteca de tipos do Outlook. Em seguida, você poderá acessar todas as propriedades, métodos e eventos expostos para esses controles na biblioteca de tipos do Outlook. Ao contrário de personalizar formulários com VBScript, você poderá ouvir todos os eventos de controle e não apenas o evento Clique . Para obter mais informações sobre controle, consulte Controles em um formulário personalizado.
Os exemplos de código a seguir mostram como o método BeforeFormRegionShow usa o parâmetro de entradaFormRegion do Outlook para obter um objeto de formulário e, em seguida, o lança para uma classe MSForms.UserForm e acessa a coleção de controles no objeto UserForm . A tela de formulário representada por este objeto UserForm tem dois controles do Outlook: uma caixa de texto chamada OlkTextBox1 e uma caixa de seleção chamada OlkCheckBox1. Ela os lança para os tipos adequados de controle do Outlook e define os valores padrão para esses controles, conforme a seguir.
No 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
No 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
Quando o Outlook for iniciado, ele lê a lista de regiões de formulário do registro do Windows e o armazena em cache os dados. Com base nesses dados, se o Outlook perceber que um suplemento deve fornecer o manifesto XML para uma região de formulário, o Outlook usará o ProgID fornecido nos dados armazenados em cache e chamará o método GetFormRegionManifest implementado por esse suplemento para obter o XML necessário para exibir a região do formulário. Se o manifesto XML não for válido e não estiver de acordo com o esquema XML da área de formulário, o Outlook não poderá carregar a área de formulário.
Para obter mais informações sobre como especificar um ProgID durante o registro de uma área de formulário, consulte Especificando áreas de formulário no Registro do Windows.
Os protótipos de método do Visual Basic e C# para GetFormRegionManifest são mostrados a seguir.
No Visual Basic:
Public Function GetFormRegionManifest(ByVal FormRegionName As String,
ByVal LCID As Integer) _
Implements Microsoft.Office.Interop.Outlook.FormRegionStartup.GetFormRegionManifest
No C#:
public object GetFormRegionManifest(string FormRegionName, int LCID)
GetFormRegionIcon
Quando o Outlook for iniciado, ele lê a lista de regiões de formulário do registro do Windows e o armazena em cache os dados associados com as regiões de formulário. Se uma área de formulário foi registrada com um ProgID, Outlook será recorrer ao suplemento correspondente chamando sua implementação do GetFormRegionIcon para qualquer ícone no manifesto XML que tenha addin como o valor de um elemento filho do elemento de ícones. Para obter mais informações sobre o uso de um suplemento para especificar ícones, consulte Como: usar um suplemento para especificar ícones de uma área de formulário.
Os protótipos de método do Visual Basic e C# para GetFormRegionIcon são mostrados a seguir.
No 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
No C#:
public object GetFormRegionIcon(string FormRegionName, int LCID, Outlook.OlFormRegionIcon Icon)
Suporte e comentários
Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.
Comentários
Em breve: ao longo de 2024, vamos eliminar problemas do GitHub como o mecanismo de comentários para conteúdo e substituí-lo por um novo sistema de comentários. Para obter mais informações, consulte: https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de