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

Visual Studio Tools for Office Runtime expõe um modelo de objeto rigidamente tipado que você pode usar para obter e definir as propriedades de fita controle em tempo de execução.Por exemplo, você pode dinamicamente preencher controles menu, ou controles de apresentação e oculte seções de contexto.Você também pode adicionar guias, grupos, e controles a uma fita, mas somente antes de fita é carregado por aplicativo do Office.Para mais informações, consulte Propriedades de configuração que se tornam somente leitura.

Aplicável a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de nível de aplicativo para os seguintes aplicativos: Excel 2013 e Excel 2010; InfoPath 2013 e InfoPath 2010; Outlook 2013 e Outlook 2010; PowerPoint 2013 e PowerPoint 2010; Project 2013 e Project 2010; Visio 2013 e Visio 2010; Word 2013 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Este modelo de objeto de fita consiste principalmente em Classe de fita, em Eventos de fita, e em Classes de controle de fita.

Classe de fita

Quando você adiciona um novo item de fita (designer visual) a um projeto, o Visual Studio adiciona uma classe de Ribbon ao seu projeto.A classe de Ribbon herda da classe de RibbonBase .

Essa classe aparece como uma classe parcial que é dividida entre o arquivo de código de fita e o arquivo de código do designer de fita.

Eventos de fita

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

Controles de fita

O namespace de Microsoft.Office.Tools.Ribbon contém um tipo para cada controle que você vê no grupo de Controles de fita do Office de Caixa de Ferramentas.

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

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

Quando você adiciona um controle ao designer de fita, o designer de fita declarar a classe para esse controle como um campo no arquivo de código do designer de fita.

Tarefas comuns usando as propriedades de controles de fita

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

Em alguns casos, as propriedades tornam-se somente leitura depois que a fita ou após um controle são adicionadas a um menu dinâmico.Para obter mais informações, consulte Propriedades de configuração que se tornam somente leitura.

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

Propriedades de configuração que se tornam somente leitura

Algumas propriedades podem ser definidas antes que a fita carregue.Há três locais para definir essas propriedades:

• Em a janela do Visual Studio Propriedades .

• Em o construtor da classe de Ribbon .

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

Os itens e fornecem algumas exceções.Você pode criar novos controles, defina suas propriedades, e adicioná-las a um menu dinâmico em tempo de execução, mesmo após a fita que contém o menu for carregada.

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

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

Definindo propriedades no construtor de fita

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

Adicione o seguinte código.

<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

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

Em o visual C# que você atualizar projetos do Visual Studio 2008, o construtor aparece no arquivo de código de fita.

Em projetos Visual Basic, visual C# ou em projetos que você criou em Visual Studio 2012, o construtor aparece no arquivo de código do designer de fita.Esse arquivo é chamado YourRibbonItem. Designer.cs ou YourRibbonItem. Designer.vb.Para ver este arquivo em projetos Visual Basic, você deve primeiro clique no botão de Mostrar todos os arquivos no solution Explorer.

Definindo propriedades no método de CreateRibbonExtensibilityObject

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

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

Adicione o seguinte código.

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

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

Propriedades que se tornam somente leitura

A tabela a seguir mostra as propriedades que só podem ser definidas antes que a fita carregue.

Observação
Você pode definir as propriedades de controles em itens e a qualquer momento.Esta tabela não se aplica em esse caso.

Propriedades de configuração para as fitas que aparecem em inspectores do Outlook

Uma nova instância de fita é criada sempre que um usuário abre um inspector em que a fita aparece.Em o entanto, você pode definir as propriedades listadas na tabela anterior somente antes que a primeira instância de fita ser criada.Após a primeira instância é criada, se torna essas propriedades somente leitura porque a primeira instância define o arquivo XML que Outlook usa para carregar a fita.

Se você tiver lógica adicional que define qualquer uma de essas propriedades para um valor diferente quando outras instâncias de fita são criadas, esse código não terá efeito.

Observação
Certifique-se de que a propriedade de Nome está definida para cada controle que você adiciona ao Outlook uma fita.Se você adicionar um controle a uma fita do Outlook em tempo de execução, você deve definir essa propriedade no seu código.Se você adicionar um controle a uma fita do Outlook em tempo de design, a propriedade de Name é definida automaticamente.

Eventos de controle fita

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

Os manipuladores de eventos para esses eventos possuem os seguintes dois parâmetros.

Consulte também

Tarefas

Como: começar a personalizar a faixa de opções.

Passo a passo: Criando uma guia personalizada usando o Designer de faixa de opções

Passo a passo: Atualizar os controles em uma faixa de opções em tempo de execução

Como: personalizar a 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 o suplemento erros de Interface do usuário

Referência

Microsoft.Office.Tools.Ribbon

Conceitos

Acessando a faixa de opções em tempo de execução

Designer de faixa de opções

Personalizando uma faixa de opções para o Outlook

Outros recursos

Visão geral da faixa de opções