Visão geral do modelo de objeto da faixa de opções

O Visual Studio Tools for Office runtime expõe um modelo de objeto fortemente tipado que você pode usar para obter e definir as propriedades de controles da Faixa de Opções em tempo de execução. Por exemplo, você pode preencher dinamicamente controles de menu ou mostrar e ocultar controles contextualmente. Você também pode adicionar guias, grupos e controles a uma faixa de opções, mas somente antes que a faixa de opções seja carregada pelo aplicativo do Office. Para obter informações, consulte Definir propriedades que se tornam somente leitura.

Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de suplemento VSTO para os seguintes aplicativos: Excel; InfoPath 2013 e InfoPath 2010; Perspectiva; PowerPoint; Projeto; Visio; Palavra. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Esse modelo de objeto da Faixa de Opções consiste principalmente nas classes de controle Ribbon, Ribbon e Ribbon.

Classe da faixa de opções

Quando você adiciona um novo item da Faixa de Opções (Visual Designer) a um projeto, o Visual Studio adiciona uma classe da Faixa de Opções ao seu projeto. A classe Ribbon herda da RibbonBase classe.

Essa classe aparece como uma classe parcial que é dividida entre o arquivo de código da Faixa de Opções e o arquivo de código do Designer da Faixa de Opções.

Eventos da faixa de opções

A classe Ribbon contém os três eventos a seguir:

Evento	Descrição
Load	Gerado quando o aplicativo do Office carrega a personalização da Faixa de Opções. O Load manipulador de eventos é adicionado automaticamente ao arquivo de código da Faixa de Opções. Use esse manipulador de eventos para executar código personalizado quando a faixa de opções for carregada.
LoadImage	Permite armazenar em cache imagens na personalização da Faixa de Opções quando a faixa de opções é carregada. Você pode obter um ligeiro ganho de desempenho se escrever código para armazenar em cache as imagens da Faixa de Opções nesse manipulador de eventos. Para obter mais informações, consulte LoadImage.
Close	Gerado quando a instância da Faixa de Opções é fechada.

Controles da faixa de opções

O Microsoft.Office.Tools.Ribbon namespace contém um tipo para cada controle que você vê no grupo Controles da Faixa de Opções do Office da Caixa de Ferramentas.

A tabela a seguir mostra o tipo para cada Ribbon controle. Para obter uma descrição de cada controle, consulte Visão geral da faixa de opções.

Nome do controle	Nome da classe
Box	RibbonBox
Botão	RibbonButton
Grupo de botões	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
Caixa de Edição	RibbonEditBox
Galeria	RibbonGallery
Grupo	RibbonGroup
Rótulo	RibbonLabel
Menu	RibbonMenu
Separador	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	RibbonTab
ToggleButton	RibbonToggleButton

O Microsoft.Office.Tools.Ribbon namespace usa o prefixo "Ribbon" para esses tipos para evitar uma colisão de nome com os nomes de classes de controle no System.Windows.Forms namespace.

Quando você adiciona um controle ao Designer da Faixa de Opções, o Designer da Faixa de Opções declara a classe desse controle como um campo no arquivo de código do Designer da Faixa de Opções.

Tarefas comuns usando as propriedades dos controles da Faixa de Opções

Cada Ribbon controle contém propriedades que você pode usar para executar várias tarefas, como atribuir um rótulo a um controle ou ocultar e mostrar controles.

Em alguns casos, as propriedades se tornam somente leitura depois que a Faixa de Opções é carregada ou depois que um controle é adicionado a um menu dinâmico. Para obter mais informações, consulte Definir propriedades que se tornam somente leitura.

A tabela a seguir descreve algumas das tarefas que você pode executar usando Ribbon propriedades de controle.

Para esta tarefa:	Faça isto
Ocultar ou mostrar um controle.	Use a propriedade Visible.
Habilitar ou desabilitar um controle.	Use a propriedade Enabled.
Defina o tamanho de um controle.	Use a propriedade ControlSize.
Obtenha a imagem que aparece em um controle.	Use a propriedade Image.
Alterar o rótulo de um controle.	Use a propriedade Label.
Adicione dados definidos pelo usuário a um controle.	Use a propriedade Tag.
Obter os itens em um RibbonBox, RibbonDropDown, RibbonGalleryou RibbonSplitButton Controle.	Use a propriedade Items.
Adicione itens a um RibbonComboBoxcontrole , RibbonDropDownou RibbonGallery .	Use a propriedade Items.
Adicionar controles a um RibbonMenuarquivo .	Use a propriedade Items. Para adicionar controles ao RibbonMenu depois que a Faixa de Opções é carregada no aplicativo do Office, você deve definir a propriedade como true antes que a Dynamic Faixa de Opções seja carregada no aplicativo do Office. Para obter informações, consulte Definir propriedades que se tornam somente leitura.
Obter o item selecionado de um RibbonComboBox, RibbonDropDown ou RibbonGallery.	Use a propriedade SelectedItem. Para um RibbonComboBox, use a Text propriedade.
Coloque os grupos em um RibbonTabarquivo .	Use a propriedade Groups.
Especifique o número de linhas e colunas que aparecem em um RibbonGalleryarquivo .	Use as RowCount propriedades e ColumnCount .

Definir propriedades que se tornam somente leitura

Algumas propriedades só podem ser definidas antes do carregamento da faixa de opções. Há três locais para definir essas propriedades:

• Na janela Propriedades do Visual Studio.

• No construtor da classe Ribbon .

• CreateRibbonExtensibilityObject No método do , ThisWorkbookou ThisDocument classe do ThisAddinseu projeto.

  Os menus dinâmicos fornecem algumas exceções. Você pode criar novos controles, definir suas propriedades e adicioná-los a um menu dinâmico em tempo de execução, mesmo depois que a faixa de opções que contém o menu for carregada.

  As propriedades dos controles que você adiciona a um menu dinâmico podem ser definidas a qualquer momento.

  Para obter mais informações, consulte Propriedades que se tornam somente leitura.

