Visão geral do modelo de objeto da Faixa de Opções

Artigo
08/25/2010

Se aplica a
As informações contidas neste tópico se aplicam apenas às especificado Ferramentas do Visual Studio para o Office projetos e as versões do Microsoft Office. Tipo de Projeto Projetos de nível de documento Projetos de nível de aplicativo Versão do Microsoft Office O Excel 2007 Word 2007 Outlook 2007 PowerPoint 2007 For more information, see Recursos disponíveis pelo aplicativo e o tipo de projeto.

As informações contidas neste tópico se aplicam apenas às especificado Ferramentas do Visual Studio para o Office projetos e as versões do Microsoft Office.

Tipo de Projeto

Projetos de nível de documento
Projetos de nível de aplicativo

Versão do Microsoft Office

O Excel 2007
Word 2007
Outlook 2007
PowerPoint 2007

For more information, see Recursos disponíveis pelo aplicativo e o tipo de projeto.

Ferramentas do Visual Studio para o Office expõe um modelo de objeto com rigidez de tipos 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 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 apenas antes que a Faixa de Opções é Carregado pelo aplicativo do Office.Para obter informações, consulte Configuração somente propriedades se tornam-se leitura.

Esse modelo de objeto da Faixa de opções consiste principalmente de classe da Faixa de opções de , eventos da Faixa de Opçõese de classes de Controlarar da Faixa de opções de .

Classe da Faixa de Opções

Quando você adiciona um novo item De Faixa de Opções (Designer Visual) em um projeto, Ferramentas do Visual Studio para o Office adiciona uma classe ao seu projeto que herda a classe OfficeRibbon.

Essa classe aparece como uma classe parcial que Dividir 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 OfficeRibbon contém os seguintes eventos três:

O evento Load é disparado quando o aplicativo do Office carrega a personalização da Faixa de Opções.O manipulador de eventos de Load é automaticamente adicionado para o arquivo de código da Faixa de Opções.Use este manipulador de eventos para executar código Personalizar quando a Faixa de Opções é carregado.

O evento LoadImage lhe para imagens de cache na personalização da Faixa de Opções quando a Faixa de Opções é carregado.Você pode obter um ganho de desempenho pequeno se você Gravar código para armazenar em cache as imagens da Faixa de Opções no manipulador de eventos.For more information, see LoadImage.

O evento Close é disparado quando a instância da Faixa de Opções fecha.

Classes de Controlarar da Faixa de Opções

O namespace Microsoft.Office.Tools.Ribbon contém uma classe da Faixa de Opções para cada controle que você vê no AAgruparar Controles da Faixa de Opções de Office de De caixa de ferramentas.

A tabela a seguir mostra a classe para cada Controlarar da Faixa de Opções.Para obter uma descrição de cada Controlarar, consulte Visão geral da Faixa de Opções.

Nome do controle	Nome da classe
Caixa	RibbonBox
Button	RibbonButton
Grupo de botões	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
Suspenso	RibbonDropDown
EditBox	RibbonEditBox
Galeria	RibbonGallery
Group	RibbonGroup
Rótulo	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	RibbonTab
ToggleButton	RibbonToggleButton

O namespace Microsoft.Office.Tools.Ribbon usa o prefixo "Faixa de Opções" para essas classes para evitar um conflito de nome com os nomes das classes de Controlarar no namespace System.Windows.Forms.

Quando você Adicionar um Controlarar para o Designer de Faixa de Opções, o Designer de Faixa de Opções declara a classe de Controlarar como um campo no arquivo de código de Designer de Faixa de Opções.

Tarefas ComComumComum usando as propriedades de classes de Controlarar da Faixa de Opções

Cada classe de controle da 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 controles.

Em alguns casos, propriedades se tornar somente leitura após as cargas de Faixa de Opções ou após um Controlarar é adicionado a um menu dinâmico.Para obter mais informações, consulte Configuração propriedades que Become somente leitura.

A tabela a seguir descreve algumas das tarefas que você pode executar usando propriedades de Controlarar da Faixa de Opções.

Para esta tarefa:	Faça o seguinte:
Ocultar ou mostrar um Controlarar.	Use a propriedade Visible.
Habilitar ou Desativar um Controlarar.	Use a propriedade Enabled.
Defina o tamanho de um Controlarar.	Use a propriedade ControlSize.
Obter a imagem que aparece em um Controlarar.	Use a propriedade Image.
Alterar o rótulo de um Controlarar.	Use a propriedade Label.
Adicionar dados definidos pelo usuário a um Controlarar.	Use a propriedade Tag.
Obter os itens em um RibbonBox, RibbonDropDown, RibbonGallery, ou Controle RibbonSplitButton	Use a propriedade Items.
Adicionar itens a um RibbonComboBox, RibbonDropDownou RibbonGallery Controlarar.	Use a propriedade Items.
Adicionar controles a um RibbonMenu.	Use a propriedade Items. Para adicionar controles ao RibbonMenu depois da Faixa de Opções é Carregado para o aplicativo do Office, você deve definir a Dynamic propriedade para true antes da Faixa de Opções é Carregado para o aplicativo do Office.Para obter informações, consulte Configuração somente propriedades se tornam-se leitura.
Obtenha o item selecionado de um RibbonComboBox, RibbonDropDown, or RibbonGallery.	Use a propriedade SelectedItem.Para um RibbonComboBox, use a propriedade Text.
Obter os grupos em um RibbonTab.	Use a propriedade Groups.
Especifique o número de linhas e colunas que Aparecerr em um RibbonGallery.	Use as propriedades de RowCount e ColumnCount.

