Barras de ferramentas no Xamarin.Mac

Este artigo descreve como trabalhar com barras de ferramentas em um aplicativo Xamarin.Mac. Ele abrange a criação e manutenção de barras de ferramentas no Xcode e no Interface Builder, expondo-as ao código e trabalhando com elas programaticamente.

Os desenvolvedores do Xamarin.Mac que trabalham com o Visual Studio para Mac têm acesso aos mesmos controles de interface do usuário disponíveis para desenvolvedores do macOS que trabalham com o Xcode, incluindo o controle da barra de ferramentas. Como o Xamarin.Mac se integra diretamente ao Xcode, é possível usar o Construtor de Interfaces do Xcode para criar e manter itens da barra de ferramentas. Esses itens da barra de ferramentas também podem ser criados em C#.

As barras de ferramentas no macOS são adicionadas à seção superior de uma janela e fornecem acesso fácil a comandos relacionados à sua funcionalidade. As barras de ferramentas podem ser ocultadas, mostradas ou personalizadas pelos usuários de um aplicativo e podem apresentar itens da barra de ferramentas de várias maneiras.

Este artigo aborda as noções básicas de como trabalhar com barras de ferramentas e itens de barra de ferramentas em um aplicativo Xamarin.Mac.

Antes de continuar, leia o artigo Olá, Mac — especificamente as seções Introdução ao Xcode e ao Construtor de Interface e Saídas e Ações — pois ele aborda os principais conceitos e técnicas que serão usados ao longo deste guia.

Dê também uma olhada na seção Expondo classes C# / métodos para Objective-C do documento Xamarin.Mac Internals . Ele explica os Register atributos e Export usados para conectar classes C# a Objective-C classes.

Introdução às barras de ferramentas

Qualquer janela em um aplicativo macOS pode incluir uma barra de ferramentas:

As barras de ferramentas fornecem uma maneira fácil para os usuários do aplicativo acessarem rapidamente recursos importantes ou usados com frequência. Por exemplo, um aplicativo de edição de documentos pode fornecer itens da barra de ferramentas para definir a cor do texto, alterar a fonte ou imprimir o documento atual.

As barras de ferramentas podem exibir itens de três maneiras:

1. Ícone e texto

   

2. Somente ícone

   

3. Somente texto

   

Alterne entre esses modos clicando com o botão direito do mouse na barra de ferramentas e selecionando um modo de exibição no menu contextual:

Use o mesmo menu para exibir a barra de ferramentas em um tamanho menor:

O menu também permite personalizar a barra de ferramentas:

Ao configurar uma barra de ferramentas no Construtor de Interface do Xcode, um desenvolvedor pode fornecer itens extras da barra de ferramentas que não fazem parte de sua configuração padrão. Os usuários do aplicativo podem personalizar a barra de ferramentas, adicionando e removendo esses itens predefinidos conforme necessário. Naturalmente, a barra de ferramentas pode ser redefinida para sua configuração padrão.

A barra de ferramentas se conecta automaticamente ao menu Exibir, o que permite aos usuários ocultá-la, mostrá-la e personalizá-la:

Consulte a documentação da funcionalidade de menu interno para obter mais detalhes.

Além disso, se a barra de ferramentas estiver configurada corretamente no Construtor de Interfaces, o aplicativo persistirá automaticamente as personalizações da barra de ferramentas em várias inicializações do aplicativo.

As próximas seções deste guia descrevem como criar e manter barras de ferramentas com o Construtor de Interface do Xcode e como trabalhar com elas no código.

Definindo um controlador de janela principal personalizado

Para expor elementos da interface do usuário ao código C# por meio de saídas e ações, o aplicativo Xamarin.Mac deve usar um controlador de janela personalizado:

1. Abra o storyboard do aplicativo no Construtor de Interfaces do Xcode.

2. Selecione o controlador de janela na superfície de design.

3. Alterne para o Inspetor de Identidade e digite "WindowController" como o Nome da classe:

   

4. Salve suas alterações e retorne ao Visual Studio para Mac para sincronizar.

