Nozioni fondamentali sui menu

Flash Player 9 e versioni successive, Adobe AIR 1.0 e versioni successive

Per una spiegazione rapida ed esempi di codice sulla creazione di menu nativi in applicazioni AIR, vedete i seguenti articoli delle Guide rapide in Centro per sviluppatori Adobe:

Le classi dei menu nativi vi consentono di accedere alle funzionalità del sistema operativo in cui l'applicazione è in esecuzione. È possibile utilizzare oggetti NativeMenu per i menu dell'applicazione (disponibili in Mac OS X), i menu delle finestre (disponibili in Windows e Linux), i menu di scelta rapida e i menu a comparsa.

Al di fuori di AIR, potete utilizzare le classi del menu di scelta rapida per modificare il menu di scelta rapida visualizzato automaticamente da Flash quando un utente fa clic con il pulsante destro del mouse o fa clic con il tasto cmd su un oggetto nell'applicazione. (Per le applicazioni AIR non viene visualizzato un menu di scelta rapida automatico.)

Classi dei menu

Le classi dei menu includono:

Tipologie di menu

AIR supporta le seguenti tipologie di menu:

Menu di scelta rapida
I menu di scelta rapida si aprono facendo clic con il pulsante destro del mouse o facendo clic mentre si tiene premuto il tasto Comando su un oggetto interattivo in un contenuto SWF o su un elemento del documento in un contenuto HTML.

Nel runtime Flash Player, un menu di scelta rapida viene automaticamente visualizzato. Potete utilizzare le classi ContextMenu e ContextMenuItem per aggiungere comandi personalizzati al menu. Potete anche rimuovere alcuni dei comandi incorporati, ma non tutti.

Nel runtime AIR, potete creare un menu di scelta rapida usando la classe NativeMenu o ContextMenu. Nel contenuto HTML in AIR, potete usare le API HTML e JavaScript di Webkit per aggiungere i menu di scelta rapida agli elementi HTML.

Menu dell'applicazione (solo AIR)
Un menu dell'applicazione è un menu globale che viene usato nell'intera applicazione. I menu dell'applicazione sono supportati in Mac OS X, ma non in Windows e Linux. In Mac OS X, il sistema operativo crea automaticamente un menu dell'applicazione. Potete usare l'API dei menu di AIR per aggiungere voci e menu secondari ai menu standard. Potete aggiungere listener per gestire i comandi dei menu esistenti, oppure rimuovere le voci di menu esistenti.

Menu delle finestre (solo AIR)
Un menu di una finestra è associato a un'unica finestra e viene visualizzato sotto la barra del titolo. È possibile aggiungere i menu a una finestra creando un oggetto NativeMenu e assegnandolo alla proprietà menu dell'oggetto NativeWindow. I menu delle finestre sono supportati nei sistemi operativi Windows e Linux, ma non in Mac OS X. I menu delle finestre nativi possono essere utilizzati solo con finestre associate a chrome di sistema.

Menu delle icone del dock e delle icone della barra delle applicazioni (solo AIR)
Questi menu a icona sono analoghi ai menu di scelta rapida e vengono assegnati a un'icona di un'applicazione nel dock di Mac OS X o nell'area di notifica della barra delle applicazioni di Windows e Linux. I menu delle icone del dock e della barra delle applicazioni usano la classe NativeMenu. In Mac OS X, le voci del menu sono aggiunte sopra le voci standard del sistema operativo. In Windows o Linux non è disponibile un menu standard.

Menu a comparsa (solo AIR)
Un menu a comparsa di AIR è simile a un menu di scelta rapida, ma non è necessariamente associato a un particolare oggetto o componente dell'applicazione. I menu a comparsa possono essere visualizzati in qualunque punto di una finestra chiamando il metodo display() per un oggetto NativeMenu.

Menu personalizzati
I menu personalizzati sono creati interamente dal sistema operativo e pertanto esistono anche all'esterno dei modelli di rendering di Flash e HTML. Anziché utilizzare i menu nativi, potete sempre creare i vostri menu non nativi personalizzati utilizzando MXML, ActionScript o JavaScript (in AIR). Per tali menu, eseguite il rendering completo all'interno del contenuto dell'applicazione.