Configuração Propriedades que se tornar somente leitura

Algumas propriedades podem ser definidas somente antes de carrega a Faixa de Opções.Há três locais para definir essas propriedades:

Na janela Visual Studio Propriedades.
No construtor da classe da Faixa de Opções.
No método CreateRibbonExtensibilityObject da classe ThisAddin do seu projeto.

Menus dinâmicos fornecem algumas exceções.Você pode criar novos controles, defina suas propriedades e, em seguida, Adicionar-las a um menu dinâmico em tempo de execução, mesmo depois que a Faixa de Opções que contém o menu é carregada.

Iniciando no Visual Studio 2008 Serviço Pack 1 (SP1), propriedades de controles que você adicionar a um menu dinâmico podem ser definidas em a a qualquer hora.No entanto, se você não tiver instalado o SP1, se algumas das propriedades tornar somente leitura depois que o Controlarar tiver sido adicionado ao menu.

Para obter mais informações, consulte propriedades que Become somente leitura.

Configuração Propriedades no construtor da Faixa de Opções

Você pode definir as propriedades de um Controlarar da Faixa de Opções no construtor da classe da Faixa de Opções.Esse código deve aparecer após a chamada ao método InitializeComponent.O exemplo a seguir adiciona um novo botão a um AAgruparar se o horário atual for 17:00 Hora do Pacífico (UTC-8) ou posterior.

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

}

Configuração Propriedades no método CreateRibbonExtensibilityObject

Você pode definir as propriedades de um Controlarar da Faixa de opções quando você substituir o método CreateRibbonExtensibilityObject no ThisAddin, ThisWorkbookou ThisDocument classe do seu projeto de.Para mais informações sobre o método CreateRibbonExtensibilityObject, consulte Visão geral da Faixa de Opções.

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

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 que se tornar somente leitura

A tabela a seguir mostra as propriedades que podem ser definidas somente antes de carrega a Faixa de Opções.

Observação:
Se você instalar SP1, Você pode definir o p roperties de controles em menu dinâmico s em a a qualquer hora.Esta tabela não Aplicar nesse maiúscminúsc.

Propriedade	Classe de Controlarar da Faixa de Opções
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Dynamic	RibbonMenu
Global	OfficeRibbon
Grupos	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Nome	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

Configuração Propriedades para faixas de opções que Aparecerr no inspetores do Outlook

Uma Novo instância da Faixa de Opções é criada sempre que um usuário abrir um Inspector em que a Faixa de Opções aparece.No entanto, você pode definir propriedades listadas na tabela acima apenas antes que a Primeiro instância de Faixa de Opções seja criada.Após a Primeiro instância é criada, essas propriedades tornam-se somente leitura porque a Primeiro instância define o arquivo XML que o Outlook usa para carregar a Faixa de Opções.

Se você tiver lógica condicional que define qualquer uma dessas propriedades como um valor diferente quando Outro instâncias da Faixa de Opções são criadas, esse código terá efeito.

Observação:
Verifique se a Nome propriedade é definida para cada Controlarar que você adicionar a uma Faixa de Opções do Outlook.Se você adicionar um Controlarar para 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 Controlarar para uma Faixa de Opções do Outlook em tempo de design, a propriedade Name é definida automaticamente.

Verifique se a Nome propriedade é definida para cada Controlarar que você adicionar a uma Faixa de Opções do Outlook.Se você adicionar um Controlarar para 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 Controlarar para uma Faixa de Opções do Outlook em tempo de design, a propriedade Name é definida automaticamente.

Eventos de Controlarar da Faixa de Opções

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

Evento	Descrição
Click	Ocorre quando um Controlarar é clicado.
TextChanged	Ocorre quando o texto de um Editar Caixa ou caixa de combinação é alterada.
ItemsLoading	Ocorre quando a coleção Items do Controlarar é solicitada pelo Office.Office armazena em cache a coleção Items até que seu código altera as propriedades do Controlarar, ou você chamar o método Microsoft.Office.Core.IRibbonUI.InvalidateControl.
ButtonClick	Ocorre quando um botão em um RibbonGallery ou RibbonDropDown é clicado.
SelectionChanged	Ocorre quando a seleção em um RibbonDropDown ou RibbonGallery é alterada.
DialogLauncherClick	Ocorre quando o ícone de iniciador de Caixa de diálogo no canto inferior direito de um AAgruparar é clicado.

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

Parâmetro	Descrição
sender	Um Object que representa o Controlarar que disparou o evento.
e	Um RibbonControlEventArgs que contém um Microsoft.Office.Core.IRibbonControl.Use esse Controlarar para acessar qualquer propriedade que não está disponível no modelo de objeto do Ferramentas do Visual Studio para o Office da Faixa de Opções.

Consulte também

Date	History	Motivo
De 2008 de julho	Revisado informações sobre Configuração propriedades de controles nos menus dinâmicos depois de instalar o SP1.	Alteração de recurso do SP1.

Partilhar via