5. Um arquivo WindowController.cs será adicionado ao seu projeto no Solution Pad no Visual Studio para Mac:

   

6. Reabra o storyboard no Construtor de Interfaces do Xcode.

7. O arquivo WindowController.h estará disponível para uso:

   

Criando e mantendo barras de ferramentas no Xcode

As barras de ferramentas são criadas e mantidas com o Construtor de Interfaces do Xcode. Para adicionar uma barra de ferramentas a um aplicativo, edite o storyboard principal do aplicativo (neste caso , Main.storyboard) clicando duas vezes nele no Painel de Soluções:

No Inspetor de biblioteca, digite "ferramenta" na caixa de pesquisa para facilitar a visualização de todos os itens da barra de ferramentas disponíveis:

Arraste uma barra de ferramentas para a janela no Editor de interface. Com a barra de ferramentas selecionada, configure seu comportamento definindo propriedades no Inspetor de Atributos:

As seguintes propriedades estão disponíveis:

1. Exibir - Controla se a barra de ferramentas exibe ícones, texto ou ambos
2. Visível na inicialização - Se selecionada, a barra de ferramentas ficará visível por padrão.
3. Personalizável - Se selecionado, os usuários podem editar e personalizar a barra de ferramentas.
4. Separador - Se selecionado, uma linha horizontal fina separa a barra de ferramentas do conteúdo da janela.
5. Tamanho - Define o tamanho da barra de ferramentas
6. Salvamento automático - Se selecionado, o aplicativo persistirá as alterações de configuração da barra de ferramentas de um usuário nas inicializações do aplicativo.

Selecione a opção Salvamento automático e deixe todas as outras propriedades em suas configurações padrão.

Depois de abrir a barra de ferramentas na Hierarquia de Interface, abra a caixa de diálogo de personalização selecionando um item da barra de ferramentas:

Use essa caixa de diálogo para definir propriedades para itens que já fazem parte da barra de ferramentas, para criar a barra de ferramentas padrão para o aplicativo e para fornecer itens extras da barra de ferramentas para um usuário selecionar ao personalizar a barra de ferramentas. Para adicionar itens à barra de ferramentas, arraste-os do Inspetor de biblioteca:

Os seguintes itens da barra de ferramentas podem ser adicionados:

• Item da barra de ferramentas de imagem - Um item da barra de ferramentas com uma imagem personalizada como ícone.

• Item da barra de ferramentas Espaço flexível - Espaço flexível usado para justificar itens subsequentes da barra de ferramentas. Por exemplo, um ou mais itens da barra de ferramentas seguidos por um item da barra de ferramentas de espaço flexível e outro item da barra de ferramentas fixariam o último item no lado direito da barra de ferramentas.

• Item da barra de ferramentas Espaço - Espaço fixo entre itens na barra de ferramentas

• Item da barra de ferramentas do separador - Um separador visível entre dois ou mais itens da barra de ferramentas, para agrupamento

• Personalizar item da barra de ferramentas - Permite que os usuários personalizem a barra de ferramentas

• Imprimir item da barra de ferramentas - Permite que os usuários imprimam o documento aberto

• Mostrar item da barra de ferramentas Cores - Exibe o seletor de cores padrão do sistema:

  

• Mostrar Item da Barra de Ferramentas de Fontes - Exibe a caixa de diálogo de fonte padrão do sistema:

  

Importante

Como será visto mais adiante, muitos controles padrão da interface do usuário do Cacau, como campos de pesquisa, controles segmentados e controles deslizantes horizontais, também podem ser adicionados a uma barra de ferramentas.

Adicionando um item a uma barra de ferramentas

Para adicionar um item a uma barra de ferramentas, selecione a barra de ferramentas na Hierarquia de Interface e clique em um de seus itens, fazendo com que a caixa de diálogo de personalização apareça. Em seguida, arraste um novo item do Inspetor de Biblioteca para a área Itens da Barra de Ferramentas Permitidos :

Para verificar se um novo item faz parte da barra de ferramentas padrão, arraste-o para a área Itens da barra de ferramentas padrão:

Para reordenar os itens da barra de ferramentas padrão, arraste-os para a esquerda ou para a direita.