Menu Flex
Il framework Adobe® Flex™ fornisce una serie di componenti per i menu Flex. I menu Flex sono ricavati dal runtime invece che dal sistema operativo e non sono menu nativi . È possibile usare un componente di un menu Flex per le finestre Flex che non dispongono di un chrome di sistema. Un altro vantaggio che deriva dall'uso dei componenti per i menu Flex consiste nel poter definire i menu in forma dichiarativa nel formato MXML. Con il framework Flex usate le classi dei menu Flex anziché le classi native per i menu delle finestre.

Menu predefiniti (solo AIR)

I seguenti menu predefiniti sono forniti dal sistema operativo o da una classe AIR incorporata:

  • Menu dell'applicazione in Mac OS X

  • Menu delle icone del dock in Mac OS X

  • Menu di scelta rapida per testo selezionato e immagini in contenuto HTML

  • Menu di scelta rapida per testo selezionato in un oggetto TextField (o in un oggetto che estende TextField)

Informazioni sui menu di scelta rapida

Nel contenuto SWF è possibile associare a qualunque oggetto che erediti da InteractiveObject un menu di scelta rapida, assegnando un oggetto menu alla relativa proprietà contextMenu . Alcuni comandi sono inclusi per impostazione predefinita: Avanti, Indietro, Stampa, Qualità e Zoom. Nel runtime di AIR, l'oggetto menu assegnato a contextMenu può essere di tipo NativeMenu o ContextMenu. Nel runtime di Flash Player, è disponibile solo la classe ContextMenu.

Quando usate le classi ContextMenu e ContextMenuItem, potete intercettare gli eventi dei menu nativi o dei menu di scelta rapida; vengono infatti inviati entrambi. Uno dei vantaggi forniti dalle proprietà dell'oggetto ContextMenuEvent è la capacità di contextMenuOwner di identificare l'oggetto a cui è associato il menu, mentre mouseTarget identifica l'oggetto su cui è stato fatto clic per aprire il menu. Queste informazioni non sono disponibili tramite l'oggetto NativeMenuEvent.

Nell'esempio che segue viene creato uno Sprite e viene aggiunto un semplice menu di scelta rapida di modifica (Edit):

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");}
Nota: a differenza del contenuto SWF visualizzato in ambiente browser, i menu di scelta rapida di AIR non hanno comandi incorporati.

Personalizzazione di un menu di scelta rapida di Flash Player

In un browser o file proiettore, i menu di scelta rapida nel contenuto SWF dispongono sempre di voci incorporate. Potete rimuovere tutti i comandi predefiniti dal menu, a eccezione delle opzioni Impostazioni e Informazioni su. Se la proprietà dello stage showDefaultContextMenu viene impostata su false , vengono rimossi questi comandi dal menu di scelta rapida.

Per creare un menu di scelta rapida personalizzato per un oggetto di visualizzazione specifico, create una nuova istanza della classe ContextMenu, chiamate il metodo hideBuiltInItems() e assegnate tale istanza alla proprietà contextMenu di quell'istanza DisplayObject. L'esempio seguente fornisce un comando di menu di scelta rapida a un quadrato tracciato dinamicamente per convertirlo in un colore casuale:

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

Struttura dei menu nativi (AIR)

Per loro natura, i menu nativi hanno una struttura gerarchica. Gli oggetti NativeMenu contengono oggetti NativeMenuItem secondari. Gli oggetti NativeMenuItem che rappresentano sottomenu possono contenere a loro volta oggetti NativeMenu. L'oggetto di un menu di livello più alto o principale nella struttura rappresenta la barra dei menu per i menu dell'applicazione e delle finestre (i menu di scelta rapida, delle icone e a comparsa non prevedono una barra dei menu).

Il seguente diagramma illustra la struttura di un menu tipico. Il menu principale rappresenta la barra dei menu e contiene due voci di menu che fanno riferimento a un sottomenu File e un sottomenu Modifica . Il sottomenu File in questa struttura contiene due comandi e una voce che richiama il sottomenu Apri recente , che a sua volta contiene tre voci. Il sottomenu Modifica contiene tre comandi e un separatore.

