Noções básicas do menu

As classes de menu incluem:

O AIR oferece suporte aos seguintes tipos de menus:

Menus de contexto

Os menus de contexto são exibidos em resposta ao clique com o botão direito do mouse ou ao clique com a tecla Command pressionada em um objeto interativo no conteúdo SWF ou um elemento de documento no conteúdo HTML.

No tempo de execução do Flash Player, um menu de contexto é automaticamente exibido. Você pode usar as classes ContextMenu e ContextMenuItem para adicionar seus próprios comandos ao menu. Também é possível remover alguns comandos incorporados, mas não todos.

No tempo de execução do AIR, você pode criar um menu de contexto usando a classe NativeMenu ou ContextMenu. No conteúdo HTML do AIR, você pode usar as APIs de kit da Web HTML e JavaScript para adicionar menus de contexto a elementos HTML.

Menus de aplicativo (somente AIR)

O menu de aplicativo é um menu global aplicável ao aplicativo inteiro. Há suporte para menus de aplicativo no Mac OS X, mas não no Windows nem no Linux. No Mac OS X , o sistema operacional cria automaticamente o menu de aplicativo. Você pode usar a API de menu AIR para adicionar itens e submenus aos menus padrão. Você pode adicionar ouvintes para tratar os comandos de menu existentes. Ou você pode remover itens existentes.

Menus de janela (somente AIR)

O menu de janela está associado a uma única janela e é exibido abaixo da barra de título. Os menus podem ser adicionados a uma janela, criando um objeto NativeMenu e atribuindo-o à propriedade menu do objeto NativeWindow. Há suporte para menus de janela nos sistemas operacionais Windows e Linux, mas não no Mac OS X. Menus de janela nativos só podem ser usados em janelas com o cromo do sistema.

Menus do ícone de bandeja de encaixe e sistema (somente AIR)

Esses menus de ícone são semelhantes aos menus de contexto e são atribuídos a um ícone de aplicativo no encaixe do Mac OS X ou nas áreas de notificação do Windows ou do Linux, na barra de tarefas. Menus de ícone da bandeja do sistema e de encaixe usam a classe NativeMenu. No Mac OS X, os itens no menu são adicionados acima dos itens padrão do sistema operacional. Não há menu padrão no Windows nem no Linux.

Menus pop-up (somente AIR)

O menu pop-up AIR é semelhante ao menu de contexto, mas não está necessariamente associado a um objeto de aplicativo ou componente específico. Os menus pop-up podem ser exibidos em qualquer lugar na janela, chamando o método display() de qualquer objeto NativeMenu.

Menus personalizados

Menus nativos são inteiramente desenhados pelo sistema operacional e, como tal, estão presentes fora dos modelos de processamento Flash e HTML. Em vez de usar menus nativos, você sempre pode criar seus próprios menus não-nativos personalizados usando MXML, ActionScript ou JavaScript (no AIR). Esses menus devem ser inteiramente renderizados no conteúdo do aplicativo.

menus do Flex

A estrutura do Adobe® Flex™ oferece um conjunto de componentes de menu do Flex. Os menus do Flex são desenhados pelo tempo de execução, e não pelo sistema operacional, e não são menus nativos. O componente de menu do Flex pode ser usado em janelas do Flex que não têm o cromo do sistema. Outra vantagem de usar o componente do menu Flex é que você pode especificar de forma clara os menus no formato MXML. Se estiver usando a estrutura do Flex, use as classes de menu do Flex em menus de janela, em vez das classes nativas.

No conteúdo SWF, qualquer objeto herdado de InteractiveObject pode ser determinado um menu de contexto atribuindo um objeto de menu à respectiva propriedade contextMenu. Vários comandos são incluídos por padrão, como Avançar, Voltar, Imprimir, Qualidade e Zoom. No tempo de execução do AIR, o objeto de menu atribuído ao contextMenu pode ser do tipo NativeMenu ou do tipo ContextMenu. No tempo de execução do Flash Player, apenas a classe ContextMenu está disponível.

Você pode ouvir eventos do menu nativo ou de menus contextuais ao usar as classes ContextMenu e ContextMenuItem; as duas são despachadas. Um benefício fornecido pelas propriedades do objeto ContextMenuEvent é que contextMenuOwner identifica o objeto ao qual o menu está associado e mouseTarget identifica o objeto que foi clicado para abrir o menu. Essas informações não estão disponíveis do objeto NativeMenuEvent.

O exemplo a seguir cria um Sprite e adiciona um menu de contexto de edição simples:

