XML da Faixa de Opções

O item faixa de opções (XML) permite personalizar uma faixa de opções usando XML. Use o item Faixa de Opções (XML) se quiser personalizar a Faixa de Opções de uma maneira que não tenha suporte no item Faixa de Opções (Designer Visual). Para obter uma comparação do que você pode fazer com cada item, consulte a visão geral do Ribbon.

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.

Adicionar um item de Faixa de Opções (XML) a um projeto

Você pode adicionar um item de Faixa de Opções (XML) a qualquer projeto do Office na caixa de diálogo Adicionar Novo Item . O Visual Studio adiciona automaticamente os seguintes arquivos ao seu projeto:

• Um arquivo XML de Ribbon. Esse arquivo define a interface do usuário (IU) da Faixa de Opções. Use esse arquivo para adicionar elementos de interface do usuário, como guias, grupos e controles. Para mais informações, consulte a referência de arquivo XML da Faixa de Opções mais adiante neste tópico.

• Um arquivo de código Ribbon. Esse arquivo contém a classe Ribbon. Essa classe tem o nome que você especificou para o item da Faixa de Opções (XML) na caixa de diálogo Adicionar Novo Item . Os aplicativos do Microsoft Office usam uma instância dessa classe para carregar a faixa de opções personalizada. Para obter detalhes, consulte a referência da classe Ribbon mais adiante neste tópico.

  Por padrão, esses arquivos adicionam um grupo personalizado à guia Complementos na faixa de opções.

Exibir a barra de ferramentas personalizada em um aplicativo do Microsoft Office

Depois de adicionar um item de Faixa de Opções (XML) ao seu projeto, você deve adicionar código à classe ThisAddin, ThisWorkbook ou ThisDocument que substitui o CreateRibbonExtensibilityObject método e retorna a classe XML da Faixa de Opções ao aplicativo do Office.

O exemplo de código a seguir substitui o CreateRibbonExtensibilityObject método e retorna uma classe XML da Faixa de Opções chamada MyRibbon.

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

Definir o comportamento da faixa de opções personalizada

Você pode responder a ações do usuário, como clicar em um botão na faixa de opções, criando métodos de retorno de chamada. Métodos de retorno de chamada se assemelham a eventos em controles do Windows Forms, mas são identificados por um atributo no XML do elemento de interface do usuário. Você escreve métodos na classe Ribbon e um controle chama o método que tem o mesmo nome que o valor do atributo. Por exemplo, você pode criar um método de retorno de chamada que é chamado quando um usuário clica em um botão no Ribbon. São necessárias duas etapas para criar um método de retorno de chamada:

• Atribua um atributo a um controle no arquivo XML da Faixa de Opções que identifica um método de retorno de chamada em seu código.

• Defina o método de retorno de chamada na classe Ribbon.

Para obter um passo a passo que demonstra como automatizar um aplicativo na faixa de opções, consulte Passo a passo: criar uma guia personalizada usando o XML da Faixa de Opções.

Atribuir métodos de retorno de chamada a controles

Para atribuir um método de retorno de chamada a um controle no arquivo XML da Faixa de Opções, adicione um atributo que especifica o tipo do método de retorno de chamada e o nome do método. Por exemplo, o elemento a seguir define um botão de alternância que tem um método de retorno de chamada onAction chamado OnToggleButton1.

<toggleButton id="toggleButton1" onAction="OnToggleButton1" />

onAction é chamado quando o usuário executa a tarefa principal associada a um controle específico. Por exemplo, o método onAction de retorno de chamada de um botão de alternância é chamado quando o usuário clica no botão.

O método especificado no atributo pode ter qualquer nome. No entanto, ele deve corresponder ao nome do método que você define no arquivo de código da Faixa de Opções.

Há muitos tipos diferentes de métodos de retorno de chamada que você pode atribuir aos controles do Ribbon. Para obter uma lista completa dos métodos de retorno de chamada disponíveis para cada controle, consulte o artigo técnico Personalizar a interface do usuário da Faixa de Opções do Office (2007) para desenvolvedores (parte 3 de 3).

Definir métodos de retorno de chamada

Defina seus métodos de retorno de chamada na classe Ribbon no arquivo de código Ribbon. Um método de retorno de chamada tem vários requisitos:

• Deve ser declarado como público.

• Seu nome deve corresponder ao nome de um Método de retorno de chamada atribuído a um controle no arquivo XML do Ribbon.

• A sua assinatura deve corresponder à assinatura de um tipo de método de retorno de chamada disponível para o controle Ribbon associado.

  Para obter uma lista completa das assinaturas do método de retorno de chamada para controles da Faixa de Opções, consulte o artigo técnico Personalizar a interface do usuário da Faixa de Opções do Office (2007) para desenvolvedores (Parte 3 de 3). O Visual Studio não fornece suporte do IntelliSense para métodos callback que você cria no arquivo de código da Faixa de Opções. Se você criar um método de retorno de chamada que não corresponda a uma assinatura válida, o código será compilado, mas nada ocorrerá quando o usuário clicar no controle.

  Todos os métodos de retorno de chamada têm um IRibbonControl parâmetro que representa o controle que chamou o método. Você pode usar esse parâmetro para reutilizar o mesmo método de retorno de chamada para vários controles. O exemplo de código a seguir demonstra um método de retorno de chamada onAction que executa tarefas diferentes dependendo de qual controle o usuário clica.

  • C#
  • VB

  public void OnActionCallback(Office.IRibbonControl control, bool isPressed)
  {
      if (control.Id == "checkBox1")
      {
          MessageBox.Show("You clicked " + control.Id);
      }
      else
      {
          MessageBox.Show("You clicked a different control.");
      }
  }
  

Referência de arquivo XML da Faixa de Opções

Você pode definir sua faixa de opções personalizada adicionando elementos e atributos ao arquivo XML da Faixa de Opções. Por padrão, o arquivo XML da Faixa de Opções contém o XML a seguir.

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup"
               label="My Group">
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

A tabela a seguir descreve os elementos padrão no arquivo XML do Ribbon.

Esses elementos têm atributos que especificam a aparência e o funcionamento da faixa de opções personalizada. A tabela a seguir descreve os atributos padrão no arquivo XML da Faixa de Opções.

Os elementos e atributos padrão no arquivo XML da Faixa de Opções são um pequeno subconjunto dos elementos e atributos disponíveis. Para obter uma lista completa dos elementos e atributos disponíveis, consulte o artigo técnico Personalizar a interface do usuário da Faixa de Opções do Office (2007) para desenvolvedores (Parte 2 de 3).

Referência de classe Ribbon

O Visual Studio gera a classe Ribbon no arquivo de código da Faixa de Opções. Adicione os métodos de retorno de chamada dos controles no Ribbon a essa classe. Essa classe implementa a interface IRibbonExtensibility.

A tabela a seguir descreve os métodos padrão nesta classe.

Conteúdo relacionado

• Visão geral do Ribbon
• Guia completa: criar uma aba personalizada usando Ribbon XML
• Personalização da interface do usuário do Office