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

Artigo
08/08/2011

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:

Projetos de destino do.NET Framework 4	Projetos de destino do.NET Framework 3.5	Description
RibbonBase.Load	OfficeRibbon.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 este manipulador de eventos para executar o código personalizado quando a faixa é carregada.
RibbonBase.LoadImage	OfficeRibbon.LoadImage	Permite a imagens de cache na personalização da faixa de opções quando a faixa é carregada. Se você escrever código para armazenar em cache as imagens de faixa de opções no manipulador de eventos, você pode obter um ganho de desempenho pequeno. For more information, see LoadImage.
RibbonBase.Close	OfficeRibbon.Close	Gerado quando a instância de 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ê 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.

Control name	Class name
Caixa	RibbonBox
Button	RibbonButton
Grupo de botões	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
Suspenso	RibbonDropDown
EditBox	RibbonEditBox
Galeria	RibbonGallery
Group	RibbonGroup
Label	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	RibbonTab
ToggleButton	RibbonToggleButton

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.

Para esta tarefa:	Faça o seguinte:
Ocultar ou mostrar um controle.	Use o Visible propriedade.
Ativar ou desativar um controle.	Use o Enabled propriedade.
Defina o tamanho de um controle.	Use o ControlSize propriedade.
Obter a imagem que aparece em um controle.	Use o Image propriedade.
Altere o rótulo de um controle.	Use o Label propriedade.
Adicione dados definidos pelo usuário a um controle.	Use o Tag propriedade.
Get the items in a RibbonBox, RibbonDropDown, RibbonGallery, or RibbonSplitButton control.	Use o Items propriedade.
Adicionar itens a uma RibbonComboBox, RibbonDropDown, ou RibbonGallery de controle.	Use o Items propriedade.
Adicionar controles a uma RibbonMenu.	Use o Items propriedade. Para adicionar controles para o RibbonMenu depois que a faixa de opções é carregada no aplicativo do Office, você deve definir o Dynamic propriedade para true antes que a faixa de opções é carregada para o aplicativo do Office. Para obter informações, consulte Somente configuração propriedades que tornam-se leitura.
Obtenha o item selecionado de um RibbonComboBox, RibbonDropDown, or RibbonGallery.	Use o SelectedItem propriedade. Para um RibbonComboBox, use o Text propriedade.
Obtenha os grupos em um RibbonTab.	Use o Groups propriedade.
Especifique o número de linhas e colunas que aparecem em um RibbonGallery.	Use o RowCount e ColumnCount Propriedades.

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.

Property	Classe de controle da faixa de opções
Style	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Dynamic	RibbonMenu
Global	OfficeRibbon
Groups	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Name	RibbonComponent
Position	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
RibbonType	OfficeRibbon
RowCount	RibbonGallery
ShowItemImage	RibbonComboBox RibbonDropDown RibbonGallery
ShowItemLabel	RibbonDropDown RibbonGallery
ShowItemSelection	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
StartFromScratch	OfficeRibbon
Guias	OfficeRibbon
Title	RibbonSeparator

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.

Event	Description
Click	Ocorre quando um controle é clicado.
TextChanged	Ocorre quando o texto de uma caixa de combinação ou caixa de edição é alterado.
ItemsLoading	Ocorre quando o Items coleção do controle é solicitada pelo Office. Caches do Office a Items coleção até que as propriedades do controle de alterações de seu código ou chamar o IRibbonUI.InvalidateControl(String) método.
ButtonClick	Ocorre quando um botão em um RibbonGallery ou RibbonDropDown é clicado.
SelectionChanged	Ocorre quando a seleção em um RibbonDropDown ou RibbonGallery alterações.
DialogLauncherClick	Ocorre quando o ícone do lançador de diálogo no canto inferior direito de um grupo é clicado.

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

Parameter	Description
sender	Um Object que representa o controle que gerou o evento.
e	A RibbonControlEventArgs que contém um Microsoft.Office.Core.IRibbonControl. Use esse controle para acessar qualquer propriedade que não está disponível no modelo de objeto de faixa de opções fornecido pelo Visual Studio Tools for Office runtime.

Consulte também

Compartilhar via