La definizione di un sottomenu richiede sia un oggetto NativeMenu sia un oggetto NativeMenuItem. L'oggetto NativeMenuItem definisce l'etichetta visualizzata nel menu superiore e consente all'utente di aprire il sottomenu. L'oggetto NativeMenu agisce da contenitore per le voci di un sottomenu. L'oggetto NativeMenuItem fa riferimento all'oggetto NativeMenu attraverso la proprietà submenu di NativeMenuItem.

Per visualizzare un esempio di codice che crea questo menu, consultate Esempio di menu nativo: menu della finestra e dell'applicazione (AIR) .

Eventi dei menu

Entrambi gli oggetti NativeMenu e NativeMenuItem inviano gli eventi preparing , displaying e select :

Preparing: ogni volta che l'oggetto sta per iniziare un'interazione utente, il menu e le voci di menu inviano un evento preparing a qualsiasi listener registrato. L'interazione include l'apertura del menu o la selezione di un elemento con una scelta rapida da tastiera.
Nota: l'evento preparing è disponibile solo per Adobe AIR 2.6 e versioni successive.
Displaying:
appena prima della visualizzazione di un menu, il menu e le relative voci inviano un evento displaying a tutti i listener registrati.

Glie eventi preparing e displaying consentono di aggiornare il contenuto del menu e la visualizzazione delle voci prima che il menu venga mostrato all'utente. Ad esempio, nel listener dell'evento displaying per un menu “Open Recent” è possibile modificare le voci di menu in modo da visualizzare l'elenco aggiornato degli ultimi documenti aperti.

Se rimuovete la voce di menu la cui scelta rapida da tastiera ha attivato un evento preparing , l'interazione di menu è effettivamente annullata e non viene inviato nessun evento select .

Le proprietà target e currentTarget dell'evento sono entrambe l'oggetto su cui è stato registrato il listener: il menu stesso o una delle sue voci.

L'evento preparing viene inviato prima dell'evento displaying . In genere si intercetta un evento o l'altro, ma non entrambi.

Seleziona:
quando l'utente sceglie un comando, viene inviato un evento select a tutti i listener registrati. Non è possibile selezionare le voci di sottomenu e separatori, che quindi non inviano mai un evento select .

Un evento select si propaga da una voce di menu al menu che la contiene, fino ad arrivare al menu principale. È possibile intercettare un evento select direttamente su una voce o in un parte precedente nella struttura dei menu. Per intercettare un evento select in corrispondenza di un menu, potete identificare la voce selezionata usando la proprietà target dell'evento. Mentre l'evento si propaga nella gerarchia dei menu, la proprietà currentTarget dell'oggetto evento identifica l'oggetto del menu corrente.

Nota: gli oggetti ContextMenu e ContextMenuItem inviano eventi menuItemSelect e menuSelect oltre agli eventi select preparing e displaying .

Tasti equivalenti per comandi di menu nativi (AIR)

Potete assegnare un equivalente da tastiera (in genere definito una scelta rapida da tastiera) a ogni comando di un menu. Quando premete il tasto o la combinazione di tasti scelta, la voce di menu invia un evento select a tutti i listener registrati. Il menu contenente la voce deve fare parte del menu dell'applicazione o del menu della finestra attiva per poter richiamare il comando.

I tasti di scelta rapida sono composti da due parti: una stringa che rappresenta il tasto principale e un array di tasti modificatori che è necessario premere insieme al tasto principale. Per assegnare il tasto principale, impostate la proprietà keyEquivalent per la voce di menu sulla stringa corrispondente al carattere del tasto. Se usate una lettera maiuscola, all'array dei modificatori viene automaticamente aggiunto il tasto Maiusc.