Definir propriedades no construtor da faixa de opções

Você pode definir as propriedades de um Ribbon controle no construtor da classe Ribbon . Esse código deve aparecer após a chamada para o InitializeComponent método. O exemplo a seguir adiciona um novo botão a um grupo se a hora atual for 17:00 Hora do Pacífico (UTC-8) ou posterior.

Adicione o código a seguir.

C#

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

VB

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

Em projetos do Visual C# que você atualizou do Visual Studio 2008, o construtor aparece no arquivo de código da faixa de opções.

Em projetos do Visual Basic ou em projetos do Visual C# que você criou no Visual Studio 2013, o construtor aparece no arquivo de código do Designer da Faixa de Opções. Esse arquivo é chamado YourRibbonItem. Designer.cs ou YourRibbonItem. Desenhista.vb. Para ver esse arquivo em projetos do Visual Basic, você deve primeiro clicar no botão Mostrar todos os arquivos no Gerenciador de Soluções.

Definir propriedades no método CreateRibbonExtensibilityObject

Você pode definir as propriedades de um Ribbon controle quando você substituir o CreateRibbonExtensibilityObject método na ThisAddinclasse , ThisWorkbookou ThisDocument do seu projeto. Para obter mais informações sobre o método, consulte Visão geral da CreateRibbonExtensibilityObject faixa de opções.

O exemplo a seguir define as CreateRibbonExtensibilityObject propriedades da Faixa de Opções no método da classe de um projeto de pasta de ThisWorkbook trabalho do Excel.

Adicione o código a seguir.

C#

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

VB

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

Propriedades que se tornam somente leitura

A tabela a seguir mostra propriedades que só podem ser definidas antes do carregamento da faixa de opções.

Observação

Você pode definir as propriedades dos controles em menus dinâmicos a qualquer momento. Esta tabela não se aplica nesse caso.

Propriedade	Classe de controle da faixa de opções
BoxStyle	RibbonBox
Tipo de botão	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Dinâmico	RibbonMenu
Global	OfficeRibbon
Grupos	RibbonTab
Nome da imagem	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
Tamanho do Item	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Nome	RibbonComponent
Cargo	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
Tipo de Faixa de Opções	OfficeRibbon
Contagem de linhas	RibbonGallery
ShowItemImage	RibbonComboBox RibbonDropDown RibbonGallery
ShowItemLabel	RibbonDropDown RibbonGallery
ShowItemSelection	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
StartFromScratch	OfficeRibbon
Guias	OfficeRibbon
Título	RibbonSeparator

Definir propriedades para faixas de opções que aparecem em inspetores do Outlook

Uma nova instância da faixa de opções é criada sempre que um usuário abre um Inspetor no qual a faixa de opções aparece. No entanto, você pode definir as propriedades listadas na tabela acima somente antes que a primeira instância da faixa de opções seja criada. Depois que a primeira instância é criada, essas propriedades se tornam somente leitura porque a primeira instância define o arquivo XML que o Outlook usa para carregar a faixa de opções.

Se você tiver uma lógica condicional que defina qualquer uma dessas propriedades como um valor diferente quando outras instâncias da faixa de opções forem criadas, esse código não terá efeito.

Observação

Verifique se a propriedade Name está definida para cada controle adicionado a uma Faixa de Opções do Outlook. Se você adicionar um controle a uma faixa de opções do Outlook em tempo de execução, você deve definir essa propriedade em seu código. Se você adicionar um controle a uma Faixa de Opções do Outlook em tempo de design, a propriedade Name será definida automaticamente.

Eventos de controle da faixa de opções

Cada classe de controle contém um ou mais eventos. A tabela a seguir descreve esses eventos.

Evento	Descrição
Clique	Ocorre quando um controle é clicado.
TextoAlterado	Ocorre quando o texto de uma caixa de edição ou caixa de combinação é alterado.
ItensCarregando	Ocorre quando a coleção Items do controle é solicitada pelo Office. O Office armazena em cache a coleção Items até que seu código altere as propriedades do controle ou você chame o InvalidateControl método.
BotãoClique	Ocorre quando um botão em um RibbonGallery ou RibbonDropDown é clicado.
SelectionChanged	Ocorre quando a seleção em um RibbonDropDown ou é RibbonGallery alterada.
DialogLauncherClique	Ocorre quando o ícone do iniciador de diálogo no canto inferior direito de um grupo é clicado.

Os manipuladores de eventos para esses eventos têm os dois parâmetros a seguir.

Parâmetro	Descrição
remetente	Um Object que representa o controle que gerou o evento.
e	A RibbonControlEventArgs que contém um IRibbonControlarquivo . Use esse controle para acessar qualquer propriedade que não esteja disponível no modelo de objeto da Faixa de Opções fornecido pelo tempo de execução do Visual Studio Tools for Office.

Conteúdo relacionado

• Acessar a faixa de opções em tempo de execução
• Visão geral da faixa de opções
• Como: Começar a personalizar a faixa de opções
• Designer da faixa de opções
• Demonstra Passo a passo: Criar uma guia personalizada usando o Designer da Faixa de Opções
• Demonstra Passo a passo: atualizar os controles em uma faixa de opções em tempo de execução
• Personalizar uma faixa de opções para o Outlook
• Como: Personalizar uma guia interna
• Como adicionar controles ao modo de exibição Backstage
• Como exportar uma faixa de opções do Designer da Faixa de Opções para o XML da Faixa de Opções
• Como: Mostrar erros de interface do usuário do suplemento