Em seguida, use o Inspetor de Atributos para definir as propriedades padrão do item:

As seguintes propriedades estão disponíveis:

• Nome da imagem - Imagem a ser usada como ícone para o item
• Rótulo - Texto a ser exibido para o item na barra de ferramentas
• Rótulo da Paleta - Texto a ser exibido para o item na área Itens da Barra de Ferramentas Permitidos
• Tag - Um identificador exclusivo opcional que ajuda a identificar o item no código.
• Identificador - Define o tipo de item da barra de ferramentas. Um valor personalizado pode ser usado para selecionar um item da barra de ferramentas no código.
• Selecionável - Se marcado, o item funcionará como um botão liga/desliga.

Importante

Adicione um item à área Itens da Barra de Ferramentas Permitidos, mas não à barra de ferramentas padrão para fornecer opções de personalização aos usuários.

Adicionando outros controles de interface do usuário a uma barra de ferramentas

Vários elementos da interface do usuário do Cocoa, como campos de pesquisa e controles segmentados, também podem ser adicionados a uma barra de ferramentas.

Para tentar isso, abra a barra de ferramentas na hierarquia de interface e selecione um item da barra de ferramentas para abrir a caixa de diálogo de personalização. Arraste um Campo de Pesquisa do Inspetor de Biblioteca para a área Itens da Barra de Ferramentas Permitidos:

A partir daqui, use o Construtor de Interface para configurar o campo de pesquisa e expô-lo ao código por meio de uma ação ou saída.

Suporte interno a itens da barra de ferramentas

Vários elementos da interface do usuário do Cocoa interagem com itens da barra de ferramentas padrão por padrão. Por exemplo, arraste um Modo de Exibição de Texto para a janela do aplicativo e posicione-o para preencher a área de conteúdo:

Salve o documento, retorne ao Visual Studio para Mac para sincronizar com o Xcode, execute o aplicativo, insira algum texto, selecione-o e clique no item da barra de ferramentas Cores . Observe que o modo de exibição de texto funciona automaticamente com o seletor de cores:

Usando imagens com itens da barra de ferramentas

Usando um Item da Barra de Ferramentas de Imagem, qualquer imagem de bitmap adicionada à pasta Recursos (e dada uma ação de compilação de Recurso de Pacote) pode ser exibida na barra de ferramentas como um ícone:

1. No Visual Studio para Mac, no Solution Pad, clique com o botão direito do mouse na pasta Recursos e selecione Adicionar>Arquivos.

2. Na caixa de diálogo Adicionar arquivos , navegue até as imagens desejadas, selecione-as e clique no botão Abrir :

   

3. Selecione Copiar, marque Usar a mesma ação para todos os arquivos selecionados e clique em OK:

   

4. No Solution Pad, clique duas vezes em MainWindow.xib para abri-lo no Xcode.

5. Selecione a barra de ferramentas na Hierarquia de Interface e clique em um de seus itens para abrir a caixa de diálogo de personalização.

6. Arraste um Item da Barra de Ferramentas de Imagem do Inspetor de Biblioteca para a área Itens da Barra de Ferramentas Permitidos da barra de ferramentas:

   

7. No Inspetor de Atributos, selecione a imagem que acabou de ser adicionada no Visual Studio para Mac:

   

8. Defina o rótulo como "Lixo" e o rótulo da paleta como "Apagar documento":

   

9. Arraste um Item da Barra de Ferramentas Separador do Inspetor de Biblioteca para a área Itens da Barra de Ferramentas Permitidos da barra de ferramentas:

   

10. Arraste o item separador e o item "Lixo" para a área Itens da barra de ferramentas padrão e defina a ordem dos itens da barra de ferramentas da esquerda para a direita da seguinte maneira (Cores, Fontes, Separador, Lixo, Espaço flexível, Imprimir):

    

11. Salve as alterações e retorne ao Visual Studio para Mac para sincronizar com o Xcode.

Execute o aplicativo para verificar se a nova barra de ferramentas é exibida por padrão:

Expondo itens da barra de ferramentas com saídas e ações

