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

O runtime das Ferramentas do Visual Studio para Office expõe um modelo de objeto fortemente tipado que você pode usar para obter e definir as propriedades dos 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; Outlook; PowerPoint; Project; Visio; Word. Para obter mais informações, consulte Os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

Esse modelo de objeto da Faixa de Opções consiste principalmente na classe Faixa de Opções, nos Eventos da Faixa de Opções e nas classes de controle Faixa de Opções.

Classe de faixa de opções

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

Essa classe aparece como uma classe parcial 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 seguintes eventos:

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 a visão geral da Faixa de Opções.

O Microsoft.Office.Tools.Ribbon namespace usa o prefixo "Ribbon" para esses tipos para evitar uma colisão de nome com os nomes das 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 para esse controle como um campo no arquivo de código do Designer de 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 para 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 só de leitura.

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

Definir propriedades que se tornam somente leitura

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

• Na janela Propriedades do Visual Studio.

• No construtor da classe Ribbon .

• No método CreateRibbonExtensibilityObject da classe ThisAddin, ThisWorkbook ou ThisDocument do seu projeto.

  Os menus dinâmicos fornecem algumas exceções. Você pode criar novos controles, definir suas propriedades e adicioná-las a um menu dinâmico em tempo de execução, mesmo após a faixa de opções que contém o menu ser 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 de leitura apenas.

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 Horário do Pacífico (UTC-8) ou posterior.

Adicione o código seguinte:

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);
    }
}

<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# criados no Visual Studio 2013, o construtor aparece no arquivo de código do Designer da Faixa de Opções. Esse arquivo se chama YourRibbonItem. Designer.cs ou YourRibbonItem. Designer.vb. Para ver esse arquivo em projetos do Visual Basic, primeiro clique 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 ao substituir o método CreateRibbonExtensibilityObject na classe ThisAddin, ThisWorkbook ou ThisDocument do seu projeto. Para mais informações sobre o método CreateRibbonExtensibilityObject, consulte a Ribbon Overview.

O exemplo a seguir define as propriedades do Ribbon no método da classe ThisWorkbook de um projeto de pasta de trabalho do Excel.

Adicione o código seguinte:

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 });
    }
}

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 as propriedades que só podem ser definidas antes do carregamento da faixa de opções.

Definir propriedades para Ribbons que aparecem nos 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 é exibida. No entanto, você pode definir as propriedades listadas na tabela acima somente antes que a primeira instância do Ribbon 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 define qualquer uma dessas propriedades para um valor diferente quando outras instâncias da faixa de opções (ribbon) forem criadas, esse código não terá efeito.

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.

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

Conteúdo relacionado

• Acessar a faixa de opções em tempo de execução
• Visão geral do Ribbon
• Como começar a personalizar a fita
• Designer de Faixa de Opções
• Passo a passo: criar uma guia personalizada usando o Designer da Faixa de Opções
• 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 integrada
• Como adicionar controles ao modo de exibição Backstage
• Como exportar uma faixa de opções do Designer de Faixa de Opções para o Ribbon XML
• Como: Mostrar erros de interface de usuário do Add-in