var sprite:Sprite = new Sprite(); 
sprite.contextMenu = createContextMenu() 
private function createContextMenu():ContextMenu{ 
    var editContextMenu:ContextMenu = new ContextMenu(); 
    var cutItem:ContextMenuItem = new ContextMenuItem("Cut") 
    cutItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCutCommand); 
    editContextMenu.customItems.push(cutItem); 
     
    var copyItem:ContextMenuItem = new ContextMenuItem("Copy") 
    copyItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCopyCommand);             
    editContextMenu.customItems.push(copyItem); 
     
    var pasteItem:ContextMenuItem = new ContextMenuItem("Paste") 
    pasteItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doPasteCommand); 
    editContextMenu.customItems.push(pasteItem); 
         
    return editContextMenu 
} 
private function doCutCommand(event:ContextMenuEvent):void{trace("cut");} 
private function doCopyCommand(event:ContextMenuEvent):void{trace("copy");} 
private function doPasteCommand(event:ContextMenuEvent):void{trace("paste");}

var square:Sprite = new Sprite(); 
square.graphics.beginFill(0x000000); 
square.graphics.drawRect(0,0,100,100); 
square.graphics.endFill(); 
square.x = 
square.y = 10; 
addChild(square); 
 
var menuItem:ContextMenuItem = new ContextMenuItem("Change Color"); 
menuItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT,changeColor); 
var customContextMenu:ContextMenu = new ContextMenu(); 
customContextMenu.hideBuiltInItems(); 
customContextMenu.customItems.push(menuItem); 
square.contextMenu = customContextMenu; 
 
function changeColor(event:ContextMenuEvent):void 
{ 
    square.transform.colorTransform = getRandomColor(); 
} 
function getRandomColor():ColorTransform 
{ 
    return new ColorTransform(Math.random(), Math.random(),         Math.random(),1,(Math.random() * 512) - 255,         (Math.random() * 512) -255, (Math.random() * 512) - 255, 0); 
}

Os menus nativos são de natureza hierárquica. Os objetos NativeMenu contêm objetos-filho NativeMenuItem. Os objetos NativeMenuItem que representam submenus, por sua vez, podem conter objetos NativeMenu. O objeto de menu de nível superior ou raiz na estrutura representa a barra de menu de menus de aplicativo e janela. (Menus de contexto, ícone e pop-up não têm uma barra de menu).

O diagrama a seguir ilustra a estrutura de um menu típico. O menu raiz representa a barra de menu e contém dois itens de menu que fazem referência ao submenu File e ao submenu Edit. O submenu Arquivo nessa estrutura contém dois itens de comando e um item que faz referência ao submenu Open Recent Menu, que contém, ele mesmo, três itens. O submenu Edit contém três comandos e um separador.

Visualizar gráfico inteiro

Definir um submenu requer um objeto NativeMenu e um objeto NativeMenuItem. O objeto NativeMenuItem define o rótulo exibido no menu pai e permite ao usuário abrir o submenu. O objeto NativeMenu funciona como um recipiente de itens no submenu. O objeto NativeMenuItem se refere ao objeto NativeMenu pela propriedade submenu NativeMenuItem.

Para exibir um exemplo de código que cria esse menu, consulte Exemplo de menu nativo: menu de janela e de aplicativo (AIR).

Os objetos NativeMenu e NativeMenuItem despacham os eventos preparing, displaying e select:

Displaying:

Imediatamente antes de o menu ser exibido, o menu e os respectivos itens de menu despacham o evento displaying para qualquer ouvinte registrado.

Os eventos preparing e displaying dão a oportunidade de atualizar o conteúdo do menu ou a aparência do item antes de eles serem mostrados ao usuário. Por exemplo, no ouvinte do evento displaying do menu “Abrir recentes”, você pode alterar os itens de menu para que reflitam a lista atual de documentos exibidos recentemente.

Se você remover o item de menu cujo atalho no teclado acionou o evento preparing, a interação com o menu é efetivamente cancelada e o evento select não é despachado.

As propriedades target e currentTarget do evento são ambas um objeto em que o ouvinte está registrado: seja o próprio menu ou um de seus itens.

O evento preparing é despachado antes do evento displaying. Geralmente, você ouve um dos dois eventos, mas não ambos.

Select:

Quando um item de comando é escolhido pelo usuário, o item despacha um evento select para qualquer ouvinte registrado. Itens de submenu e separadores não podem ser selecionados, portanto, nunca despacham um evento select.

O evento select surge em bolha de um item de menu para o menu que o contém, em cima do menu raiz. Você pode ouvir eventos select diretamente em um item e pode ouvir mais acima na estrutura de menu. Quando você ouvir o evento select em um menu, poderá identificar o item selecionado usando a propriedade target do evento. Conforme o evento surge em bolha pela hierarquia de menu, a propriedade currentTarget do objeto event identifica o objeto de menu atual.

Nota: Os objetos ContextMenu e ContextMenuItem despacham eventos menuItemSelect e menuSelect, bem como eventos select, preparing e displaying.

