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

O Visual Studio Tools for Office runtime expõe um modelo de objeto com rigidez de tipos 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 dinamicamente Preencher controles de menu, ou mostrar e ocultar controles contextualmente. Você também pode adicionar guias, grupos e controles para uma faixa de opções, mas antes da faixa de opções é carregada pelo aplicativo do Office. Para obter informações, consulte Somente configuração propriedades que tornam-se 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 2007 e Excel 2010; InfoPath 2010; Outlook 2007 e Outlook 2010; PowerPoint 2007 e PowerPoint 2010; Project 2010; Visio 2010; Word 2007 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Esse modelo de objeto de faixa de opções consiste, principalmente o Classe Ribbon, Eventos de faixa de opções, e Classes de controle da faixa de opções.

Classe de faixa de opções

Quando você adiciona um novo a faixa de opções (Visual Designer) item a um projeto Visual Studio adiciona uma classe de faixa de opções ao seu projeto. Se os destinos do projeto a .NET Framework 4, a faixa de opções classe herda da RibbonBase classe. Se os destinos do projeto a.NET Framework 3.5, a classe Ribbon herda de OfficeRibbon 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 de faixa de opções.

Eventos da faixa de opções

A classe de faixa de opções contém três eventos a seguintes:

Controles da faixa de opções

O Microsoft.Office.Tools.Ribbon namespace contém um tipo para cada controle que você vê na Controles de faixa de opções do Office grupo do caixa de ferramentas.

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

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

Quando você adiciona um controle para o Designer de faixa de opções, o Designer de faixa de opções declara a classe para o 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 controle de faixa de opções contém propriedades que você pode usar para executar várias tarefas, como atribuir um rótulo a um controle, ou ocultando e mostrando os controles.

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

A tabela a seguir descreve algumas das tarefas que você pode executar usando as propriedades de controle da faixa de opções.

Definindo propriedades somente leitura

Algumas propriedades só podem ser definidas antes que a faixa é carregada. Há três locais para definir essas propriedades:

• No Visual Studio Propriedades janela.

• No construtor da classe da faixa de opções.

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

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

Propriedades de controles que você adicionar a um menu dinâmico podem ser definidas a qualquer momento.

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

Definindo propriedades no construtor da faixa de opções

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

Para projetos destinados a .NET Framework 4, 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);
    }
}

Para projetos destinados a.NET Framework 3.5, adicione o seguinte código:

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

    'This call is required by the Component Designer.
    InitializeComponent()
    If DateTime.Now.Hour > 16 Then
        Group1.Items.Add(New RibbonButton())
        CType(Group1.Items.Last(), RibbonButton).Label = "New Button"
    End If
End Sub

public Ribbon1()
{
    InitializeComponent();
    if (DateTime.Now.Hour > 16)
    {
        group1.Items.Add(new RibbonButton());
        ((RibbonButton)group1.Items.Last()).Label = "New Button";
    }

}

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

Em projetos de Visual Basic, ou em projetos do Visual C# que você criou em 2010 de Visual Studio, o construtor aparece no arquivo de código do Designer de faixa de opções. Este arquivo é nomeado YourRibbonItem.CS ou YourRibbonItem.Designer. Para ver este arquivo em projetos de Visual Basic, primeiro você deve clicar na Mostrar todos os arquivos botão no Solution Explorer.

Propriedades de configuração no método CreateRibbonExtensibilityObject

Você pode definir as propriedades de um controle de faixa de opções quando você substituir o CreateRibbonExtensibilityObject método na ThisAddin, ThisWorkbook, ou ThisDocument a classe do seu projeto. For more information about the CreateRibbonExtensibilityObject method, see Visão geral da faixa de opções.

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

Para projetos destinados a .NET Framework 4, 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 });
    }
}

Para projetos destinados a.NET Framework 3.5, 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 New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    End If
End Function

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

Propriedades somente leitura

A tabela a seguir mostra as propriedades que só podem ser definidas antes que a faixa é carregada.

Observação
Você pode definir as propriedades de controles nos menus dinâmicos a qualquer momento. Esta tabela não será aplicada nesse caso.

Definindo propriedades para faixas de opções que aparecem no inspetores do Outlook

Uma nova instância da faixa de opções é criada sempre que um usuário abre um Inspetor em que a faixa de opções é exibida. No entanto, você pode definir as propriedades listadas na tabela acima, antes da primeira instância da faixa de opções é criada. Após a primeira instância é criada, essas propriedades se tornar 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 a lógica condicional que define qualquer uma dessas propriedades para um valor diferente de quando outras instâncias da faixa de opções são criadas, esse código não terá efeito.

Observação
Certifique-se de que o nome for definida para cada controle que você adicionar uma faixa de opções do Outlook. Se você adicionar um controle 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, o Name propriedade é 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.

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

Consulte também

Tarefas

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

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

Demonstra Passo a passo: A atualização de controles em uma faixa de opções em tempo de execução

Como: Personalizar a guia interna

Como: Personalizar o Menu Microsoft Office

Como: Exportar uma faixa de opções do Designer de 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

Personalização para Outlook

Outros recursos

Visão geral da faixa de opções