In Mac OS X, il modificatore predefinito è il tasto Comando ( Keyboard.COMMAND ). In Windows e Linux è il tasto Ctrl ( Keyboard.CONTROL ). I tasti predefiniti vengono aggiunti automaticamente all'array modificatore. Per usare tasti modificatori diversi, assegnate un nuovo array contenente i codici dei tasti desiderati alla proprietà keyEquivalentModifiers . L'array predefinito viene sovrascritto. Sia quando usate i modificatori predefiniti sia quando create un array di modificatori personalizzato, se la stringa assegnata alla proprietà keyEquivalent è una lettera maiuscola viene sempre aggiunto il tasto Maiusc. Le costanti corrispondenti ai codici dei tasti da usare per i tasti modificatori sono definite nella classe Keyboard.

La stringa della scelta rapida da tastiera assegnata viene automaticamente visualizzata accanto al nome della voce di menu. Il formato dipende dal sistema operativo dell'utente e dalle preferenze di sistema impostate.

Nota: se assegnate a un array di modificatori il valore Keyboard.COMMAND in Windows, nel menu non vengono visualizzate scelte rapide da tastiera. Tuttavia, per attivare il comando del menu è necessario premere il tasto Ctrl.

Nel seguente esempio viene usato Ctrl+Maiusc+G come scelta rapida da tastiera per una voce di menu:

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

In questo esempio viene assegnata la combinazione Ctrl+Maiusc+G come scelta rapida da tastiera impostando direttamente l'array di modificatori:

var item:NativeMenuItem = new NativeMenuItem("Ungroup"); 
item.keyEquivalent = "G"; 
item.keyEquivalentModifiers = [Keyboard.CONTROL]; 
Nota: le scelte rapide da tastiera vengono attivate solo per i menu dell'applicazione e delle finestre. Se aggiungete una scelta rapida da tastiera a un menu a comparsa o di scelta rapida, questa verrà visualizzata nell'etichetta del menu, ma il comando associato non sarà mai eseguito.

Caratteri mnemonici (AIR)

I caratteri mnemonici sono un sistema per garantire l'interazione tra tastiera e menu. In Linux, Mac OS X e Windows, sebbene con alcune piccole differenze, gli utenti possono aprire i menu e selezionarne i comandi usando la tastiera.

In Mac OS X l'utente digita la prima lettera (o le prime due) del menu o del comando e quindi preme il tasto Invio. La proprietà mnemonicIndex viene ignorata.

In Windows, è significativa solo la prima lettera. Per impostazione predefinita, la lettera significativa è il primo carattere dell'etichetta, ma se si assegna un carattere mnemonico alla voce di menu, il carattere significativo diventa la lettera indicata. Se due voci di un menu hanno lo stesso carattere significativo (assegnato o meno come carattere mnemonico), l'interazione tra tastiera e menu cambia leggermente. Invece di premere una sola lettera per selezionare il menu o il comando, l'utente deve premere la lettera il numero di volte necessario per evidenziare la voce desiderata e quindi premere Invio per completare la selezione. Per garantire un comportamento coerente, si consiglia di assegnare un carattere mnemonico univoco a ogni voce di un menu per i menu delle finestre.

In Linux non è presente alcun carattere mnemonico predefinito. Affinché una voce di menu comprenda un carattere mnemonico, dovete specificare un valore per la proprietà mnemonicIndex .

Specificate il carattere mnemonico come indice nella stringa dell'etichetta. L'indice del primo carattere di un'etichetta è 0. Pertanto, per usare “r” come carattere mnemonico per una voce di menu con etichetta “Format”, occorre impostare la proprietà mnemonicIndex su 2.

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

Stato delle voci di menu

Le voci di menu hanno due proprietà che ne descrivono lo stato: checked e enabled .

checked
Impostate la proprietà su true per visualizzare un segno di spunta accanto all'etichetta della voce.
var item:NativeMenuItem = new NativeMenuItem("Format"); 
item.checked = true; 

enabled
Alternate il valore tra true e false per attivare o disattivare il comando. Le voci disattivate vengono “oscurate” e non inviano eventi select .
var item:NativeMenuItem = new NativeMenuItem("Format"); 
item.enabled = false; 

Associazione di un oggetto a una voce di menu

La proprietà data della classe NativeMenuItem consente di fare riferimento a un oggetto arbitrario in ogni voce. Ad esempio, nel menu “Open Recent” potete assegnare l'oggetto File di ogni documento a ogni voce di menu.

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