Você pode atribuir um equivalente de tecla (às vezes chamado de acelerador) em um comando de menu. O item do menu despacha o evento select para qualquer ouvinte registrado quando a tecla ou combinação de teclas é pressionada. O menu que contém o item deve ser parte do menu do aplicativo ou a janela ativa do comando que deve ser chamado.

Os equivalentes de tecla têm duas partes, uma seqüência representando a tecla primária e uma matriz de teclas do modificador, que também devem ser pressionadas. Para atribuir a tecla primária, defina a propriedade keyEquivalent do item de menu para a seqüência de caractere único dessa tecla. Se você usar uma letra maiúscula, a tecla Shift é adicionada à matriz do modificador automaticamente.

No Mac OS X, o modificador padrão é a tecla Command (Keyboard.COMMAND). No Windows e no Linux, é a tecla Control (Keyboard.CONTROL). Essas teclas padrão são adicionadas automaticamente à matriz do modificador. Para atribuir teclas do modificador diferentes, atribua uma nova matriz contendo os códigos de tecla desejados à propriedade keyEquivalentModifiers. A matriz padrão é sobrescrita. Se você usar os modificadores padrão ou atribuir a sua própria matriz de modificador, a tecla Shift será adicionada, se a seqüência atribuída à propriedade keyEquivalent for uma letra maiúscula. As constantes dos códigos de tecla para usar nas teclas do modificador são definidas na classe Keyboard.

A seqüência de equivalente de tecla atribuída é exibida automaticamente ao lado no nome do item de menu. O formato depende do sistema operacional do usuário e das preferências do sistema.

O exemplo a seguir atribui Ctrl+Shift+G como equivalente de tecla de um item de menu:

var item:NativeMenuItem = new NativeMenuItem("Ungroup"); 
item.keyEquivalent = "G"; 

Este exemplo atribui Ctrl+Shift+G como equivalente de tecla, definindo diretamente a matriz do modificador:

var item:NativeMenuItem = new NativeMenuItem("Ungroup"); 
item.keyEquivalent = "G"; 
item.keyEquivalentModifiers = [Keyboard.CONTROL]; 

Os mnemônicos são parte da interface de teclado do sistema operacional em menus. Linux, Mac OS X e Windows permitem a usuários abrir menus e selecionar comandos com o teclado, mas há diferenças sutis.

No Mac OS X, o usuário digita a primeira ou as duas primeiras letras do menu ou comando e, em seguida, pressiona a tecla retornar. A propriedade mnemonicIndex é ignorada.

No Windows, apenas uma única letra é significativa. Por padrão, a letra significativa é o primeiro caractere no rótulo, mas se você atribuir um mnemônico ao item de menu, o caractere significativo se torna a letra designada. Se dois itens em um menu têm o mesmo caractere significativo (quer um mnemônico tenha ou não sido atribuído), a interação de teclado do usuário com o menu muda um pouco. Em vez de pressionar uma única letra para selecionar o menu ou comando, o usuário deve pressionar a letra quantas vezes for necessário para realçar o item desejado e, em seguida, pressionar a tecla Enter para concluir a seleção. Para manter um comportamento consistente, você deve atribuir um mnemônico exclusivo a cada item no menu, em menus de janela.

No Linux, nenhum mnemônico padrão é fornecido. Você deve especificar um valor para a propriedade mnemonicIndex de um item de menu para fornecer um mnemônico.

Especifique o caractere mnemônico como índice na seqüência de rótulo. O índice do primeiro caractere em um rótulo é 0. Portanto, para usar "r" como o mnemônico de um item de menu rotulado, "Format", você deve definir a propriedade mnemonicIndex igual a 2.

var item:NativeMenuItem = new NativeMenuItem("Format"); 
item.mnemonicIndex = 2; 

Os itens de menu têm duas propriedades de estados, marcados e ativados:

marcado

Defina como true para exibir uma marca de seleção ao lado do rótulo de item.

var item:NativeMenuItem = new NativeMenuItem("Format"); 
item.checked = true; 

ativado

Alterne o valor entre true e false para controlar se o comando está ativado. Itens desativados ficam visualmente “esmaecidos” e não despacham eventos select.

var item:NativeMenuItem = new NativeMenuItem("Format"); 
item.enabled = false; 

A propriedade data da classe NativeMenuItem permite fazer referência a um objeto arbitrário em cada item. Por exemplo, no menu "Open Recent", você pode atribuir o objeto File de cada documento a cada item do menu.

var file:File = File.applicationStorageDirectory.resolvePath("GreatGatsby.pdf") 
var menuItem:NativeMenuItem = docMenu.addItem(new NativeMenuItem(file.name)); 
menuItem.data = file;