Para acessar uma barra de ferramentas ou item da barra de ferramentas no código, ele deve ser anexado a uma tomada ou uma ação:

1. No Solution Pad, clique duas vezes em Main.storyboard para abri-lo no Xcode.

2. Verifique se a classe personalizada "WindowController" foi atribuída ao controlador de janela principal no Inspetor de identidade:

   

3. Em seguida, selecione o item da barra de ferramentas na hierarquia de interface:

   

4. Abra o Modo de Exibição do Assistente, selecione o arquivo WindowController.h e arraste com a tecla Control pressionada do item da barra de ferramentas para o arquivo WindowController.h.

5. Defina o tipo de conexão como Ação, digite "trashDocument" para o Nome e clique no botão Conectar :

   

6. Exponha o modo de exibição de texto como uma saída chamada "documentEditor" no arquivo ViewController.h :

   

7. Salve suas alterações e retorne ao Visual Studio para Mac para sincronizar com o Xcode.

No Visual Studio para Mac, edite o arquivo ViewController.cs e adicione o seguinte código:

public void EraseDocument() {
    documentEditor.Value = "";
}

Em seguida, edite o arquivo WindowController.cs e adicione o seguinte código à parte inferior da WindowController classe:

[Export ("trashDocument:")]
void TrashDocument (NSObject sender) {

    var controller = ContentViewController as ViewController;
    controller.EraseDocument ();
}

Ao executar o aplicativo, o item da barra de ferramentas Lixo estará ativo:

Observe que o item da barra de ferramentas Lixeira agora pode ser usado para excluir texto.

Desabilitando itens da barra de ferramentas

Para desabilitar um item em uma barra de ferramentas, crie uma classe personalizada NSToolbarItem e substitua o Validate método. Em seguida, no Construtor de Interfaces, atribua o tipo personalizado ao item que você deseja habilitar/desabilitar.

Para criar uma classe personalizadaNSToolbarItem, clique com o botão direito do mouse no projeto e selecione Adicionar>novo arquivo.... Selecione General>Empty Class, digite "ActivatableItem" para o Nome e clique no botão Novo:

Em seguida, edite o arquivo ActivatableItem.cs para ler da seguinte maneira:

using System;

using Foundation;
using AppKit;

namespace MacToolbar
{
    [Register("ActivatableItem")]
    public class ActivatableItem : NSToolbarItem
    {
        public bool Active { get; set;} = true;

        public ActivatableItem ()
        {
        }

        public ActivatableItem (IntPtr handle) : base (handle)
        {
        }

        public ActivatableItem (NSObjectFlag  t) : base (t)
        {
        }

        public ActivatableItem (string title) : base (title)
        {
        }

        public override void Validate ()
        {
            base.Validate ();
            Enabled = Active;
        }
    }
}

Clique duas vezes em Main.storyboard para abri-lo no Xcode. Selecione o item da barra de ferramentas Lixo criado acima e altere sua classe para "ActivatableItem" no Inspetor de Identidade:

Crie uma saída chamada trashItem para o item da barra de ferramentas Lixeira . Salve as alterações e retorne ao Visual Studio para Mac para sincronizar com o Xcode. Finalmente, abra MainWindow.cs e atualize o método para ler o AwakeFromNib seguinte:

public override void AwakeFromNib ()
{
    base.AwakeFromNib ();

    // Disable trash
    trashItem.Active = false;
}

Execute o aplicativo e observe que o item Lixo agora está desabilitado na barra de ferramentas:

Resumo

Este artigo deu uma olhada detalhada no trabalho com barras de ferramentas e itens de barra de ferramentas em um aplicativo Xamarin.Mac. Ele descreveu como criar e manter barras de ferramentas no Construtor de Interface do Xcode, como alguns controles de interface do usuário funcionam automaticamente com itens da barra de ferramentas, como trabalhar com barras de ferramentas no código C# e como habilitar e desabilitar itens da barra de ferramentas.

Links relacionados

• Hello, Mac
• Diretrizes de interface humana para barras de ferramentas
• Introdução às barras de ferramentas