Sei sulla pagina 1di 159

BlackBerry Java SDK

UI and Navigation
Versione: 6.0
Guida allo sviluppo
Pubblicato: 2010-12-21
SWD-1239696-1223125741-004
Indice
1 Creazione di un'interfaccia utente compatibile con le interfacce utente BlackBerry standard....................... 6

2 Modalità di input e navigazione per l'utente BlackBerry.................................................................................. 7


Touchscreen...................................................................................................................................................... 7
Trackball o trackpad.......................................................................................................................................... 9
Sensibilità della trackball........................................................................................................................... 9
Movimento della trackball......................................................................................................................... 9
Rotellina............................................................................................................................................................ 10
Tastiera............................................................................................................................................................. 10
Metodi di interazione dei dispositivi BlackBerry.............................................................................................. 10

3 Schermate......................................................................................................................................................... 11
Classi di schermate........................................................................................................................................... 11
Gestione di un'area di disegno......................................................................................................................... 12
Creazione di una transizione di schermata....................................................................................................... 13
Esempio di codice: creazione di una transizione di schermata................................................................. 14
Specifica dell'orientamento e della direzione dello schermo........................................................................... 15
Recupero dell'orientamento del touchscreen........................................................................................... 17
Limitazione della direzione del touchscreen............................................................................................. 17
Ricezione delle notifiche quando la dimensione dell'area di disegno del touchscreen cambia................ 17

4 Accelerometro.................................................................................................................................................. 18
Tipi di dati forniti dall'accelerometro............................................................................................................... 18
Recupero dei dati dell'accelerometro............................................................................................................... 18
Recupero dei dati dell'accelerometro a intervalli specifici............................................................................... 19
Invio di una query all'accelerometro quando l'applicazione è in primo piano................................................. 20
Invio di una query all'accelerometro quando l'applicazione è in background.................................................. 20
Archiviazione delle letture dell'accelerometro in un buffer............................................................................. 21
Recupero delle letture dell'accelerometro da un buffer.................................................................................. 22
Recupero dell'ora di una lettura dall'accelerometro........................................................................................ 22

5 Eventi................................................................................................................................................................ 23
Risposta agli eventi di navigazione................................................................................................................... 23
Determinazione del tipo di metodo di immissione........................................................................................... 23
Modelli di interazione del touchscreen............................................................................................................ 24
Risposta agli eventi del touchscreen................................................................................................................ 25
Risposta agli eventi di sistema quando l'utente tocca lo schermo............................................................ 26
Risposta a un utente che fa scorrere rapidamente il dito verso l'alto sullo schermo............................... 26
Risposta a un utente che fa scorrere rapidamente il dito verso il basso sullo schermo............................ 27
Risposta a un utente che fa scorrere rapidamente il dito a sinistra sullo schermo................................... 28
isposta a un utente che fa scorrere rapidamente il dito a destra sullo schermo...................................... 28
Risposta a un utente che fa clic sullo schermo.......................................................................................... 29
Risposta a un utente che tocca lo schermo due volte rapidamente......................................................... 30
Risposta a un utente che tocca e trascina un elemento sullo schermo.................................................... 30
Risposta a un utente che tocca leggermente lo schermo.......................................................................... 31
Risposta a un'azione di scorrimento.......................................................................................................... 31
Risposta a un utente che tocca lo schermo contemporaneamente in due posizioni................................ 32
Avvicinamento o allontanamento del pollice e dell'indice sullo schermo........................................................ 32
Avvicinamento e allontanamento del pollice e dell'indice sullo schermo................................................. 33
Azioni di spostamento tramite trackpad.......................................................................................................... 34
Azioni di spostamento tramite trackpad................................................................................................... 35
Avvio eventi...................................................................................................................................................... 36

6 API Command Framework................................................................................................................................ 37


Utilizzo di un comando con un componente dell'interfaccia utente................................................................ 38
Utilizzo di un comando in una o più applicazioni.............................................................................................. 39

7 Disposizione dei componenti dell'interfaccia utente....................................................................................... 42


Disposizione dei componenti dell'interfaccia utente....................................................................................... 43
Creazione di un layout di griglia........................................................................................................................ 43
Creazione di un layout di griglia................................................................................................................ 45
Visualizzazione di campi in una coppia di gestori temporanea........................................................................ 47
Visualizzazione temporanea di un oggetto ButtonField e di un oggetto LabelField nella parte superiore
e inferiore della schermata........................................................................................................................ 47
Visualizzazione di un campo in una posizione assoluta della schermata......................................................... 50
Visualizzazione di un'etichetta in una posizione assoluta della schermata............................................... 50
Esempio di codice: visualizzazione di un'etichetta in una posizione assoluta della schermata................ 51

8 Componenti dell'interfaccia utente.................................................................................................................. 52


Aggiunta di un componente interfaccia utente a una schermata.................................................................... 52
Allineamento di un campo a una riga di testo.................................................................................................. 52
Pulsanti............................................................................................................................................................. 52
Procedura consigliata: implementazione dei pulsanti............................................................................... 53
Creazione di un pulsante........................................................................................................................... 53
Caselle di controllo........................................................................................................................................... 54
Procedura consigliata: implementazione delle caselle di controllo.......................................................... 54
Creazione di una casella di controllo......................................................................................................... 55
Creazione di un file bitmap............................................................................................................................... 56
Creazione di un campo personalizzato............................................................................................................. 57
Creazione di un campo di visualizzazione del contenuto Web......................................................................... 60
Visualizzazione del contenuto HTML in un campo del browser................................................................ 60
Visualizzazione del contenuto HTML da una pagina web in un campo del browser................................. 62
Visualizzazione del contenuto HTML da una risorsa nell'applicazione...................................................... 63
Configurazione di un campo del browser.................................................................................................. 65
Invio dei dati dei moduli a un indirizzo Web in un campo del browser..................................................... 66
Finestre di dialogo............................................................................................................................................ 68
Procedura consigliata: implementazione delle finestre di dialogo............................................................ 69
Creazione di una finestra di dialogo.......................................................................................................... 71
Elenchi a discesa............................................................................................................................................... 71
Procedura consigliata: implementazione degli elenchi a discesa.............................................................. 72
Creazione di un elenco a discesa............................................................................................................... 72
Etichette............................................................................................................................................................ 75
Procedura consigliata: implementazione delle etichette.......................................................................... 75
Creazione di un'etichetta di testo.............................................................................................................. 75
Elenchi e tabelle................................................................................................................................................ 75
Procedura consigliata: implementazione di elenchi e tabelle................................................................... 78
Creazione di una casella di riepilogo......................................................................................................... 78
Pulsanti di opzione............................................................................................................................................ 80
Procedura consigliata: implementazione dei pulsanti di opzione............................................................. 81
Creazione di un pulsante di opzione.......................................................................................................... 81
Indicatori di attività e indicatori di progresso................................................................................................... 83
Procedura consigliata: implementazione degli indicatori di attività e degli indicatori di progresso......... 84
Indicazione del progresso delle attività..................................................................................................... 85
Selettori............................................................................................................................................................ 92
Procedura consigliata: implementazione di selettori................................................................................ 94
Creazione di un selettore di data............................................................................................................... 94
Creazione di un selettore di file................................................................................................................. 97
Ricerca.............................................................................................................................................................. 100
Procedura consigliata: implementazione della ricerca.............................................................................. 101
Creazione di un campo di ricerca.............................................................................................................. 102
Campo di testo con completamento automatico...................................................................................... 104
Caselle di selezione........................................................................................................................................... 109
Creazione di una casella di selezione......................................................................................................... 110
Procedura consigliata: implementazione delle caselle di selezione.......................................................... 112
Campi di testo................................................................................................................................................... 113
Procedura consigliata: implementazione dei campi di testo..................................................................... 114
Creazione di un campo di testo................................................................................................................. 114
Creazione di un campo data...................................................................................................................... 115
Creazione di un campo Password.............................................................................................................. 116
Visualizzazioni ad albero................................................................................................................................... 116
Procedura consigliata: implementazione delle visualizzazioni ad albero.................................................. 117
Creazione di un campo con visualizzazione ad albero............................................................................... 117

9 Immagini........................................................................................................................................................... 119
Utilizzo di immagini codificate.......................................................................................................................... 119
Accesso a un'immagine codificata attraverso un flusso di input............................................................... 119
Codifica di un'immagine............................................................................................................................ 119
Visualizzazione di un'immagine codificata................................................................................................ 120
Specifica della dimensione di visualizzazione di un'immagine codificata.................................................. 120
Specifica della modalità di decodifica di un'immagine.............................................................................. 120
Visualizzazione di un'immagine per zoom e panoramica................................................................................. 120
Esempio di codice: visualizzazione di un'immagine per zoom e panoramica............................................ 121
Visualizzazione di un'immagine per zoom e panoramica.......................................................................... 121
Visualizzazione di una fila di immagini per lo scorrimento............................................................................... 122
Esempio di codice: visualizzazione di una fila di immagini per lo scorrimento......................................... 122
Visualizzazione di una fila di immagini per lo scorrimento........................................................................ 123

10 Voci di menu..................................................................................................................................................... 125


Creazione di un menu....................................................................................................................................... 125
Esempio di codice: creazione di un menu................................................................................................. 126
Procedura consigliata: implementazione dei menu......................................................................................... 127
Sottomenu........................................................................................................................................................ 127
Procedura consigliata: implementazione di sottomenu............................................................................ 129
Creazione di un sottomenu....................................................................................................................... 129
Esempio di codice: creazione di un sottomenu......................................................................................... 131
Menu a comparsa............................................................................................................................................. 132
Procedura consigliata: implementazione di menu a comparsa................................................................. 133
Informazioni sul posizionamento di voci nei menu a comparsa................................................................ 133
Supporto per i menu di scelta rapida esistenti.......................................................................................... 134
Creazione di un menu a comparsa............................................................................................................ 134
Aggiunta di una voce di menu a un'applicazione BlackBerry Device Software................................................. 139
Aggiunta di una voce di menu a un'applicazione BlackBerry Device Software......................................... 140
Modifica dell'aspetto di un menu..................................................................................................................... 141
Modifica dell'aspetto di un menu.............................................................................................................. 141
Esempio di codice: modifica dell'aspetto di un menu............................................................................... 143
11 Caratteri personalizzati..................................................................................................................................... 145
Installazione e utilizzo di un carattere personalizzato in una BlackBerry Java Application.............................. 145
Esempio di codice: installazione e utilizzo di un carattere personalizzato in una BlackBerry Java Application
.......................................................................................................................................................................... 146

12 Controllo ortografico........................................................................................................................................ 148


Aggiunta della funzionalità di controllo ortografico......................................................................................... 148
Ascolto di un evento di controllo ortografico................................................................................................... 149

13 Risorse correlate............................................................................................................................................... 150

14 Glossario........................................................................................................................................................... 151

15 Commenti e suggerimenti................................................................................................................................ 152

16 Cronologia delle revisioni del documento........................................................................................................ 153

17 Note legali......................................................................................................................................................... 155


Guida allo sviluppo Creazione di un'interfaccia utente compatibile con le interfacce utente BlackBerry standard

Creazione di un'interfaccia utente compatibile 1


con le interfacce utente BlackBerry standard
È possibile utilizzare le API MIDP standard e le API dell'interfaccia utente BlackBerry® per creare un'interfaccia utente
BlackBerry® Java® Application.
I componenti delle API dell'interfaccia utente BlackBerry sono progettati per fornire layout e comportamenti
compatibili con le applicazioni di BlackBerry® Device Software. L'utilizzo di queste API consente non solo di utilizzare
i componenti che gli utenti BlackBerry conoscono bene, ma anche di risparmiare tempo poiché non è necessario
crearli.
• I componenti della schermata possono fornire un layout standard di schermata, un menu predefinito e un
comportamento standard quando un utente BlackBerry preme il tasto ESC, fa clic sul trackpad oppure tocca lo
schermo.
• I componenti dei campi possono fornire elementi standard per la selezione di date, pulsanti di scelta, caselle di
controllo, elenchi, campi di testo, etichette e comandi della barra di stato.
• I gestori di layout forniscono un'applicazione in grado di disporre i componenti sullo schermo di un dispositivo
BlackBerry secondo la modalità standard, ad esempio orizzontalmente, verticalmente o in modalità di
scorrimento da sinistra a destra.
È possibile utilizzare le API dell'interfaccia utente BlackBerry per creare un'interfaccia utente che includa tabelle,
griglie e altre funzionalità specifiche. È possibile utilizzare un modello di eventi Java standard per ricevere e rispondere
a tipi di eventi specifici. Un'applicazione BlackBerry può ricevere e rispondere agli eventi degli utenti, ad esempio
quando l'utente fa clic sul trackpad o digita sulla tastiera e agli eventi di sistema, ad esempio gli avvisi globali, i
cambiamenti dell'orologio e le connessioni mediante la porta USB.

6
Guida allo sviluppo Modalità di input e navigazione per l'utente BlackBerry

Modalità di input e navigazione per l'utente 2


BlackBerry
Per le attività di input e di navigazione i dispositivi BlackBerry® dispongono di tastiera, rotellina, trackball o trackpad,
nonché del tasto ESC. Sui dispositivi BlackBerry con touchscreen SurePress™, il clic sulla schermata equivale al clic
con la trackball o con la rotellina.
Una BlackBerry® Java® Application dovrebbe utilizzare il modello di input e navigazione seguente il più attentamente
possibile.
• Facendo clic con la rotellina, con la trackball o sulla schermata viene richiamato generalmente un menu.
• Con il tasto ESC è possibile annullare azioni o tornare alla schermata precedente. Premendo il tasto ESC varie
volte è possibile tornare alla schermata iniziale. Tenendo premuto il tasto ESC è possibile chiudere il browser o
l'applicazione multimediale.
Per impostazione predefinita, gli oggetti Screen BlackBerry forniscono questa funzionalità senza alcuna
personalizzazione; tuttavia, è necessario aggiungere voci di menu, ulteriore interfaccia utente e logica di navigazione.

Touchscreen
Per interagire con le applicazioni di un dispositivo BlackBerry® con touchscreen SurePress™, gli utenti utilizzano un
dito. Gli utenti digitano un testo e navigano tra le schermate eseguendo varie operazioni sul touchscreen.
Gli utenti possono inoltre eseguire delle operazioni facendo clic sulle icone presenti nella barra degli strumenti o
premendo il tasto Menu.
Sui dispositivi BlackBerry con touchscreen, gli utenti possono effettuare le seguenti operazioni:

Azione Risultato
toccare leggermente lo schermo Questa azione consente di evidenziare una voce.
In un campo di testo, se gli utenti toccano lo schermo vicino al cursore,
intorno al cursore viene visualizzato un riquadro. Il riquadro consente agli
utenti di riposizionare più facilmente il cursore.
toccare lo schermo Nelle applicazioni che supportano una visualizzazione a schermo intero,
come ad esempio BlackBerry® Maps e BlackBerry® Browser, questa azione
mostra e nasconde la barra degli strumenti.
toccare lo schermo due volte In una pagina Web, una mappa, un'immagine o una presentazione allegata
questa azione consente di ingrandire la pagina Web, la mappa, l'immagine
o la presentazione allegata.
tenere premuto un dito su un Nella barra degli strumenti questa azione consente di visualizzare una
elemento descrizione comandi che illustra l'azione rappresentata dall'icona.

7
Guida allo sviluppo Touchscreen

Azione Risultato
In un elenco messaggi, se gli utenti tengono premuto un dito sul mittente
o sull'oggetto di un messaggio, il dispositivo BlackBerry cerca il mittente o
l'oggetto.
toccare e trascinare un elemento Questa azione consente di spostare il contenuto presente sullo schermo
presente sullo schermo nella direzione indicata dal movimento. Quando gli utenti toccano e
trascinano una voce di menu, ad esempio, l'elenco delle voci di menu si
sposta nella stessa direzione.
In un campo di testo questa azione consente di spostare il riquadro e il
cursore nella stessa direzione.
toccare lo schermo Questa azione consente di evidenziare il testo o l'elenco di voci (ad esempio
contemporaneamente in due un elenco di messaggi) contenuto tra le due posizioni. Per aggiungere o
posizioni rimuovere il testo o le voci evidenziate, è possibile toccare la schermata in
un'altra posizione.
premere (fare clic su) lo schermo Questa azione consente di avviare un'azione. Quando ad esempio gli utenti
fanno clic su una voce presente in un elenco, viene visualizzata la schermata
associata a tale voce. Questa azione equivale a fare clic con la rotellina, con
la trackball o con il trackpad.
In una mappa, un'immagine o una presentazione allegata questa azione
consente di ingrandire la mappa, l'immagine o la presentazione allegata. In
una pagina Web questa azione consente di ingrandire la pagina Web o di
seguire un collegamento.
In un campo di testo questa azione consente di posizionare il cursore. Se il
campo contiene del testo, viene visualizzato un riquadro intorno al cursore.
far scorrere rapidamente un dito Far scorrere rapidamente un dito verso l'alto consente di visualizzare la
verso l'alto o verso il basso sullo schermata successiva. Far scorrere rapidamente un dito verso il basso
schermo consente di visualizzare la schermata precedente.
Quando viene visualizzata la tastiera, far scorrere rapidamente un dito verso
il basso consente di nascondere la tastiera e di visualizzare la barra degli
strumenti.
far scorrere rapidamente un dito Questa azione consente di visualizzare l'immagine o il messaggio precedenti
verso destra o verso sinistra sullo o successivi oppure il giorno, la settimana o il mese precedenti o successivi
schermo in un calendario.
far scorrere un dito verso l'alto o In modalità fotocamera, far scorrere un dito verso l'alto consente di
verso il basso sullo schermo ingrandire un soggetto. Far scorrere un dito verso il basso consente di
rimpicciolire un soggetto.
far scorrere un dito in qualunque Questa azione consente di scorrere una mappa o una pagina Web. Se viene
direzione ingrandita un'immagine, questa azione consente inoltre di scorrere tale
immagine.
premere il tasto ESC Questa azione rimuove l'evidenziazione da un testo o da un elenco di voci.

8
Guida allo sviluppo Trackball o trackpad

Azione Risultato
In una pagina Web, una mappa o un'immagine, questa azione consente di
tornare al livello di visualizzazione precedente. Premendo il tasto ESC due
volte è possibile tornare alla visualizzazione originale.

Trackball o trackpad
Nei dispositivi BlackBerry® con trackball o trackpad, questi ultimi rappresentano il comando principale per la
navigazione dell'utente. Gli utenti possono eseguire le seguenti operazioni:
• Ruotare la trackball o far scorrere un dito sul trackpad per spostare il cursore.
• Fare clic con la trackball o il trackpad per eseguire le operazioni predefinite o aprire un menu di scelta rapida.
• Fare clic con la trackball o il trackpad premendo al contempo il tasto Maiusc per evidenziare un testo o i messaggi
in un elenco di messaggi.
I dispositivi BlackBerry con trackball o trackpad includono inoltre un tasto Menu a sinistra della trackball o del
trackpad. Gli utenti possono premere il tasto Menu per visualizzare un menu completo delle operazioni disponibili.

Sensibilità della trackball


La sensibilità della trackball fa riferimento alla quantità di movimento richiesta dal sistema per identificare un
movimento come un evento di navigazione e per inviare tale evento al livello software. L'hardware del dispositivo
BlackBerry® misura il movimento fisico della trackball mediante unità chiamate tick. Quando il numero di tick lungo
un asse supera la soglia del sistema o di un'applicazione BlackBerry, un evento di navigazione viene inviato al livello
software e il sistema azzera il conteggio di tick. Inoltre, i conteggi dei tick vengono azzerati dopo un determinato
periodo di inattività.
È possibile utilizzare l'API Trackball per impostarne la sensibilità. Una sensibilità elevata della trackball corrisponde
a una soglia di tick inferiore (una piccola quantità di movimento genera un evento di navigazione). Una bassa
sensibilità della trackball corrisponde a una soglia di tick superiore (per generare eventi di navigazione è necessaria
una quantità più grande di movimento).

Movimento della trackball


È possibile utilizzare l'API Trackball per filtrare i dati relativi al movimento della trackball che l'hardware del dispositivo
BlackBerry® invia al livello software. L'API Trackball può filtrare il movimento "rumore" o i movimenti superflui.
È possibile utilizzare l'API Trackball anche per modificare le impostazioni, ad esempio l'accelerazione del movimento
della trackball. Se si aumenta il valore dell'impostazione relativa all'accelerazione del movimento della trackball, il
livello software potrebbe considerare la velocità del movimento della trackball come se fosse superiore a quella
rilevata dall'hardware del dispositivo BlackBerry, purché l'utente ruoti ininterrottamente la trackball. La sensibilità
della trackball aumenta temporaneamente quando l'utente ruota la trackball senza pause.

9
Guida allo sviluppo Rotellina

Rotellina
I dispositivi BlackBerry® che precedono BlackBerry® Pearl™ 8100 Series utilizzano una rotellina come strumento di
controllo primario per la navigazione dell'utente. La rotellina è situata sul lato destro del dispositivo BlackBerry®.
Gli utenti possono eseguire le seguenti operazioni:
• ruotare la rotellina per spostare il cursore in senso verticale
• ruotare la rotellina tenendo premuto il tasto Alt per spostare il cursore orizzontalmente
• fare clic con la rotellina per iniziare un'operazione o aprire il menu

Tastiera
Gli utenti utilizzano la tastiera principalmente per digitare un testo. I tasti dei caratteri inviano un carattere al
dispositivo BlackBerry®. Un tasto di modifica cambia la funzionalità dei tasti carattere. I tasti di modifica includono
il tasto Maiusc e il tasto Alt. Quando gli utenti premono un tasto di modifica, nell'angolo superiore destro della
schermata viene visualizzato un indicatore di modalità di digitazione.
Nei dispositivi BlackBerry non touchscreen, gli utenti possono utilizzare la tastiera anche per spostarsi all'interno di
una schermata (ad esempio per visualizzare diverse sezioni di una mappa). La navigazione tramite tastiera dovrebbe
tuttavia rappresentare solamente un'alternativa alla navigazione tramite rotellina, trackball o trackpad.
I dispositivi BlackBerry dispongono di una tastiera completa o ridotta. Nei dispositivi BlackBerry con touchscreen
SurePress™, nella maggior parte dei casi la tastiera completa viene visualizzata in senso orizzontale, mentre la tastiera
ridotta viene visualizzata in senso verticale.

Metodi di interazione dei dispositivi BlackBerry


Modello del dispositivo BlackBerry Metodo di interazione
BlackBerry® 7100 Series rotellina
BlackBerry® 8700 Series rotellina
BlackBerry® 8800 Series trackball
Smartphone BlackBerry® Bold™ 9000 trackball
BlackBerry® Bold™ 9650 Smartphone trackpad
Smartphone BlackBerry® Bold™ 9700
BlackBerry® Curve™ 8300 Series trackball
BlackBerry® Curve™ 8500 Series trackpad
Smartphone BlackBerry® Curve™ 8900 trackball
BlackBerry® Pearl™ 8100 Series trackball
BlackBerry® Pearl™ Flip 8200 Series trackball
BlackBerry® Storm™ 9500 Series touchscreen
Smartphone BlackBerry® Tour™ 9630 trackball

10
Guida allo sviluppo Schermate

Schermate 3
Il componente principale dell'interfaccia utente di un dispositivo BlackBerry® è l'oggetto Screen.
Un dispositivo BlackBerry può avere aperte contemporaneamente più schermate, ma può essere visualizzata una
sola schermata alla volta. BlackBerry® Java® Virtual Machine mantiene un insieme ordinato di oggetti Screen in uno
stack di visualizzazione. La schermata presente all'inizio dello stack è la schermata attiva che viene visualizzata
dall'utente BlackBerry. Quando un'applicazione BlackBerry visualizza una schermata, questa viene spostata all'inizio
dello stack. Quando un'applicazione BlackBerry chiude una schermata, questa viene rimossa dall'inizio dello stack.
L'applicazione visualizza la schermata successiva dello stack, ridisegnando la schermata come richiesto.
Ogni schermata può essere presente nello stack di visualizzazione una sola volta. BlackBerry JVM genera un'eccezione
di runtime se una schermata spostata nello stack dall'applicazione BlackBerry esiste già. Un'applicazione BlackBerry
deve rimuovere una schermata dallo stack di visualizzazione quando l'utente non interagisce più con essa in modo
da poter utilizzare la memoria in modo efficiente. Utilizzare solamente alcune schermate modali alla volta, poiché
ogni schermata utilizza un thread separato.
Le API dell'interfaccia utente inizializzano semplici oggetti Screen. Dopo aver creato una schermata, è possibile
aggiungere dei campi e un menu e fare in modo che l'utente visualizzi la schermata spostandola nello stack di
visualizzazione. A seconda delle necessità, è possibile modificare l'interfaccia utente del dispositivo BlackBerry e
implementare nuovi tipi di campi. È inoltre possibile aggiungere una modalità di navigazione personalizzata.
La classe Screen non implementa la risoluzione delle ambiguità, cosa che è richiesta dai metodi di immissione
complessi come le tastiere internazionali. Per ottenere l'integrazione dei diversi metodi di immissione, è possibile
estendere la classe Field o una delle sue sottoclassi. Non utilizzare gli oggetti Screen per digitare testo.

Classi di schermate
Classe Descrizione
Screen È possibile utilizzare la classe Screen per creare una schermata e un gestore
di layout per disporre sulla schermata i componenti dell'interfaccia utente.
È possibile definire un tipo di schermata specifico utilizzando gli stili definiti
dalle costanti nella superclasse Field.
FullScreen È possibile utilizzare la classe FullScreen per creare una schermata vuota
a cui aggiungere i componenti dell'interfaccia utente seguendo un layout
standard verticale. Se si desidera utilizzare un altro stile di layout, ad
esempio orizzontale o diagonale, è possibile utilizzare invece la classe
Screen e aggiungervi un gestore di layout.
MainScreen È possibile utilizzare la classe MainScreen per creare una schermata con i
seguenti componenti standard dell'interfaccia utente:
• il titolo predefinito della schermata, seguito da un SeparatorField
• la sezione principale scorrevole, contenuta in un
VerticalFieldManager

11
Guida allo sviluppo Gestione di un'area di disegno

Classe Descrizione
• il menu predefinito che contiene la voce di menu Chiudi
• l'azione predefinita di chiusura, che consente di chiudere la schermata
quando l'utente BlackBerry® fa clic sulla voce del menu Chiudi o preme
il tasto ESC
Si consiglia di utilizzare un oggetto MainScreen per la prima schermata
dell'applicazione BlackBerryal fine di mantenere la coerenza con le altre
applicazioni BlackBerry.

Gestione di un'area di disegno


L'oggetto Graphics rappresenta l'intera superficie di disegno disponibile per l'applicazione BlackBerry®. Per limitare
quest'area, suddividerla in oggetti XYRect. Ogni XYPoint rappresenta un punto della schermata, composto da una
coordinata X e da una coordinata Y.

1. Importare le seguenti classi:


• net.rim.device.api.ui.Graphics
• net.rim.device.api.ui.XYRect
• net.rim.device.api.ui.XYPoint
2. Creare oggetti XYPoint che rappresentino il punto in alto a sinistra e il punto in basso a destra di un rettangolo.
Creare un oggetto XYRect utilizzando gli oggetti XYPoint al fine di creare un'area di ridimensionamento
rettangolare.
XYPoint bottomRight = new XYPoint(50, 50);
XYPoint topLeft = new XYPoint(10, 10);
XYRect rectangle = new XYRect(topLeft, bottomRight);
3. Richiamare Graphics.pushContext() per effettuare chiamate di disegno che specifichino che l'origine
dell'area non deve modificare l'offset di disegno. Richiamare Graphics.pushContext() per inviare l'area di
ridimensionamento rettangolare allo stack di contesto. Richiamare Graphics.drawRect() per disegnare un
rettangolo e richiamare Graphics.fillRect() per riempire il rettangolo. Richiamare
Graphics.popContext() per estrarre il contesto attuale dallo stack di contesto.
graphics.pushContext(rectangle, 0, 0);
graphics.fillRect(10, 10, 30, 30);
graphics.drawRect(15, 15, 30, 30);
graphics.popContext();
graphics.drawRect(15, 15, 30, 30);
graphics.pushContext(rectangle, 0, 0);
graphics.fillRect(10, 10, 30, 30);
graphics.drawRect(15, 15, 30, 30);
graphics.popContext();
graphics.drawRect(15, 15, 30, 30);
4. Richiamare pushRegion() e specificare che l'origine dell'area deve modificare l'offset di disegno. Richiamare
Graphics.drawRect() per disegnare un rettangolo e richiamare Graphics.fillRect() per riempire un
rettangolo. Richiamare Graphics.popContext() per estrarre il contesto attuale dallo stack di contesto.

12
Guida allo sviluppo Creazione di una transizione di schermata

graphics.pushRegion(rectangle);
graphics.fillRect(10, 10, 30, 30);
graphics.drawRect(15, 15, 30, 30);
graphics.popContext();
5. Specificare la porzione dell'oggetto Graphics da inviare allo stack.
6. Dopo avere richiamato pushContext() (o pushRegion()), fornire la porzione dell'oggetto Graphics da
invertire.
graphics.pushContext(rectangle);
graphics.invert(rectangle);
graphics.popContext();
7. Richiamare translate(). XYRect viene traslato dalla sua origine (1, 1) all'origine (20, 20). Dopo la traslazione,
la porzione inferiore dell'oggetto XYRect si estende oltre i confini del contesto grafico e lo ritaglia.
XYRect rectangle = new XYRect(1, 1, 100, 100);
XYPoint newLocation = new XYPoint(20, 20);
rectangle.translate(newLocation);

Creazione di una transizione di schermata


È possibile creare una transizione di schermata per applicare un effetto visivo visualizzato quando l'applicazione apre
o chiude una schermata su un dispositivo BlackBerry®. È possibile creare i seguenti tipi di transizione di schermata
per l'applicazione tramite la classe net.rim.device.api.ui.TransitionContext.

Transizione Descrizione
TRANSITION_FADE Questa transizione consente di visualizzare o rimuovere una schermata
eseguendo la dissolvenza in entrata o in uscita. Questa transizione di
schermata crea l'effetto visivo di dissolvenza modificando l'opacità della
schermata.
TRANSITION_SLIDE Questa transizione consente di visualizzare o rimuovere una schermata
eseguendo lo scorrimento in entrata o in uscita dal display del dispositivo.
È possibile utilizzare gli attributi per specificare lo scorrimento della nuova
schermata e della schermata corrente per creare un effetto in cui entrambe
le schermate si spostano oppure la nuova schermata si sovrappone a quella
corrente.
TRANSITION_WIPE L'effetto visivo di questa transizione è la visualizzazione o la rimozione
graduale della schermata sul dispositivo.
TRANSITION_ZOOM L'effetto visivo di questa transizione è la visualizzazione o rimozione della
schermata sul dispositivo tramite zoom avanti o indietro.
TRANSITION_NONE Non ha luogo alcuna transizione.

13
Guida allo sviluppo Creazione di una transizione di schermata

Ogni tipo di transizione di schermata prevede alcuni attributi che è possibile utilizzare per personalizzare gli effetti
visivi della transizione stessa. Ad esempio, è possibile personalizzare l'effetto di scorrimento in modo che la schermata
scorra dalla parte inferiore verso la parte superiore del display del dispositivo. Se la transizione di schermata non
viene personalizzata, l'applicazione utilizza gli attributi predefiniti. Per ulteriori informazioni sugli attributi predefiniti,
vedere il riferimento API per BlackBerry® Java® Development Environment.
Dopo aver creato una transizione di schermata, è necessario registrarla all'interno dell'applicazione richiamando
UiEngineInstance.setTransition() nonché specificare la schermata in uscita da rimuovere, la schermata in
entrata da visualizzare, gli eventi che causano la transizione e la transizione da visualizzare.
Per scaricare un'applicazione di esempio che mostra come utilizzare le transizioni di schermata, visitare il sito Web
www.blackberry.com/go/screentransitionssample. Per ulteriori informazioni sulle transizioni di schermata, vedere
il riferimento API per BlackBerry Java Development Environment.
Nota: Il tema disponibile sul dispositivo BlackBerry controlla gli effetti visivi visualizzati quando un utente apre
un'applicazione. Per ulteriori informazioni, consultare l'opuscolo Manuale dell'utente di BlackBerry Theme Studio .

Esempio di codice: creazione di una transizione di schermata


Il seguente esempio di codice illustra una transizione di scorrimento e una transizione di dissolvenza. Quando l'utente
apre l'applicazione, sul dispositivo BlackBerry® viene visualizzata la prima schermata che contiene un pulsante.
Quando l'utente fa clic su tale pulsante, una seconda schermata si sovrappone alla prima con un effetto di scorrimento
proveniente da destra. Dopo due secondi la seconda schermata scompare automaticamente con un effetto di
dissolvenza.

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.decor.*;
public class ScreenTransitionSample extends UiApplication implements
FieldChangeListener {
private Screen _secondaryScreen;
private Runnable _popRunnable;
public static void main(String[] args) {
ScreenTransitionSample theApp = new ScreenTransitionSample ();
theApp.enterEventDispatcher();
}
public ScreenTransitionSample () {
_secondaryScreen = new FullScreen();
_secondaryScreen.setBackground(
BackgroundFactory.createSolidBackground(Color.LIGHTBLUE) );
LabelField labelField = new LabelField("The screen closes automatically in
two seconds by using a fade transition");
_secondaryScreen.add(labelField);
TransitionContext transition = new
TransitionContext(TransitionContext.TRANSITION_SLIDE);
transition.setIntAttribute(TransitionContext.ATTR_DURATION, 500);
transition.setIntAttribute(TransitionContext.ATTR_DIRECTION,
TransitionContext.DIRECTION_RIGHT);
transition.setIntAttribute(TransitionContext.ATTR_STYLE,
TransitionContext.STYLE_PUSH);
UiEngineInstance engine = Ui.getUiEngineInstance();

14
Guida allo sviluppo Specifica dell'orientamento e della direzione dello schermo

engine.setTransition(null, _secondaryScreen, UiEngineInstance.TRIGGER_PUSH,


transition);
transition = new TransitionContext(TransitionContext.TRANSITION_FADE);
transition.setIntAttribute(TransitionContext.ATTR_DURATION, 500);
transition.setIntAttribute(TransitionContext.ATTR_KIND,
TransitionContext.KIND_OUT);
engine.setTransition(_secondaryScreen, null, UiEngineInstance.TRIGGER_POP,
transition);
MainScreen baseScreen = new MainScreen();
baseScreen.setTitle("Screen Transition Sample");
ButtonField buttonField = new ButtonField("View Transition",
ButtonField.CONSUME_CLICK) ;
buttonField.setChangeListener(this);
baseScreen.add(buttonField);
pushScreen(baseScreen);
_popRunnable = new Runnable() {
public void run() {
popScreen(_secondaryScreen);
}
};
}
public void fieldChanged(Field field, int context)
{
pushScreen(_secondaryScreen);
invokeLater(_popRunnable, 2000, false);
}
}

Specifica dell'orientamento e della direzione dello schermo


Nelle applicazioni touchscreen, si possono prendere in considerazione l'orientamento e la direzione dello schermo.
L'orientamento si riferisce al formato dello schermo. La direzione si riferisce all'area di disegno dello schermo.
Orientamento
Un utente con un dispositivo BlackBerry® con touchscreen può modificare l'orientamento dello schermo ruotando
il dispositivo. Se un utente tiene il dispositivo BlackBerry con il logo BlackBerry rivolto verso l'alto, lo schermo ha un
orientamento verticale. Se l'utente ruota il dispositivo di 90 gradi a sinistra o destra, lo schermo ha un orientamento
orizzontale.
È possibile utilizzare la classe net.rim.device.api.system.Display per recuperare i dati dell'orientamento
dello schermo. La classe Display contiene le costanti che corrispondono agli orientamenti utilizzati dal dispositivo
con touchscreen per visualizzare le informazioni. Ad esempio, gli orientamenti verticale, orizzontale e quadrato
corrispondono alle costanti Display.ORIENTATION_PORTRAIT, Display.ORIENTATION_LANDSCAPEe
Display.ORIENTATION_SQUARE.

Per recuperare i dati dell'orientamento dello schermo, è possibile richiamare il metodo Display.getOrientation
(). Questo metodo restituisce un numero intero che corrisponde a uno degli orientamenti che possono essere
utilizzati dal dispositivo BlackBerry.

15
Guida allo sviluppo Specifica dell'orientamento e della direzione dello schermo

Per rilevare le modifiche dell'orientamento dello schermo, è possibile sovrascrivere il metodo Screen.sublayout
(). In questo metodo, richiamare super.sublayout() e controllare le modifiche nei valori di width e height.

Direzione
Un dispositivo BlackBerry con touchscreen può visualizzare le informazioni sullo schermo in direzioni diverse. La
direzione si riferisce alla parte superiore dell'area di disegno dello schermo, che è relativa alla posizione del logo
BlackBerry. La direzione punta a nord se la parte superiore dell'area di disegno corrisponde al lato dello schermo più
vicino al logo BlackBerry; la direzione punta a ovest se la parte superiore dell'area di disegno è a sinistra del logo
BlackBerry; la direzione punta a est se la parte superiore dell'area di disegno è a destra del logo BlackBerry.
È possibile utilizzare le classi net.rim.device.api.system.Display, net.rim.device.api.ui.Ui e
net.rim.device.api.ui.UiEngineInstance per controllare la direzione utilizzata dal dispositivo BlackBerry
per visualizzare le informazioni sullo schermo. La classe Display contiene le costanti che corrispondono alle direzioni
che il dispositivo può utilizzare per visualizzare le informazioni. Ad esempio, le direzioni nord, ovest ed est
corrispondono alle costanti Display.DIRECTION_NORTH, Display.DIRECTION_WEST e
Display.DIRECTION_EAST.

È possibile creare un oggetto della classe net.rim.device.api.ui.Ui e richiamare Ui.getUiEngineInstance


() per recuperare un oggetto della classe UiEngineInstance. Richiamando
UiEngineInstance.setAcceptableDirections() con una delle costanti che corrispondono alle direzioni della
classe Display, si imposta la direzione che il dispositivo BlackBerry può utilizzare per visualizzare le informazioni.

Esempio di codice: recupero dell'orientamento dello schermo


switch(Display.getOrientation())
{
case Display.ORIENTATION_LANDSCAPE:
Dialog.alert("Screen orientation is landscape"); break;
case Display.ORIENTATION_PORTRAIT:
Dialog.alert("Screen orientation is portrait"); break;
case Display.ORIENTATION_SQUARE:
Dialog.alert("Screen orientation is square"); break;
default:
Dialog.alert("Screen orientation is not known"); break;
}

Esempio di codice: imposizione dell'orientamento verticale in un'applicazione API BlackBerry


// Use code like this before invoking UiApplication.pushScreen()
int direction = Display.DIRECTION_NORTH;
Ui.getUiEngineInstance().setAcceptableDirections(direction);

Esempio di codice: imposizione dell'orientamento orizzontale in un'applicazione MIDlet


// Use code like this before invoking Display.setCurrent() in the MIDlet constructor
DirectionControl dc =
(DirectionControl) ((Controllable) Display.getDisplay(this)).

16
Guida allo sviluppo Specifica dell'orientamento e della direzione dello schermo

getControl("net.rim.device.api.lcdui.control.DirectionControl");
int directions = DirectionControl.DIRECTION_EAST | DirectionControl.DIRECTION_WEST;
dc.setAcceptableScreenDirections(directions);

Recupero dell'orientamento del touchscreen


1. Importare la classe net.rim.device.api.system.Display.
2. Richiamare net.rim.device.api.system.Display.getOrientation().
int orientation = Display.getOrientation();

Limitazione della direzione del touchscreen


1. Importare le seguenti classi:
• net.rim.device.api.ui.Ui
• net.rim.device.api.ui.UiEngineInstance
2. Richiamare net.rim.device.api.ui.Ui.getUiEngineInstance().
UiEngineInstance _ue;
_ue = Ui.getUiEngineInstance();
3. Richiamare net.rim.device.api.ui.UiEngineInstance.setAcceptableDirections(byte
flags) e passare l'argomento per la direzione dello Screen.
_ue.setAcceptableDirections(Display.DIRECTION_WEST);

Ricezione delle notifiche quando la dimensione dell'area di disegno del


touchscreen cambia
1. Importare le seguenti classi:
• javax.microedition.lcdui.Canvas
• net.rim.device.api.ui.component.Dialog
2. Estendere javax.microedition.lcdui.Canvas.
3. Sovrascrivere Canvas.sizeChanged(int, int).
protected void sizeChanged(int w, int h) {
Dialog.alert("The size of the Canvas has changed");
}

17
Guida allo sviluppo Accelerometro

Accelerometro 4
Un dispositivo BlackBerry® con touchscreen include un accelerometro, strumento concepito per percepire
l'orientamento e l'accelerazione del dispositivo BlackBerry. Quando un utente BlackBerry sposta il dispositivo
BlackBerry, l'accelerometro è in grado di percepire il movimento nello spazio 3-D lungo gli assi x, y e z. Quando l'utente
modifica l'orientamento del dispositivo, viene a sua volta modificata la direzione di visualizzazione della schermata
di un'applicazione BlackBerry da verticale a orizzontale o viceversa.
È possibile utilizzare le API Accelerometer nel pacchetto net.rim.device.api.system per rispondere
all'orientamento e all'accelerazione di un dispositivo BlackBerry. È possibile, ad esempio, manipolare un'applicazione
di gioco al fine di modificare la direzione e la velocità di un oggetto in movimento sullo schermo quando l'utente
sposta e ruota il dispositivo BlackBerry a velocità diverse.
Per scaricare un'applicazione di prova che mostri come utilizzare l'accelerometro, visitare il sito Web
www.blackberry.com/go/accelerometersample. Per ulteriori informazioni sull'applicazione di prova, visitare il sito
Web www.blackberry.com/go/devguides e leggere il documento Panoramica dell'applicazione di prova
dell'accelerometro.

Tipi di dati forniti dall'accelerometro


Un'applicazione BlackBerry® è in grado di recuperare i dati restituiti dall'accelerometro.

Tipo di dati Descrizione


orientamento L'orientamento del dispositivo BlackBerry rispetto al suolo.
accelerazione L'accelerazione della rotazione del dispositivo BlackBerry.

Per ulteriori informazioni sui tipi di dati restituiti dall'accelerometro, consultare la documentazione di riferimento
sulle API per BlackBerry® Java® Development Environment.

Recupero dei dati dell'accelerometro


L'accelerometro è progettato per tenere traccia della direzione e della velocità dei movimenti lungo gli assi x, y e z
quando un utente sposta il dispositivo BlackBerry®. L'asse x è parallelo alla larghezza del dispositivo BlackBerry. L'asse
y è parallelo alla lunghezza del dispositivo BlackBerry. L'asse z è parallelo alla profondità (dal lato anteriore a quello
posteriore) del dispositivo BlackBerry. Per ulteriori informazioni sugli assi x, y e z dell'accelerometro, vedere la classe
net.rim.device.api.system.AccelerometerSensor nella documentazione di riferimento sulle API per
BlackBerry® Java® Development Environment.
È possibile attivare un'applicazione BlackBerry in modo che reagisca all'accelerazione del dispositivo BlackBerry che
include un accelerometro. Ad esempio, un utente può spostare il dispositivo BlackBerry per controllare la direzione
e la velocità di un oggetto che si muove nel labirinto di un gioco.

18
Guida allo sviluppo Recupero dei dati dell'accelerometro a intervalli specifici

Utilizzare le API Accelerometer nel pacchetto net.rim.device.api.system per reagire all'accelerazione del
dispositivo BlackBerry. Occorre prima determinare se il dispositivo BlackBerry supporta un accelerometro
richiamando net.rim.device.api.system.AccelerometerSensor.isSupported(). Se il metodo
restituisce il valore true, il dispositivo BlackBerry supporta un accelerometro.
È possibile utilizzare la classe AccelerometerData per identificare la direzione in cui l'utente sposta il dispositivo
BlackBerry. Richiamando AccelerometerData.getOrientation() viene restituita una delle costanti della classe
AccelerometerSensor che corrispondono alla direzione del dispositivo BlackBerry. Ad esempio, se
AccelerometerData.getOrientation() restituisce un valore pari a
AccelerometerSensor.ORIENTATION_LEFT_UP, il lato sinistro del dispositivo BlackBerryè orientato verso l'alto.

È possibile utilizzare la classe AccelerometerSensor per recuperare i dati di accelerazione dal dispositivo
BlackBerry. Richiamando AccelerometerSensor.openRawDataChannel() viene restituito un oggetto della
classe net.rim.device.api.system.AccelerometerSensor.Channel. La classe
AccelerometerSensor.Channel consente di aprire una connessione all'accelerometro. Per recuperare i dati
dall'accelerometro, richiamare AccelerometerSensor.Channel.getLastAccelerationData().
Se si mantiene una connessione all'accelerometro, si riduce la carica della batteria del dispositivo BlackBerry. Quando
l'applicazione BlackBerry non deve più recuperare dati dall'accelerometro, richiamare
AccelerometerSensor.Channel.close() per chiudere la connessione.

Esempio di codice: recupero dei dati dall'accelerometro


short[] xyz = new short[3];
while( running ) {
channel.getLastAccelerationData(xyz);
}
channel.close();

Recupero dei dati dell'accelerometro a intervalli specifici


Se un'applicazione BlackBerry® in primo piano apre un canale con l'accelerometro, quando l'esecuzione
dell'applicazione passa in background, il canale viene messo in pausa e non vengono più inviate richieste di
informazioni all'accelerometro. Se un'applicazione BlackBerryrichiama AccelerometerSensor.Channel.
getLastAccelerationData(short[]) a intervalli ravvicinati oppure se non ci sono eventi di movimento sul
dispositivo BlackBerry, il metodo potrebbe restituire valori duplicati.
1. Importare le seguenti classi:
• net.rim.device.api.system.AccelerometerSensor.Channel;
• net.rim.device.api.system.AccelerometerSensor;
2. Aprire un canale con l'accelerometro. Mentre il canale è aperto, l'applicazione BlackBerry richiederà informazioni
all'accelerometro.
Channel rawDataChannel = AccelerometerSensor.openRawDataChannel
( Application.getApplication() );
3. Creare una matrice per memorizzare i dati dell'accelerometro.

19
Guida allo sviluppo Invio di una query all'accelerometro quando l'applicazione è in primo piano

short[] xyz = new short[ 3 ];


4. Creare un thread.
while( running ) {
5. Richiamare Channel.getLastAccelerationData(short[]) per recuperare dati dall'accelerometro.
rawDataChannel.getLastAccelerationData( xyz );
6. Richiamare Thread.sleep() per specificare l'intervallo tra le query inviate all'accelerometro, espresso in
millisecondi.
Thread.sleep( 500 );
7. Richiamare Channel.close() per chiudere il canale con l'accelerometro.
rawDataChannel.close();

Invio di una query all'accelerometro quando l'applicazione


è in primo piano
1. Importare le seguenti classi:
• net.rim.device.api.system.AccelerometerChannelConfig
• net.rim.device.api.system.AccelerometerSensor.Channel
2. Aprire un canale per recuperare i dati di accelerazione dall'accelerometro.
Channel channel = AccelerometerSensor.openRawAccelerationChannel
( Application.getApplication());
3. Richiamare Thread.sleep() per specificare l'intervallo tra le query inviate all'accelerometro, espresso in
millisecondi.
short[] xyz = new short[ 3 ];
while( running ) {
channel.getLastAccelerationData( xyz );
Thread.sleep( 500 );
}
4. Richiamare Channel.close() per chiudere il canale con l'accelerometro.
channel.close();

Invio di una query all'accelerometro quando l'applicazione


è in background
1. Importare le seguenti classi:
• net.rim.device.api.system.AccelerometerChannelConfig;
• net.rim.device.api.system.AccelerometerSensor.Channel;

20
Guida allo sviluppo Archiviazione delle letture dell'accelerometro in un buffer

2. Creare una configurazione per un canale con l'accelerometro.


AccelerometerChannelConfig channelConfig = new AccelerometerChannelConfig
( AccelerometerChannelConfig.TYPE_RAW );
3. Richiamare AccelerometerChannelConfig.setBackgroundMode(Boolean) per specificare il supporto
per un'applicazione che si trova in background.
channelConfig.setBackgroundMode( true );
4. Richiamare AccelerometerSensor.openChannel() per aprire un canale in background con l'accelerometro.
Channel channel = AccelerometerSensor.openChannel( Application.getApplication(),
channelConfig );
5. Richiamare Thread.sleep() per specificare l'intervallo tra le query inviate all'accelerometro, espresso in
millisecondi.
short[] xyz = new short[ 3 ];
while( running ) {
channel.getLastAccelerationData( xyz );
Thread.sleep( 500 );
}
6. Richiamare Channel.close() per chiudere il canale con l'accelerometro.
channel.close();

Archiviazione delle letture dell'accelerometro in un buffer


1. Importare le seguenti classi:
• net.rim.device.api.system.AccelerometerChannelConfig;
• net.rim.device.api.system.AccelerometerSensor.Channel;
2. Creare una configurazione per un canale con l'accelerometro.
AccelerometerChannelConfig channelConfig = new AccelerometerChannelConfig
( AccelerometerChannelConfig.TYPE_RAW );
3. Richiamare AccelerometerChannelConfig.setSamplesCount() per specificare il numero di letture di
accelerazione da archiviare nel buffer. Ogni elemento presente nel buffer contiene le letture di accelerazione
per gli assi x, y e z, come pure i dati relativi al momento in cui è avvenuta la lettura.
channelConfig.setSamplesCount( 500 );
4. Richiamare AccelerometerSensor.openChannel() per aprire un canale con l'accelerometro.
Channel bufferedChannel = AccelerometerSensor.openChannel
( Application.getApplication(), channelConfig );

21
Guida allo sviluppo Recupero delle letture dell'accelerometro da un buffer

Recupero delle letture dell'accelerometro da un buffer


1. Importare le seguenti classi:
• net.rim.device.api.system.AccelerometerData;
• net.rim.device.api.system.AccelerometerSensor.Channel;
2. Inviare una query al buffer per i dati dell'accelerometro.
AccelerometerData accData = bufferedChannel.getAccelerometerData();
3. Richiamare AccelerometerData.getNewBatchLength() per ottenere il numero delle letture recuperate a
partire dall'ultima query.
int newBatchSize = accData.getNewBatchLength();
4. Richiamare AccelerometerData.getXAccHistory(), AccelerometerData.getYAccHistory()e
AccelerometerData.getZAccHistory() per recuperare i dati dell'accelerometro dal buffer per ogni asse.
short[] xAccel = accData.getXAccHistory();
short[] yAccel = accData.getYAccHistory();
short[] zAccel = accData.getZAccHistory();

Recupero dell'ora di una lettura dall'accelerometro


1. Importare la classe net.rim.device.api.system.AccelerometerData.
2. Inviare una query al buffer per i dati dell'accelerometro.
AccelerometerData accData;
accData = bufferedChannel.getAccelerometerData();
3. Richiamare AccelerometerData.getSampleTsHistory().
long[] queryTimestamps = accData.getSampleTsHistory();

22
Guida allo sviluppo Eventi

Eventi 5
Risposta agli eventi di navigazione
È possibile utilizzare i metodi di navigazione Screen per creare un'applicazione BlackBerry®. Se l'applicazione
BlackBerry esistente implementa l'interfaccia TrackwheelListener, aggiornare tale applicazione in modo che
utilizzi i metodi di navigazione Screen.
1. Importare la classe net.rim.device.api.ui.Screen.
2. Gestire gli eventi di navigazione estendendo la classe net.rim.device.api.ui.Screen (o una delle sue
sottoclassi) e sovrascrivendo i metodi di navigazione seguenti:
navigationClick(int status, int time)
navigationUnclick(int status, int time)
navigationMovement(int dx, int dy, int status, int time)

Determinazione del tipo di metodo di immissione


1. Importare una o più delle seguenti classi:
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.Field
2. Importare l'interfaccia net.rim.device.api.system.KeypadListener.
3. Implementare l'interfaccia net.rim.device.api.system.KeypadListener.
4. Estendere la classe Screen, la classe Field o entrambe.
5. Nell'implementazione di uno dei metodi navigationClick, navigationUnclick o
navigationMovement, eseguire un'operazione bitwise AND sul parametro status per ottenere maggiori
informazioni sull'evento. Implementare il metodo navigationClick(int status, int time) per
determinare se la rotellina o il dispositivo di immissione di navigazione a quattro vie (ad esempio, una trackball)
avviano un evento.
public boolean navigationClick(int status, int time) {
if ((status & KeypadListener.STATUS_TRACKWHEEL) ==
KeypadListener.STATUS_TRACKWHEEL) {
//Input came from the trackwheel
} else if ((status & KeypadListener.STATUS_FOUR_WAY) ==
KeypadListener.STATUS_FOUR_WAY) {
//Input came from a four way navigation input device
}
return super.navigationClick(status, time);
}
Per ulteriori informazioni sui modificatori di stato per la classe
net.rim.device.api.system.KeypadListener, vedere la documentazione di riferimento sulle API per
BlackBerry® Java® Development Environment.

23
Guida allo sviluppo Modelli di interazione del touchscreen

Modelli di interazione del touchscreen


I dispositivi BlackBerry® con touchscreen e trackpad utilizzano un modello di interazione dei clic che non richiede
pressione, grazie al quale l'utente BlackBerry può eseguire un'operazione toccando lo schermo o utilizzando il
trackpad. Questo modello differisce dai dispositivi BlackBerry con touchscreen SurePress™, in cui l'utente doveva
fare clic sulla schermata (o esercitare una pressione) per eseguire un'operazione.
Su entrambi i tipi di dispositivi, quando l'utente tocca lo schermo, si verifica un evento TouchEvent.DOWN.
Sui dispositivi con touchscreen SurePress , quando l'utente applica la pressione e fa clic sullo schermo, si verifica un
evento TouchEvent.CLICK. Quando la pressione diminuisce, si verifica un evento TouchEvent.UNCLICK. In
genere, le azioni (come il richiamo di un'azione basato su un pulsante) si verificano nell'evento
TouchEvent.UNCLICK. Quando l'utente rilascia completamente lo schermo, si verifica un evento TouchEvent.UP.

Sui dispositivi con touchscreen che supporta i clic che non richiedono pressione, non è disponibile il clic fisico. Invece,
ci si aspetta che le azioni si verifichino quando l'utente tocca lo schermo. Un tocco è un evento
TouchEvent.DOWN seguito rapidamente da un evento TouchEvent.UP. Questa combinazione di eventi di tocco è
detta gesto e quindi si verifica un TouchGesture. Nel caso di un tocco, si verifica un evento TouchGesture.TAP
(con l'evento TouchEvent.DOWN e TouchEvent.UP).
Per una maggiore compatibilità tra i due tipi di modelli di interazione di touchscreen, sui dispositivi che supportano
i clic che non richiedono pressione, l'evento TouchEvent.CLICK e l'eventoTouchEvent.UNCLICK si verificano
dopo l'evento TouchGesture.TAP. Dunque, è possibile richiamare un'azione nell'evento TouchEvent.UNCLICK
su tutti i dispositivi touchscreen, indipendentemente dal fatto che il dispositivo sia touchscreen SurePress o meno.

Dispositivi che supportano un clic che


Azione dell'utente Dispositivi con touchscreen SurePress
non richiede pressione
Toccare lo schermo. TouchEvent.DOWN TouchEvent.DOWN
Toccare e tenere TouchGesture.HOVER TouchGesture.HOVER
premuto un dito su un
elemento.
Fare clic sullo schermo. — TouchEvent.CLICK
Fare clic e tenere — TouchEvent.CLICK_REPEAT
premuto lo schermo.
Rilasciare lo schermo. — TouchEvent.UNCLICK
Rimuovere un dito dallo TouchEvent.UP TouchEvent.UP
schermo.
Toccare lo schermo. TouchEvent.DOWN TouchEvent.DOWN

TouchGesture.TAP TouchGesture.TAP

TouchEvent.CLICK TouchEvent.UP

TouchEvent.UNCLICK

TouchEvent.UP

24
Guida allo sviluppo Risposta agli eventi del touchscreen

È possibile determinare se un dispositivo con touchscreen supporta i clic che non richiedono pressione richiamando
DeviceCapability.isTouchClickSupported(). Se il dispositivo supporta i clic che non richiedono pressione,
il metodo restituisce false. Se il dispositivo dispone di touchscreen SurePress, il metodo restituisce true.

Risposta agli eventi del touchscreen


Gli utenti che utilizzano un dispositivo BlackBerry® con touchscreen possono compiere le stesse azioni eseguibili su
un dispositivo BlackBerry con trackball. Ad esempio, gli utenti BlackBerry possono utilizzare il touchscreen per aprire
un menu, scorrere un elenco di opzioni e selezionare un'opzione.
Se si utilizza una versione di BlackBerry® Java® Development Environment precedente alla 4.7 per creare
un'applicazione per il dispositivo BlackBerry, è possibile modificare il file .jad dell'applicazione per consentire a
quest'ultima di rispondere quando un utente BlackBerry tocca il touchscreen. Nel file .jad, impostare l'opzione RIM-
TouchCompatibilityMode su false.

Se si utilizza BlackBerry JDE versione 4.7 o successiva per creare un'applicazione per il dispositivo BlackBerry, è
possibile fare in modo che l'applicazione identifichi l'azione eseguita sul touchscreen dall'utente BlackBerry
estendendo la classe net.rim.device.api.ui.Screen, la classe net.rim.device.api.ui.Field o una delle
sottoclassi della classe Field e sovrascrivendo il metodo touchEvent(). Nel metodo touchEvent() confrontare
il valore che TouchEvent.getEvent() restituisce con le costanti della classe
net.rim.device.api.ui.TouchEvent e della classe net.rim.device.api.ui.TouchGesture.

La classe TouchEvent contiene le costanti che rappresentano le varie azioni che un utente può eseguire sul
touchscreen. Ad esempio, le azioni per fare clic, toccare e spostare un elemento corrispondono alle costanti
TouchEvent.CLICK, TouchEvent.DOWNe TouchEvent.MOVE.

La classe TouchGesture contiene le costanti che rappresentano i vari movimenti che un utente può eseguire sul
touchscreen. Ad esempio, i movimenti per toccare e spostare un elemento corrispondono alle costanti
TouchGesture.TAP e TouchGesture.SWIPE.

Esempio di codice: identificazione dell'azione eseguita da un utente sul touchscreen


Il seguente esempio di codice utilizza un'istruzione switch per identificare l'azione.

protected boolean touchEvent(TouchEvent message) {


switch(message.getEvent()) {
case TouchEvent.CLICK:
Dialog.alert("A click action occurred");
return true;
case TouchEvent.DOWN:
Dialog.alert("A down action occurred");
return true;
case TouchEvent.MOVE:
Dialog.alert("A move action occurred");
return true;
}
return false;
}

25
Guida allo sviluppo Risposta agli eventi del touchscreen

Risposta agli eventi di sistema quando l'utente tocca lo schermo


1. Importare le classi seguenti:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), richiamare
TouchEvent.getEvent().
4. Controllare se il valore restituito da TouchEvent.getEvent() è uguale a TouchEvent.CANCEL.
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.CANCEL:
Dialog.alert("System event occurred while processing touch events");
return true;
}
return false;
}

Risposta a un utente che fa scorrere rapidamente il dito verso l'alto sullo


schermo
1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.TouchGesture
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), richiamare
TouchEvent.getEvent().
4. Controllare se il valore restituito da TouchGesture.getSwipeDirection() è uguale a
TouchGesture.SWIPE_NORTH.

26
Guida allo sviluppo Risposta agli eventi del touchscreen

protected boolean touchEvent(TouchEvent message) {


switch(message.getEvent()) {
case TouchEvent.GESTURE:
TouchGesture gesture = message.getGesture();
switch(gesture.getEvent()) {
case TouchGesture.SWIPE:
if(gesture.getSwipeDirection() == TouchGesture.SWIPE_NORTH) {
Dialog.alert("Upward swipe occurred");
return true;
}
}
return false;
}
}

Risposta a un utente che fa scorrere rapidamente il dito verso il basso sullo


schermo
1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.TouchGesture
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), richiamare
TouchEvent.getEvent().
4. Controllare se il valore restituito da TouchGesture.getSwipeDirection() è uguale a
TouchGesture.SWIPE_SOUTH.
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.GESTURE:
TouchGesture gesture = message.getGesture();
switch(gesture.getEvent()) {
case TouchGesture.SWIPE:
if(gesture.getSwipeDirection() == TouchGesture.SWIPE_SOUTH) {
Dialog.alert("Downward swipe occurred");
return true;
}
}
return false;
}
}

27
Guida allo sviluppo Risposta agli eventi del touchscreen

Risposta a un utente che fa scorrere rapidamente il dito a sinistra sullo


schermo
1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.TouchGesture
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), richiamare
TouchEvent.getEvent().
4. Controllare se il valore restituito da TouchGesture.getSwipeDirection() è uguale a
TouchGesture.SWIPE_EAST.
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.GESTURE:
TouchGesture gesture = message.getGesture();
switch(gesture.getEvent()) {
case TouchGesture.SWIPE:
if(gesture.getSwipeDirection() == TouchGesture.SWIPE_EAST) {
Dialog.alert("Eastward swipe occurred");
return true;
}
}
return false;
}
}

isposta a un utente che fa scorrere rapidamente il dito a destra sullo


schermo
1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.TouchGesture
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.

28
Guida allo sviluppo Risposta agli eventi del touchscreen

public class newButtonField extends ButtonField {


3. Nell'implementazione del metodo touchEvent(TouchEvent message), richiamare
TouchEvent.getEvent().
4. Controllare se il valore restituito da TouchGesture.getSwipeDirection() è uguale a
TouchGesture.SWIPE_WEST.
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.GESTURE:
TouchGesture gesture = message.getGesture();
switch(gesture.getEvent()) {
case TouchGesture.SWIPE:
if(gesture.getSwipeDirection() == TouchGesture.SWIPE_WEST) {
Dialog.alert("Westward swipe occurred");
return true;
}
}
return false;
}
}

Risposta a un utente che fa clic sullo schermo


1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), richiamare
TouchEvent.getEvent().
4. Controllare se il valore restituito da TouchEvent.getEvent() è uguale a TouchEvent.CLICK.
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.CLICK:
Dialog.alert("CLICK occurred");
return true;
}
return false;
}

29
Guida allo sviluppo Risposta agli eventi del touchscreen

Risposta a un utente che tocca lo schermo due volte rapidamente


1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.TouchGesture
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), verificare l'occorrenza di un evento
TouchGesture.TAP e che TouchGesture.getTapCount restituisca 2.
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.GESTURE:
TouchGesture gesture = message.getGesture();
switch(gesture.getEvent()) {
case TouchGesture.TAP:
if(gesture.getTapCount() == 2) {
Dialog.alert("Double tap occurred");
return true;
}
}
}
return false;
}

Risposta a un utente che tocca e trascina un elemento sullo schermo


1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), richiamare
TouchEvent.getEvent().
4. Controllare se il valore restituito da TouchEvent.getEvent() è uguale a TouchEvent.MOVE.

30
Guida allo sviluppo Risposta agli eventi del touchscreen

protected boolean touchEvent(TouchEvent message) {


switch(message.getEvent()) {
case TouchEvent.MOVE:
Dialog.alert("Move event occurred");
return true;
}
return false;
}

Risposta a un utente che tocca leggermente lo schermo


1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.TouchGesture
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), richiamare
TouchEvent.getEvent().
4. Controllare se il valore restituito da TouchEvent.getEvent() è uguale a TouchEvent.DOWN.
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.DOWN:
Dialog.alert("Touch occurred");
return true;
}
return false;
}

Risposta a un'azione di scorrimento


1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.TouchGesture
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
2. Creare una classe che estenda la classe Manager.
public class newManager extends Manager {

31
Guida allo sviluppo Avvicinamento o allontanamento del pollice e dell'indice sullo schermo

3. Nell'implementazione del metodo touchEvent(TouchEvent message), verificare se il valore restituito da


TouchEvent.getEvent() è uguale a TouchEvent.MOVE.
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.MOVE:
return true;
}
return false;
}

Risposta a un utente che tocca lo schermo contemporaneamente in due


posizioni
1. Importare le seguenti classi:
• net.rim.device.api.ui.TouchEvent
• net.rim.device.api.ui.Field
• net.rim.device.api.ui.Manager
• net.rim.device.api.ui.Screen
• net.rim.device.api.ui.component.Dialog
2. Creare una classe che estenda le classi Manager, Screen e Field oppure una delle sottoclassi di Field.
public class newButtonField extends ButtonField {
3. Nell'implementazione del metodo touchEvent(TouchEvent message), verificare se i seguenti richiami del
metodo restituiscono valori maggiori di zero: TouchEvent.getX(1), TouchEvent.getY(1),
TouchEvent.getX(2), TouchEvent.getY(2).
protected boolean touchEvent(TouchEvent message) {
switch(message.getEvent()) {
case TouchEvent.MOVE:
if(message.getX(1) > 0 && message.getY(1) > 0) {
Dialog.alert("First finger touched/moved");
}
if(message.getX(2) > 0 && message.getY(2) > 0) {
Dialog.alert("Second finger touched/moved");
}
return true;
}
return false;
}

Avvicinamento o allontanamento del pollice e dell'indice


sullo schermo
I dispositivi BlackBerry® con touchscreen supportano la funzionalità di avvicinamento o allontanamento del pollice
e dell'indice sullo schermo. Questi movimenti in genere consentono di ingrandire e ridurre un oggetto sulla
schermata.

32
Guida allo sviluppo Avvicinamento o allontanamento del pollice e dell'indice sullo schermo

Un movimento di questo tipo inizia quando vengono rilevati due punti di contatto sul touchscreen. Un punto focale
di questo movimento è definito come il punto intermedio tra i due punti di contatto iniziali.
• Quando vengono rilevati due punti di contatto, si verifica un evento TouchGesture.PINCH_BEGIN. I punti
coordinati del punto focale di tale movimento sono memorizzati come TouchEvent.getX(1) e
TouchEvent.getY(1). È possibile accedere al valore di zoom iniziale richiamando
TouchGesture.getPinchMagnitude().
• Appena l'utente sposta uno o entrambi i punti di contatto, si verifica una serie di eventi
TouchGesture.PINCH_UPDATE. È possibile accedere ai valori di zoom durante il movimento richiamando
TouchGesture.getPinchMagnitude().
• Quando l'utente completa il movimento, si verifica un evento TouchGesture.PINCH_END. È possibile accedere
al valore di zoom finale richiamando TouchGesture.getPinchMagnitude().

Esempio di codice: recupero di informazioni relative all'allontanamento e avvicinamento del pollice e dell'indice
sullo schermo
Questo esempio mostra come gestire un movimento di avvicinamento o allontanamento del pollice e dell'indice sullo
schermo nel metodo touchEvent() di una schermata.

protected boolean touchEvent(TouchEvent message)


{
switch(message.getEvent())
{
case TouchEvent.GESTURE:
TouchGesture gesture = message.getGesture();
switch(gesture.getEvent())
{
case TouchGesture.PINCH_END:
Dialog.alert("Focal point: " + message.getX(1)
+ ", " + message.getY(1)
+ "\nFinal zoom value: " + gesture.getPinchMagnitude());
return true;
}
}
return false;
}

Avvicinamento e allontanamento del pollice e dell'indice sullo schermo


Per impostazione predefinita, questi movimenti non sono consentiti su una schermata in un'applicazione
BlackBerry® . È necessario impostare una proprietà della schermata per consentire movimenti di questo tipo su una
schermata.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.input.*;
2. Nell'oggetto Screen, creare un oggetto InputSettings per inserirvi le proprietà del touchscreen.

33
Guida allo sviluppo Azioni di spostamento tramite trackpad

InputSettings ts = TouchscreenSettings.createEmptySet();
3. Impostare la proprietà TouchscreenSettings.DETECT_PINCH su 1.
ts.set(TouchscreenSettings.DETECT_PINCH, 1);
4. Richiamare Screen.addInputSettings() per aggiungere le impostazioni di immissione alla schermata.
addInputSettings(ts);

È possibile modificare il valore della proprietà TouchscreenSettings.DETECT_PINCH in qualsiasi momento, non


appena si crea la schermata.

Esempio di codice
Questo esempio mostra come attivare la funzione di avvicinamento o allontanamento del pollice e dell'indice sullo
schermo in un costruttore della schermata.

public MyScreen()
{
setTitle("Sample Screen");
InputSettings ts = TouchscreenSettings.createEmptySet();
ts.set(TouchscreenSettings.DETECT_PINCH, 1);
addInputSettings(ts);
...
}

Azioni di spostamento tramite trackpad


Allo stesso modo dei dispositivi BlackBerry® con touchscreen, i dispositivi con trackpad supportano la funzionalità di
spostamento che gli utenti BlackBerry eseguono tramite trackpad.
Un oggetto TouchEvent con il tipo di evento TouchGesture.NAVIGATION_SWIPE viene generato quando l'utente
utilizza il trackpad per le operazioni di spostamento. È possibile recuperare informazioni sullo spostamento tramite
trackpad utilizzando i seguenti metodi:
• TouchGesture.getSwipeAngle()
• TouchGesture.getSwipeDirection()
• TouchGesture.getSwipeContentAngle()
• TouchGesture.getSwipeContentDirection()
• TouchGesture.getSwipeMagnitude()

Esempio di codice: recupero di informazioni relative allo spostamento tramite trackpad


Questo esempio mostra come gestire un movimento di questo tipo nel metodo touchEvent() di una schermata.

protected boolean touchEvent(TouchEvent message)


{
switch(message.getEvent())

34
Guida allo sviluppo Azioni di spostamento tramite trackpad

{
case TouchEvent.GESTURE:
TouchGesture gesture = message.getGesture();
switch(gesture.getEvent())
{
case TouchGesture.NAVIGATION_SWIPE:
Dialog.alert("Swipe direction: " + gesture.getSwipeDirection()
+ ", "
+ "\nMagnitude: " + gesture.getSwipeMagnitude());
return true;
}
}
return false;
}

Azioni di spostamento tramite trackpad


Per impostazione predefinita, le azioni di spostamento effettuate dagli utenti BlackBerry® con il trackpad non sono
attivate su una schermata. È necessario impostare una proprietà di navigazione per consentire l'azione di
spostamento tramite trackpad su una schermata.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.input.*;
2. Nell'oggetto Screen, creare un oggetto InputSettings per inserirvi le proprietà di navigazione.
InputSettings nd = NavigationDeviceSettings.createEmptySet();
3. Impostare la proprietà NavigationDeviceSettings.DETECT_SWIPE su 1.
nd.set(NavigationDeviceSettings.DETECT_SWIPE, 1);
4. Richiamare Screen.addInputSettings() per aggiungere le impostazioni di immissione alla schermata.
addInputSettings(nd);

È possibile modificare il valore della proprietà NavigationDeviceSettings.DETECT_SWIPE in qualsiasi


momento, non appena si crea la schermata.

Esempio di codice
Questo esempio mostra come attivare lo spostamento tramite trackpad in un costruttore della schermata.

public MyScreen()
{
setTitle("Sample Screen");
InputSettings nd = NavigationDeviceSettings.createEmptySet();
nd.set(NavigationDeviceSettings.DETECT_SWIPE, 1);

35
Guida allo sviluppo Avvio eventi

addInputSettings(nd);
...
}

Avvio eventi
È possibile generare eventi dell'interfaccia utente in modo programmatico servendosi della classe
EventInjector e delle sue classi interne. Sui dispositivi BlackBerry® con BlackBerry® Device Software versione 5.0
o successiva e con touchscreen, è possibile avviare gli eventi touch (tocco o colpo sullo schermo). È possibile utilizzare
una delle classi interne di EventInjector per creare un modello di evento e utilizzare il metodo invokeEvent
() per avviare l'evento. L'evento viene inviato all'applicazione attualmente selezionata e pronta ad accettare l'input.

È possibile utilizzare avvio eventi per automatizzare il testing. È possibile inoltre utilizzare Event Injector per consentire
alle periferiche di interagire con un dispositivo BlackBerry. È possibile utilizzarlo anche nelle applicazioni accessibili
come i programmi di riconoscimento vocale. Per scaricare un'applicazione di prova che mostri come utilizzare Event
Injector, visitare il sito Web www.blackberry.com/go/toucheventinjectorsampleapp e scaricare l'applicazione di
prova Touch Event Injector. Per ulteriori informazioni sull'applicazione di prova, visitare il sito www.blackberry.com/
go/docs/developers e leggere il documento Toccare la Panoramica dell'Applicazione di prova dell'avvio eventi.

36
Guida allo sviluppo API Command Framework

API Command Framework 6


È possibile utilizzare l'API Command Framework nel pacchetto net.rim.device.api.command per definire la
funzionalità che è possibile utilizzare in diverse posizioni nell'applicazione o in altre applicazioni sul dispositivo
BlackBerry® .
L'API Command Framework contiene gestori di comando, metadati di comando e comandi.

Componente Descrizione
Gestore di comando Si utilizza la classe CommandHandler per definire la funzionalità che si desidera
rendere disponibile nell'applicazione o nelle altre applicazioni sul dispositivo.
Viene creata una classe che estende la classe astratta CommandHandler e
definisce la funzionalità nel metodo della classe execute(). Tale funzionalità
viene denominata comando.
Metadati di comando Si utilizza la classe CommandMetadata per definire i metadati che descrivono un
comando. Tutti i metadati di comando sono incapsulati in un oggetto
CommandMetadata. L'unica parte dei metadati richiesta per un comando è l'ID
del comando, che viene fornito quando l'oggetto CommandMetadata viene creato
e memorizzato nel campo COMMAND_ID dell'oggetto.
CommandMetadata fornisce altri campi da utilizzare per descrivere il comando,
ad esempio RESOURCE_BUNDLE_NAME, a cui è possibile assegnare il nome del
bundle di risorse utilizzato dal comando. È possibile definire anche voci di metadati
specifiche per un comando particolare.
Comando Si utilizza la classe Command per eseguire un comando. Un'istanza Command
funziona come proxy per un'istanza di una classe che estende
CommandHandler. Quando Command.execute() viene richiamato, la chiamata
viene delegata all'istanza CommandHandler associata, che passa il contesto
attuale e in modo trasparente una versione di sola lettura dei metadati del
comando associati per l'esecuzione.

L'API Command Framework fornisce due registri che è possibile utilizzare per memorizzare i comandi:
• È possibile utilizzare il registro locale per memorizzare comandi per l'utilizzo nell'applicazione tramite la classe
LocalCommandRegistrarConnection.
• È possibile utilizzare il registro globale per memorizzare comandi per l'utilizzo in altre applicazioni sul dispositivo
tramite la classe RemoteCommandRegistrarConnection.
Le applicazioni di esempio Command Framework Demo e Command Framework Demo Remote App sono incluse in
BlackBerry® Java® SDK. Queste applicazioni di esempio dimostrano come definire e utilizzare comandi in una sola
applicazione e come definire comandi in un'applicazione e utilizzarli nelle altre applicazioni.

37
Guida allo sviluppo Utilizzo di un comando con un componente dell'interfaccia utente

Utilizzo di un comando con un componente dell'interfaccia


utente
È possibile definire un comando per l'utilizzo con un componente dell'interfaccia utente nell'applicazione
BlackBerry®. Utilizzando questo approccio, non è necessario definire i metadati per il comando. I componenti
dell'interfaccia utente principali per le applicazioni BlackBerry che supportano i comandi includono voci di menu,
pulsanti, voci di menu a comparsa e barre degli strumenti.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.command.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
2. Creare un gestore di comando creando una classe che estende la classe astratta CommandHandler. In execute
(), definire la funzionalità che si desidera associare al componente dell'interfaccia utente. Per specificare se un
comando è eseguibile per un dato oggetto di contesto, è possibile implementare un metodo canExecute()
nel gestore di comando. Se non si implementa canExecute(), il comando è sempre eseguibile.
// this command is always executable
class DialogCommandHandler extends CommandHandler
{
public void execute(ReadOnlyCommandMetadata metadata, Object context)
{
Dialog.alert("Executing command for " + context.toString());
}
}
3. Creare il componente dell'interfaccia utente.
MenuItem myItem = new MenuItem(new StringProvider("My Menu Item"),
0x230000, 0);
4. Per una voce di menu o per il pulsante, è possibile impostare facoltativamente il contesto per il comando che
utilizza il metodo setCommandContext() del componente dell'interfaccia utente. Per alcuni comandi,
potrebbe essere necessario un contesto per determinare cosa dovrebbe fare il comando. Se non si imposta un
contesto, l'oggetto della voce di menu o l'oggetto del pulsante è il contesto.
myItem.setCommandContext(new Object()
{
public String toString()
{
return "My MenuItem Object";
}
});
5. Richiamare setCommand() per specificare il comando per il componente dell'interfaccia utente e fornire il
gestore di comando come argomento del metodo.
myItem.setCommand(new Command(new DialogCommandHandler()));
6. Aggiungere il componente alla schermata.

38
Guida allo sviluppo Utilizzo di un comando in una o più applicazioni

addMenuItem(myItem);

Il comando viene eseguito quando un utente BlackBerry esegue un'azione sul componente dell'interfaccia utente
(ad esempio, quando l'utente fa clic su una voce di menu).

Esempi di codice
Per gli esempi di questo approccio per la definizione e l'utilizzo di comandi, vedere gli oggetti MenuItem e
ButtonField nel il riferimento API.

Utilizzo di un comando in una o più applicazioni


È possibile memorizzare un comando in un registro locale per l'utilizzo in una specifica applicazione o in un registro
globale per l'utilizzo in qualsiasi applicazione sul dispositivo BlackBerry® .
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.command.*;
import net.rim.device.api.command.registrar.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
2. Creare un gestore di comando creando una classe che estende la classe astratta CommandHandler. In execute
(), definire la funzionalità che si desidera rendere disponibile. Per specificare se un comando è eseguibile per
un dato oggetto di contesto, opzionalmente è possibile implementare un metodo canExecute() nel gestore
di comando. Se non si implementa canExecute(), il comando è sempre eseguibile.
private static class ViewContactCommand extends CommandHandler
{
public void execute(ReadOnlyCommandMetadata metadata, Object context)
{
// Invoke the Contacts application to view a contact here
}
public boolean canExecute(ReadOnlyCommandMetadata metadata, Object context)
{
// Return true if the command can be executed
// with the passed-in context object.
}
}
3. Definire i metadati del comando.
String id = "com.example.contacts.view.emailaddr";
CommandMetadata metadata = new CommandMeta(id);
4. Se le applicazioni che utilizzano il comando devono creare istanze del comando, memorizzare il nome classe del
comando nei metadati.
metadata.setClassname(ViewContactCommand.class.getName());
Nota: Le applicazioni possono creare istanze di comandi di terzi in modo dinamico solo se i comandi sono
memorizzati nel registro locale.

39
Guida allo sviluppo Utilizzo di un comando in una o più applicazioni

5. Facoltativamente, definire le categorie di comando e di contesto per il comando. Le applicazioni che utilizzano
il comando utilizzano le categorie per trovare i comandi in un registro e determinare se un comando è eseguibile.

Tipo di categoria Descrizione


Comando Specificare un tipo di categorizzazione che si desidera per il proprio comando. Le
applicazioni che utilizzano i comandi possono inviare una query a un registro per i
comandi nelle categorie specificate.
Contesto Specificare i contesti appropriati per il comando da eseguire all'interno. È possibile
utilizzare questa categoria per comunicare alle applicazioni che utilizzano il comando
quali tipi di oggetti di contesto possono essere passati a CommandHandler.Execute
().

String[] myCommandCategories = {"app.contacts", "action.view"};


metadata.setCommandCategories(new CategoryCollection(myCommandCategories));
String[] myContextCategories = {emailaddr};
metadata.setContextCategories(new CategoryCollection(myContextCategories));
6. Registrare il comando.
a. Se si desidera che il comando sia disponibile solo in un'applicazione specifica, utilizzare un oggetto
LocalCommandRegistrarConnection. Il registro locale è disponibile solo nel processo corrente.
LocalCommandRegistrarConnection connection =
new LocalCommandRegistrarConnection();
connection.registerCommand(new ViewContactCommand(), metadata);
Nota: Affinché le applicazioni creino istanze del comando in modo dinamico, è necessario registrare il
comando solo con i metadati richiamando registerCommand(CommandMetadata). Altrimenti, viene
utilizzato il CommandHandler registrato.
b. Se si desidera che il comando in uso sia disponibile in qualsiasi applicazione, utilizzare un oggetto
RemoteCommandRegistrarConnection. Il registro globale è disponibile per tutti i processi in esecuzione
sul dispositivo.
RemoteCommandRegistrarConnection connection =
new RemoteCommandRegistrarConnection();
connection.registerCommand(new ViewContactCommand(), metadata);

7. Da un'altra posizione nell'applicazione (per i comandi locali) o da qualsiasi applicazione sul dispositivo (per i
comandi globali), recuperare e utilizzare il comando.
a. Creare un oggetto CommandRequest e compilarlo con le informazioni sul comando che si desiderano
recuperare dal registro.
CommandRequest request = new CommandRequest();
String[] myCommandCategories = {"app.contacts", "action.view"};
request.setCommandCategories(new CategoryCollection(myCommandCategories));
...
b. Recuperare il comando dal registro.

40
Guida allo sviluppo Utilizzo di un comando in una o più applicazioni

// using the local registry


LocalCommandRegistrarConnection connection =
new LocalCommandRegistrarConnection();
Command command = connection.getCommand(request);
// using the global registry
RemoteCommandRegistrarConnection connection =
new RemoteCommandRegistrarConnection();
Command command = connection.getCommand(request);
c. Utilizzare il comando. L'esempio seguente esegue il comando, a seconda del contesto.
command.execute(context); // context is the context object

Esempi di codice
Due applicazioni di esempio che utilizzano l'API Command Framework sono incluse in BlackBerry® Java® SDK:
• Command Framework Demo Remote App mostra come creare un comando e memorizzarlo nel registro globale
per l'utilizzo in altre applicazioni.
• Command Framework Demo mostra come creare comandi, memorizzarli nel registro locale e aggiungerli come
voci di menu nei menu a comparsa per i campi, a seconda del contenuto dei campi. Questa applicazione di
esempio esegue anche un comando memorizzato nel registro globale da Command Framework Demo Remote
App.

41
Guida allo sviluppo Disposizione dei componenti dell'interfaccia utente

Disposizione dei componenti dell'interfaccia 7


utente
È possibile disporre i componenti dell'interfaccia utente sulla schermata di un'applicazione utilizzando i gestori di
layout dell'API di BlackBerry®. Le seguenti classi estendono la classe Manager disponibile nel pacchetto
net.rim.device.apu.ui e forniscono i layout predefiniti per i componenti dell'interfaccia utente presenti nella
schermata dell'applicazione in uso.

Gestore di layout Descrizione


FlowFieldManager Questo gestore di layout dispone i componenti dell'interfaccia utente in
senso verticale e quindi orizzontale a seconda delle dimensioni della
schermata. Il primo componente dell'interfaccia utente viene posizionato
nell'angolo superiore-sinistro della schermata e i componenti successivi
vengono collocati orizzontalmente a destra del primo componente fino a
quando viene completata la larghezza della schermata. Quando i
componenti dell'interfaccia utente non rientrano più nella prima riga, il
componente successivo viene collocato su una riga sottostante che
presenta un'altezza equivalente al componente più alto della riga
sovrastante. È possibile applicare i bit di stile verticale (ad esempio
Field.FIELD_TOP Field.FIELD_BOTTOMo Field.FIELD_VCENTER)
per allineare i componenti di interfaccia utente in senso verticale all'interno
della loro riga.
HorizontalFieldManager Questo gestore di layout dispone i componenti dell'interfaccia utente su
un'unica riga orizzontale, che inizia sul lato sinistro della schermata e
termina sul lato destro. Poiché questo gestore di layout dispone i
componenti dell'interfaccia utente in senso orizzontale, non è possibile
applicare i bit di stile orizzontale ai componenti dell'interfaccia utente (ad
esempio Field.FIELD_LEFT Field.FIELD_HCENTER o
Field.FIELD_RIGHT). È possibile applicare i bit di stile verticale (ad
esempio Field.FIELD_TOP Field.FIELD_BOTTOMo
Field.FIELD_VCENTER).

Se i componenti dell'interfaccia utente non rientrano nella larghezza


disponibile per la schermata, è necessario utilizzare
Manager.HORIZONTAL_SCROLL per attivare lo scorrimento orizzontale.
In caso contrario, la schermata visualizzerà il maggior numero possibile di
componenti dell'interfaccia utente entro la larghezza disponibile per la
schermata nascondendo il resto. I componenti dell'interfaccia utente
esistono ma non sono visibili. Questa situazione può richiedere agli utenti
di scorrere la schermata.

42
Guida allo sviluppo Disposizione dei componenti dell'interfaccia utente

Gestore di layout Descrizione


VerticalFieldManager Questo gestore di layout dispone i componenti dell'interfaccia utente in
un'unica colonna verticale che inizia nella parte superiore della schermata
e termina nella parte inferiore. Poiché questo gestore di layout è progettato
in modo da disporre le voci in senso verticale, non è possibile applicare i bit
di stile verticale ai componenti dell'interfaccia utente (ad esempio
Field.FIELD_TOP, Field.FIELD_BOTTOM o Field.FIELD_VCENTER).
È possibile applicare i bit di stile orizzontale (ad esempio
Field.FIELD_LEFT Field.FIELD_HCENTERo Field.FIELD_RIGHT).

È possibile utilizzare ulteriori gestori di layout per disporre i componenti dell'interfaccia utente nell'applicazione in
uso. È possibile, ad esempio, utilizzare il gestore di layout GridFieldManager per posizionare i componenti
dell'interfaccia utente nelle righe e nelle colonne di una schermata al fine di creare una griglia. È possibile utilizzare
il gestore di layout EyelidFieldManager per visualizzare i componenti dell'interfaccia utente su una coppia di
gestori che verranno visualizzati temporaneamente nella parte superiore e inferiore della schermata.

Disposizione dei componenti dell'interfaccia utente


1. Importare le classi e le interfacce richieste.
net.rim.device.api.ui.container.HorizontalFieldManager;
net.rim.device.api.ui.component.ButtonField;
2. Creare un'istanza di HorizontalFieldManager.
HorizontalFieldManager _fieldManagerBottom = new HorizontalFieldManager();
3. Richiamare add() per aggiungere HorizontalFieldManager a una schermata.
myScreen.add(_fieldManagerBottom);
4. Creare un'istanza di ButtonField.
ButtonField mySubmitButton = new ButtonField("Submit");
5. Aggiungere ButtonField a HorizontalFieldManager.
_fieldManagerBottom.add(mySubmitButton);

Creazione di un layout di griglia


Nota: Per informazioni sulla creazione di un layout di griglia nelle versioni di BlackBerry® Java® Development
Environment antecedenti alla 5.0, visitare il sito Web http://www.blackberry.com/knowledgecenterpublic e leggere
l'articolo DB-00783.
È possibile posizionare i campi in righe e colonne su una schermata per creare una griglia utilizzando la classe
GridFieldManager. Quando viene creata la griglia, è possibile specificare il numero di righe e di colonne. Dopo
aver creato la griglia, non è possibile modificare il numero di righe e di colonne contenute.

43
Guida allo sviluppo Creazione di un layout di griglia

Le griglie sono indicizzate con base zero, pertanto la prima cella è posizionata sulla fila 0, colonna 0. In un lingua con
scrittura da sinistra a destra, la prima cella si trova nell'angolo superiore sinistro della griglia.

In una lingua con scrittura da destra a sinistra, la prima cella si trova nell'angolo superiore destro della griglia.

È possibile aggiungere campi alla griglia in modo sequenziale (da sinistra a destra, dall'alto verso il basso nelle lingue
con scrittura da sinistra a destra; da destra a sinistra, dall'alto verso il basso nelle lingue con scrittura da destra a
sinistra) oppure specificando una riga e una colonna nella griglia. È possibile eliminare i campi e i campi di inserimento,
specificare la spaziatura tra le colonne e le righe e recuperare le proprietà della griglia.
Le griglie non dispongono di righe o colonne di intestazione definite. È possibile simulare l'aspetto delle intestazioni
modificando l'aspetto dei campi della prima riga o nella prima colonna della griglia.
È possibile scorrere le griglie orizzontalmente o verticalmente se la larghezza o l'altezza della griglia supera l'area
visibile della schermata.
È possibile specificare la larghezza della colonna richiamando GridFieldManager.setColumnProperty() e
l'altezza della riga richiamando GridFieldManager.setRowProperty(). Quando si richiamano questi metodi, è
necessario specificare una proprietà GridFieldManager.

Proprietà Descrizione
FIXED_SIZE La larghezza o l'altezza presentano una dimensione fissa in pixel
PREFERRED_SIZE La larghezza o l'altezza è una dimensione preferita basata sulla
dimensione massima dei campi della colonna o della riga
(PREFERRED_SIZE è la proprietà predefinita)
PREFERRED_SIZE_WITH_MAXIMUM La larghezza o l'altezza presenta una dimensione preferita fino alla
dimensione massima

44
Guida allo sviluppo Creazione di un layout di griglia

Proprietà Descrizione
AUTO_SIZE La larghezza o l'altezza è basata sulla spaziatura della schermata
disponibile

Creazione di un layout di griglia


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. Nell'esempio, la classe GridScreen, descritta nel passaggio 3, rappresenta la schermata
personalizzata.
class GridFieldManagerDemo extends UiApplication
{
public static void main(String[] args)
{
GridFieldManagerDemo theApp = new GridFieldManagerDemo();
theApp.enterEventDispatcher();
}
GridFieldManagerDemo()
{
pushScreen(new GridScreen());
}
}
3. Creare il framework della schermata personalizzata estendendo la classe MainScreen.
class GridScreen extends MainScreen
{
public GridScreen()
{
}
}
4. Nel costruttore della schermata richiamare setTitle() per impostare il testo che si desidera visualizzare nella
sezione del titolo della schermata.
setTitle("GridFieldManager Demo");
5. Nel costruttore della schermata creare un'istanza della classe GridFieldManager. Specificare il numero di file,
il numero di colonne e lo stile della griglia (utilizzando uno stile ereditato da
net.rim.device.api.ui.Manager). Specificare 0 per far sì che lo stile utilizzi lo stile predefinito.
GridFieldManager grid;
grid = new GridFieldManager(2,3,0);
6. Nel costruttore della schermata richiamare GridFieldManager.add() per aggiungere i campi alla griglia.

45
Guida allo sviluppo Creazione di un layout di griglia

grid.add(new LabelField("one"));
grid.add(new LabelField("two"));
grid.add(new LabelField("three"));
grid.add(new LabelField("four"));
grid.add(new LabelField("five"));
7. Nel costruttore della schermata richiamare i metodi GridFieldManager set() per specificare le proprietà
della griglia.
grid.setColumnPadding(20);
grid.setRowPadding(20);
8. Nel costruttore della schermata richiamare Screen.add() per aggiungere la griglia alla schermata.
add(grid);

Al termine:
È possibile modificare la griglia dopo averla creata. Ad esempio, è possibile aggiungere o eliminare campi oppure
modificare le proprietà della griglia.

Esempio di codice: creazione di un layout di griglia


/*
* GridFieldManagerDemo.java
*
* Research In Motion Limited proprietary and confidential
* Copyright Research In Motion Limited, 2009
*/
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
public class GridFieldManagerDemo extends UiApplication
{
public static void main(String[] args)
{
GridFieldManagerDemo theApp = new GridFieldManagerDemo();
theApp.enterEventDispatcher();
}
GridFieldManagerDemo()
{
pushScreen(new GridScreen());
}
}
class GridScreen extends MainScreen
{
public GridScreen()
{
setTitle("GridFieldManager Demo");
GridFieldManager grid = new GridFieldManager(2,3,0);
grid.add(new LabelField("one"));
grid.add(new LabelField("two"));
grid.add(new LabelField("three"));
grid.add(new LabelField("four"));
grid.add(new LabelField("five"));

46
Guida allo sviluppo Visualizzazione di campi in una coppia di gestori temporanea

grid.setColumnPadding(20);
grid.setRowPadding(20);
add(grid);
// The grid looks like this:
// | one | two | three
// | four | five |
// insert a cell first row, second column
grid.insert(new LabelField("insert"), 0, 1);
// The grid now looks like this:
// | one | insert | two
// | three | four | five
// delete a cell second row, second column
grid.delete(1,1);
// The grid now looks like this:
// | one | insert | two
// | three | | five
// Add field to first unoccupied cell
grid.add(new LabelField("new"));
// The grid now looks like this:
// | one | insert | two
// | three | new | five
}
}

Visualizzazione di campi in una coppia di gestori


temporanea
È possibile utilizzare la classe EyelidFieldManager per visualizzare i campi di una coppia di gestori che verranno
visualizzati temporaneamente nella parte superiore e inferiore della schermata.
Per impostazione predefinita, i campi vengono visualizzati quando l'utente BlackBerry® muove la trackball oppure,
per un dispositivo con touchscreen, tocca lo schermo. I campi scompaiono dopo un periodo di inattività (1,2 secondi
per impostazione predefinita). È possibile ignorare queste proprietà predefinite.
Non c'è limite al numero e alla dimensione dei campi. Se i gestori contengono più campi di quanti ne possono essere
visualizzati, i gestori superiore e inferiore si sovrappongono al gestore nella parte superiore della schermata.

Visualizzazione temporanea di un oggetto ButtonField e di un oggetto


LabelField nella parte superiore e inferiore della schermata
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.extension.container.*;

47
Guida allo sviluppo Visualizzazione di campi in una coppia di gestori temporanea

2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe EyelidFieldManagerDemoScreen, descritta nel passaggio 3, rappresenta la
schermata personalizzata.
public class EyelidFieldManagerDemo extends UiApplication
{
public static void main(String[] args)
{
EyelidFieldManagerDemo app = new EyelidFieldManagerDemo();
app.enterEventDispatcher();
}
public EyelidFieldManagerDemo()
{
pushScreen(new EyelidFieldManagerDemoScreen());
}
}
3. Creare il framework della schermata personalizzata estendendo la classe MainScreen.
class EyelidFieldManagerDemoScreen extends MainScreen {
{
public EyelidFieldManagerDemoScreen()
{
}
}
4. Nel costruttore della schermata richiamare setTitle() per specificare il testo visualizzato nella sezione del
titolo della schermata.
setTitle("EyelidFieldManager Demo");
5. Nel costruttore della schermata creare un'istanza della classe EyelidFieldManager.
EyelidFieldManager manager = new EyelidFieldManager();
6. Nel costruttore della schermata richiamare EyelidFieldManager.addTop() per aggiungere un oggetto
LabelField al gestore della parte superiore di EyelidFieldManager. .
manager.addTop(new LabelField("Hello World"));
7. Nel costruttore della schermata creare un oggetto HorizontalFieldManager. Richiamare
HorizontalFieldManager.add() per aggiungere pulsanti a HorizontalFieldManager. Richiamare
EyelidFieldManager.addBottom() per aggiungere HorizontalFieldManager al gestore della parte
inferiore di EyelidFieldManager.
HorizontalFieldManager buttonPanel = new HorizontalFieldManager
(Field.FIELD_HCENTER | Field.USE_ALL_WIDTH);
buttonPanel.add(new SimpleButton("Button 1"));
buttonPanel.add(new SimpleButton("Button 2"));
manager.addBottom(buttonPanel);

48
Guida allo sviluppo

8. Nel costruttore della schermata richiamare EyelidFieldManager.setEyelidDisplayTime() per


specificare il periodo di inattività, espresso in millisecondi, che deve trascorrere prima che la coppia di gestori
scompaia.
manager.setEyelidDisplayTime(3000);
9. Nel costruttore di schermata, richiamare add() per aggiungere EyelidFieldManager alla schermata.
add(manager);

Esempio di codice: visualizzazione temporanea di un elemento ButtonField e di un


elemento LabelField nella parte superiore e inferiore della schermata
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.extension.container.*;
public class EyelidFieldManagerDemo extends UiApplication
{
public static void main(String[] args)
{
EyelidFieldManagerDemo app = new EyelidFieldManagerDemo();
app.enterEventDispatcher();
}
public EyelidFieldManagerDemo()
{
pushScreen(new EyelidFieldManagerDemoScreen());
}
}
class EyelidFieldManagerDemoScreen extends MainScreen
{
public EyelidFieldManagerDemoScreen()
{
setTitle("EyelidFieldManager Demo");
EyelidFieldManager manager = new EyelidFieldManager();
manager.addTop(new LabelField("Hello World"));
HorizontalFieldManager buttonPanel = new HorizontalFieldManager
(Field.FIELD_HCENTER | Field.USE_ALL_WIDTH);
buttonPanel.add(new ButtonField("Button 1"));
buttonPanel.add(new ButtonField("Button 2"));
manager.addBottom(buttonPanel);
manager.setEyelidDisplayTime(3000);
add(manager);
}
}

49
Guida allo sviluppo Visualizzazione di un campo in una posizione assoluta della schermata

Visualizzazione di un campo in una posizione assoluta della


schermata
È possibile utilizzare la classe AbsoluteFieldManager per specificare una posizione assoluta, basata sulle
coordinate x-y, di un campo su una schermata piuttosto che una posizione relativa agli altri campi sulla schermata.
È possibile utilizzare la classe AbsoluteFieldManager per il controllo della posizione di campi e per sovrapporre
campi sulla schermata.

Visualizzazione di un'etichetta in una posizione assoluta della schermata


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe AbsoluteFieldManagerDemoScreen, descritta nel passaggio 3, rappresenta la
schermata personalizzata.
public class AbsoluteFieldManagerDemo extends UiApplication
{
public static void main(String[] args)
{
AbsoluteFieldManagerDemo app = new AbsoluteFieldManagerDemo();
app.enterEventDispatcher();
}
public AbsoluteFieldManagerDemo()
{
pushScreen(new AbsoluteFieldManagerDemoScreen());
}
}
3. Creare il framework della schermata personalizzata estendendo la classe MainScreen. Richiamare setTitle
() per impostare il testo visualizzato nella sezione del titolo della schermata.
class AbsoluteFieldManagerDemoScreen extends MainScreen
{
public AbsoluteFieldManagerDemoScreen()
{
setTitle("AbsoluteFieldManager Demo");
}
}
4. Nel costruttore della schermata creare un'istanza della classe AbsoluteFieldManager.
AbsoluteFieldManager manager = new AbsoluteFieldManager();

50
Guida allo sviluppo Visualizzazione di un campo in una posizione assoluta della schermata

5. Nel costruttore della schermata, creare e inizializzare una variabile per memorizzare una coordinata Y che
corrisponde al centro verticale della schermata.
int halfwayDown = Display.getHeight() / 2;
6. Nel costruttore della schermata, richiamare AbsoluteFieldManager.add() per aggiungere un oggetto
LabelField al centro verticale della schermata e con una coordinata X di 2.
manager.add(new LabelField("Hello world"), 2, halfwayDown);
7. Nel costruttore di schermata, richiamare add() per aggiungere AbsoluteFieldManager alla schermata.
add(manager);

Esempio di codice: visualizzazione di un'etichetta in una posizione assoluta


della schermata
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.*;
public class AbsoluteFieldManagerDemo extends UiApplication
{
public static void main(String[] args)
{
AbsoluteFieldManagerDemo app = new AbsoluteFieldManagerDemo();
app.enterEventDispatcher();
}
public AbsoluteFieldManagerDemo()
{
pushScreen(new AbsoluteFieldManagerDemoScreen());
}
}
class AbsoluteFieldManagerDemoScreen extends MainScreen
{
public AbsoluteFieldManagerDemoScreen()
{
setTitle("AbsoluteFieldManager Demo");
AbsoluteFieldManager manager = new AbsoluteFieldManager();
int halfwayDown = Display.getHeight() / 2;
manager.add(new LabelField("Hello world"), 2, halfwayDown);
add(manager);
}
}

51
Guida allo sviluppo Componenti dell'interfaccia utente

Componenti dell'interfaccia utente 8


Aggiunta di un componente interfaccia utente a una
schermata
1. Importare le seguenti classi:
• net.rim.device.api.ui.component.CheckboxField
• net.rim.device.api.ui.container.MainScreen
2. Creare un'istanza di un componente di interfaccia utente.
CheckboxField myCheckbox = new CheckboxField("First checkbox", true);
3. Aggiungere il componente dell'interfaccia utente all'estensione di una classe Screen.
mainScreen.add(myCheckbox);

Allineamento di un campo a una riga di testo


È possibile creare un'applicazione in grado di allineare un oggetto Field all'inizio naturale della riga di testo
utilizzando il contrassegno Field.FIELD_LEADING. Ad esempio, se si crea un oggetto Field con il contrassegno
di allineamento Field.FIELD_LEADING e lo si aggiunge a VerticalFieldManager, se l'applicazione si avvia in
lingua inglese o cinese, l'oggetto Field viene allineato al lato sinistro della schermata. Se l'applicazione si avvia in
lingua araba o ebraica, l'oggetto Field si allinea al lato destro della schermata.

Pulsanti
Utilizzare i pulsanti per consentire agli utenti di eseguire un'operazione da una finestra di dialogo. I menu in genere
includono azioni associate a una schermata.
Con un pulsante gli utenti possono eseguire le seguenti operazioni:

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Evidenziare un pulsante. Far scorrere un dito sul trackpad. • Toccare leggermente il pulsante.
• Far scorrere un dito sul trackpad.
Eseguire un'azione. Fare clic sul trackpad o premere il tasto • Toccare la voce.
Invio. • Fare clic sul trackpad.
• Premere il tasto Invio.

52
Guida allo sviluppo Pulsanti

Procedura consigliata: implementazione dei pulsanti


• Evitare l'uso di pulsanti sulla schermata di un'applicazione. Per fornire accesso alle funzionalità associate a una
schermata, utilizzare il menu dell'applicazione. BlackBerry® Sui dispositivi con un trackpad, il menu è disponibile
immediatamente per gli utenti, indipendentemente dalla posizione del cursore sulla schermata. I pulsanti sono
statici: per eseguire l'azione associata devono essere evidenziati dagli utenti. Se si utilizzano i pulsanti, includere
le voci di menu corrispondenti nel menu dell'applicazione. Sui dispositivi BlackBerry con touchscreen, è possibile
utilizzare pulsanti per le azioni critiche.
• Utilizzare le caselle di controllo per opzioni quali l'attivazione o la disattivazione di una funzionalità.
• Utilizzare la classe ButtonField per creare pulsanti.
• Utilizzare come pulsante predefinito quello che verrà selezionato con maggiore probabilità dagli utenti. Evitare
di utilizzare come pulsante predefinito un pulsante associato a un'azione negativa.
Linee guida per le etichette
• Utilizzare etichette chiare e concise.
• Laddove possibile, utilizzare etichette contenenti un'unica parola. Le dimensioni di un pulsante variano a seconda
della lunghezza dell'etichetta. Se un'etichetta è troppo lunga, un'ellissi (...) indica che il testo è troncato.
• Utilizzare verbi che descrivono l'azione associata (ad esempio "Annulla", "Elimina", "Ignora" o "Salva"). Se
necessario, includere un testo descrittivo più lungo in un altro punto della schermata (ad esempio in un
messaggio dell'applicazione).
• Evitare di utilizzare etichette quali "Sì" e "No".
• Evitare di utilizzare la punteggiatura in un'etichetta. Utilizzare dei puntini di sospensione nell'etichetta di un
pulsante per indicare che gli utenti dovranno eseguire un'ulteriore operazione dopo avere fatto clic su di esso.

Creazione di un pulsante
1. Importare la classe net.rim.device.api.ui.component.ButtonField.
2. Creare un'istanza di ButtonField utilizzando un parametro di stile.
ButtonField mySubmitButton = new ButtonField("Submit");

53
Guida allo sviluppo Caselle di controllo

Caselle di controllo
Utilizzare caselle di controllo per le opzioni binarie che possono essere comprese facilmente dagli utenti. Ad esempio,
utilizzare una casella di controllo per un'opzione che può essere attivata e disattivata.
Con una casella di controllo gli utenti possono eseguire la seguente operazione:

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Selezionare una casella di Premere il tasto Space o fare clic sul • Toccare la voce.
controllo. trackpad. • Premere il tasto Space.
• Fare clic sul trackpad.

Procedura consigliata: implementazione delle caselle di controllo


• Utilizzare le caselle di controllo quando gli utenti possono selezionare più opzioni.
• Utilizzare la classe CheckboxField per creare le caselle di controllo.
• Non avviare un'azione quando gli utenti selezionano una casella di controllo. Non aprire, ad esempio, una nuova
schermata.
• Allineare le caselle di controllo in senso verticale.
• Raggruppare e ordinare le caselle di controllo in senso logico (raggruppare ad esempio le opzioni correlate o
visualizzare per prime le opzioni più comuni). Evitare di ordinare le caselle di controllo in senso alfabetico, poiché
tale ordine dipende dalla lingua.
Linee guida per le etichette
• Utilizzare etichette chiare e concise. Verificare che l'etichetta descriva chiaramente quale azione viene avviata
dagli utenti quando selezionano la casella di controllo.
• Utilizzare etichette che esprimano un'azione positiva, laddove possibile. Se ad esempio gli utenti hanno la
possibilità di attivare o disattivare una funzione, utilizzare nell'etichetta il verbo "attivare" anziché "disattivare".

54
Guida allo sviluppo Caselle di controllo

• Posizionare le etichette sul lato destro delle caselle di controllo. Nelle schermate delle opzioni, posizionare le
etichette sul lato sinistro delle caselle di controllo.
• Iniziare le frasi con la lettera maiuscola.
• Aggiungere alle etichette delle caselle di controllo il carattere due punti (:).

Creazione di una casella di controllo


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe MyUiScreen, descritta nel passaggio 3, rappresenta la schermata personalizzata.
public class MyUi extends UiApplication
{
public static void main(String[] args)
{
MyUi theApp = new MyUi();
theApp.enterEventDispatcher();
}
public MyUi()
{
pushScreen(new MyUiScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore della
schermata richiamare setTitle() per specificare il titolo della schermata.
class MyUiScreen extends MainScreen
{
public MyUiScreen()
{
setTitle("UI Component Sample");
}
}
4. Nel costruttore della schermata creare una casella di controllo utilizzando la classe CheckboxField. Nel
costruttore CheckboxField specificare l'etichetta della casella di controllo e utilizzare un valore booleano per
indicare se la casella di controllo è la selezione predefinita (true indica, ad esempio, che la casella di controllo
è selezionata per impostazione predefinita). Richiamare add() per aggiungere la casella di controllo alla
schermata.
add(new CheckboxField("First Check Box", true));
add(new CheckboxField("Second Check Box", false));

55
Guida allo sviluppo Creazione di un file bitmap

5. Per modificare il comportamento predefinito di una casella di controllo, utilizzare gli stili ereditati dalla classe
Field. Per creare, ad esempio, una casella di controllo che gli utenti non possano modificare, utilizzare lo stile
READONLY.
add(new CheckboxField("First Check Box", true, this.READONLY));
6. Per sovrascrivere la funzionalità predefinita che richiede all'utente di salvare le modifiche prima della chiusura
dell'applicazione, nell'estensione della classe MainScreen, sovrascrivere il metodo
MainScreen.onSavePrompt(). Nel seguente esempio di codice, viene restituito il valore true. Ciò significa
che l'applicazione non invia una richiesta all'utente prima di chiudersi.
public boolean onSavePrompt()
{
return true;
}

Esempio di codice: creazione di una casella di controllo


import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
public class MyUi extends UiApplication
{
public static void main(String[] args)
{
MyUi theApp = new MyUi();
theApp.enterEventDispatcher();
}
public MyUi()
{
pushScreen(new MyUiScreen());
}
}
class MyUiScreen extends MainScreen
{
public MyUiScreen()
{
setTitle("UI Component Sample");
add(new CheckboxField("First Check Box", true));
add(new CheckboxField("Second Check Box", false));
}
public boolean onSavePrompt()
{
return true;
}
}

Creazione di un file bitmap


1. Importare la classe net.rim.device.api.ui.component.BitmapField.
2. Creare un'istanza di BitmapField.

56
Guida allo sviluppo Creazione di un campo personalizzato

BitmapField myBitmapField = new BitmapField();

Creazione di un campo personalizzato


È possibile aggiungere a un campo personalizzato solamente voci di menu di scelta rapida personalizzate e layout
personalizzati.

1. Importare le seguenti classi:


• net.rim.device.api.ui.Field
• java.lang.String
• net.rim.device.api.ui.Font
• java.lang.Math
• net.rim.device.api.ui.Graphics
2. Importare l'interfaccia net.rim.device.api.ui.DrawStyle.
3. Estendere la classe Field, o una delle sue sottoclassi, implementando l'interfaccia DrawStyle per specificare
le caratteristiche del campo personalizzato e attivare gli stili di disegno.
public class CustomButtonField extends Field implements DrawStyle {
public static final int RECTANGLE = 1;
public static final int TRIANGLE = 2;
public static final int OCTAGON = 3;
private String _label;
private int _shape;
private Font _font;
private int _labelHeight;
private int _labelWidth;
}
4. Implementare dei costruttori per definire l'etichetta, la forma e lo stile del pulsante personalizzato.
public CustomButtonField(String label) {
this(label, RECTANGLE, 0);
}
public CustomButtonField(String label, int shape) {
this(label, shape, 0);
}
public CustomButtonField(String label, long style) {
this(label, RECTANGLE, style);
}
public CustomButtonField(String label, int shape, long style) {
super(style);
_label = label;
_shape = shape;
_font = getFont();
_labelHeight = _font.getHeight();
_labelWidth = _font.getAdvance(_label);
}

57
Guida allo sviluppo Creazione di un campo personalizzato

5. Implementare layout() per specificare la disposizione dei dati del campo. Eseguire i calcoli più complessi in
layout() anziché in paint(). Il gestore del campo richiama layout() per stabilire come disporre i contenuti
del campo all'interno dello spazio disponibile. Richiamare Math.min() per restituire il valore più piccolo tra i
valori di larghezza e altezza specificati ed inoltre i valori preferiti per la larghezza e l'altezza del campo. Richiamare
Field.setExtent(int,int) per impostare le dimensioni richieste per il campo.
protected void layout(int width, int height) {
_font = getFont();
_labelHeight = _font.getHeight();
_labelWidth = _font.getAdvance(_label);
width = Math.min( width, getPreferredWidth() );
height = Math.min( height, getPreferredHeight() );
setExtent( width, height );
}
6. Implementare getPreferredWidth() utilizzando le dimensioni relative dell'etichetta del campo per
assicurarsi che l'etichetta non superi le dimensioni del componente. Utilizzare un blocco switch per stabilire la
larghezza preferita sulla base della forma del campo personalizzato. Per ogni tipo di forma utilizzare una
istruzione if per confrontare le dimensioni e stabilire la larghezza preferita del campo personalizzato.
public int getPreferredWidth() {
switch(_shape) {
case TRIANGLE:
if (_labelWidth < _labelHeight) {
return _labelHeight << 2;
} else {
return _labelWidth << 1;
}
case OCTAGON:
if (_labelWidth < _labelHeight) {
return _labelHeight + 4;
} else {
return _labelWidth + 8;
}
case RECTANGLE: default:
return _labelWidth + 8;
}
}
7. Implementare getPreferredHeight() utilizzando le dimensioni relative dell'etichetta del campo per stabilire
l'altezza preferita. Utilizzare un blocco switch per stabilire l'altezza preferita sulla base della forma del campo
personalizzato. Per ogni tipo di forma utilizzare una istruzione if per confrontare le dimensioni e stabilire l'altezza
preferita del campo personalizzato.
public int getPreferredHeight() {
switch(_shape) {
case TRIANGLE:
if (_labelWidth < _labelHeight) {
return _labelHeight << 1;
} else {
return _labelWidth;
}
case RECTANGLE:
return _labelHeight + 4;

58
Guida allo sviluppo Creazione di un campo personalizzato

case OCTAGON:
return getPreferredWidth();
}
return 0;
}
8. Implementare paint(). Il gestore di un campo richiama paint() per ridisegnare il campo quando un'area del
campo viene contrassegnata come non valida. Utilizzare un blocco switch per ridisegnare un campo
personalizzato sulla base della forma del campo personalizzato. Per un campo di forma triangolare od ottagonale,
utilizzare la larghezza del campo per calcolare la posizione orizzontale e verticale del punto iniziale e del punto
finale delle righe. Richiamare graphics.drawLine() e utilizzare il punto iniziale e il punto finale per tracciare
le righe che definiscono il campo personalizzato. Per un campo di forma rettangolare, richiamare
graphics.drawRect() e utilizzare la larghezza e l'altezza del campo per disegnare il campo personalizzato.
Richiamare graphics.drawText() e utilizzare la larghezza del campo per disegnare una stringa di testo in
un'area del campo.
protected void paint(Graphics graphics) {
int textX, textY, textWidth;
int w = getWidth();
switch(_shape) {
case TRIANGLE:
int h = (w>>1);
int m = (w>>1)-1;
graphics.drawLine(0, h-1, m, 0);
graphics.drawLine(m, 0, w-1, h-1);
graphics.drawLine(0, h-1, w-1, h-1);
textWidth = Math.min(_labelWidth,h);
textX = (w - textWidth) >> 1;
textY = h >> 1;
break;
case OCTAGON:
int x = 5*w/17;
int x2 = w-x-1;
int x3 = w-1;
graphics.drawLine(0, x, 0, x2);
graphics.drawLine(x3, x, x3, x2);
graphics.drawLine(x, 0, x2, 0);
graphics.drawLine(x, x3, x2, x3);
graphics.drawLine(0, x, x, 0);
graphics.drawLine(0, x2, x, x3);
graphics.drawLine(x2, 0, x3, x);
graphics.drawLine(x2, x3, x3, x2);
textWidth = Math.min(_labelWidth, w - 6);
textX = (w-textWidth) >> 1;
textY = (w-_labelHeight) >> 1;
break;
case RECTANGLE: default:
graphics.drawRect(0, 0, w, getHeight());
textX = 4;
textY = 2;
textWidth = w - 6;
break;
}

59
Guida allo sviluppo Creazione di un campo di visualizzazione del contenuto Web

graphics.drawText(_label, textX, textY, (int)( getStyle() & DrawStyle.ELLIPSIS


| DrawStyle.HALIGN_MASK ), textWidth );
}
9. Implementare i metodi Field set() e get(). Implementare i metodi Field.getLabel(),
Field.getShape(), Field.setLabel(String label) e Field.setShape(int shape) per restituire
le variabili di istanza del campo personalizzato.
public String getLabel() {
return _label;
}
public int getShape() {
return _shape;
}
public void setLabel(String label) {
_label = label;
_labelWidth = _font.getAdvance(_label);
updateLayout();
}
public void setShape(int shape) {
_shape = shape;
}

Creazione di un campo di visualizzazione del contenuto


Web
Visualizzazione del contenuto HTML in un campo del browser
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.browser.field2.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe BrowserFieldDemoScreen, come descritto al passaggio 3, rappresenta la schermata
personalizzata.
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{

60
Guida allo sviluppo Creazione di un campo di visualizzazione del contenuto Web

pushScreen(new BrowserFieldDemoScreen());
}
}
3. Creare la schermata personalizzata estendendo la classe MainScreen.
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
}
}
4. Nel costruttore della schermata creare un'istanza della classe BrowserField.
BrowserField myBrowserField = new BrowserField();
5. Nel costruttore della schermata richiamare add() per aggiungere l'oggetto BrowserField alla schermata.
add(myBrowserField);
6. Nel costruttore di schermata richiamare BrowserField.displayContent() per specificare e visualizzare il
contenuto HTML.
myBrowserField.displayContent("<html><body><h1>Hell
o World!</h1></body></html>", "http://localhost");

Esempio di codice: visualizzazione del contenuto HTML in un campo di browser


import net.rim.device.api.browser.field2.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
BrowserField myBrowserField = new BrowserField();
add(myBrowserField);
myBrowserField.displayContent("<html><body><h1>Hello
World!</h1></body></html>", "http://localhost");
}
}

61
Guida allo sviluppo Creazione di un campo di visualizzazione del contenuto Web

Visualizzazione del contenuto HTML da una pagina web in un campo del


browser
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.browser.field2.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe BrowserFieldDemoScreen, come descritto al passaggio 3, rappresenta la schermata
personalizzata.
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
3. Creare il framework della schermata personalizzata estendendo la classe MainScreen.
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
}
}
4. Nel costruttore della schermata creare un'istanza della classe BrowserField.
BrowserField myBrowserField = new BrowserField();
5. Nel costruttore della schermata richiamare add() per aggiungere l'oggetto BrowserField alla schermata.
add(myBrowserField);
6. Nel costruttore della schermata richiamare BrowserField.requestContent() per specificare la posizione
del contenuto HTML e visualizzarlo.
myBrowserField.requestContent("http://www.blackberry.com");

62
Guida allo sviluppo Creazione di un campo di visualizzazione del contenuto Web

Esempio di codice: visualizzazione di contenuto HTML da una pagina Web in un campo


Browser
import net.rim.device.api.browser.field2.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
BrowserField myBrowserField = new BrowserField();
add(myBrowserField);
myBrowserField.requestContent("http://www.blackberry.com");
}
}

Visualizzazione del contenuto HTML da una risorsa nell'applicazione


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.browser.field2.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe BrowserFieldDemoScreen, come descritto al passaggio 3, rappresenta la schermata
personalizzata.
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{

63
Guida allo sviluppo Creazione di un campo di visualizzazione del contenuto Web

pushScreen(new BrowserFieldDemoScreen());
}
}
3. Creare la schermata personalizzata estendendo la classe MainScreen.
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
}
}
4. Nel costruttore della schermata creare un'istanza della classe BrowserField.
BrowserField myBrowserField = new BrowserField();
5. Nel costruttore della schermata richiamare add() per aggiungere l'oggetto BrowserField alla schermata.
add(myBrowserField);
6. Nel costruttore della schermata richiamare BrowserField.requestContent() per specificare la posizione
della risorsa nell'applicazione e visualizzare il contenuto HTML.
myBrowserField.requestContent("local:///test.html");
Nota: la classe BrowserField non accede alle risorse utilizzando una struttura delle cartelle. La classe
BrowserField visualizza la prima risorsa trovata che corrisponde al nome del file specificato.

Esempio di codice: visualizzazione di contenuto HTML da una risorsa dell'applicazione


in uso
import net.rim.device.api.browser.field2.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
BrowserField myBrowserField = new BrowserField();
add(myBrowserField);

64
Guida allo sviluppo Creazione di un campo di visualizzazione del contenuto Web

myBrowserField.requestContent("local:///test.html");
}
}

Configurazione di un campo del browser


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.browser.field2.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe BrowserFieldDemoScreen, come descritto al passaggio 3, rappresenta la schermata
personalizzata.
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
3. Creare il framework della schermata personalizzata estendendo la classe MainScreen.
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
}
}
4. Nel costruttore della schermata creare un'istanza della classe BrowserFieldConfig.
BrowserFieldConfig myBrowserFieldConfig = new BrowserFieldConfig();
5. Nel costruttore della schermata richiamare BrowserFieldConfig.setProperty() per specificare una
proprietà di BrowserFieldBrowserField. Il primo parametro di setProperty() specifica la proprietà, mentre
il secondo parametro specifica il valore della proprietà. Ad esempio, il seguente esempio di codice specifica la
proprietà NAVIGATION_MODE di un oggetto BrowserField:
myBrowserFieldConfig.setProperty(BrowserFieldConfig.NAVIGATION_MODE,
BrowserFieldConfig.NAVIGATION_MODE_POINTER);
6. Nel costruttore della schermata creare un'istanza della classe BrowserField che utilizza la configurazione che
è stata definita.

65
Guida allo sviluppo Creazione di un campo di visualizzazione del contenuto Web

BrowserField browserField = new BrowserField(myBrowserFieldConfig);

Esempio di codice: configurazione di un campo Browser


import net.rim.device.api.browser.field2.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
BrowserFieldConfig myBrowserFieldConfig = new BrowserFieldConfig();
myBrowserFieldConfig.setProperty(BrowserFieldConfig
.NAVIGATION_MODE,BrowserFieldConfig.NAVIGATION_MODE_POINTER);
BrowserField browserField = new BrowserField(myBrowserFieldConfig);
}
}

Invio dei dati dei moduli a un indirizzo Web in un campo del browser
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.browser.field2.*;
import net.rim.device.api.io.http.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import java.lang.*;
import java.util.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe BrowserFieldDemoScreen, come descritto al passaggio 3, rappresenta la schermata
personalizzata.
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();

66
Guida allo sviluppo Creazione di un campo di visualizzazione del contenuto Web

app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
3. Creare la schermata personalizzata estendendo la classe MainScreen.
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
}
}
4. Nel costruttore della schermata creare un'istanza della classe BrowserField.
BrowserField browserField = new BrowserField();
5. Nel costruttore della schermata richiamare add() per aggiungere l'oggetto BrowserField alla schermata.
add(browserField);
6. Nel costruttore della schermata, creare un oggetto String che contiene l'indirizzo Web di base della pagina
Web alla quale inviare i dati del modulo.
String baseURL = "http://www.blackberry.com";
7. Nel costruttore della schermata, creare un oggetto String che specifica i dati del modulo che l'applicazione
invia alla pagina Web.
String postData = "fieldname1=value1&fieldname2=value2";
8. Nel costruttore della schermata, creare un oggetto Hashtable per memorizzare le informazioni
dell'intestazione per i dati del modulo.
Hashtable header = new Hashtable();
9. Nel costruttore della schermata, creare un oggetto Hashtable.put() per specificare le informazioni
dell'intestazione per i dati del modulo.
header.put("Content-Length", "" + postData.length());
header.put("Content-Type", "application/x-www-form-urlencoded");
10. Nel costruttore del schermata, richiamare BrowserField.requestContent() per inviare i dati del modulo
alla pagina Web e visualizzarla.
browserField.requestContent(baseURL, postData.getBytes(), new
HttpHeaders(header));

67
Guida allo sviluppo Finestre di dialogo

Esempio di codice: invio dei dati di un modulo a un indirizzo Web in un campo Browser
import net.rim.device.api.browser.field2.*;
import net.rim.device.api.io.http.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import java.lang.*;
import java.util.*;
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
BrowserField browserField = new BrowserField();}
add(browserField);
String baseURL = "http://www.blackberry.com";
String postData = "fieldname1=value1&fieldname2=value2";
Hashtable header = new Hashtable();
header.put("Content-Length", "" + postData.length());
header.put("Content-Type", "application/x-www-form-urlencoded");
browserField.requestContent(baseURL, postData.getBytes(), new
HttpHeaders(header));
}
}

Finestre di dialogo
Utilizzare le finestre di dialogo per eseguire le seguenti operazioni:
• Richiedere agli utenti informazioni necessarie per completare un'attività iniziata dall'utente.
• Fornire agli utenti informazioni urgenti, informarli sullo stato di operazioni importanti.
• Avvisare gli utenti di condizioni o situazioni impreviste o potenzialmente dannose.
Le finestre di dialogo sono finestre modali; interrompono il normale funzionamento del dispositivo BlackBerry® e
vengono posizionate all'inizio dello stack. Una finestra di dialogo include un messaggio, pulsanti che consentono agli
utenti di eseguire un'azione e un indicatore che indica il tipo di finestra di dialogo. La dimensione della finestra di
dialogo dipende dalla dimensione dello schermo del dispositivo BlackBerry. Il tema selezionato sul dispositivo
BlackBerry determina lo stile visivo della finestra di dialogo.

68
Guida allo sviluppo Finestre di dialogo

Procedura consigliata: implementazione delle finestre di dialogo


• Utilizzare i pulsanti per confermare o annullare le azioni nelle finestre di dialogo. Evitare di utilizzare collegamenti
o altri componenti.
• Utilizzare un indicatore standard che sia appropriato al tipo di finestra di dialogo. Evitare di utilizzare più indicatori
in una finestra di dialogo.
• Evitare che gli utenti debbano scorrere una finestra di dialogo. Includere frecce di scorrimento se il messaggio
o i pulsanti della finestra di dialogo non vengono visualizzati interamente nella finestra di dialogo. Se si utilizzano
dei componenti standard, le frecce di scorrimento vengono visualizzate automaticamente, se necessario.
• Consentire sempre agli utenti di utilizzare il tasto ESC per chiudere una finestra di dialogo. Evitare di
implementare un'altra azione quando gli utenti premono il tasto ESC per chiudere una finestra di dialogo. Se,
ad esempio, una finestra di dialogo consente agli utenti di modificare un'impostazione, non implementare alcuna
modifica quando gli utenti premono il tasto ESC. Se necessario, visualizzare la finestra di dialogo in un momento
successivo.
• Se gli utenti premono il tasto Fine/Accensione quando una finestra di dialogo viene visualizzata nella schermata
di un'applicazione, visualizzare la schermata iniziale o l'elenco delle applicazioni. Se gli utenti ritornano
all'applicazione, visualizzare di nuovo la finestra di dialogo.
Linee guida per il layout
• Collocare la finestra di dialogo al centro della schermata. Se si utilizzano componenti standard, il dispositivo
BlackBerry® centrerà automaticamente la finestra di dialogo.
• Creare finestre di dialogo con dimensioni fino al 90%, e non superiori, della larghezza e dell'altezza della
schermata. Se si utilizzano componenti standard, il dispositivo BlackBerry calcola automaticamente le dimensioni
appropriate delle finestre di dialogo.
• Collocare l'indicatore della finestra di dialogo al centro in senso verticale rispetto al messaggio della finestra di
dialogo.
• Visualizzare i messaggi a destra dell'indicatore e al di sopra dei pulsanti per la maggior parte delle lingue.
• Collocare prima i pulsanti che richiedono una conferma delle azioni. Ad esempio, collocare "Salva" prima di
"Ignora" o "Annulla".
• Collocare i pulsanti al centro in senso orizzontale nelle finestre di dialogo.

69
Guida allo sviluppo Finestre di dialogo

• Collocare i pulsanti in senso verticale nella finestra di dialogo. Il layout verticale consente ai pulsanti di espandersi
per ospitare le etichette localizzate.
• Se si include una casella di controllo, allineare la casella di controllo al messaggio della finestra di dialogo.
Posizionare la casella di controllo sopra i pulsanti. Per impostazione predefinita, la casella di controllo deve
essere sempre selezionata, a meno che la finestra di dialogo non visualizzi un messaggio con informazioni critiche
per gli utenti.

Linee guida per i messaggi


• Essere precisi. Se possibile, utilizzare una frase breve per esporre chiaramente il motivo della visualizzazione
della finestra di dialogo e le azioni che consentono di chiuderla.
• Laddove possibile utilizzare delle frasi complete per i messaggi.
• Utilizzare un vocabolario che risulti comprensibile agli utenti. Utilizzare ad esempio "Non è stato possibile salvare
il file perché la scheda di memoria è piena" anziché "Errore durante la scrittura del file su disco".
• Utilizzare delle espressioni positive, laddove possibile, ed evitare di biasimare l'utente. Non scrivere mai
messaggi che diano la colpa agli utenti di errori o condizioni impreviste. Al contrario, concentrare la propria
attenzione sulle azioni che gli utenti possono svolgere per risolvere il problema.
• Rivolgersi agli utenti utilizzando la seconda persona (tu, tuo).
• Iniziare le frasi con la lettera maiuscola.
• Evitare di utilizzare dei punti esclamativi (!) nei messaggi.
• Evitare di utilizzare i puntini di sospensione (...) nei messaggi, a meno che non si intenda indicare un'azione in
corso (ad esempio "Attendere...").

Linee guida per i pulsanti


• Utilizzare come pulsante predefinito quello che verrà selezionato con maggiore probabilità dagli utenti. Evitare
di utilizzare come pulsante predefinito un pulsante associato a un'azione negativa. Le eccezioni a questa regola
sono rappresentate dai casi in cui gli utenti avviano un'azione negativa secondaria (come eliminare una singola
voce) e l'azione più comune da parte degli utenti consiste nel proseguire tale operazione.
• Evitare di collocare più di tre pulsanti in una finestra di dialogo. Se si rende necessario utilizzare più di tre pulsanti,
utilizzare una schermata di applicazione con pulsanti di opzione.

70
Guida allo sviluppo Elenchi a discesa

• Sui dispositivi BlackBerry con tastiera fisica, associare tasti di scelta rapida ai pulsanti. In genere, il tasto di scelta
rapida corrisponde alla prima lettera dell'etichetta del pulsante.
• Utilizzare etichette chiare e concise.
• Laddove possibile, utilizzare etichette contenenti un'unica parola. Le dimensioni di un pulsante variano a seconda
della lunghezza dell'etichetta. Se un'etichetta è troppo lunga, un'ellissi (...) indica che il testo è troncato.
• Evitare di utilizzare le etichette "Sì" e "No". Utilizzare dei verbi che descrivono l'azione associata (ad esempio
"Annulla", "Elimina", "Ignora" o "Salva"). Questo approccio consente agli utenti di capire rapidamente quale
operazione viene eseguita quando fanno clic sul pulsante. Se necessario, includere un testo descrittivo più lungo
in un altro punto della schermata (ad esempio in un messaggio dell'applicazione).
• Evitare di utilizzare simboli o oggetti grafici nelle etichette.
• Evitare di utilizzare la punteggiatura nelle etichette. Utilizzare i puntini di sospensione nell'etichetta di un
pulsante per indicare che è necessario fornire ulteriori informazioni prima di eseguire l'azione associata.

Creazione di una finestra di dialogo


Utilizzare le finestre di dialogo di avviso per notificare agli utenti un'azione critica, come la disattivazione del
dispositivo BlackBerry®, o un errore, come la digitazione di informazioni non valide. In una finestra di dialogo di avviso
viene visualizzato un indicatore a forma di punto esclamativo (!). Per chiudere una finestra di dialogo di avviso, gli
utenti possono fare clic su OK o premere il tasto ESC. Per ulteriori informazioni sugli altri tipi di finestre di dialogo,
consultare la documentazione di riferimento sulle API per BlackBerry® Java® Development Environment.

1. Importare la classe net.rim.device.api.ui.component.Dialog.


2. Creare una finestra di dialogo di avviso specificando il testo di avviso che si desidera visualizzare.
Dialog.alert("Specify the alert text that you want to display.")

Elenchi a discesa
Utilizzare gli elenchi a discesa per fornire una serie di valori di esclusione reciproci.
Con un elenco a discesa gli utenti possono eseguire la seguente operazione:

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Fare clic su un valore in un Premere il tasto Invio o fare clic sul • Toccare la voce.
elenco a discesa. trackpad. • Premere il tasto Invio.
• Fare clic sul trackpad.

71
Guida allo sviluppo Elenchi a discesa

Procedura consigliata: implementazione degli elenchi a discesa


• Quando esistono dei problemi di spazio, utilizzare un elenco a discesa per visualizzare due o più scelte. Se non
esistono problemi di spazio, utilizzare pulsanti di opzione per consentire agli utenti di visualizzare le opzioni
disponibili sullo schermo.
• Utilizzare la classe ObjectChoiceField o NumericChoiceField per creare elenchi a discesa.
• Utilizzare come valore predefinito quello che verrà scelto con maggiore probabilità dagli utenti.
• Utilizzare l'opzione evidenziata come elemento attivo predefinito quando gli utenti scorrono l'elenco.
• Se gli utenti non devono necessariamente selezionare un valore, includere il valore "Nessuno" nell'elenco a
discesa. Collocare sempre il valore "Nessuno" all'inizio dell'elenco.
• Raggruppare e ordinare i valori in senso logico (raggruppare ad esempio i valori correlati o visualizzare per primi
i valori più comuni). Evitare di ordinare i valori in senso alfabetico, poiché tale ordine dipende dalla lingua.
Linee guida per le etichette
• Utilizzare etichette chiare e concise per gli elenchi a discesa e per i valori presenti in elenchi a discesa. Verificare
che l'etichetta descriva chiaramente quale azione viene avviata dagli utenti quando fanno clic sul valore. La
larghezza dell'elenco a discesa varia a seconda della lunghezza delle etichette dei valori. Se un'etichetta è troppo
lunga, viene visualizzata un'ellissi (...) per indicare che il testo è troncato.
• Evitare di utilizzare le etichette "Sì" e "No" come valori dell'elenco a discesa. Riformulare l'opzione e utilizzare
invece una casella di controllo.
• Collocare l'etichetta sul lato sinistro di un elenco a discesa.
• Iniziare le etichette e i valori dell'elenco a discesa con la maiuscola (a meno che i valori non vengano letti in
modo più simile a una frase).
• Aggiungere alle etichette degli elenchi a discesa il carattere due punti (:).

Creazione di un elenco a discesa


1. Importare le classi e le interfacce richieste.

72
Guida allo sviluppo Elenchi a discesa

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe MyUiScreen, descritta nel passaggio 3, rappresenta la schermata personalizzata.
public class MyUi extends UiApplication
{
public static void main(String[] args)
{
MyUi theApp = new MyUi();
theApp.enterEventDispatcher();
}
public MyUi()
{
pushScreen(new MyUiScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore della
schermata richiamare setTitle() per specificare il titolo della schermata.
class MyUiScreen extends MainScreen
{
public MyUiScreen()
{
setTitle("UI Component Sample");
}
}
4. Nel costruttore della schermata creare un elenco a discesa che visualizzi un elenco di parole o di frasi utilizzando
la classe ObjectChoiceField. Creare una matrice String per memorizzare le voci che si desidera visualizzare
nell'elenco a discesa. Creare un oggetto int per memorizzare la voce predefinita da visualizzare nell'elenco a
discesa. Nel costruttore ObjectChoiceField specificare l'etichetta dell'elenco a discesa, la matrice di voci da
visualizzare e la voce predefinita. Nel seguente esempio di codice, mercoledì è visualizzato per impostazione
predefinita. Richiamare add() per aggiungere l'elenco a discesa alla schermata.
String choices[] =
{"Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"};
int iSetTo = 2;
add(new ObjectChoiceField("First Drop-down List",choices,iSetTo));
5. Nel costruttore della schermata creare un secondo elenco a discesa che visualizzi un elenco di numeri utilizzando
la classe NumericChoiceField. Nel costruttore NumericChoiceField specificare l'etichetta dell'elenco a
discesa, il primo e l'ultimo numero da visualizzare nell'elenco a discesa, l'incremento da utilizzare per l'elenco
di numeri e il numero predefinito. Nel seguente esempio di codice, i parametri numerici sono memorizzati in
oggetti int. Nell'elenco a discesa sono inclusi i numeri da 1 a 31. Per impostazione predefinita viene visualizzato
il numero 10. Richiamare add() per aggiungere il secondo elenco a discesa alla schermata.

73
Guida allo sviluppo Elenchi a discesa

int iStartAt = 1;
int iEndAt = 31;
int iIncrement = 1;
iSetTo = 10;
add(new NumericChoiceField("Numeric Drop-Down
List",iStartAt,iEndAt,iIncrement,iSetTo));
6. Per sovrascrivere la funzionalità predefinita che richiede all'utente di salvare le modifiche prima della chiusura
dell'applicazione, nell'estensione della classe MainScreen, sovrascrivere il metodo
MainScreen.onSavePrompt(). Nel seguente esempio di codice, viene restituito il valore true. Ciò significa
che l'applicazione non invia una richiesta all'utente prima di chiudersi.
public boolean onSavePrompt()
{
return true;
}

Esempio di codice: creazione di un elenco a discesa


import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
public class MyUi extends UiApplication
{
public static void main(String[] args)
{
MyUi theApp = new MyUi();
theApp.enterEventDispatcher();
}
public MyUi()
{
pushScreen(new MyUiScreen());
}
}
class MyUiScreen extends MainScreen
{
public MyUiScreen()
{
setTitle("UI Component Sample");
String choices[] =
{"Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"};
int iSetTo = 2;
add(new ObjectChoiceField("First Drop-down List",choices,iSetTo));
int iStartAt = 1;
int iEndAt = 31;
int iIncrement = 1;
iSetTo = 10;
add(new NumericChoiceField("Numeric Drop-Down
List",iStartAt,iEndAt,iIncrement,iSetTo));
}
public boolean onSavePrompt()
{

74
Guida allo sviluppo Etichette

return true;
}
}

Etichette
Utilizzare un'etichetta per visualizzare un testo che identifica un comando.

Procedura consigliata: implementazione delle etichette


• Utilizzare la classe LabelField per creare le etichette.
• Utilizzare etichette chiare e concise.
• Raggruppare e ordinare le etichette in senso logico (raggruppare ad esempio le voci correlate o visualizzare per
prime le voci più comuni). Evitare di ordinare i valori in senso alfabetico, poiché tale ordine dipende dalla lingua.
• Aggiungere all'etichetta il carattere due punti (:).

Creazione di un'etichetta di testo


1. Importare la classe net.rim.device.api.ui.component.LabelField.
2. Creare un'istanza di una classe LabelField per aggiungere un'etichetta di testo a una schermata.
LabelField title = new LabelField("UI Component Sample", LabelField.ELLIPSIS);

Elenchi e tabelle
Utilizzare elenchi e tabelle per visualizzare voci che gli utenti possono evidenziare e aprire. Se l'elenco è lungo, le
voci vengono recuperate e visualizzate in batch. Quando gli utenti raggiungono l'ultima voce nell'elenco, il batch
successivo di voci viene visualizzato alla fine dell'elenco.
Utilizzare un elenco semplice per visualizzare facilmente il testo nelle righe.

75
Guida allo sviluppo Elenchi e tabelle

Utilizzare un elenco complesso per visualizzare facilmente righe di testo e icone. Attualmente, gli elenchi complessi
visualizzano solo informazioni e non sono interattivi.

Se si desidera presentare voci in colonne e righe, utilizzare una tabella.

76
Guida allo sviluppo Elenchi e tabelle

È possibile raggruppare le voci sotto le intestazioni per consentire agli utenti di navigare in un elenco lungo. Ad
esempio, è possibile creare intestazioni che vengono compresse, rendendo più facile l'individuazione delle voci
nell'elenco.

È anche possibile raggruppare le voci sotto le intestazioni da visualizzare sempre all'inizio dell'elenco. Ad esempio,
è possibile aggiungere una data come intestazione e raggruppare i messaggi ricevuti in tale data sotto l'intestazione.
Gli utenti possono evidenziare un'intestazione per eseguire un'azione sul gruppo di voci o possono utilizzare i tasti
di scelta rapida per spostarsi nell'elenco.

Gli utenti possono eseguire le seguenti azioni negli elenchi e nelle tabelle:

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Scorrere le voci nell'elenco. Far scorrere un dito in senso verticale sul • Trascinare un dito in senso verticale
trackpad. sulla schermata.
• Spostarsi su o giù sulla schermata.
• Far scorrere un dito in senso
verticale sul trackpad.

77
Guida allo sviluppo Elenchi e tabelle

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Evidenziare una voce Far scorrere un dito in senso verticale sul • Toccare leggermente la voce.
presente nell'elenco. trackpad. • Far scorrere un dito in senso
verticale sul trackpad.
Aprire una voce presente • Fare clic sul trackpad. • Toccare la voce.
nell'elenco. • Premere il tasto Invio. • Fare clic sul trackpad.
• Premere il tasto Invio.

Procedura consigliata: implementazione di elenchi e tabelle


• Utilizzare la classe SimpleList per creare un elenco con testo. Utilizzare la classe RichList per creare un
elenco di sola visualizzazione con testo e icone. Utilizzare la classe TableView per creare un elenco complesso
interattivo con testo e icone.
• Utilizzare la classe TableView per creare una tabella con righe e colonne. È possibile utilizzare
GridFieldManager se il numero di righe e colonne nella tabella è fisso.
• Se l'elenco è lungo e si desidera visualizzare le voci in schermate separate, includere i pulsanti Avanti e Indietro
nella parte inferiore della schermata. In alternativa, se l'elenco è molto lungo (ad esempio, migliaia di voci),
aggiungere i numeri di schermata.
• Se si prevede che gli utenti si spostino tra le voci nell'elenco (ad esempio, in un elenco messaggi o un feed),
assegnare tasti di scelta rapida per lo spostamento alla voce successiva o precedente nell'elenco. Dove possibile,
in inglese, consentire agli utenti di premere "N" per spostarsi alla voce successiva nell'elenco e "P" per spostarsi
alla voce precedente nell'elenco.

Creazione di una casella di riepilogo


Utilizzare una casella di riepilogo per visualizzare un elenco in cui gli utenti possono selezionare uno o più valori.

1. Importare le seguenti classi:


import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import java.util.Vector;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere eventi. Nel
costruttore, richiamare pushScreen per visualizzare la schermata personalizzata per l'applicazione. La classe
CreateMenuScreen rappresenta la schermata personalizzata descritta nel passaggio 3.
public class ListFields extends UiApplication
{
public static void main(String[] args)
{
ListFields theApp = new ListFields();
theApp.enterEventDispatcher();

78
Guida allo sviluppo Elenchi e tabelle

}
public ListFields()
{
pushScreen(new ListFieldScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore,
richiamare setTitle() per visualizzare il titolo della schermata. Richiamare add() per visualizzare un campo
di testo sulla schermata. Richiamare addMenuItem() per aggiungere una voce di menu al menu che crea
MainScreen.
class ListFieldScreen extends MainScreen
{
private ListField _listField;
private Vector _listElements;
public ListFieldScreen()
{
setTitle("List Field Sample");
}
}
4. Nel costruttore della schermata creare la casella di riepilogo. Creare una matrice per le voci che si desidera
aggiungere alla casella di riepilogo utilizzando la classe Vector. Creare la casella di riepilogo utilizzando la classe
ListField(). Richiamare add() per aggiungere la casella di riepilogo alla schermata. Richiamare
initializeList(), descritto nel passaggio 4, per aggiungere la casella di riepilogo.
_listElements = new Vector();
_listField = new ListField();
ListCallback _callback = new ListCallback();
_listField.setCallback(_callback);
add(_listField);
initializeList();
5. Creare un metodo per specificare le voci che si desidera visualizzare nella casella di riepilogo utilizzando l'oggetto
String. Richiamare addElement() per aggiungere le voci all'elenco. Richiamare setSize() per specificare
il numero di voci della casella di riepilogo.
private void initializeList()
{
String itemOne = "List item one";
String itemTwo = "List item two";
_listElements.addElement(itemOne);
_listElements.addElement(itemTwo);
reloadList();
}
private void reloadList()
{
_listField.setSize(_listElements.size());
}

79
Guida allo sviluppo Pulsanti di opzione

6. Creare una classe che implementi l'interfaccia ListFieldCallback. Implementare drawListRow() per
aggiungere alla schermata le voci della casella di riepilogo. Implementare get() per restituire la voce della
casella di riepilogo all'indice specificato. Implementare indexOfList() per restituire la prima occorrenza di
una determinata stringa. Implementare getPreferredWidth() per recuperare la larghezza della casella di
riepilogo.
private class ListCallback implements ListFieldCallback
{
public void drawListRow(ListField list, Graphics g, int index, int y, int w)
{
String text = (String)_listElements.elementAt(index);
g.drawText(text, 0, y, 0, w);
}
public Object get(ListField list, int index)
{
return _listElements.elementAt(index);
}
public int indexOfList(ListField list, String prefix, int string)
{
return _listElements.indexOf(prefix, string);
}
public int getPreferredWidth(ListField list)
{
return Display.getWidth();
}
}

Pulsanti di opzione
Utilizzare i pulsanti di opzione per indicare una serie di scelte correlate ma che si escludono a vicenda.
Tramite i pulsanti di opzione gli utenti possono eseguire le seguenti operazioni:

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Selezionare un pulsante di Premere il tasto Space o fare clic sul • Toccare la voce.
opzione. trackpad. • Premere il tasto Space.
• Fare clic sul trackpad.

80
Guida allo sviluppo Pulsanti di opzione

Procedura consigliata: implementazione dei pulsanti di opzione


• Quando non esistono problemi di spazio, utilizzare i pulsanti di opzione per visualizzare due o più scelte. Se al
contrario esistono dei problemi di spazio, utilizzare un elenco a discesa.
• Utilizzare la classe RadioButtonField per creare pulsanti di opzione.
• Verificare che il contenuto dei pulsanti di opzione rimanga statico. Il contenuto dei pulsanti di opzione non deve
variare in base al contesto.
• Non avviare un'azione quando gli utenti selezionano un pulsante di opzione. Non aprire, ad esempio, una nuova
schermata.
• Allineare i pulsanti di opzione in senso verticale.
• Raggruppare e ordinare i valori in senso logico (raggruppare ad esempio i pulsanti di opzione correlati o
visualizzare per primi i valori più comuni). Evitare di ordinare i pulsanti di opzione in senso alfabetico, poiché
tale ordine dipende dalla lingua.
Linee guida per le etichette
• Utilizzare etichette chiare e concise. Verificare che l'etichetta descriva chiaramente quale azione viene avviata
dagli utenti quando selezionano il pulsante di opzione. Se le etichette sono troppo lunghe, vanno a capo
automaticamente.
• Collocare le etichette sul lato destro dei pulsanti di opzione.
• Iniziare le frasi con la lettera maiuscola.
• Non utilizzare alcuna punteggiatura finale.

Creazione di un pulsante di opzione


È possibile creare un gruppo di pulsanti di opzione utilizzando la classe RadioButtonGroup. Un utente può
selezionare un'unica opzione da un gruppo di pulsanti di opzione.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;

81
Guida allo sviluppo Pulsanti di opzione

2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe MyUiScreen, descritta nel passaggio 3, rappresenta la schermata personalizzata.
public class MyUi extends UiApplication
{
public static void main(String[] args)
{
MyUi theApp = new MyUi();
theApp.enterEventDispatcher();
}
public MyUi()
{
pushScreen(new MyUiScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore della
schermata, richiamare setTitle() per specificare il titolo della schermata.
class MyUiScreen extends MainScreen
{
public MyUiScreen()
{
setTitle("UI Component Sample");
}
}
4. Nel costruttore della schermata creare un gruppo di pulsanti di opzione utilizzando la classe
RadioButtonGroup. Creare i pulsanti di opzione che si desidera aggiungere al gruppo utilizzando la classe
RadioButtonField. Nel costruttore RadioButtonField specificare l'etichetta del pulsante di opzione, il
gruppo e un valore booleano indicante la selezione predefinita (true indica, ad esempio, che l'opzione è
selezionata per impostazione predefinita). Richiamare add() per aggiungere i pulsanti di opzione alla schermata.
RadioButtonGroup rbg = new RadioButtonGroup();
add(new RadioButtonField("Option 1",rbg,true));
add(new RadioButtonField("Option 2",rbg,false));
5. Per sovrascrivere la funzionalità predefinita che richiede all'utente di salvare le modifiche prima della chiusura
dell'applicazione, nell'estensione della classe MainScreen, sovrascrivere il metodo
MainScreen.onSavePrompt(). Nel seguente esempio di codice, viene restituito il valore true. Ciò significa
che l'applicazione invia una richiesta all'utente prima di chiudersi.
public boolean onSavePrompt()
{
return true;
}

82
Guida allo sviluppo Indicatori di attività e indicatori di progresso

Esempio di codice: creazione di un pulsante di opzione


import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
public class MyUi extends UiApplication
{
public static void main(String[] args)
{
MyUi theApp = new MyUi();
theApp.enterEventDispatcher();
}
public MyUi()
{
pushScreen(new MyUiScreen());
}
}
class MyUiScreen extends MainScreen
{
public MyUiScreen()
{
setTitle("UI Component Sample");
RadioButtonGroup rbg = new RadioButtonGroup();
add(new RadioButtonField("Option 1",rbg,true));
add(new RadioButtonField("Option 2",rbg,false));
}
public boolean onSavePrompt()
{
return true;
}
}

Indicatori di attività e indicatori di progresso


Gli indicatori di attività e gli indicatori di progresso mostrano agli utenti le azioni che stanno eseguendo i dispositivi
BlackBerry®, ad esempio la ricerca di elementi o la rimozione di lingue.
Utilizzare un indicatore di attività se si desidera mostrare che il dispositivo BlackBerry® sta eseguendo un'azione e
non è possibile determinarne la durata. È possibile aggiungere un indicatore di attività a qualsiasi componente, ad
esempio una schermata, un campo di testo o una voce di elenco. È possibile, inoltre, aggiungere a un indicatore di
attività il testo desiderato per descrivere l'operazione corrispondente.

83
Guida allo sviluppo Indicatori di attività e indicatori di progresso

Indicatore di attività in un campo Indicatore di attività con testo

Utilizzare un indicatore di progresso quando è possibile stabilire la durata di un'azione. Gli indicatori di progresso
includono un'etichetta che indica la natura dell'azione e una barra orizzontale che avanza da sinistra a destra durante
lo svolgimento dell'azione. Sulla barra viene visualizzata una percentuale che indica lo stato di completamento
dell'azione.

Procedura consigliata: implementazione degli indicatori di attività e degli


indicatori di progresso
• Aggiungere sempre un indicatore di progresso quando un'azione impiega più di 2 secondi per essere completata.
• Utilizzare un indicatore di progresso quando è possibile stabilire la durata di un'azione.
• Utilizzare un indicatore di attività quando non è possibile stabilire la durata di un'attività.
• Utilizzare la classe ActivityIndicatorView per creare gli indicatori di attività. Utilizzare la classe
ProgressIndicatorView per creare gli indicatori di progresso.
• Fornire informazioni di avanzamento utili. Ad esempio, se gli utenti scaricano un'applicazione sul dispositivo,
indicare la percentuale di dati che il dispositivo BlackBerry® ha scaricato. Si raccomanda di essere il più possibile
precisi nel fornire le informazioni di avanzamento.

84
Guida allo sviluppo Indicatori di attività e indicatori di progresso

• Consentire sempre agli utenti di utilizzare il tasto Fine per nascondere un indicatore di progresso.
Linee guida per il testo
• Utilizzare un testo conciso e descrittivo (ad esempio "Caricamento dei dati in corso..." o "Creazione di un elenco
delle applicazioni in corso...").
• Se un'azione è lunga e si desidera comunicare ciò che succede in ogni fase, fornire il testo che descrive ciascuna
fase (ad esempio, "Download in corso..." o "Installazione in corso...").
• Iniziare le frasi con la lettera maiuscola.
• Aggiungere al testo dei puntini di sospensione (...).

Indicazione del progresso delle attività


È possibile utilizzare l'API Activity and Progress Indicator fornita nel pacchetto
net.rim.device.api.ui.component.progressindicator per visualizzare suggerimenti visivi su una
schermata che indicano se l'attività è stata svolta o è in fase di svolgimento. È possibile rappresentare un'attività la
cui durata è sconosciuta, nonché il progresso che può essere rappresentato sotto forma di numero (ad esempio,
come una percentuale di un'attività completata).
L'API Activity and Progress Indicator utilizza il modello di progettazione di tipo modello-visualizzazione-controller e
include due campi che sono responsabili per il rendering dell'attività o del progresso:
• La classe ActivityImageField rappresenta l'attività tramite una bitmap che contiene i frame di
un'animazione. Il frame visualizzato cambia nel tempo. In genere, questo campo è una casella di selezione, una
clessidra o un altro suggerimento visivo animato simile. Questo campo viene creato e impostato tramite la classe
ActivityIndicatorView.
• La classe ProgressBarField rappresenta il progresso di un'attività come una barra che si riempie man mano
che l'attività viene completata. Questo campo viene creato e impostato tramite la classe
ProgressIndicatorView.

L'applicazione di esempio della demo dell'indicatore di progresso è inclusa in BlackBerry® Java® SDK.
Quest'applicazione di esempio mostra come creare e gestire diversi indicatori di attività e una barra dell'indicatore
di progresso.

Indicazione dell'attività
È possibile visualizzare un campo nell'applicazione BlackBerry® che indica che un'attività è in fase di svolgimento. In
genere, il campo è una casella di selezione, una clessidra o un altro suggerimento visivo animato simile. Il campo
viene implementato tramite la classe ActivityImageField.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.system.Bitmap;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.progressindicator.*;
import net.rim.device.api.ui.container.*;

85
Guida allo sviluppo Indicatori di attività e indicatori di progresso

2. Creare un'immagine che contiene i frame di un'animazione e includerla nel progetto. L'immagine deve essere
costituita da una serie di frame dell'animazione disposti in orizzontale. La larghezza dell'immagine deve essere
uguale alla larghezza di un frame moltiplicata per il numero di frame.
Ad esempio, la seguente immagine dispone di cinque frame di dimensioni uguali.

3. Creare un file bitmap dall'immagine.


Bitmap bitmap = Bitmap.getBitmapResource("spinner.png");
4. Creare un oggetto ActivityIndicatorView. È possibile specificare uno stile per la visualizzazione nel
costruttore.
ActivityIndicatorView view = new ActivityIndicatorView(Field.USE_ALL_WIDTH);
Per specificare un gestore da utilizzare per il layout e l'evidenziazione, fornire un secondo argomento quando
si crea ActivityIndicatorView. Se non viene specificato un gestore, viene utilizzato un oggetto
VerticalFieldManager.
5. Creare un modello e un controller.
ActivityIndicatorModel model = new ActivityIndicatorModel();
ActivityIndicatorController controller = new ActivityIndicatorController();
6. Collegare la visualizzazione, il modello e il controller.
view.setController(controller);
view.setModel(model);
controller.setModel(model);
controller.setView(view);
model.setController(controller);
7. Creare il campo che esegue il rendering dell'attività dal file bitmap.
view.createActivityImageField(bitmap, 5, Field.FIELD_HCENTER);
In quest'esempio, il file bitmap consiste in cinque frame ed è centrato nel gestore della visualizzazione.
8. Aggiungere la visualizzazione alla schermata.
add(view);
9. Controllare l'indicazione di attività controllando il modello della visualizzazione, come necessario.
MenuItem _stopIndicator = new MenuItem("Stop spinner", 66000, 0)
{
public void run()
{
view.getModel().cancel();
}
};
MenuItem _resumeIndicator = new MenuItem("Resume spinner", 66010, 0)
{
public void run()
{

86
Guida allo sviluppo Indicatori di attività e indicatori di progresso

view.getModel().resume();
}
};
Questo esempio richiama il metodo del modello cancel() per arrestare l'animazione. L'esempio richiama il
metodo del modello resume() per riprendere l'animazione.

Esempio di codice
public class ActivityIndicatorScreen extends MainScreen
{
ActivityIndicatorView view = new ActivityIndicatorView(Field.USE_ALL_WIDTH);
ActivityIndicatorModel model = new ActivityIndicatorModel();
ActivityIndicatorController controller = new ActivityIndicatorController();
public ActivityIndicatorScreen ()
{
setTitle("Activity Indicator Demo");
view.setController(controller);
view.setModel(model);
controller.setModel(model);
controller.setView(view);
model.setController(controller);
// Define the indicator image and create a field from it
Bitmap bitmap = Bitmap.getBitmapResource("spinner.png");
view.createActivityImageField(bitmap, 5, Field.FIELD_HCENTER);
// add the view to the screen
add(view);
MenuItem _stopIndicator = new MenuItem("Stop spinner", 66000, 0)
{
public void run()
{
view.getModel().cancel();
}
};
MenuItem _resumeIndicator = new MenuItem("Resume spinner", 66010, 0)
{
public void run()
{
view.getModel().resume();
}
};
addMenuItem(_stopIndicator);
addMenuItem(_resumeIndicator);
}
}

L'applicazione di esempio della demo dell'indicatore di progresso inclusa in BlackBerry® Java® SDK crea e gestisce
vari indicatori di attività, compresa la casella di selezione visualizzata sopra.

Indicazione di progresso
È possibile visualizzare un campo nell'applicazione BlackBerry® che indica che un'attività è in fase di svolgimento. Lo
stato di avanzamento è rappresentato da una barra che si riempie man mano che l'attività viene completata.
1. Importare le classi e le interfacce richieste.

87
Guida allo sviluppo Indicatori di attività e indicatori di progresso

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.progressindicator.*;
2. Creare un oggetto ProgressIndicatorView. È possibile specificare uno stile per la visualizzazione nel
costruttore. Nell'esempio seguente, non è specificato alcuno stile.
ProgressIndicatorView view = new ProgressIndicatorView(0);
Per specificare un gestore da utilizzare per il layout e l'evidenziazione, fornire un secondo argomento quando
si crea ProgressIndicatorView. Se non viene specificato un gestore, viene utilizzato un oggetto
VerticalFieldManager.
3. Creare un oggetto ProgressIndicatorController.
ProgressIndicatorController controller = new ProgressIndicatorController();
4. Creare un oggetto ProgressIndicatorModel. Questo oggetto rappresenta lo stato di avanzamento
dell'attività. Quando si crea l'oggetto, è possibile specificare il valore iniziale, massimo e minimo del modello.
ProgressIndicatorModel utilizza un oggetto Adjustment per consentire l'accesso in thread al modello di
dati e consentire all'attività di essere rappresentato dai valori interi.
ProgressIndicatorModel model = new ProgressIndicatorModel(0, 100, 0);
In questo esempio, l'attività si avvia con il valore 0 e può raggiungere 100. Questi valori gestiscono il
completamento di un'attività come una percentuale.
5. Collegare il controller, il modello e la visualizzazione.
model.setController(controller);
view.setModel(model);
view.setController(controller);
controller.setModel(model);
controller.setView(view);
6. Creare un thread per elaborare l'attività. In genere, le attività che richiedono indicatori di progresso vengono
eseguite tramite un thread. Man mano che l'attività procede, aggiornare il valore del modello in base allo stato
di avanzamento dell'attività.
class ProgressThread extends Thread
{
private boolean _paused;
private boolean _stop;
public void run()
{
// perform the task here and update the model's value as appropriate
}
public synchronized void setPaused(boolean paused)
{
// pause the indicator here
}
public synchronized void stopThread()
{
// stop the indicator here
}
}

88
Guida allo sviluppo Indicatori di attività e indicatori di progresso

7. Creare una classe che implementa l'interfaccia ProgressIndicatorListener in modo da ricevere una
notifica in caso di modifiche al modello di dati. È possibile ricevere una notifica quando il modello viene
ripristinato, ripreso o annullato o quando il valore del modello è stato modificato tramite metodi non
programmatici.
private final class DemoProgressIndicatorListener implements
ProgressIndicatorListener
{
public void cancelled()
{
_progressThread.setPaused(true);
}
public void resumed()
{
_progressThread.setPaused(false);
}
...
}
8. Associare il listener al modello.
model.addListener(new DemoProgressIndicatorListener());
9. Impostare l'etichetta per la visualizzazione. L'etichetta viene visualizzata sopra l'oggetto
ProgressIndicatorField di cui è stato eseguito il rendering (presupponendo che il gestore sia
VerticalFieldManager, che è il gestore predefinito).
view.setLabel("Percent completion");

10. Creare il campo che esegue il rendering del progresso. È possibile fornire stili che sono definiti in
ProgressBarField per specificare se il testo viene visualizzato sulla barra e come viene visualizzato. Per
impostazione predefinita, il valore del modello è visualizzato al centro dello spazio occupato dalla barra.
view.createProgressBar(Field.FIELD_HCENTER);
In questo esempio, la barra di avanzamento utilizza lo stile di testo predefinito ed è visualizzata al centro nel
gestore della visualizzazione.
11. Aggiungere la visualizzazione alla schermata.
add(view);
12. Controllare l'indicazione di progresso controllando il modello della visualizzazione, come necessario.
MenuItem _pauseIndicator = new MenuItem("Pause indicator", 66010, 0)
{
public void run()
{
view.getModel().cancel();
}
};
MenuItem _resumeIndicator = new MenuItem("Resume indicator", 66020, 0)
{
public void run()
{

89
Guida allo sviluppo Indicatori di attività e indicatori di progresso

view.getModel().resume();
}
};
Questo esempio richiama il metodo cancel() del modello per arrestare l'indicazione di progresso. L'esempio
richiama il metodo del modello resume() per riprendere l'indicazione di progresso.

Esempio di codice
public class ProgressIndicatorScreen extends MainScreen
{
ProgressIndicatorView view = new ProgressIndicatorView(0);
ProgressIndicatorModel model = new ProgressIndicatorModel(0, 100, 0);
ProgressIndicatorController controller = new ProgressIndicatorController();
ProgressThread _progressThread;
public ProgressIndicatorScreen()
{
setTitle("Progress Indicator Screen");
model.setController(controller);
model.addListener(new DemoProgressIndicatorListener());
view.setModel(model);
view.setController(controller);
controller.setModel(model);
controller.setView(view);
view.setLabel("Percent completion");
view.createProgressBar(Field.FIELD_HCENTER);
add(view);
MenuItem _startIndicator = new MenuItem("Start indicator", 66000, 0)
{
public void run()
{
if(_progressThread != null)
{
_progressThread.stopThread();
}
_progressThread = new ProgressThread();
_progressThread.start();
}
};
MenuItem _pauseIndicator = new MenuItem("Pause indicator", 66010, 0)
{
public void run()
{
view.getModel().cancel();
}
};
MenuItem _resumeIndicator = new MenuItem("Resume indicator", 66020, 0)
{
public void run()
{
view.getModel().resume();
}
};
addMenuItem(_startIndicator);
addMenuItem(_pauseIndicator);
addMenuItem(_resumeIndicator);

90
Guida allo sviluppo Indicatori di attività e indicatori di progresso

}
class ProgressThread extends Thread
{
private boolean _paused;
private boolean _stop;
public void run()
{
// Run dummy operations to simulate the processing of
// a collection of data.
for(int i = 0; i <= 100; ++i)
{
synchronized(this)
{
if(_stop)
{
break;
}
if(_paused)
{
try
{
wait();
}
catch(InterruptedException ie)
{
}
}
}
ProgressIndicatorScreen.this.model.setValue(i);
try
{
// Simulate work
sleep(250);
}
catch(InterruptedException ie)
{
}
}
}
public synchronized void setPaused(boolean paused)
{
_paused = paused;
this.notify();
}
public synchronized void stopThread()
{
_stop = true;
if(_paused)
{
// If the thread is in a paused state, wake it up
this.notify();
}
}
}
private final class DemoProgressIndicatorListener implements
ProgressIndicatorListener

91
Guida allo sviluppo Selettori

{
public void cancelled()
{
_progressThread.setPaused(true);
}
public void resumed()
{
_progressThread.setPaused(false);
}
public void reset()
{
// Not implemented
}
public void setNonProgrammaticValue(int value)
{
// Not implemented
}
public void configurationChanged(Adjustment source)
{
// Not implemented
}
public void valueChanged(Adjustment source)
{
// Not implemented
}
}
}

L'applicazione di esempio della demo dell'indicatore di progresso inclusa in BlackBerry® Java® SDK crea e gestisce
una barra di avanzamento.

Selettori
È possibile utilizzare i selettori per consentire agli utenti di selezionare facilmente una voce da un elenco.

Tipo di selettore Descrizione


Archivia Questo selettore consente agli utenti di cercare file sui loro dispositivi BlackBerry®.

92
Guida allo sviluppo Selettori

Tipo di selettore Descrizione

Location Questo selettore consente agli utenti di scegliere una posizione da un elenco
predefinito. È possibile ad esempio consentire agli utenti di scegliere la loro posizione
GPS o una posizione selezionata in precedenza.

Data Questo selettore consente agli utenti di scegliere un giorno, un mese o un anno
determinati. Ad esempio, è possibile consentire agli utenti di scegliere un mese e un
anno per specificare la scadenza della propria carta di credito.

93
Guida allo sviluppo Selettori

Tipo di selettore Descrizione

Ora Questo selettore consente agli utenti di scegliere un'ora, un minuto o un secondo
determinati.

Procedura consigliata: implementazione di selettori


Utilizzare le classi FilePicker, LocationPickere DateTimePicker per creare selettori.
Linee guida per i selettori file
• Specificare una visualizzazione specifica per mostrare i tipi di file che corrispondono allo scopo dell'utente. Ad
esempio, se un utente sfoglia le immagini, visualizza le immagini nel selettore file.
• Consentire agli utenti di iniziare la navigazione a partire da una cartella predefinita appropriata, se possibile.

Creazione di un selettore di data


1. Importare le classi e le interfacce richieste.

94
Guida allo sviluppo Selettori

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.picker.*;
import java.util.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore, richiamare pushScreen() per visualizzare la schermata personalizzata dell'applicazione. La classe
DatePickScreen rappresenta la schermata personalizzata descritta nel passaggio 3.
public class DatePick extends UiApplication
{
public static void main(String[] args)
{
DatePick theApp = new DatePick();
theApp.enterEventDispatcher();
}
public DatePick()
{
pushScreen(new DatePickScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore,
richiamare setTitle() per visualizzare un titolo sulla schermata. Richiamare add() per visualizzare un campo
RTF sulla schermata.
class DatePickScreen extends MainScreen
{
public DatePickScreen()
{
setTitle("Date Picker Sample");
add(new RichTextField("Trying Date Picker"));
}
}
4. Aggiungere una sezione di codice alla coda eventi dell'applicazione richiamando invokeLater(). Creare un
oggetto Runnable e passarlo come parametro a invokeLater(). Sovrascrivere run() nella definizione di
Runnable.
class DatePickScreen extends MainScreen
{
public DatePickScreen()
{
setTitle("Date Picker Sample");
add(new RichTextField("Trying Date Picker"));
UiApplication.getUiApplication().invokeLater(new Runnable()
{
public void run()
{
}

95
Guida allo sviluppo Selettori

});
}
}
5. In run(), richiamare DateTimePicker.getInstance() per restituire un oggetto DateTimePicker.
Richiamare doModal() per visualizzare il selettore di data. Richiamare getDateTime() per restituire un
oggetto Calendar che rappresenti la data e l'ora selezionate dall'utente. Utilizzare getTime() per restituire
la data e l'ora come oggetto Date. Utilizzare Dialog.alert() per visualizzare la data e l'ora selezionate.
class DatePickScreen extends MainScreen
{
public DatePickScreen()
{
setTitle("Date Picker Sample");
add(new RichTextField("Trying Date Picker"));
UiApplication.getUiApplication().invokeLater(new Runnable()
{
public void run()
{
DateTimePicker datePicker = DateTimePicker.getInstance();
datePicker.doModal();
Calendar cal = datePicker.getDateTime();
Date date = cal.getTime();
Dialog.alert("You selected " + date.toString());
}
});
}
}

Esempio di codice: creazione di un selettore di data


import net.rim.device.api.ui.*;
import net.rim.device.api.ui.picker.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.database.*;
import net.rim.device.api.io.*;
import java.util.*;
public class DatePick extends UiApplication
{
public static void main(String[] args)
{
DatePick theApp = new DatePick();
theApp.enterEventDispatcher();
}
public DatePick()
{
pushScreen(new DatePickScreen());
}
}
class DatePickScreen extends MainScreen
{
public DatePickScreen()
{
setTitle("Date Picker Sample");

96
Guida allo sviluppo Selettori

add(new RichTextField("Trying Date Picker"));


UiApplication.getUiApplication().invokeLater(new Runnable()
{
public void run()
{
DateTimePicker datePicker = DateTimePicker.getInstance();
datePicker.doModal();
Calendar cal = datePicker.getDateTime();
Date date = cal.getTime();
Dialog.alert("You selected " + date.toString());
}
});
}
}

Creazione di un selettore di file


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.picker.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import java.util.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe FilePickScreen rappresenta la schermata personalizzata descritta nel passaggio 3.
public class FilePick extends UiApplication
{
public static void main(String[] args)
{
FilePick theApp = new FilePick();
theApp.enterEventDispatcher();
}
public FilePick()
{
pushScreen(new FilePickScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore della
schermata richiamare setTitle() per specificare un titolo per la schermata. Richiamare add() per aggiungere
un campo etichetta alla schermata.
class FilePickScreen extends MainScreen
{
public FilePickScreen()
{
setTitle("File Picker Sample");

97
Guida allo sviluppo Selettori

add(new LabelField("Trying File Picker"));


}
}
4. Nel costruttore della schermata richiamare invokeLater() per aggiungere una sezione di codice alla coda
eventi dell'applicazione. Creare un oggetto Runnable e passarlo come parametro a invokeLater().
class FilePickScreen extends MainScreen
{
public FilePickScreen()
{
setTitle("File Picker Sample");
add(new LabelField("Trying File Picker"));
UiApplication.getUiApplication().invokeLater(new Runnable()
{
public void run()
{
}
});
}
}
5. Sovrascrivere run() nella definizione di Runnable. In run(), richiamare FilePicker.getInstance() per
restituire un oggetto FilePicker. Creare un oggetto FilePickListener, descritto nel passaggio 6.
Richiamare setListener() per registrare il listener del selettore di file. Richiamare show() per visualizzare
il selettore di file sulla schermata.

class FilePickScreen extends MainScreen


{
public FilePickScreen()
{
setTitle("File Picker Sample");
add(new LabelField("Trying File Picker"));
UiApplication.getUiApplication().invokeLater(new Runnable()
{
public void run()
{
FilePicker fp = FilePicker.getInstance();
FilePickListener fileListener = new FilePickListener();
fp.setListener(fileListener);
fp.show();
}
});
}
}
6. Richiamare Dialog.alert per creare una finestra di dialogo contenente un messaggio che visualizza il file
selezionato. Richiamare Dialog.alert in una classe che implementa l'interfaccia FilePicker.Listener
sovrascrivendo selectionDone(). L'applicazione esegue una chiamata a selectionDone() quando l'utente
seleziona un file utilizzando il selettore di file.
class FilePickListener implements FilePicker.Listener
{
public void selectionDone(String str)

98
Guida allo sviluppo

{
Dialog.alert("You selected " + str);
}
}

Esempio di codice: creazione di un selettore file

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.picker.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.io.*;
public class FilePick extends UiApplication
{
public static void main(String[] args)
{
FilePick theApp = new FilePick();
theApp.enterEventDispatcher();
}
public FilePick()
{
pushScreen(new FilePickScreen());
}
}
class FilePickScreen extends MainScreen
{
public FilePickScreen()
{
setTitle("File Picker Sample");
add(new LabelField("Trying File Picker"));
UiApplication.getUiApplication().invokeLater(new Runnable()
{
public void run()
{
FilePicker fp = FilePicker.getInstance();
FilePickListener fileListener = new FilePickListener();
fp.setListener(fileListener);
fp.show();
}
});
}
}
class FilePickListener implements FilePicker.Listener
{
public void selectionDone(String str)
{
Dialog.alert("You selected " + str);
}
}

99
Guida allo sviluppo Ricerca

Ricerca
Gli utenti possono utilizzare il campo di ricerca sulla schermata iniziale per cercare elementi in qualsiasi applicazione
sul dispositivo, incluse le applicazioni di terzi. La ricerca può includere anche il contenuto che non è memorizzato sul
dispositivo, ad esempio un database dell'organizzazione o un sito Web.

Gli utenti possono utilizzare anche un campo di ricerca in un'applicazione per cercare elementi in tale applicazione.
Ad esempio, gli utenti possono cercare un messaggio e-mail in un elenco messaggi, un brano nell'applicazione
Multimedia o un contatto nell'elenco contatti. In alcuni casi, è possibile che si desideri di visualizzare i risultati della
ricerca dalle altre applicazioni.
In alcune applicazioni, il campo di ricerca viene visualizzato sulla schermata. Negli altri casi, la ricerca è disponibile
dal menu completo, il menu a comparsa o la barra degli strumenti. Poiché gli utenti digitano il testo in un campo di
ricerca, visualizzare i risultati della ricerca. Se vengono restituiti molti risultati della ricerca, è possibile consentire
agli utenti di restringere la propria ricerca a un campo o un gruppo di campi. Ad esempio, se gli utenti eseguono una
ricerca nell'elenco dei messaggi, possono utilizzare l'elenco a discesa alla destra del campo di ricerca per restringere
la propria ricerca al campo "A" o al campo "Oggetto". Per ulteriori informazioni sull'aggiunta di un campo di ricerca
all'applicazione in uso, vedere Guida a BlackBerry Java Application per sviluppatori - Integrazione.

100
Guida allo sviluppo Ricerca

In un campo di ricerca gli utenti possono eseguire le seguenti operazioni:

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Aprire una voce evidenziata • Premere il tasto Invio. • Toccare lo schermo.
nei risultati di ricerca. • Fare clic sul trackpad. • Premere il tasto Invio.
• Fare clic sul trackpad.
Visualizzare un menu a Fare clic e tenere premuto il trackpad. • Toccare e tenere premuto un
comparsa con alcune azioni risultato della ricerca sulla
per un risultato della ricerca schermata.
(ad esempio, chiamare un • Fare clic e tenere premuto il
contatto) trackpad.

È possibile registrare il contenuto nell'applicazione in uso in modo che possa essere incluso nei risultati della ricerca.
È anche possibile registrare l'applicazione in uso come metodo per gli utenti per estendere una ricerca. Ad esempio,
se gli utenti cercano un brano nell'applicazione Multimedia e non lo trovano, è possibile consentire agli utenti di
ricercare nell'applicazione in uso come origine alternativa di risultati della ricerca. Per ulteriori informazioni sulla
registrazione di contenuto o su un'applicazione, vedere Guida a BlackBerry Java Application per sviluppatori -
Integrazione.

Procedura consigliata: implementazione della ricerca


• Utilizzare il pacchetto net.rim.device.api.unifiedsearch per implementare le funzionalità di ricerca.
• Accertarsi che il contenuto registrato venga incluso nei risultati della ricerca. Registrare solo il contenuto che
fornisce risultati della ricerca significativi per gli utenti.
• Tentare di presentare gli elementi più pertinenti all'inizio dell'elenco di risultati della ricerca. Ad esempio, se gli
utenti cercano un ristorante che si trova in diverse zone, visualizzare il ristorante più vicino alla posizione
dell'utente all'inizio dell'elenco dei risultati della ricerca.
• Nei risultati della ricerca, visualizzare in grassetto il testo che corrisponde al testo digitato dagli utenti. Questo
approccio consente agli utenti di vedere perché ogni elemento viene visualizzato nell'elenco dei risultati della
ricerca.
• Se gli utenti devono cercare una parola su una schermata (ad esempio, in un messaggio o su una pagina Web),
utilizzare il termine "Trova" nel Menu.
Implementazione dei campi di ricerca
• Impostare come elemento attivo predefinito il campo di ricerca. Quando vengono visualizzati i risultati della
ricerca, impostare come elemento attivo predefinito il primo elemento nell'elenco dei risultati della ricerca.
• Utilizzare il termine "Cerca" come il testo di suggerimento nel campo di ricerca.
• Non rendere i campi di ricerca sensibili alla distinzione tra maiuscole e minuscole.
• Posizionare il campo di ricerca sotto la barra del titolo sulla schermata di un'applicazione.

101
Guida allo sviluppo Ricerca

• Non assegnare tasti di scelta rapida a una schermata che include un campo di ricerca. Se si desidera utilizzare i
tasti di scelta rapida, fornire la funzionalità di ricerca alternativa. Ad esempio, consentire agli utenti di cercare
messaggi in un elenco messaggi tramite il menu.

Creazione di un campo di ricerca


È possibile creare un'applicazione che utilizzi la classe KeywordFilterField, inclusa nel pacchetto
net.rim.device.api.ui.component, per fornire un campo di interfaccia utente costituito da un singolo campo
di immissione testo e da un elenco di elementi selezionabili. Quando gli utenti digitano un testo in un campo di
ricerca, l'applicazione filtra gli elementi presenti nell'elenco che iniziano con il testo di ricerca. Per ulteriori
informazioni sull'utilizzo della classe KeywordFilterField, vedere l'applicazione di prova Keyword Filter Field,
inclusa in BlackBerry® Java® Development Environment versione 4.3.1 o successiva.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.collection.util.SortedReadableList;
import net.rim.device.api.io.LineReader;
import net.rim.device.api.ui.component.KeywordFilterField;
import net.rim.device.api.ui.component.KeywordProvider;
import java.io.InputStream;
import java.lang.String;
import java.util.Vector;
2. Creare le variabili. Nel seguente esempio di codice, CountryList estende la classe SortedReadableList e
implementa l'interfaccia KeywordProvider.
private KeywordFilterField _keywordField;
private CountryList _CountryList;
private Vector _countries;
3. Per creare un elenco di voci di testo selezionabili, popolare un vettore con i dati presi da un file di testo.
_countries = getDataFromFile();
4. Creare un'istanza di una classe che estenda la classe SortedReadableList.
_CountryList = new
CountryList(StringComparator.getInstance(true),_countries);
5. Per specificare gli elementi dell'elenco, creare una nuova istanza di un oggetto KeywordFilterField.
_keywordField = new KeywordFilterField();
6. Richiamare KeywordFilterField.setList().
_keywordField.setList(_CountryList, _CountryList);
7. Impostare un'etichetta per il campo di immissione dell'oggetto KeywordFilterFIeld.
_keywordField.setLabel("Search: ");
8. Creare la schermata principale dell'applicazione e aggiungere un oggetto KeywordFilterField alla schermata
principale.

102
Guida allo sviluppo Ricerca

KeywordFilterDemoScreen screen = new


KeywordFilterDemoScreen(this,_keywordField);
screen.add(_keywordField.getKeywordField());
screen.add(_keywordField);
pushScreen(screen);
9. Per creare un metodo che popoli e restituisca un vettore di oggetti Country contenente dati presi dal file di
testo, nella firma del metodo specificare Vector come tipo restituito.
public Vector getDataFromFile()
10. Creare e memorizzare un riferimento a un nuovo oggetto Vector.
Vector countries = new Vector();
11. Creare un flusso di input verso il file di testo.
InputStream stream =
getClass().getResourceAsStream("/Data/CountryData.txt");
12. Leggere le righe con delimitazione CRLF dal flusso di input.
LineReader lineReader = new LineReader(stream);
13. Leggere i dati dal flusso di input, una riga alla volta, fino a quando non si raggiunge il termine del contrassegno
del file. Ogni riga viene analizzata al fine di estrarre i dati utilizzati per creare oggetti Country.
for(;;){
//Obtain a line of text from the text file
String line = new String(lineReader.readLine());
//If we are not at the end of the file, parse the line of text
if(!line.equals("EOF")) {
int space1 = line.indexOf(" ");
String country = line.substring(0,space1);
int space2 = line.indexOf(" ",space1+1);
String population = line.substring(space1+1,space2);
String capital = line.substring(space2+1,line.length());
// Create a new Country object
countries.addElement(new Country(country,population,capital));

}
else {
break;
}
} // end the for loop
return countries;
14. Per aggiungere una parola chiave all'elenco di voci di testo selezionabili, richiamare
SortedReadableList.doAdd(element).
SortedReadableList.doAdd(((Country)countries.elementAt(i))
.getCountryName()) ;
15. Per aggiornare l'elenco di voci di testo selezionabili, richiamare KeywordFilterField.updateList().
_keywordField.updateList();

103
Guida allo sviluppo Ricerca

16. Per ottenere la parola chiave digitata da un utente BlackBerry nell'oggetto KeywordFilterField, richiamare
KeywordFilterField.getKeyword().
String userTypedWord = _keywordField.getKeyword();

Campo di testo con completamento automatico


È possibile utilizzare un campo di testo con completamento automatico per prevedere ciò che l'utente BlackBerry®
desidera digitare e per visualizzare una parola o una frase prima che venga digitata completamente dall'utente.
Quando si crea un oggetto AutoCompleteField, è necessario associare ad esso un oggetto
BasicFilteredList. L'oggetto BasicFilteredList mantiene i riferimenti agli oggetti dati che vengono utilizzati
come elementi di confronto per produrre un elenco di parole e di frasi. È possibile scegliere quali campi degli oggetti
dati devono essere utilizzati come elementi di confronto e quali campi devono essere visualizzati quando viene
rinvenuta una corrispondenza. È possibile, ad esempio, confrontare il testo digitato dall'utente con il valore del campo
DATA_FIELD_CONTACTS_BIRTHDAY nell'origine dati DATA_SOURCE_CONTACTS e restituire il valore del campo
DATA_FIELD_CONTACTS_NAME_FULL corrispondente.
Esistono quattro tipi di dati che è possibile associare a un oggetto BasicFilteredList da utilizzare con un oggetto
AutoCompleteField.

È possibile specificare l'insieme delle stringhe da mettere a confronto nei seguenti modi:
• una matrice di stringhe letterali
• una matrice di oggetti che supportano toString()
• origini dati su un dispositivo BlackBerry, come contatti, promemoria, attività e vari tipi di file multimediali
• una matrice di oggetti e una matrice di stringhe con indici corrispondenti
Per impostazione predefinita, il campo di testo con completamento automatico visualizza l'insieme delle stringhe
che viene restituito dal processo di confronto in un elenco a discesa. È possibile configurare l'aspetto di tale elenco
specificando i contrassegni di stile durante il processo di creazione del campo di testo con completamento
automatico. È possibile modificare l'aspetto dell'elenco e il modo in cui gli utenti interagiscono con esso.

Creazione di un campo di testo con completamento automatico da un set di dati


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.component.AutoCompleteField;
import net.rim.device.api.collection.util.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore, richiamare pushScreen() per visualizzare la schermata personalizzata dell'applicazione. La classe
HomeScreen, descritta nel passaggio 3, rappresenta la schermata personalizzata.
public class AutoCompleteFieldApp extends UiApplication
{
public static void main(String[] args)

104
Guida allo sviluppo Ricerca

{
AutoCompleteFieldApp app = new AutoCompleteFieldApp();
app.enterEventDispatcher();
}
AutoCompleteFieldApp()
{
pushScreen(new HomeScreen());
}
}
3. Creare la schermata personalizzata estendendo la classe MainScreen.
class HomeScreen extends MainScreen
{
public HomeScreen()
{
}
}
4. Nel costruttore, creare un oggetto BasicFilteredList. Creare una matrice String e memorizzare le stringhe
che si desidera far corrispondere all'interno della matrice. In questo esempio, le stringhe sono i giorni della
settimana. Richiamare addDataSet() per associare i dati della matrice a BasicFilteredList.
BasicFilteredList filterList = new BasicFilteredList();
String[] days =
{"Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sund
ay"};
filterList.addDataSet(1,days,"days",BasicFilteredList.COMPARISON_IGNORE_CASE);
5. Nel costruttore, creare un oggetto AutoCompleteField. Passare un'istanza di BasicFilteredList al
costruttore AutoCompleteField per associare BasicFilteredList al campo di testo con completamento
automatico. Richiamare add() per aggiungere il campo alla schermata.
AutoCompleteField autoCompleteField = new
AutoCompleteField(filterList);
add(autoCompleteField);

Esempio di codice: creazione di un campo con completamento automatico da un set di dati


import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.component.AutoCompleteField;
import net.rim.device.api.collection.util.*;
public class AutoCompleteFieldApp extends UiApplication
{
public static void main(String[] args)
{
AutoCompleteFieldApp app = new AutoCompleteFieldApp();
app.enterEventDispatcher();
}
AutoCompleteFieldApp()
{
HomeScreen scr = new HomeScreen();
this.pushScreen(scr);
}

105
Guida allo sviluppo Ricerca

}
class HomeScreen extends MainScreen
{
public HomeScreen()
{
BasicFilteredList filterList = new BasicFilteredList();
String[] days = {"Monday","Tuesday","Wednesday",
"Thursday","Friday","Saturday","Sunday"};
filterList.addDataSet(1,days,"days",BasicFilteredList
.COMPARISON_IGNORE_CASE);
AutoCompleteField autoCompleteField = new AutoCompleteField(filterList);
add(autoCompleteField);
}
}

Creazione di un campo di testo con completamento automatico da un'origine di dati


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.component.AutoCompleteField;
import net.rim.device.api.collection.util.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe HomeScreen rappresenta la schermata personalizzata descritta nel passaggio 3.
public class AutoCompleteFieldApp extends UiApplication
{
public static void main(String[] args)
{
AutoCompleteFieldApp app = new AutoCompleteFieldApp();
app.enterEventDispatcher();
}
public AutoCompleteFieldApp()
{
pushScreen(new HomeScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen.
class HomeScreen extends MainScreen
{
public HomeScreen()
{
}
}
4. Nel costruttore della schermata creare un oggetto BasicFilteredList. Richiamare addDataSource() per
associare un'origine dati a BasicFilteredList. In questo esempio, i dati corrispondono alle informazioni
contatto e l'origine dati all'elenco contatti. Il primo argomento che viene passato a addDataSource() è un ID
univoco. Il secondo argomento associa l'oggetto BasicFilteredList a un'origine dati. Il terzo argomento

106
Guida allo sviluppo Ricerca

specifica il gruppo di campi dell'origine dati con cui eseguire il confronto. Il quarto argomento specifica il gruppo
di campi dell'origine dati da rendere disponibili quando viene trovata una corrispondenza. In questo esempio,
i campi per il confronto corrispondono ai campi da rendere disponibili quando viene trovata una corrispondenza.
Il quinto argomento specifica il campo di visualizzazione primario. Il sesto argomento specifica il campo di
visualizzazione secondario. Il valore è -1 se non si desidera utilizzarlo. L'ultimo argomento specifica un nome per
BasicFilteredList. Il suo valore viene generato automaticamente se si specifica null.
BasicFilteredList filterList = new BasicFilteredList();
filterList.addDataSource(
1,
BasicFilteredList.DATA_SOURCE_CONTACTS,
BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL |
BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY |
BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL,
BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL |
BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY |
BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL,
BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL,
-1,
null);
5. Nel costruttore della schermata, creare un oggetto AutoCompleteField. Passare l'oggetto
BasicFilteredList creato nel passaggio 4 al costruttore AutoCompleteField per associare
BasicFilteredList al campo di testo con completamento automatico. Richiamare add() per aggiungere il
campo alla schermata.
AutoCompleteField autoCompleteField = new
AutoCompleteField(filterList);
add(autoCompleteField);

Esempio di codice: creazione di un campo con completamento automatico da un'origine dati


import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.component.AutoCompleteField;
import net.rim.device.api.collection.util.*;
public class AutoCompleteFieldApp extends UiApplication
{
public static void main(String[] args)
{
AutoCompleteFieldApp app = new AutoCompleteFieldApp();
app.enterEventDispatcher();
}
AutoCompleteFieldApp()
{
HomeScreen scr = new HomeScreen();
this.pushScreen(scr);
}
}
class HomeScreen extends MainScreen
{
public HomeScreen()
{
BasicFilteredList filterList = new BasicFilteredList();

107
Guida allo sviluppo Ricerca

filterList.addDataSource(1,
BasicFilteredList.DATA_SOURCE_CONTACTS,
BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL |
BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY |
BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL,
BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL |
BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY |
BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL,
BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL,
BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL,
null);
AutoCompleteField autoCompleteField = new AutoCompleteField(filterList);
add(autoCompleteField);
}
}

Utilizzo di origini dati e campi in un campo di testo con completamento automatico


È possibile utilizzare le classi AutoCompleteField e BasicFilteredList per confrontare il testo digitato da un
utente in un campo di testo con completamento automatico con i valori dei campi presenti in un'origine dati
specificata. Specificare i campi da utilizzare e le loro origini dati utilizzando un oggetto BasicFilteredList che
viene passato come argomento al costruttore della classe AutoCompleteField.

Origine dati Campi


DATA_SOURCE_APPOINTMENTS • DATA_FIELD_APPOINTMENTS_ALL
• DATA_FIELD_APPOINTMENTS_ATTENDEES
• DATA_FIELD_APPOINTMENTS_ORGANIZER
• DATA_FIELD_APPOINTMENTS_SUBJECT
DATA_SOURCE_CONTACTS • DATA_FIELD_CONTACTS_ADDRESS_ALL
• DATA_FIELD_CONTACTS_ADDRESS_HOME
• DATA_FIELD_CONTACTS_ADDRESS_WORK
• DATA_FIELD_CONTACTS_ANNIVERSARY
• DATA_FIELD_CONTACTS_BIRTHDAY
• DATA_FIELD_CONTACTS_CATEGORIES
• DATA_FIELD_CONTACTS_COMPANY
• DATA_FIELD_CONTACTS_EMAIL
• DATA_FIELD_CONTACTS_FAX
• DATA_FIELD_CONTACTS_JOB_TITLE
• DATA_FIELD_CONTACTS_NAME_FULL
• DATA_FIELD_CONTACTS_NAME_FIRST
• DATA_FIELD_CONTACTS_NAME_LAST
• DATA_FIELD_CONTACTS_NOTES
• DATA_FIELD_CONTACTS_PAGER
• DATA_FIELD_CONTACTS_PHONE_ALL

108
Guida allo sviluppo Caselle di selezione

Origine dati Campi


• DATA_FIELD_CONTACTS_PHONE_HOME
• DATA_FIELD_CONTACTS_PHONE_HOME2
• DATA_FIELD_CONTACTS_PHONE_MOBILE
• DATA_FIELD_CONTACTS_PHONE_OTHER
• DATA_FIELD_CONTACTS_PHONE_WORK
• DATA_FIELD_CONTACTS_PHONE_WORK2
• DATA_FIELD_CONTACTS_PIN
DATA_SOURCE_MEMOS • DATA_FIELD_MEMOS_TITLE
DATA_SOURCE_MESSAGES • DATA_FIELD_MESSAGES_ALL
• DATA_FIELD_MESSAGES_RECIPIENT
• DATA_FIELD_MESSAGES_SENDER
• DATA_FIELD_MESSAGES_SUBJECT
DATA_SOURCE_MUSIC • DATA_FIELD_MUSIC_ALL
• DATA_FIELD_MUSIC_ALBUM
• DATA_FIELD_MUSIC_ARTIST
• DATA_FIELD_MUSIC_GENRE
• DATA_FIELD_MUSIC_PLAYLIST
• DATA_FIELD_MUSIC_SONG
DATA_SOURCE_PICTURES • DATA_FIELD_PICTURES_TITLE
DATA_SOURCE_RINGTONES • DATA_FIELD_RINGTONES_TITLE
DATA_SOURCE_TASKS • DATA_FIELD_TASKS_TITLE
DATA_SOURCE_VIDEOS • DATA_FIELD_VIDEOS_TITLE
DATA_SOURCE_VOICENOTES • DATA_FIELD_VOICENOTES_TITLE

Caselle di selezione
Utilizzare una casella di selezione per consentire agli utenti di scegliere facilmente una voce da un elenco ordinato.
Utilizzare le caselle di selezione, ad esempio, per consentire agli utenti di trovare un numero o modificare il giorno
della settimana.

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Trovare una voce Far scorrere un dito in senso verticale sul • Trascinare un dito in senso verticale
nell'elenco. trackpad. sulla schermata.
• Spostarsi su o giù sulla schermata.
• Far scorrere un dito in senso
verticale sul trackpad.

109
Guida allo sviluppo Caselle di selezione

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Spostare un dito su o giù sulla schermata
o sul trackpad.
Scegliere una voce Fare clic sul trackpad. • Sollevare un dito dallo schermo.
dall'elenco. • Fare clic sul trackpad.
Passare a un'altra casella di Far scorrere un dito in senso verticale sul • Trascinare un dito in senso verticale
selezione. trackpad. sulla schermata.
• Far scorrere un dito in senso
verticale sul trackpad.

Creazione di una casella di selezione


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.component.Dialog;
import net.rim.device.api.ui.component.TextSpinBoxField;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.container.SpinBoxFieldManager;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe HomeScreen rappresenta la schermata personalizzata descritta nel passaggio 3.
public class SpinBoxApp extends UiApplication
{
public static void main(String[] args)
{
SpinBoxApp app = new SpinBoxApp();
app.enterEventDispatcher();
}
public SpinBoxApp()

110
Guida allo sviluppo Caselle di selezione

{
pushScreen(new HomeScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Dichiarare una
variabile per ogni campo della casella di selezione e dichiarare una variabile per il gestore del campo della casella
di selezione.
class HomeScreen extends MainScreen
{
TextSpinBoxField spinBoxDays;
TextSpinBoxField spinBoxMonths;
SpinBoxFieldManager spinBoxMgr;
public HomeScreen()
{
}
}
4. Nel costruttore della schermata creare una matrice di oggetti String per ciascuno dei campi della casella di
selezione.
final String[] DAYS =
{"Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"};
final String[] MONTHS =
{"January","February","March","April","May","June","July","A
ugust","September","October","November","December"};
5. Nel costruttore della schermata creare delle nuove istanze del gestore del campo della casella di selezione e i
due campi della casella di selezione. Passare la matrice appropriata di stringhe come argomenti a ciascuno dei
costruttori dei campi della casella di selezione.
spinBoxMgr = new SpinBoxFieldManager();
spinBoxDays = new TextSpinBoxField(DAYS);
spinBoxMonths = new TextSpinBoxField(MONTHS);
6. Nel costruttore della schermata aggiungere i campi della casella di selezione al gestore del campo della casella
di selezione. Richiamare add() per aggiungere alla schermata il gestore e i campi che esso contiene.
spinBoxMgr.add(spinBoxDays);
spinBoxMgr.add(spinBoxMonths);
add(spinBoxMgr);

Esempio di codice: creazione di una casella di selezione


import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.container.SpinBoxFieldManager;
import net.rim.device.api.ui.component.Dialog;
import net.rim.device.api.ui.component.TextSpinBoxField;
public class SpinBoxApp extends UiApplication
{
public static void main(String[] args)
{
SpinBoxApp app = new SpinBoxApp();

111
Guida allo sviluppo

app.enterEventDispatcher();
}
public SpinBoxApp()
{
HomeScreen homeScreen = new HomeScreen();
pushScreen(homeScreen);
}
}
class HomeScreen extends MainScreen
{
TextSpinBoxField spinBoxDays;
TextSpinBoxField spinBoxMonths;
SpinBoxFieldManager spinBoxMgr;
public HomeScreen()
{
final String[] DAYS =
{"Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"};
final String[] MONTHS =
{"January","February","March","April","May","June","July","August","Sep
tember","October","November","December"};
spinBoxMgr = new SpinBoxFieldManager();
spinBoxDays = new TextSpinBoxField(DAYS);
spinBoxMonths = new TextSpinBoxField(MONTHS);
spinBoxMgr.add(spinBoxDays);
spinBoxMgr.add(spinBoxMonths);
add(spinBoxMgr);
}
public void close()
{
Dialog.alert("You selected " +
(String)spinBoxDays.get(spinBoxDays.getSelectedIndex()) + " and " +
(String)spinBoxMonths.get(spinBoxMonths.getSelectedIndex()));
super.close();
}
}

Procedura consigliata: implementazione delle caselle di selezione


• Utilizzare le caselle di selezione per creare elenchi di voci sequenziali.
• Utilizzare gli elenchi a discesa per creare elenchi di voci non sequenziali o di voci a intervalli irregolari. È possibile
utilizzare una casella di selezione per offrire agli utenti un'esperienza più interattiva nel caso di un elenco ristretto
di voci non sequenziali.
• Evitare di utilizzare una casella di selezione se sulla schermata sono presenti molti altri componenti.
• Utilizzare la classe SpinBoxField e la classe SpinBoxFieldManager per creare le caselle di selezione.
• Laddove possibile, aggiungere alle finestre di dialogo caselle di selezione invece di schermate.
• Quando gli utenti evidenziano una casella di selezione, visualizzare da tre a cinque voci in senso verticale.
• Utilizzare un formato identificabile per la sequenza di voci (ad esempio 5, 10, 15), in modo che gli utenti possano
valutare quanto devono scorrere per trovare la voce desiderata.
• Evitare di far scorrere gli utenti in senso orizzontale per visualizzare più caselle di selezione. Se necessario,
distribuire le caselle di selezione in più campi.
• Se il testo di una casella di selezione è troppo lungo, utilizzare i puntini di sospensione (...).

112
Guida allo sviluppo Campi di testo

Campi di testo
Gli utenti possono utilizzare un campo di testo per digitare un testo.

Tipo di campo di
Descrizione
testo
e-mail Gli utenti possono inserire il simbolo chiocciola (@) o un punto (.) nel campo di un indirizzo
e-mail premendo il tasto Space.
data e ora Gli utenti possono modificare la data o l'ora sui dispositiviBlackBerry® con un trackpad
utilizzando la tastiera o scorrendo un dito in senso verticale sul trackpad.
Gli utenti possono modificare la data o l'ora sui dispositivi BlackBerry con touchscreen
spostandosi su o giù sulla schermata.
numero Quando gli utenti devono immettere un valore in un campo numerico su una tastiera fisica,
il dispositivo BlackBerry seleziona la modalità blocco numeri per far sì che gli utenti non
debbano premere il tasto Alt per digitare i numeri.
Quando gli utenti devono immettere un valore in un campo numerico su una tastiera
virtuale, viene visualizzata la tastiera numerica.
password Quando gli utenti immettono un valore in un campo Password, vengono visualizzati
asterischi (*) al posto del testo. Nei campi Password non è possibile tagliare, copiare o
incollare un testo o utilizzare il Glossario.
Sui dispositivi BlackBerry con tecnologia SureType®, la multipressione è il metodo di
digitazione predefinito per i campi Password.
numero di telefono Quando gli utenti immettono un valore nel campo Numero di telefono su una tastiera fisica,
il dispositivo BlackBerry seleziona la modalità blocco numeri per far sì che gli utenti non
debbano premere il tasto Alt per digitare i numeri. Nei campi Numero di telefono è inoltre
possibile consentire agli utenti di eseguire le seguenti operazioni:
• Digitare il segno più (+) per i numeri di telefono internazionali.
• Digitare dei caratteri di formattazione come il segno meno (-), il punto (.), le parentesi
(()) e gli spazi.
• Digitare il simbolo cancelletto (#) o un asterisco (*).
• Indicare una pausa digitando una virgola (,) o indicare un'attesa digitando un punto
esclamativo (!).
• Indicare un'estensione premendo il tasto Alt + E, X o T.
Quando gli utenti devono immettere un valore in un campo Numero di telefono su una
tastiera virtuale, viene visualizzata la tastiera numerica. Nei campi Numero di telefono è
inoltre possibile consentire agli utenti di eseguire le seguenti operazioni:
• Digitare il simbolo cancelletto (#) o un asterisco (*).
• Indicare una pausa o un'estensione tenendo premuto il tasto asterisco (*).

113
Guida allo sviluppo Campi di testo

Tipo di campo di
Descrizione
testo
• Indicare un'attesa o un'estensione tenendo premuto il tasto cancelletto (#).
testo Nei campi di testo gli utenti digitano un testo. Nei campi di testo gli utenti possono tagliare,
copiare e incollare un testo. Quando il cursore raggiunge il termine di una riga, il testo va
a capo e prosegue nella riga successiva.
Nei campi di testo i dispositivi BlackBerry possono inoltre convertire automaticamente
numeri di telefono, pagine Web e indirizzi e-mail in collegamenti.
indirizzo Web Premendo il tasto Space gli utenti possono inserire un punto (.) nel campo di un indirizzo.

Procedura consigliata: implementazione dei campi di testo


• Utilizzare la classe TextField per creare campi testo.
• Scegliere il tipo di campo di testo considerando che cosa ci si aspetta che gli utenti digitino. Utilizzare il campo
di testo più appropriato consente di visualizzare l'indicatore più appropriato al testo che gli utenti digitano sulla
schermata. Quando, ad esempio, gli utenti digitano un testo nel campo Numero di telefono, nell'angolo superiore
destro della schermata verrà visualizzato l'indicatore blocco numeri. Nei dispositivi BlackBerry con tecnologia
SureType® il campo scelto influenza anche il metodo di digitazione predefinito per il campo.
• Se possibile, utilizzare o estendere dei campi esistenti invece di creare dei campi personalizzati, in modo che i
campi ereditino il comportamento predefinito appropriato.
• Se necessario, includere un testo di suggerimento per aiutare gli utenti. Utilizzare un testo di suggerimento se
lo spazio di una schermata è limitato e non è possibile includere un'etichetta o un testo con istruzioni. Il testo
di suggerimento viene visualizzato nel campo e scompare quando gli utenti iniziano a digitare.
Linee guida per le etichette
• Utilizzare etichette concise e descrittive. Evitare di utilizzare etichette che vadano a capo automaticamente.
• Adottare l'uso delle iniziali maiuscole proprio dei titoli.
• Aggiungere alle etichette dei campi il carattere due punti (:).
• Se si utilizza un testo di suggerimento, esso deve essere conciso. Iniziare le frasi con la lettera maiuscola.

Creazione di un campo di testo


Creazione di un campo di testo di sola lettura che consente la formattazione
1. Importare la classe net.rim.device.api.ui.component.RichTextField.
2. Creare un'istanza di RichTextField.
RichTextField rich = new RichTextField("RichTextField");

Creazione di un campo di testo modificabile senza formattazione e che accetta i filtri


1. Importare le seguenti classi:
• net.rim.device.api.ui.component.BasicEditField

114
Guida allo sviluppo Campi di testo

• net.rim.device.api.ui.component.EditField
2. Creare un'istanza di BasicEditField.
BasicEditField bf = new BasicEditField("BasicEditField: ", "", 10,
EditField.FILTER_UPPERCASE);

Creazione di un campo di testo modificabile che consenta l'utilizzo di caratteri speciali


1. Importare la classe net.rim.device.api.ui.component.EditField.
2. Creare un'istanza di EditField.
EditField edit = new EditField("EditField: ", "", 10, EditField.FILTER_DEFAULT);

Creare un campo di testo per il Glossario


Se un campo di testo supporta il Glossario, quando gli utenti premono due volte il tasto SPACE, il dispositivo
BlackBerry® inserisce un punto, scrive in maiuscolo la lettera successiva e sostituisce le parole sulla base dei
suggerimenti dell'applicazione Glossario.
1. Importare le seguenti classi:
• net.rim.device.api.ui.component.AutoTextEditField
• net.rim.device.api.ui.autotext.AutoText
• net.rim.device.api.ui.component.BasicEditField
2. Creare un'istanza di AutoTextEditField.
AutoTextEditField autoT = new AutoTextEditField("AutoTextEditField: ", "");

Creazione di un campo data


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import java.lang.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe MyUiScreen, descritta nel passaggio 3, rappresenta la schermata personalizzata.
public class MyUi extends UiApplication
{
public static void main(String[] args)
{
MyUi theApp = new MyUi();
theApp.enterEventDispatcher();
}
public MyUi()
{

115
Guida allo sviluppo Visualizzazioni ad albero

pushScreen(new MyUiScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore della
schermata, richiamare setTitle() per specificare il titolo della schermata.
class MyUiScreen extends MainScreen
{
public MyUiScreen()
{
setTitle("UI Component Sample");
}
}
4. Nel costruttore della schermata, creare un campo data utilizzando la classe DateField. Fornire
System.currentTimeMillis() come parametro per restituire l'ora corrente. Utilizzare lo stile
DateField.DATE_TIME per visualizzare sia la data che l'ora. È possibile utilizzare altri stili per visualizzare solo
la data o l'ora.
add(new DateField("Date: ", System.currentTimeMillis(),
DateField.DATE_TIME));

Creazione di un campo Password


1. Importare la classe net.rim.device.api.ui.component.PasswordEditField.
2. Creare un'istanza di PasswordEditField.
La seguente istanza utilizza, ad esempio, un costruttore che consente di fornire un valore iniziale predefinito
per PasswordEditField:
PasswordEditField pwd = new PasswordEditField("PasswordEditField: ", "");

Visualizzazioni ad albero
Utilizzare una visualizzazione ad albero per visualizzare oggetti, ad esempio le cartelle, in modo gerarchico.
Gli oggetti presenti in una visualizzazione ad albero sono detti nodi. Il nodo più alto è detto nodo radice. Il nodo di
un albero può avere nodi figlio. Un nodo che presenta un figlio è detto nodo padre.
In una visualizzazione ad albero gli utenti possono eseguire le seguenti operazioni:

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Espandere o comprimere un Premere il tasto Space o fare clic sul • Toccare l'oggetto.
oggetto contrassegnato dal trackpad. • Premere il tasto Space.
segno più (+) o dal segno • Fare clic sul trackpad.
meno (-) in una gerarchia.

116
Guida allo sviluppo Visualizzazioni ad albero

Procedura consigliata: implementazione delle visualizzazioni ad albero


• Utilizzare la classe TreeField per creare le visualizzazioni ad albero.
• Fornire un menu a comparsa se gli utenti possono eseguire più azioni quando fanno clic su un nodo di livello
superiore.
• Includere un nodo radice solamente se gli utenti devono avere la possibilità di eseguire delle operazioni
sull'intero albero. In caso contrario escludere il nodo radice.

Creazione di un campo con visualizzazione ad albero


Utilizzare una visualizzazione ad albero per visualizzare in modo gerarchico gli oggetti come una struttura di cartelle.
Un oggetto TreeField contiene nodi. Il nodo più alto è detto nodo radice. Il nodo di un albero può avere nodi figlio.
Un nodo che presenta un figlio è detto nodo padre.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.component.TreeField;
import net.rim.device.api.ui.component.TreeFieldCallback;
import net.rim.device.api.ui.container.MainScreen;
import java.lang.String;
2. Implementare l'interfaccia TreeFieldCallback.
3. Richiamare TreeField.setExpanded() sull'oggetto TreeField per specificare se una cartella è
comprimibile. Creare un oggetto TreeField e più nodi figlio per l'oggetto TreeField. Richiamare
TreeField.setExpanded() utilizzando node4 come parametro per comprimere la cartella.
String fieldOne = new String("Main folder");
...
TreeCallback myCallback = new TreeCallback();
TreeField myTree = new TreeField(myCallback, Field.FOCUSABLE);
int node1 = myTree.addChildNode(0, fieldOne);
int node2 = myTree.addChildNode(0, fieldTwo);
int node3 = myTree.addChildNode(node2, fieldThree);
int node4 = myTree.addChildNode(node3, fieldFour);
...

117
Guida allo sviluppo Visualizzazioni ad albero

int node10 = myTree.addChildNode(node1, fieldTen);


myTree.setExpanded(node4, false);
...
mainScreen.add(myTree);
4. Per ridisegnare un oggetto TreeField quando un nodo viene modificato, creare una classe che implementi
l'interfaccia TreeFieldCallback e il metodo TreeFieldCallback.drawTreeItem. Il metodo
TreeFieldCallback.drawTreeItem utilizza il cookie di un nodo d'albero per disegnare un oggetto
String nella posizione di un nodo. Il metodo TreeFieldCallback.drawTreeItem richiama
Graphics.drawText() per disegnare l'oggetto String.
private class TreeCallback implements TreeFieldCallback
{
public void drawTreeItem(TreeField _tree, Graphics g, int node, int y, int
width, int indent)
{
String text = (String)_tree.getCookie(node);
g.drawText(text, indent, y);
}
}

118
Guida allo sviluppo Immagini

Immagini 9
Utilizzo di immagini codificate
Accesso a un'immagine codificata attraverso un flusso di input
1. Importare le classi richieste.
import java.io.InputStream;
2. Salvare l'immagine nella cartella di progetto o in una sottocartella.
3. Aggiungere l'immagine al progetto in BlackBerry® Java® Plug-in per Eclipse® o BlackBerry® Java® Development
Environment.
4. Richiamare getClass().getResourceAsStream() per recuperare l'immagine come un flusso di input di
byte.
private InputStream input;
...
Class _class = this.getClass();
input = _class.getResourceAsStream("/images/example.png");

Codifica di un'immagine
1. Importare le classi richieste.
import net.rim.device.api.system.EncodedImage;
2. Richiamare EncodedImage.createEncodedImage(). Questo metodo utilizza i dati di immagine non elaborati
nella matrice di byte per creare un'istanza di EncodedImage.
3. Verificare la presenza dell'eccezione IllegalArgumentException generata da
EncodedImage.createEncodedImage() se la matrice di byte fornito come parametro non contiene un
formato immagine riconosciuto.
// Store the contents of the image file.
private byte[] data = new byte[2430];
try {
// Read the image data into the byte array
input.read(data);
} catch (IOException e) {
// Handle exception.
}
try {
EncodedImage image = EncodedImage.createEncodedImage(data, 0, data.length);
} catch (IllegalArgumentException iae) {
System.out.println("Image format not recognized.");
}

119
Guida allo sviluppo Visualizzazione di un'immagine per zoom e panoramica

Visualizzazione di un'immagine codificata


1. Importare la classe richiesta.
import net.rim.device.api.ui.component.BitmapField;
2. Richiamare BitmapField.setImage() per assegnare l'immagine codificata a un BitmapField.
3. Richiamare add() per aggiungere BitmapField alla schermata.
BitmapField field = new BitmapField();
field.setImage(image);
add(field);

Specifica della dimensione di visualizzazione di un'immagine codificata


1. Importare la classe richiesta.
import net.rim.device.api.system.EncodedImage;
2. Richiamare EncodedImage.scaleImage32(int scaleX, int scaleY). I parametri del valore di
adattamento passati devono essere net.rim.device.api.math.Fixed32 (0 < adattamento < 1 per
l'upscaling e adattamento > 1 per il downscaling). scaleImage32() crea un nuovo elemento
EncodedImage anziché modificare quello corrente.

Specifica della modalità di decodifica di un'immagine


1. Importare la classe richiesta.
import net.rim.device.api.system.EncodedImage;
2. Richiamare EncodedImage.setDecodeMode() utilizzando una delle seguenti modalità come parametro:
• Utilizzare DECODE_ALPHA per decodificare un canale alfa, se presente (questa è la modalità predefinita).
• Utilizzare DECODE_NATIVE per imporre la decodifica dell'immagine bitmap nel tipo nativo di immagine
bitmap di BlackBerry® Device Software.
• Utilizzare DECODE_READONLY per contrassegnare l'immagine bitmap decodificata come di sola lettura.

Visualizzazione di un'immagine per zoom e panoramica


La classe ZoomScreen consente di fornire funzionalità di zoom e panoramica a un'immagine. Quando un utente
BlackBerry® fa clic sulla trackball o sul touchscreen, la schermata visualizza l'area centrale dell'immagine ingrandita.
Quando l'immagine viene ingrandita, sullo schermo viene anche visualizzata una sovrapposizione che evidenzia l'area
ingrandita. Facendo scorrere la trackball o sfiorando lo schermo con il dito è possibile spostare l'immagine. Quando
l'utente interrompe la panoramica e lo zoom, la sovrapposizione scompare dallo schermo.

120
Guida allo sviluppo Visualizzazione di un'immagine per zoom e panoramica

Sui dispositivi BlackBerry con touchscreen, gli utenti possono definire l'area dell'immagine da ingrandire. L'utente
può toccare due punti sull'immagine per definire gli angoli diagonalmente opposti dell'area. Dopo aver selezionato
l'area, l'utente può sfiorare l'immagine con un dito per spostare l'area di zoom. Per ingrandire l'area definita, l'utente
può fare clic sullo schermo. Per rimpicciolire l'area, l'utente può premere il tasto ESC.

Esempio di codice: visualizzazione di un'immagine per zoom e panoramica


import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.extension.container.*;
public class ZoomableImageApp extends UiApplication
{
public static void main(String[] args)
{
ZoomableImageApp theApp = new ZoomableImageApp();
theApp.enterEventDispatcher();
}
public ZoomableImageApp()
{
EncodedImage myImg = new EncodedImage("myImg.jpg");
ZoomScreen zoomableImg = new ZoomScreen(myImg);
pushScreen(zoomableImg);
}
}

Visualizzazione di un'immagine per zoom e panoramica


1. Importare le classi e le interfacce richieste:
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.extension.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore, creare EncodedImage utilizzando una risorsa del progetto, creare ZoomScreen
conEncodedImage e richiamare pushScreen() per visualizzare l'immagine per zoom e panoramica.
public class ZoomableImageApp extends UiApplication
{
public static void main(String[] args)
{
ZoomableImageApp theApp = new ZoomableImageApp();
theApp.enterEventDispatcher();
}
public ZoomableImageApp()
{
EncodedImage myImg = new EncodedImage("myImg.jpg");
ZoomScreen zoomableImg = new ZoomScreen(myImg);

121
Guida allo sviluppo Visualizzazione di una fila di immagini per lo scorrimento

pushScreen(zoomableImg);
}
}

Visualizzazione di una fila di immagini per lo scorrimento


È possibile utilizzare la classe PictureScrollField per eseguire il rendering di una fila orizzontale di immagini che
l'utente può scorrere utilizzando la trackball o toccandole.
PictureScrollField consente di definire lo stile di evidenziazione dell'immagine selezionata, lo stile dello sfondo
di PictureScrollField, il testo visualizzato sotto l'immagine selezionata, il testo della descrizione comandi
visualizzato quando un'immagine viene inizialmente selezionata e l'altezza e la larghezza delle immagini.

Esempio di codice: visualizzazione di una fila di immagini per lo scorrimento


import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.decor.*;
import net.rim.device.api.ui.extension.component.*;
public class PictureScrollFieldDemo extends UiApplication
{
public static void main(String[] args)
{
PictureScrollFieldDemo app = new PictureScrollFieldDemo();
app.enterEventDispatcher();
}
public PictureScrollFieldDemo()
{
pushScreen(new PictureScrollFieldDemoScreen());
}
}
class PictureScrollFieldDemoScreen extends MainScreen
{
public PictureScrollFieldDemoScreen()
{
setTitle("PictureScrollField Demo");
Bitmap[] images = new Bitmap[3];
String[] labels = new String[3];
String[] tooltips = new String[3];
images[0] = Bitmap.getBitmapResource("img1.jpg");
labels[0] = "Label for image 1";
tooltips[0] = "Tooltip for image 1";
images[1] = Bitmap.getBitmapResource("img2.jpg");
labels[1] = "Label for image 2";
tooltips[1] = "Tooltip for image 2";
images[2] = Bitmap.getBitmapResource("img3.jpg");
labels[2] = "Label for image 3";
tooltips[2] = "Tooltip for image 3";
ScrollEntry[] entries = ScrollEntry[3];
for (int i = 0; i < entries.length; i++)

122
Guida allo sviluppo Visualizzazione di una fila di immagini per lo scorrimento

{
entries[i] = new ScrollEntry(images[i], labels[i],tooltips[i]);
}
PictureScrollField pictureScrollField = new PictureScrollField(150, 100);
pictureScrollField.setData(entries, 0);
pictureScrollField.setHighlightStyle(HighlightStyle.ILLUMINATE);
pictureScrollField.setHighlightBorderColor(Color.BLUE);
pictureScrollField.setBackground
(BackgroundFactory.createSolidTransparentBackground(Color.RED, 150));
pictureScrollField.setLabelsVisible(true);
add(pictureScrollField);
}
}

Visualizzazione di una fila di immagini per lo scorrimento


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.decor.*;
import net.rim.device.api.ui.extension.component.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore, richiamare pushScreen() per visualizzare la schermata personalizzata dell'applicazione. La classe
PictureScrollFieldDemoScreen, descritta nel passaggio 3, rappresenta la schermata personalizzata.
public class PictureScrollFieldDemo extends UiApplication
{
public static void main(String[] args)
{
PictureScrollFieldDemo app = new PictureScrollFieldDemo();
app.enterEventDispatcher();
}
public PictureScrollFieldDemo()
{
pushScreen(new PictureScrollFieldDemoScreen());
}
}
3. Creare il framework della schermata personalizzata estendendo la classe MainScreen.
class PictureScrollFieldDemoScreen extends MainScreen
{
public PictureScrollFieldDemoScreen()
{
}
}
4. Nel costruttore, richiamare setTitle() per impostare il testo visualizzato nella sezione del titolo della
schermata.

123
Guida allo sviluppo Visualizzazione di una fila di immagini per lo scorrimento

setTitle("PictureScrollField Demo");
5. Nel costruttore, creare e inizializzare tre matrici per archiviare le immagini da visualizzare in
PictureScrollField, le etichette e il testo della descrizione comandi visualizzati al momento della selezione
di ciascuna immagine. In questo esempio, PictureScrollField contiene tre immagini.
Bitmap[] images = new Bitmap[3];
String[] labels = new String[3];
String[] tooltips = new String[3];
images[0] = Bitmap.getBitmapResource("img1.jpg");
labels[0] = "Label for image 1";
tooltips[0] = "Tooltip for image 1";
images[1] = Bitmap.getBitmapResource("img2.jpg");
labels[1] = "Label for image 2";
tooltips[1] = "Tooltip for image 2";
images[2] = Bitmap.getBitmapResource("img3.jpg");
labels[2] = "Label for image 3";
tooltips[2] = "Tooltip for image 3";
6. Nel costruttore, creare e inizializzare una matrice di oggetti ScrollEntry. Un oggetto ScrollEntry
rappresenta ciascuna voce in PictureScrollField.
ScrollEntry[] entries = ScrollEntry[3];
for (int i = 0; i < entries.length; i++)
{
entries[i] = new ScrollEntry(images[i], labels[i], tooltips[i]);
}
7. Nel costruttore, creare e inizializzare PictureScrollField con ciascuna immagine con larghezza di 150 pixel
e altezza di 100 pixel. Richiamare setData() per impostare le voci in PictureScrollField. Il secondo
parametro in setData() specifica la posizione dell'immagine selezionata per impostazione predefinita.
PictureScrollField pictureScrollField = new PictureScrollField(150,
100);
pictureScrollField.setData(entries, 0);
8. Nel costruttore, impostare lo stile di PictureScrollField. Richiamare setHighlightStyle() per
specificare il modo in cui l'immagine selezionata viene evidenziata. Richiamare setHighlightBorderColor
() per specificare il colore del bordo dell'immagine selezionata. Richiamare setBackground() per specificare
lo sfondo di PictureScrollField. Richiamare setLabelVisible() per specificare se in
PictureScrollField viene visualizzata l'etichetta dell'immagine selezionata.
pictureScrollField.setHighlightStyle(HighlightStyle.ILLUMINATE);
pictureScrollField.setHighlightBorderColor(Color.BLUE);
pictureScrollField.setBackground(BackgroundFactory
.createSolidTransparentBackground(Color.RED, 150));
pictureScrollField.setLabelsVisible(true);
9. Nel costruttore, richiamare add() per visualizzare PictureScrollField.
add(pictureScrollField);

124
Guida allo sviluppo Voci di menu

Voci di menu 10
Creazione di un menu
La classe MainScreen fornisce alcuni componenti standard delle applicazioni BlackBerry®. Include un menu
predefinito.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe CreateMenuScreen, descritta nel passaggio 3, rappresenta la schermata
personalizzata.
public class CreateMenu extends UiApplication
{
public static void main(String[] args)
{
CreateMenu theApp = new CreateMenu();
theApp.enterEventDispatcher();
}
public CreateMenu()
{
pushScreen(new CreateMenuScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore di
schermata, richiamare setTitle() per specificare il titolo della schermata. Richiamare add() per aggiungere
un campo di testo alla schermata. Richiamare addMenuItem() per aggiungere una voce di menu al menu che
crea MainScreen.
class CreateMenuScreen extends MainScreen
{
public CreateMenuScreen()
{
setTitle("Create Menu Sample");
add(new RichTextField("Create a menu"));
addMenuItem(_viewItem);
}
}
4. Creare la voce di menu utilizzando la classe MenuItem. Sovrascrivere run() per specificare quale operazione
viene selezionata dall'utente facendo clic sulla voce di menu. Quando l'utente fa clic sulla voce di menu,
l'applicazione richiama Menu.run().

125
Guida allo sviluppo Creazione di un menu

private MenuItem _viewItem = new MenuItem("More Info", 110, 10)


{
public void run()
{
Dialog.inform("Display more information");
}
};
5. Sovrascrivere close() per visualizzare una finestra di dialogo quando l'utente fa clic sulla voce di menu Chiudi.
Per impostazione predefinita, la voce di menu Chiudi è inclusa nel menu creato da MainScreen. Richiamare
super.close() per chiudere l'applicazione. Quando l'utente chiude la finestra di dialogo, l'applicazione
richiama MainScreen.close() per chiudere l'applicazione.
public void close()
{
Dialog.alert("Goodbye!");
super.close();
}

Esempio di codice: creazione di un menu


import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
public class CreateMenu extends UiApplication
{
public static void main(String[] args)
{
CreateMenu theApp = new CreateMenu();
theApp.enterEventDispatcher();
}
public CreateMenu()
{
pushScreen(new CreateMenuScreen());
}
}
class CreateMenuScreen extends MainScreen
{
public CreateMenuScreen()
{
setTitle("Create Menu Sample");
add(new RichTextField("Create a menu"));
addMenuItem(_viewItem);
}
private MenuItem _viewItem = new MenuItem("More Info", 110, 10)
{
public void run()
{
Dialog.inform("Display more information");
}
};
public void close()
{
Dialog.alert("Goodbye!");

126
Guida allo sviluppo Procedura consigliata: implementazione dei menu

super.close();
}
}

Procedura consigliata: implementazione dei menu


• Fornire sempre un menu completo.
• Assicurarsi che gli utenti possano premere il tasto Menu per aprire il menu completo e avviare un'azione quando
è stata evidenziata una voce di menu. Assicurarsi inoltre che gli utenti possano tenere premuto il tasto Menu
per aprire la finestra di dialogo che consente di passare da un'applicazione a un'altra.
• Utilizzare come voce di menu predefinita quella che verrà selezionata con maggiore probabilità dagli utenti.
• Collocare la voce di menu predefinita e le altre voci normali di menu al centro del menu.
• Verificare che l'ordine delle voci di menu sia coerente con quello delle voci di menu di altre applicazioni
BlackBerry®.
• Raggruppare le voci di menu in base al loro utilizzo o alle funzionalità comuni e, laddove possibile, verificare le
proprie decisioni con gli utenti.
• Inserire dei separatori tra i raggruppamenti delle voci di menu.
• Non collocare delle voci di menu che provocano azioni contrarie nelle immediate vicinanze. Non collocare ad
esempio la voce di menu "Elimina" accanto alla voce di menu "Apri".
• Includere sempre le voci di menu "Passa da un applicazione a un'altra" e "Chiudi". Collocare queste voci al
termine del menu. Se si utilizzano dei componenti standard, queste voci di menu sono incluse automaticamente.
Linee guida per le etichette
• Utilizzare etichette concise e descrittive, di lunghezza non superiore ai 12 caratteri. Se un'etichetta è troppo
lunga, viene visualizzata un'ellissi (...) per indicare che il testo è troncato.
• Utilizzare dei verbi per le etichette.
• Iniziare le etichette con la lettera maiuscola.
• Utilizzare dei puntini di sospensione nell'etichetta di una voce di menu per indicare che gli utenti dovranno
eseguire un'ulteriore operazione dopo avere fatto clic sulla voce. Se, ad esempio, gli utenti fanno clic sulla voce
di menu del calendario Vai alla data..., essi dovranno specificare una data sulla schermata che verrà visualizzata.
• Evitare di utilizzare simboli come gli asterischi (*) nelle etichette.

Sottomenu
Un sottomenu è un gruppo di voci di menu correlate che vengono visualizzate come un sottoinsieme di una voce di
menu nel menu completo. Includendo voci a un sottomenu, gli utenti possono trovare più facilmente le voci utilizzate
di frequente o quelle più importanti all'interno del menu completo. Il sottomenu include in genere i tipi seguenti di
azioni:
• invio di elementi in modalità diverse (ad esempio, invio di un'immagine in un messaggio e-mail, un messaggio
di MMS o come una cartolina audio)
• ordinamento, ricerca, individuazione e filtraggio degli elementi in modi diversi (ad esempio, filtraggio dei
messaggi per mittente oppure oggetto)

127
Guida allo sviluppo Sottomenu

• modifica della visualizzazione (ad esempio, la visualizzazione Giorno, Settimana o Agenda in un calendario)

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Quando una voce di menu è • Fare clic sul trackpad. • Toccare la voce di menu.
evidenziata in un menu • Spostare un dito verso destra sul • Fare clic sul trackpad.
completo, visualizzare un trackpad. • Spostare un dito verso destra sul
sottomenu. • Premere il tasto Menu. trackpad.
• Premere il tasto Invio. • Premere il tasto Menu.
• Premere il tasto Invio.
Scegliere una voce di menu • Fare clic sul trackpad. • Toccare la voce di menu.
da un sottomenu. • Premere il tasto Menu. • Fare clic sul trackpad.
• Premere il tasto Invio. • Premere il tasto Menu.
• Premere il tasto Invio.
Chiudere un sottomenu. • Spostare un dito verso sinistra sul • Toccare fuori del sottomenu.
trackpad. • Spostare un dito verso sinistra sul
• Pressione del tasto ESC. trackpad.
• Pressione del tasto ESC.
Chiudere un sottomenu e un Premere il tasto ESC due volte. • Toccare due volte fuori dal menu
menu completo. completo e dal sottomenu.
• Premere il tasto ESC due volte.
• Aprire o chiudere il cursore.

Viene visualizzata una freccia quando sono disponibili voci di sottomenu per una voce nel menu completo.

Una voce del menu completo con una freccia Un menu completo e un sottomenu

128
Guida allo sviluppo Sottomenu

Procedura consigliata: implementazione di sottomenu


• Utilizzare la sottoclasse Submenu per creare il sottomenu.
• Utilizzare i sottomenu per ridurre il numero di voci di menu nel menu completo. Ad esempio, se gli utenti devono
scorrere per vedere tutte le voci in un menu completo, raggruppare alcune delle voci di menu in un sottomenu.
• Raggruppare le voci correlate in un sottomenu. Ad esempio, se viene visualizzato "Ordina per" nel menu
completo, raggruppare "Data", "Nome" e "Oggetto" in un sottomenu.
• Considerare di raggruppare le funzionalità avanzate in un sottomenu. Ad esempio, utilizzare "Opzioni aggiuntive"
nel menu completo e raggruppare le opzioni nel sottomenu.
• Evitare di utilizzare sottomenu solo per una o due voci di menu.
• Se un sottomenu include più di sei voci, considerare di raggruppare le voci in due sezioni nel sottomenu.
Posizionare le voci di menu utilizzate di frequente nella parte superiore del sottomenu, inserire un separatore,
quindi ordinare il resto delle voci in senso alfabetico.
• Se una voce di menu richiede agli utenti altre operazioni rispetto a un semplice clic sulla voce (ad esempio, se
un utente deve specificare una data), aprire una finestra di dialogo.
• Evitare di includere le voci di menu utilizzate frequentemente o le voci di menu importanti nei sottomenu.
• Evitare di implementare un sottomenu da un sottomenu.
Linee guida per le etichette
• Nel menu completo, utilizzare etichette concise, descrittive che definiscono chiaramente l'azione. Non dovrebbe
essere necessario aprire il sottomenu per capire il significato della voce nel menu completo.
• Nel menu completo, utilizzare verbi per le etichette. Utilizzare sostantivi solo se il significato è chiaro. Ad esempio,
se viene visualizzato "Account e-mail" nel menu completo, raggruppare ciascun account e-mail in un sottomenu.
• Evitare di ripetere verbi nei sottomenu. Ad esempio, evitare di utilizzare "Ordina per" nel menu completo e
"Ordina per data" e "Ordina per nome" nel sottomenu.
• Iniziare le etichette con la lettera maiuscola. Scrivere la prima parola nel sottomenu con la lettera maiuscola,
anche se è una preposizione. Ad esempio, utilizzare "Invia"> "Come e-mail" invece di "come e-mail".
• Evitare di utilizzare il termine "Altro" nel menu completo, a meno che la posizione della voce di menu non indichi
chiaramente a cosa si riferisce "altro". Ad esempio, se vengono visualizzati "Posta in arrivo", "Posta in uscita" e
"Altro" tra i separatori nel menu completo, raggruppare le opzioni aggiuntive associate a una cassetta postale
in un sottomenu.

Creazione di un sottomenu
È possibile creare un sottomenu per l'applicazione BlackBerry®. Un sottomenu viene visualizzato quando un utente
seleziona una voce di menu a cui è associato un sottomenu.
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;

129
Guida allo sviluppo Sottomenu

2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe CreateSubmenuScreen, descritta nel passaggio 3, rappresenta la schermata
personalizzata.
public class CreateSubmenu extends UiApplication
{
public static void main(String[] args)
{
CreateSubmenu theApp = new CreateSubmenu();
theApp.enterEventDispatcher();
}
public CreateSubmenu()
{
pushScreen(new CreateSubmenuScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore di
schermata, richiamare setTitle() per specificare il titolo della schermata. Richiamare add() per aggiungere
un campo di testo alla schermata.
class CreateSubmenuScreen extends MainScreen
{
public CreateSubmenuScreen()
{
setTitle("Create Submenu Sample");
add(new RichTextField("Create a submenu"));
}
}
4. Creare le voci del sottomenu tramite la classe MenuItem. Per ciascuna voce del sottomenu, sovrascrivere run
() per specificare quale operazione viene selezionata dall'utente facendo clic sulla voce di menu. Quando
l'utente fa clic sulla voce di menu, l'applicazione richiama Menu.run().
private MenuItem _status1 = new MenuItem("Available", 100, 1)
{
public void run()
{
Dialog.inform("I'm available");
}
};
private MenuItem _status2 = new MenuItem("Unavailable", 200, 2)
{
public void run()
{
Dialog.inform("I'm unavailable");
}
};
5. Sovrascrivere makeMenu() per creare il menu per l'applicazione. Creare il sottomenu tramite la classe
SubMenu. Richiamare add() per aggiungere le voci del sottomenu al sottomenu. Richiamare super.makeMenu
() per creare il menu.

130
Guida allo sviluppo Sottomenu

protected void makeMenu( Menu menu, int instance )


{
SubMenu statusSubMenu = new SubMenu(null,"My Status",300,3);
statusSubMenu.add(_status1);
statusSubMenu.add(_status2);
menu.add(statusSubMenu);
super.makeMenu(menu, instance);
};

Esempio di codice: creazione di un sottomenu


import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
public class CreateSubmenu extends UiApplication
{
public static void main(String[] args)
{
CreateSubmenu theApp = new CreateSubmenu();
theApp.enterEventDispatcher();
}
public CreateSubmenu()
{
pushScreen(new CreateSubmenuScreen());
}
}
class CreateSubmenuScreen extends MainScreen
{
public CreateSubmenuScreen()
{
setTitle("Create Submenu Sample");
add(new RichTextField("Create a submenu"));
}
private MenuItem _status1 = new MenuItem("Available", 100, 1)
{
public void run()
{
Dialog.inform("I'm available");
}
};
private MenuItem _status2 = new MenuItem("Unavailable", 200, 2)
{
public void run()
{
Dialog.inform("I'm unavailable");
}
};
protected void makeMenu( Menu menu, int instance )
{
SubMenu statusSubMenu = new SubMenu(null,"My Status",300,3);
statusSubMenu.add(_status1);
statusSubMenu.add(_status2);
menu.add(statusSubMenu);

131
Guida allo sviluppo Menu a comparsa

super.makeMenu(menu, instance);
};
}

Menu a comparsa
Un menu a comparsa fornisce agli utenti un modo rapido per accedere alle azioni più comuni per una voce evidenziata.
È anche possibile utilizzare un menu a comparsa se una voce evidenziata dispone di più azioni ad essa associate o se
una voce evidenziata non dispone di alcuna azione primaria ad essa associata. È possibile creare un menu a comparsa
che contiene nove, sei e tre azioni.

Dispositivi BlackBerry con touchscreen e


Azione Dispositivi BlackBerry solo con trackpad
trackpad
Aprire il menu a comparsa • Fare clic sul trackpad. • Toccare la voce.
• Se un'azione primaria è stata già • Fare clic sul trackpad.
assegnata a una voce (ad esempio, • Se un'azione primaria è stata già
apre un messaggio), gli utenti assegnata a una voce (ad esempio,
possono tenere premuto il apre un messaggio), gli utenti
trackpad per aprire un menu a possono tenere premuto il
comparsa. trackpad o toccare e tenere
premuto un dito sul touchscreen
per aprire un menu a comparsa.
Scegliere una voce da un • Fare clic sul trackpad. • Toccare la voce.
menu a comparsa. • Premere il tasto Invio. • Fare clic sul trackpad.
• Premere il tasto Invio.
Chiudere un menu a Pressione del tasto ESC. • Toccare fuori dal menu a comparsa.
comparsa. • Pressione del tasto ESC.
• Aprire o chiudere il cursore.

132
Guida allo sviluppo Menu a comparsa

I menu a comparsa sostituiscono i menu di scelta rapida o i menu brevi. Qualsiasi menu di scelta rapida esistente
viene convertito automaticamente in menu a comparsa.

Procedura consigliata: implementazione di menu a comparsa


• Utilizzare menu a comparsa invece di menu di scelta rapida (menu brevi). Assicurarsi che il menu a comparsa
sia appropriato per gli utenti.
• Impostare la voce di menu che verrà scelta con maggiore probabilità dagli utenti come voce di menu predefinita.
La voce predefinita del menu a comparsa deve essere identica a quella del menu completo.
• Includere solo le azioni più comuni per una voce evidenziata in un menu a comparsa.
• Includere un'icona e un'etichetta per ogni voce nel menu a comparsa. Creare icone con una dimensione media
di 33 per 33 pixel. Queste icone vengono visualizzate in un'area disegno di 60 per 40 pixel e dovrebbero disporre
di spazio negativo.
Linee guida per la collocazione di voci nei menu a comparsa
• Collocare la voce di menu predefinita al centro del menu a comparsa.
• Ordinare il resto delle voci dalla più comune alla meno comune, secondo le posizioni numerate riportate di
seguito. Strutturare le azioni in modo simile all'ordine delle azioni che si trovano nelle altre
applicazioniBlackBerry®.

• Se le posizioni vengono riempite in modo dinamico, non visualizzare voci di menu che non sono disponibili.
Consentire alle voci di menu disponibili di cambiare posizione.
• Se non ci sono abbastanza azioni per riempire il menu, utilizzare un menu più piccolo. Se è necessario riempire
una o due posizioni, includere azioni utili quali Copia o Cerca. Se non si riempie una posizione, viene visualizzato
il messaggio "Cambia applicazione" o "Schermata iniziale".

Informazioni sul posizionamento di voci nei menu a comparsa


I menu a comparsa riportano voci di menu in una griglia 3 per 3, 3 per 2 o 3 per 1, a seconda del numero di voci. Per
impostazione predefinita, il menu a comparsa include sempre una voce per aprire il menu completo. È possibile
aggiungere fino a otto voci. Se si aggiungono più di otto voci, le voci aggiuntive non vengono visualizzate. È invece
possibile aggiungere voci aggiuntive al menu completo.
La prima voce che si aggiunge al vettore di elementi CommandItem è la voce predefinita nel menu a comparsa. La
voce predefinita viene visualizzata evidenziata al centro della griglia quando l'utente BlackBerry® apre il menu a
comparsa. Le altre voci sono posizionate nel menu a comparsa in base ordine in cui vengono aggiunte.

133
Guida allo sviluppo Menu a comparsa

Se il numero di voci aggiunte al menu a comparsa lascia alcune celle vuote nella griglia, vengono inserite voci di
riempimento al menu. La prima voce di riempimento è un'opzione per passare da un'applicazione all'altra. La seconda
voce di riempimento è un'opzione per tornare alla schermata iniziale.

Supporto per i menu di scelta rapida esistenti


Da BlackBerry® Java® SDK 6.0, un menu di scelta rapida dell'applicazione o un menu breve viene convertito in un
menu a comparsa. Se sono state aggiunte voci di menu a un menu di scelta rapida o sono state utilizzate voci che
sono state aggiunte al menu di scelta rapida per impostazione predefinita, non è necessario modificare il proprio
codice per visualizzare queste voci nel menu a comparsa. Tuttavia, BlackBerry Java SDK 6.0 include classi e interfacce
che possono essere utilizzate per creare un menu a comparsa e consente di utilizzare l'API Command Framework e
rendere il proprio codice più modulare. Ad esempio, se l'applicazione in uso dispone di un componente dell'interfaccia
utente e di una voce di menu che eseguono la stessa funzione, utilizzando l'API Command Framework, è possibile
scrivere il codice per quella funzione una volta e utilizzarlo in ogni parte dell'applicazione, nonché renderlo disponibile
per le altre applicazioni da utilizzare.
In una voce di menu di scelta rapida è stato incluso un numero ordinale che ha determinato il collocamento della
voce nel menu. Più il numero ordinale è basso, più è alta la posizione della voce nel menu. Quando un menu di scelta
rapida viene convertito in un menu a comparsa, la voce di menu che dispone del numero ordinale inferiore diventa
la voce predefinita del menu a comparsa. Le restanti voci vengono aggiunte al menu a comparsa dal numero ordinale
più basso al più alto. Se un'icona è stata associata a una voce di menu nel menu di scelta rapida esistente, viene
utilizzata per la voce nel menu a comparsa. Altrimenti, viene utilizzata un'icona predefinita. In maniera simile agli
altri menu a comparsa, nel menu a comparsa vengono visualizzate solo le prime otto voci del menu di scelta rapida.
Se il menu di scelta rapida dispone di più di otto voci di menu, assicurarsi di utilizzare appropriatamente i numeri
ordinali per le voci di menu, in modo che le voci più importanti e utili vengano visualizzate nel menu a comparsa.
Per ulteriori informazioni sulla creazione di menu di scelta rapida, visitare il Centro di risorse per sviluppatori
BlackBerry sul sito Web www.blackberry.com/developer e leggere l'argomento relativo alla distinzione tra un menu
completo e un menu di azioni primarie.

Creazione di un menu a comparsa


È possibile creare un menu a comparsa utilizzando le classi disponibili nel pacchetto
net.rim.device.api.ui.menu ed è possibile definire la funzionalità delle voci del menu a comparsa utilizzando
l'API Command Framework.

134
Guida allo sviluppo Menu a comparsa

Un menu a comparsa consiste in un provider di menu di scelta rapida, un provider di voci di comando e voci di
comando.

Componente Descrizione
Provider di menu di scelta rapida Si utilizza la classe DefaultContextMenuProvider per creare e
visualizzare un menu a comparsa della schermata. Quando un utente
BlackBerry® apre un menu a comparsa, il provider del menu di scelta rapida
cerca i campi sulla schermata che sono provider di voci di comando.
DefaultContextMenuProvider è l'implementazione predefinita di
ContextMenuProvider. Se non viene fornita una schermata con un
provider del menu di scelta rapida, il menu di scelta rapida esistente viene
convertito e visualizzato come un menu a comparsa.
Provider di voci di comando Si utilizza la classe CommandItemProvider per configurare un campo sulla
schermata dell'interfaccia utente in modo che il campo possa fornire il
contesto e le voci di comando al menu a comparsa in base al contesto
attuale. Ad esempio, è possibile configurare un indirizzo e-mail come un
provider di voci di comando e fornire all'utente diverse azioni in base alla
possibilità che l'indirizzo e-mail sia nell'elenco contatti dell'utente.
Voci di comando Si utilizza la classe CommandItem per specificare il testo, l'icona e il
comportamento di una voce del menu a comparsa. Si definisce il
comportamento del menu a comparsa tramite un comando. Il comando
agisce come proxy per un'istanza di un gestore di comando, che definisce
la funzionalità della voce del menu a comparsa. Ad esempio, per un indirizzo
e-mail, è possibile fornire le voci di comando per aggiungere o visualizzare
un contatto in base alla possibilità che l'indirizzo e-mail selezionato venga
visualizzato nell'elenco contatti dell'utente. Il gestore di comando deve
contenere il codice per aggiungere o visualizzare il contatto.
Per ulteriori informazioni sui comandi e i gestori di comando, vedere API
Command Framework. L'applicazione di esempio della struttura dei
comandi fornita in BlackBerry® Java® SDK mostra i comandi e i gestori di
comando.

Se si utilizza un menu di scelta rapida esistente, BlackBerry® Device Software 6.0 converte le voci del menu di scelta
rapida in voci di comando e le fornisce al provider di voci di comando. Per ulteriori informazioni, consultareSupporto
per i menu di scelta rapida esistenti.

Creazione di un menu a comparsa


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.command.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;

135
Guida allo sviluppo Menu a comparsa

import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.menu.*;
import net.rim.device.api.ui.image.*;
import net.rim.device.api.util.*;
import java.util.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe MyPopUpMenuScreen, descritta nel passaggio 3, rappresenta la schermata
personalizzata.
public class MyPopUpMenuApp extends UiApplication
{
public static void main(String[] args)
{
Mypop-upMenuApp theApp = new Mypop-upMenuApp();
theApp.enterEventDispatcher();
}
public Mypop-upMenuApp()
{
pushScreen(new Mypop-upMenuScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore della
schermata, richiamare setTitle() per specificare il titolo della schermata.
class MyPopUpMenuScreen extends MainScreen
{
EmailAddressEditField emailAddress;
public Mypop-upMenuScreen()
{
setTitle("Pop-Up Menu Demo");
}
}
4. Nel costruttore di schermata, specificare un provider di menu di scelta rapida. Passare un oggetto
DefaultContextMenuProvider a Screen.setContextMenuProvider() per consentire la visualizzazione
di un menu a comparsa nella schermata.
setContextMenuProvider(new DefaultContextMenuProvider());
5. Nel costruttore della schermata, creare i componenti dell'interfaccia utente che possono richiamare il menu a
comparsa. Nel seguente esempio di codice, l'etichetta utilizza la proprietà Field.FOCUSABLE per consentire
agli utenti di evidenziare il campo .
LabelField labelField = new LabelField("Click to invoke pop-up menu",
Field.FOCUSABLE);
emailAddress = new EmailAddressEditField("Email address: ", "name@blackberry.com",
40);

136
Guida allo sviluppo Menu a comparsa

6. Nel costruttore della schermata, configurare i componenti dell'interfaccia utente come provider di voci di
comando. L'oggetto DefaultContextMenuProvider cerca i campi configurati come provider di voci di
comando e li utilizza per creare e visualizzare un menu a comparsa. Per ogni componente, richiamare
Field.setCommandItemProvider() per configurare il campo come un provider di voci di comando. La classe
ItemProvider è descritta nel passaggio 7.
ItemProvider itemProvider = new ItemProvider();
labelField.setCommandItemProvider(itemProvider);
emailAddress.setCommandItemProvider(itemProvider);
7. Nella schermata personalizzata, implementare l'interfaccia CommandItemProvider. In getContext(),
restituire il campo configurato come provider di voci di comando. In getItems(), creare un oggetto Vector
per aggiungervi le voci del menu a comparsa.
class ItemProvider implements CommandItemProvider
{
public Object getContext(Field field)
{
return field;
}
public Vector getItems(Field field)
{
}
}
8. In getItems(), fornire le voci del menu a comparsa creando istanze della classe CommandItem. Per ciascuna
voce di comando, specificare il testo, l'icona e il comando del menu a comparsa. Nel seguente esempio di codice,
viene utilizzata un'istruzione if-then-else per controllare quale componente ha richiamato il menu a
comparsa prima di creare CommandItem. Il comando funziona come un proxy a un'istanza di una classe che
estende la classe astratta CommandHandler, come descritto nel passaggio 9. Richiamare Vector.addElement
() per aggiungere le voci del menu a comparsa a Vector. Restituire Vector.
CommandItem defaultCmd;
Image myIcon = ImageFactory.createImage(Bitmap.getBitmapResource("my_logo.png"));
if(field.equals(emailAddress)){
defaultCmd = new CommandItem(new StringProvider("Email Address"), myIcon, new
Command(new DialogCommandHandler()));
}
else {
defaultCmd = new CommandItem(new StringProvider("Label Field"), myIcon, new
Command(new DialogCommandHandler()));
}
items.addElement(defaultCmd);
return items;
9. Nella schermata personalizzata, creare un gestore di comando creando una classe che estende la classe astratta
CommandHandler. In execute(), definire la funzionalità che si desidera associare alle voci del menu a
comparsa. Il gestore di comando potrebbe essere utilizzato da qualsiasi componente dell'interfaccia utente sulla
schermata (ad esempio le voci, i pulsanti del menu completo, e così via). Poiché canExecute() non è
implementato, questo comando è sempre eseguibile. Nel seguente esempio di codice, viene visualizzata una
finestra di dialogo quando l'utente fa clic su una voce del menu a comparsa.

137
Guida allo sviluppo Menu a comparsa

class DialogCommandHandler extends CommandHandler


{
public void execute(ReadOnlyCommandMetadata metadata, Object context)
{
Dialog.alert("Executing command for " + context.toString());
}
}

Esempio di codice: creazione di un menu a comparsa


import net.rim.device.api.command.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.menu.*;
import net.rim.device.api.ui.image.*;
import net.rim.device.api.util.*;
import java.util.*;
public class MyPopUpMenuApp extends UiApplication
{
public static void main(String[] args)
{
MyPopUpMenuApp theApp = new MyPopUpMenuApp();
theApp.enterEventDispatcher();
}
public MyPopUpMenuApp()
{
pushScreen(new MyPopUpMenuScreen());
}
}
class MyPopUpMenuScreen extends MainScreen
{
EmailAddressEditField emailAddress;
public MyPopUpMenuScreen()
{
setTitle("Pop-Up Menu Demo");
setContextMenuProvider(new DefaultContextMenuProvider());
LabelField labelField = new LabelField("Click to invoke pop-up menu",
Field.FOCUSABLE);
emailAddress = new EmailAddressEditField("Email address: ",
"name@blackberry.com", 40);
ItemProvider itemProvider = new ItemProvider();
labelField.setCommandItemProvider(itemProvider);
emailAddress.setCommandItemProvider(itemProvider);
add(labelField);
add(emailAddress);
}
/* To override the default functionality that prompts the user to save changes
before the application closes,
* override the MainScreen.onSavePrompt() method. In the following code sample,
the return value is true which
* indicates that the application does not prompt the user before closing.
*/
protected boolean onSavePrompt()

138
Guida allo sviluppo Aggiunta di una voce di menu a un'applicazione BlackBerry Device Software

{
return true;
}
class ItemProvider implements CommandItemProvider
{
public Object getContext(Field field)
{
return field;
}
public Vector getItems(Field field)
{
Vector items = new Vector();
CommandItem defaultCmd;
Image myIcon = ImageFactory.createImage(Bitmap
.getBitmapResource("my_logo.png"));
if(field.equals(emailAddress)){
defaultCmd = new CommandItem(new StringProvider("Email Address"),
myIcon, new Command(new DialogCommandHandler()));
}
else{
defaultCmd = new CommandItem(new StringProvider("Label Field"),
myIcon, new Command(new DialogCommandHandler()));
}
items.addElement(defaultCmd);
return items;
}
}
class DialogCommandHandler extends CommandHandler
{
public void execute(ReadOnlyCommandMetadata metadata, Object context)
{
Dialog.alert("Executing command for " + context.toString());
}
}
}

Aggiunta di una voce di menu a un'applicazione BlackBerry


Device Software
È possibile aggiungere una voce di menu a un'applicazione BlackBerry® Device Software utilizzando l'API Menu Item
disponibile nel pacchetto net.rim.blackberry.api.menuitem. È possibile, ad esempio, aggiungere una voce di
menu chiamata Visualizza ordini di vendita all'applicazione Contatti di un dispositivo BlackBerry per far sì che, quando
un utente fa clic su tale voce, venga aperta un'applicazione CRM e venga visualizzato un elenco di ordini di vendita
per tale contatto.
La classe ApplicationMenuItemRepository fornisce le costanti che specificano in quale applicazione BlackBerry
Device Software debba essere visualizzata la voce. La costante MENUITEM_MESSAGE_LIST specifica ad esempio che
la voce di menu deve essere visualizzata nell'applicazione Messaggi.

139
Guida allo sviluppo Aggiunta di una voce di menu a un'applicazione BlackBerry Device Software

Aggiunta di una voce di menu a un'applicazione BlackBerry Device


Software
1. Importare le classi e le interfacce richieste.
import net.rim.blackberry.api.menuitem.*;
import net.rim.blackberry.api.pdap.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
2. Estendere la classe ApplicationMenuItem astratta per creare una voce di menu. Sovrascrivere il costruttore
ApplicationMenuItem() con un numero intero per specificare la posizione della voce all'interno del menu.
Un numero elevato posiziona la voce più in basso all'interno del menu.
public class SampleMenuItem extends ApplicationMenuItem
{
SampleMenuItem()
{
super(20);
}
}
3. Implementare toString() per specificare il testo della voce di menu.
public String toString()
{
return "Open the Contacts Demo application";
}
4. Richiamare getInstance() per recuperare il repository dell'applicazione.
ApplicationMenuItemRepository repository =
ApplicationMenuItemRepository.getInstance();
5. Creare un'istanza di una classe per estendere la classe MenuItem.
ContactsDemoMenuItem contactsDemoMenuItem = new
ContactsDemoMenuItem();
6. Richiamare ApplicationMenuItemRepository.addMenuItem() per aggiungere la voce di menu al
repository dell'applicazione BlackBerry® pertinente.
repository.addMenuItem(ApplicationMenuItemRepository
.MENUITEM_ADDRESSCARD_VIEW, contactsDemoMenuItem);
7. Implementare run() per specificare il comportamento della voce di menu. Nell'esempio di codice seguente,
quando si fa clic sulla nuova voce di menu e un oggetto Contact esiste, l'applicazione ContactsDemo riceve
l'evento e richiama ContactsDemo.enterEventDispatcher().
public Object run(Object context)
{
BlackBerryContact c = (BlackBerryContact)context;
if ( c != null )
{
new ContactsDemo().enterEventDispatcher();

140
Guida allo sviluppo Modifica dell'aspetto di un menu

}
else
{
throw new IllegalStateException( "Context is null, expected a Contact
instance");
}
Dialog.alert("Viewing an email message in the email view");
return null;
}

Modifica dell'aspetto di un menu


È possibile modificare lo sfondo, il bordo e il carattere di un menu utilizzando la classe Menu del pacchetto
net.rim.device.api.ui.component. È possibile, ad esempio, modificare l'aspetto del menu in modo che sia
simile agli altri elementi dell'applicazione BlackBerry® in uso. Quando si modifica l'aspetto di un menu, l'applicazione
BlackBerry sovrascrive il tema impostato sul dispositivo BlackBerry.

Modifica dell'aspetto di un menu


1. Importare le classi e le interfacce richieste.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.decor.*;
import net.rim.device.api.system.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe CreateCustomMenuScreen, descritta nel passaggio 3, rappresenta la schermata
personalizzata.
public class CreateCustomMenu extends UiApplication
{
public static void main(String[] args)
{
CreateCustomMenu theApp = new CreateCustomMenu();
theApp.enterEventDispatcher();
}
public CreateCustomMenu()
{
pushScreen(new CreateCustomMenuScreen());
}
}
3. Creare la schermata personalizzata per l'applicazione estendendo la classe MainScreen. Nel costruttore di
schermata, richiamare setTitle() per specificare il titolo della schermata. Richiamare add() per visualizzare
un campo di testo sulla schermata.

141
Guida allo sviluppo Modifica dell'aspetto di un menu

class CreateCustomMenuScreen extends MainScreen


{
Background _menuBackground;
Border _menuBorder;
Font _menuFont;
CreateCustomMenuScreen()
{
setTitle("Custom Menu Sample");
add(new RichTextField("Creating a custom menu"));
}
}
4. Nel costruttore della schermata specificare l'aspetto del menu. Assegnare uno spazio al bordo del menu creando
un oggetto XYEdges. Richiamare createRoundedBorder() per creare un bordo con gli angoli arrotondati.
Richiamare createSolidTransparentBackground() per assegnare un colore trasparente allo sfondo del
menu.
XYEdges thickPadding = new XYEdges(10, 10, 10, 10);
_menuBorder = BorderFactory.createRoundedBorder(thickPadding,
Border.STYLE_DOTTED);
_menuBackground = BackgroundFactory.createSolidTransparentBackground(Color
.LIGHTSTEELBLUE, 50);
5. Nel costruttore della schermata specificare il carattere utilizzato nel menu servendosi di un oggetto
FontFamily. Richiamare forName() per recuperare un carattere dal dispositivo BlackBerry®. Richiamare
getFont() per specificare lo stile e le dimensioni del carattere.
try
{
FontFamily family = FontFamily.forName("BBCasual");
_menuFont = family.getFont(Font.PLAIN, 30, Ui.UNITS_px);
}
catch(final ClassNotFoundException cnfe)
{
UiApplication.getUiApplication().invokeLater(new Runnable()
{
public void run()
{
Dialog.alert("FontFamily.forName() threw " + cnfe.toString());
}
});
}
6. Nella classe della schermata sovrascrivere makeMenu() per applicare l'aspetto del menu. Richiamare
setBackground(), setBorder() e setFont() per applicare l'aspetto del menu specificato nei passi 4 e 5.
protected void makeMenu(Menu menu, int context)
{
menu.setBorder(_menuBorder);
menu.setBackground(_menuBackground);
menu.setFont(_menuFont);
super.makeMenu(menu, context);
}

142
Guida allo sviluppo Modifica dell'aspetto di un menu

Esempio di codice: modifica dell'aspetto di un menu


import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.decor.*;
import net.rim.device.api.system.*;
public class CreateCustomMenu extends UiApplication
{
public static void main(String[] args)
{
CreateCustomMenu theApp = new CreateCustomMenu();
theApp.enterEventDispatcher();
}
public CreateCustomMenu()
{
pushScreen(new CreateCustomMenuScreen());
}
}
class CreateCustomMenuScreen extends MainScreen
{
Border _menuBorder;
Background _menuBackground;
Font _menuFont;
CreateCustomMenuScreen()
{
setTitle("Custom Menu Sample");
add(new RichTextField("Creating a custom menu"));
XYEdges thickPadding = new XYEdges(10, 10, 10, 10);
_menuBorder = BorderFactory.createRoundedBorder(thickPadding,
Border.STYLE_DOTTED);
_menuBackground = BackgroundFactory.createSolidTransparentBackground(Color
.LIGHTSTEELBLUE, 50);
try
{
FontFamily family = FontFamily.forName("BBCasual");
_menuFont = family.getFont(Font.PLAIN, 30, Ui.UNITS_px);
}
catch(final ClassNotFoundException cnfe)
{
UiApplication.getUiApplication().invokeLater(new Runnable()
{
public void run()
{
Dialog.alert("FontFamily.forName() threw " + cnfe.toString());
}
});
}
}
protected void makeMenu(Menu menu, int context)
{
menu.setBorder(_menuBorder);
menu.setBackground(_menuBackground);
menu.setFont(_menuFont);

143
Guida allo sviluppo Modifica dell'aspetto di un menu

super.makeMenu(menu, context);
}
}

144
Guida allo sviluppo Caratteri personalizzati

Caratteri personalizzati 11
La classe FontManager del pacchetto net.rim.device.api.ui fornisce costanti e metodi che è possibile
utilizzare per installare e disinstallare un carattere TrueType su un dispositivo BlackBerry®. La dimensione massima
consentita per il file del carattere TrueType è 60 KB. È possibile specificare se il carattere è disponibile per
l'applicazione che installa tale carattere o per tutte le applicazioni sul dispositivo BlackBerry.
La classe FontManager fornisce anche i metodi per impostare il carattere predefinito per il dispositivo o l'applicazione
BlackBerry.

Installazione e utilizzo di un carattere personalizzato in una


BlackBerry Java Application
1. Importare le classi e le interfacce richieste.
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.*;
import java.util.*;
2. Creare il framework dell'applicazione estendendo la classe UiApplication. In main(), creare un'istanza della
nuova classe e richiamare enterEventDispatcher() per abilitare l'applicazione a ricevere gli eventi. Nel
costruttore dell'applicazione, richiamare pushScreen() per visualizzare la schermata personalizzata per
l'applicazione. La classe FontLoadingDemoScreen, come descritto al passaggio 3, rappresenta la schermata
personalizzata.
public class FontLoadingDemo extends UiApplication
{
public static void main(String[] args)
{
FontLoadingDemo app = new FontLoadingDemo();
app.enterEventDispatcher();
}
public FontLoadingDemo()
{
pushScreen(new FontLoadingDemoScreen());
}
}
3. Creare la schermata personalizzata estendendo la classe MainScreen. Richiamare setTitle() per impostare
il testo visualizzato nella sezione del titolo della schermata. Creare un nuovo oggetto LabelField. Applicare il
carattere personalizzato a questo oggetto.
class FontLoadingDemoScreen extends MainScreen
{
public FontLoadingDemoScreen()
{
setTitle("Font Loading Demo");

145
Guida allo sviluppo Esempio di codice: installazione e utilizzo di un carattere personalizzato in una BlackBerry Java Application

LabelField helloWorld = new LabelField("Hello World");


}
}
4. Nel costruttore della schermata richiamare il metodo FontManager.getInstance() per ottenere un
riferimento all'oggetto FontManager, quindi richiamare il metodo load() per installare il carattere. Includere
la chiamata a load() in un'istruzione IF per verificare che l'installazione sia stata eseguita correttamente. Il
metodo load() restituisce un contrassegno che specifica se il carattere è stato installato correttamente. Il
codice seguente specifica che il carattere può essere utilizzato soltanto dall'applicazione.
if (FontManager.getInstance().load("Myfont.ttf", "MyFont",
FontManager.APPLICATION_FONT) == FontManager.SUCCESS)
{
}
5. Nel costruttore della schermata, in un blocco try/catch dell'istruzione IF creato nel passaggio 5, creare un oggetto
Font per il carattere appena installato. Richiamare il metodo setFont() per applicare il carattere all'oggetto
LabelField creato nel passaggio 5.
try
{
FontFamily family = FontFamily.forName("MyFont");
Font myFont = family.getFont(Font.PLAIN, 50);
helloWorld.setFont(myFont);
}
catch (ClassNotFoundException e)
{
System.out.println(e.getMessage());
}
6. Nel costruttore di schermata, richiamare add() per aggiungere LabelField alla schermata.
add(helloWorld);

Esempio di codice: installazione e utilizzo di un carattere


personalizzato in una BlackBerry Java Application
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.*;
import java.util.*;
public class FontLoadingDemo extends UiApplication
{
public static void main(String[] args)
{
FontLoadingDemo app = new FontLoadingDemo();
app.enterEventDispatcher();
}
public FontLoadingDemo()
{
pushScreen(new FontLoadingDemoScreen());
}

146
Guida allo sviluppo Esempio di codice: installazione e utilizzo di un carattere personalizzato in una BlackBerry Java Application

}
class FontLoadingDemoScreen extends MainScreen
{
public FontLoadingDemoScreen()
{
setTitle("Font Loading Demo");
LabelField helloWorld = new LabelField("Hello World");
if (FontManager.getInstance().load("Myfont.ttf", "MyFont",
FontManager.APPLICATION_FONT) == FontManager.SUCCESS)
{
try
{
FontFamily typeface = FontFamily.forName("MyFont");
Font myFont = typeface.getFont(Font.PLAIN, 50);
helloWorld.setFont(myFont);
}
catch (ClassNotFoundException e)
{
System.out.println(e.getMessage());
}
}
add(helloWorld);
}
}

147
Guida allo sviluppo Controllo ortografico

Controllo ortografico 12
È possibile utilizzare le voci del pacchetto net.rim.blackberry.api.spellcheck per aggiungere la funzionalità
di controllo ortografico a un'applicazione. L'interfaccia SpellCheckEngine attiva un'applicazione in grado di
controllare l'ortografia di un valore presente in un campo dell'interfaccia utente e fornisce all'utente BlackBerry® le
opzioni per effettuare le correzioni ortografiche necessarie. L'interfaccia SpellCheckUI attiva un'applicazione in
grado di fornire un'interfaccia utente che consenta all'utente BlackBerry di risolvere un problema di ortografia
interagendo con l'implementazione di SpellCheckEngine.
Per ulteriori informazioni su come utilizzare l'API Spell Check, vedere l'applicazione di prova relativa al controllo
ortografico, fornita con BlackBerry® Java® Development Environment 4.3.1 o versione successiva e con BlackBerry®
Java® Plug-in per Eclipse®.

Aggiunta della funzionalità di controllo ortografico


1. Importare le seguenti classi:
• net.rim.blackberry.api.spellcheck.SpellCheckEngineFactory
• java.lang.StringBuffer
2. Importare le seguenti interfacce:
• net.rim.blackberry.api.spellcheck.SpellCheckEngine
• net.rim.blackberry.api.spellcheck.SpellCheckUI
• net.rim.blackberry.api.spellcheck.SpellCheckUIListener
3. Creare le variabili per gli oggetti del controllo ortografico
SpellCheckEngine _spellCheckEngine;
SpellCheckUI _spellCheckUI;
4. Richiamare createSpellCheckUI().
_spellCheckUI = SpellCheckEngineFactory.createSpellCheckUI();
5. Per inviare una notifica a un'applicazione quando si verifica un evento del controllo ortografico, richiamare
addSpellCheckUIListener() con un oggetto SpellCheckUIListener come parametro.
_spellCheckUI.addSpellCheckUIListener(new SpellCheckUIListener());
6. Per far sì che un'applicazione esegua il controllo ortografico di alcuni campi dell'interfaccia utente e suggerisca
delle correzioni ortografiche all'utente BlackBerry, ottenere un oggetto SpellCheckEngine e richiamare
getSpellCheckEngine().
_spellCheckEngine = _spellCheckUI.getSpellCheckEngine();
7. Per utilizzare una correzione per una parola con ortografia errata, richiamare
SpellCheckEngine.learnCorrection(). Utilizzare i parametri new StringBuffer(text), new
StringBuffer(correction), dove text rappresenta la parola con ortografia errata e correction
rappresenta la parola corretta.

148
Guida allo sviluppo Ascolto di un evento di controllo ortografico

_spellCheckEngine.learnCorrection(new StringBuffer(text), new StringBuffer


(correction));
8. Per eseguire le operazioni di controllo ortografico su un campo, richiamare SpellCheckUI.spellCheck(),
con un field come parametro.
_spellCheckUI.spellCheck(field);
9. Per accettare una parola con ortografia errata come corretta, richiamare SpellCheckEngine.learnWord
(), con la parola da apprendere come parametro.
_spellCheckEngine.learnWord(new StringBuffer(word));

Ascolto di un evento di controllo ortografico


1. Importare le seguenti classi:
• java.lang.StringBuffer
• net.rim.device.api.ui.UiApplication
• net.rim.device.api.ui.Field
2. Importare le seguenti interfacce:
• net.rim.blackberry.api.spellcheck.SpellCheckUIListener
• net.rim.blackberry.api.spellcheck.SpellCheckEngine
3. Creare un metodo che restituisca la costante SpellCheckUIListener.LEARNING_ACCEPT quando
SpellCheckEngine apprende una parola nuova.
public int wordLearned(SpellCheckUI ui, StringBuffer word) {
UiApplication.getUiApplication().invokeLater(new popUpRunner("Word learned"));
return SpellCheckUIListener.LEARNING_ACCEPT;
}
4. Creare un metodo che restituisca la costante SpellCheckUIListener.LEARNING_ACCEPT quando
SpellCheckEngine apprende la correzione di una parola.
public int wordCorrectionLearned(SpellCheckUI ui, StringBuffer word, StringBuffer
correction){
UiApplication.getUiApplication().invokeLater(new popUpRunner("Correction
learned"));
return SpellCheckUIListener.LEARNING_ACCEPT;
}
5. Creare un metodo che restituisca la costante SpellCheckUIListener.ACTION_OPEN_UI quando
SpellCheckEngine trova una parola con ortografia errata.
public int misspelledWordFound(SpellCheckUI ui, Field field, int offset, int len){
UiApplication.getUiApplication().invokeLater(new popUpRunner("Misspelled word
found"));
return SpellCheckUIListener.ACTION_OPEN_UI;
}

149
Guida allo sviluppo Risorse correlate

Risorse correlate 13
• www.blackberry.com/go/apiref: per trovare la versione più recente del riferimento API per BlackBerry® Java®
SDK.
• www.blackberry.com/go/devguides: per trovare guide allo sviluppo, note sulla versione e panoramiche delle
applicazioni di esempio per BlackBerry Java SDK.
• www.blackberry.com/developers: visitare BlackBerry® Developer Zone per trovare risorse sullo sviluppo di
applicazioni per dispositivi BlackBerry.
• www.blackberry.com/go/developerkb: per leggere articoli della Knowledge Base relativi allo sviluppo di
BlackBerry.
• www.blackberry.com/developers/downloads: per trovare i più recenti strumenti per lo sviluppo e download
per lo sviluppo di applicazioni per dispositivi BlackBerry.

150
Guida allo sviluppo Glossario

Glossario 14
3-D
tridimensionale

API
Application Programming Interface

JVM
Java® Virtual Machine

MIDP
Mobile Information Device Profile

151
Guida allo sviluppo Commenti e suggerimenti

Commenti e suggerimenti 15
Per fornire commenti su questo prodotto, visitare il sito www.blackberry.com/docsfeedback.

152
Guida allo sviluppo Cronologia delle revisioni del documento

Cronologia delle revisioni del documento 16


Data Descrizione
16 agosto 2010 È stato rimosso il seguente argomento:
• Creazione di un indicatore di progresso
3 agosto 2010 Sono stati aggiunti i seguenti argomenti:
• Accesso a un'immagine codificata attraverso un flusso di input
• Informazioni sul posizionamento di voci nei menu a comparsa
• Procedura consigliata: implementazione di menu a comparsa
• Procedura consigliata: implementazione di sottomenu
• API Command Framework
• Creazione di un menu a comparsa
• Creazione di un menu a comparsa
• Creazione di un sottomenu
• Visualizzazione di un'etichetta in una posizione assoluta della
schermata
• Visualizzazione di un'immagine codificata
• Visualizzazione di un'immagine per zoom e panoramica
• Visualizzazione di una fila di immagini per lo scorrimento
• Visualizzazione di un campo in una posizione assoluta della schermata

• Visualizzazione di un'immagine per zoom e panoramica


• Visualizzazione di una fila di immagini per lo scorrimento
• Avvicinamento e allontanamento del pollice e dell'indice sullo schermo

• Azioni di spostamento tramite trackpad


• Codifica di un'immagine
• Immagini
• Indicazione dell'attività
• Indicazione di progresso
• Indicazione del progresso delle attività
• Avvicinamento o allontanamento del pollice e dell'indice sullo schermo

• Menu a comparsa
• Specifica della modalità di decodifica di un'immagine
• Specifica della dimensione di visualizzazione di un'immagine codificata

• Sottomenu

153
Guida allo sviluppo Cronologia delle revisioni del documento

Data Descrizione
• Supporto per i menu di scelta rapida esistenti
• Azioni di spostamento tramite trackpad
• Modelli di interazione del touchscreen
• Utilizzo di un comando in una o più applicazioni
• Utilizzo di un comando con un componente dell'interfaccia utente
• Utilizzo di immagini codificate
Sono stati aggiunti i seguenti esempi di codice:
• Esempio di codice: creazione di un menu a comparsa
• Esempio di codice: creazione di un sottomenu
• Esempio di codice: visualizzazione di una fila di immagini per lo
scorrimento
• Esempio di codice: visualizzazione di un'etichetta in una posizione
assoluta della schermata
• Esempio di codice: visualizzazione di un'immagine per zoom e
panoramica
Sono stati modificati i seguenti argomenti:
• Indicatori di attività e indicatori di progresso
• Pulsanti
• Creazione di un'interfaccia utente compatibile con le interfacce utente
BlackBerry standard
• Finestre di dialogo
• Elenchi a discesa
• Elenchi e tabelle
• Selettori
• Pulsanti di opzione
• Ricerca
• Caselle di selezione
• Campi di testo
• Visualizzazioni ad albero
Sono stati rimossi i seguenti argomenti:
• Aggiunta di un'icona a una voce di menu
• Aggiunta di un'icona a una voce di menu
• Esempio di codice: aggiunta di un'icona a una voce di menu

154
Guida allo sviluppo Note legali

Note legali 17
©2010 Research In Motion Limited. Tutti i diritti riservati. BlackBerry®, RIM®, Research In Motion® e i relativi marchi,
nomi e logo sono di proprietà di Research In Motion Limited e sono registrati e/o utilizzati negli Stati Uniti e in altri
Paesi.
Eclipse è un marchio di Eclipse Foundation, Inc. Java è un marchio di Oracle America, Inc. TrueType è un marchio di
Apple Inc. Tutti gli altri marchi sono di proprietà dei rispettivi titolari.

La presente documentazione, compresa tutta la documentazione ivi allegata come riferimento, ad esempio la
documentazione fornita o resa disponibile sul sito www.blackberry.com/go/docs, viene fornita o resa accessibile
"COSÌ COM'È" e "SE DISPONIBILE" e senza alcuna condizione, approvazione, garanzia o dichiarazione di alcun tipo da
parte di Research In Motion Limited e delle relative società affiliate ("RIM") e RIM non si assume alcuna responsabilità
per errori tipografici, tecnici o per altre imprecisioni, errori od omissioni presenti nella documentazione. Al fine di
tutelare le informazioni proprietarie e riservate e/o i segreti commerciali di RIM, è possibile che alcuni aspetti delle
tecnologie di RIM vengano descritti in modo generico nella presente documentazione. RIM si riserva il diritto di
modificare periodicamente le informazioni contenute nella presente documentazione, senza alcun obbligo di
distribuzione agli abbonati di modifiche, aggiornamenti, miglioramenti o aggiunte al documento in tempo utile.
La presente documentazione potrebbe contenere riferimenti a fonti di informazioni, hardware o software, prodotti
o servizi di terzi, compresi componenti e contenuti protetti da copyright e/o siti Web di terzi (collettivamente
denominati "Prodotti e servizi di terzi"). RIM non controlla né è responsabile per eventuali Prodotti e servizi di terzi,
inclusi, senza alcuna limitazione, il contenuto, l'accuratezza, la conformità al copyright, le prestazioni, la compatibilità,
l'affidabilità, la legalità, la decenza, i collegamenti o qualsiasi altro aspetto dei Prodotti e servizi di terzi. La presenza
di riferimenti a Prodotti e servizi di terzi nella presente documentazione non implica in nessun caso l'approvazione
da parte di RIM dei Prodotti e servizi di terzi o dei terzi.
A MENO CHE LE LEGGI APPLICABILI NELLA GIURISDIZIONE VIGENTE LO PROIBISCANO, CON IL PRESENTE DOCUMENTO
SI ESCLUDONO TUTTE LE CONDIZIONI, APPROVAZIONI, GARANZIE, DICHIARAZIONI IMPLICITE O ESPLICITE DI OGNI
GENERE, COMPRESE, SENZA ALCUNA LIMITAZIONE, LE CONDIZIONI, APPROVAZIONI, GARANZIE, DICHIARAZIONI O
GARANZIE DI DURATA, IDONEITÀ A UN PARTICOLARE SCOPO O USO, COMMERCIABILITÀ, QUALITÀ, NON VIOLAZIONE,
QUALITÀ SODDISFACENTE O TITOLO, OVVERO DERIVANTI DA STATUTI O USANZE COMMERCIALI O USI DI
COMMERCIO, O ANCORA CORRELATE ALLA DOCUMENTAZIONE O ALL'USO DI QUESTA, OVVERO ALLE PRESTAZIONI
O ALLE MANCATE PRESTAZIONI DI SOFTWARE, HARDWARE, SERVIZI O QUALSIASI TIPO DI PRODOTTI E SERVIZI DI
TERZI IVI NOMINATI. L'UTENTE POTREBBE INOLTRE GODERE DI ULTERIORI DIRITTI A SECONDA DELLO STATO O DELLA
PROVINCIA DI APPARTENENZA. È POSSIBILE CHE ALCUNE GIURISDIZIONI NON CONSENTANO L'ESCLUSIONE O LA
LIMITAZIONE DI GARANZIE E CONDIZIONI IMPLICITE. NEI LIMITI CONSENTITI DALLA LEGGE, TUTTE LE GARANZIE E
CONDIZIONI IMPLICITE IN RELAZIONE ALLA PRESENTE DOCUMENTAZIONE, CONSIDERANDO CHE LA LORO
ESCLUSIONE NON È CONCESSA, IN BASE A QUANTO SPECIFICATO PRIMA, MENTRE LA LORO LIMITAZIONE È
CONCESSA, VENGONO QUI LIMITATE A NOVANTA (90) GIORNI A PARTIRE DALLA DATA DI ACQUISTO DELLA
DOCUMENTAZIONE O L'ELEMENTO OGGETTO DELLA LAMENTELA.
ENTRO I LIMITI MASSIMI CONSENTITI DALLE LEGGI APPLICABILI NELLA GIURISDIZIONE VIGENTE, RIM NON PUÒ
ESSERE IN NESSUN CASO RITENUTA RESPONSABILE DI QUALSIASI TIPO DI DANNI RELATIVI ALLA PRESENTE
DOCUMENTAZIONE O ALL'USO DI QUESTA, OVVERO ALLE PRESTAZIONI O MANCATE PRESTAZIONI DI QUALSIASI

155
Guida allo sviluppo Note legali

SOFTWARE, HARDWARE, SERVIZIO O QUALSIASI DEI PRODOTTI E SERVIZI DI TERZI DI CUI SOPRA, COMPRESI, SENZA
LIMITAZIONE, I DANNI SEGUENTI: DIRETTI, CONSEQUENZIALI, ESEMPLARI, INCIDENTALI, INDIRETTI, SPECIALI,
PUNITIVI O AGGRAVATI, DANNI DERIVANTI DALLA PERDITA DI RICAVI O PROFITTI, MANCATA REALIZZAZIONE DEI
GUADAGNI PREVISTI, INTERRUZIONE DELL'ATTIVITÀ COMMERCIALE, PERDITA DI INFORMAZIONI COMMERCIALI,
PERDITA DI OPPORTUNITÀ COMMERCIALI OVVERO DANNEGGIAMENTO O PERDITA DI DATI, MANCATA
TRASMISSIONE O RICEZIONE DI DATI, PROBLEMI ASSOCIATI A QUALSIASI DELLE APPLICAZIONI UTILIZZATE CON I
PRODOTTI O I SERVIZI RIM, COSTI DERIVANTI DA TEMPI MORTI, MANCATO USO DEI PRODOTTI O DEI SERVIZI RIM O
DI PARTI DI ESSI OVVERO DI QUALSIASI SERVIZIO DI DISPONIBILITÀ, COSTO DI SERVIZI SOSTITUTIVI, COSTI DI
COPERTURA, STRUTTURE O SERVIZI, COSTI DI CAPITALE OVVERO ALTRE PERDITE DI CARATTERE PECUNIARIO DI TALE
TIPO, SIA NEL CASO IN CUI TALI DANNI SIANO PREVISTI CHE NEL CASO IN CUI NON LO SIANO, E ANCHE QUALORA
RIM SIA STATA AVVISATA DELLA POSSIBILITÀ DEL VERIFICARSI DI TALI DANNI.
NEI LIMITI MASSIMI CONSENTITI DALLE LEGGI APPLICABILI NELLA GIURISDIZIONE VIGENTE, RIM NON HA NESSUN
ALTRO OBBLIGO, DOVERE O RESPONSABILITÀ RELATIVAMENTE ALL'ADEMPIMENTO DEL CONTRATTO, NEGLIGENZA
O ALTRO NEI CONFRONTI DELL'UTENTE, COMPRESA LA RESPONSABILITÀ PER NEGLIGENZA O COMPATIBILITÀ.
LE LIMITAZIONI, ESCLUSIONI ED ESCLUSIONI DI RESPONSABILITÀ RIPORTATE NEL PRESENTE DOCUMENTO SI
APPLICANO: (A) INDIPENDENTEMENTE DALLA NATURA DELLA CAUSA DELL'AZIONE, DELLA RICHIESTA O DELL'AZIONE
INTRAPRESA DALL'UTENTE, COMPRESE, SENZA LIMITAZIONE, LA VIOLAZIONE DEL CONTRATTO, LA NEGLIGENZA, LE
AZIONI LESIVE, LA COMPATIBILITÀ O QUALSIASI ALTRO DANNO CONTEMPLATO DALLA LEGGE E RIMARRANNO IN
VIGORE IN SEGUITO A VIOLAZIONI DI FONDO O AL MANCATO ADEMPIMENTO DELLO SCOPO ALLA BASE DEL PRESENTE
CONTRATTO O DI QUALSIASI CLAUSOLA IN ESSO PRESENTE; E (B) A RIM E ALLE RELATIVE SOCIETÀ AFFILIATE, AI
SUCCESSORI DI QUESTE, AI CESSIONARI, AGLI AGENTI, AI FORNITORI (IVI COMPRESI I PROVIDER DI SERVIZI), AI
RIVENDITORI AUTORIZZATI RIM (IVI COMPRESI I PROVIDER DI SERVIZI) E AI RISPETTIVI DIRETTORI, DIPENDENTI E
COLLABORATORI INDIPENDENTI.
OLTRE ALLE LIMITAZIONI ED ESCLUSIONI DI CUI SOPRA, IN NESSUN CASO SUI DIRETTORI, I DIPENDENTI, GLI AGENTI,
I RIVENDITORI, I FORNITORI, I COLLABORATORI INDIPENDENTI DI RIM O TUTTI GLI AFFILIATI DI RIM RICADRÀ LA
RESPONSABILITÀ DERIVANTE DA O CORRELATA ALLA PRESENTE DOCUMENTAZIONE.
Prima della sottoscrizione, dell'installazione o dell'utilizzo di Prodotti e servizi di terzi, è responsabilità dell'utente
assicurarsi che il provider di servizi garantisca il supporto di tutte le relative funzioni. Alcuni provider di servizi
potrebbero non offrire la funzionalità di esplorazione in Internet con un abbonamento a BlackBerry® Internet Service.
Verificare con il provider di servizi la disponibilità, le disposizioni di roaming, i piani di servizio e le funzionalità. Per
l'installazione o l'utilizzo di Prodotti e servizi di terzi con prodotti e servizi RIM potrebbero essere necessari uno o più
brevetti, marchi, copyright o licenze di altro tipo al fine di evitare violazioni dei diritti di terzi. L'utilizzo di Prodotti e
servizi di terzi e l'eventuale necessità di licenze di terzi sono responsabilità esclusive dell'utente. Nel caso in cui sia
necessario, l'utente è responsabile del relativo acquisto. L'utente non deve installare o utilizzare Prodotti e servizi di
terzi fino all'acquisto delle relative licenze richieste. Tutti i Prodotti e servizi di terzi forniti con i prodotti e i servizi
RIM hanno lo scopo di offrire maggiore comodità all'utente e vengono forniti "COSÌ COME SONO", senza condizioni,
approvazioni, garanzie, dichiarazioni espresse o implicite di qualsiasi tipo da parte di RIM. RIM non si assume nessun
tipo di responsabilità a tale riguardo. L'utilizzo da parte dell'utente di Prodotti e servizi di terzi deve essere sottoposto
e soggetto all'accettazione da parte dell'utente stesso dei termini di licenze indipendenti e altri contratti ivi applicabili
con terzi, salvo quanto espressamente coperto da eventuali licenze o altri contratti stipulati con RIM.

156
Guida allo sviluppo Note legali

Alcune funzionalità illustrate nella presente documentazione richiedono una versione minima del software
BlackBerry® Enterprise Server, BlackBerry® Desktop Software, e/o BlackBerry® Device Software.
I termini di utilizzo di tutti i prodotti o servizi RIM vengono definiti in una licenza o in un altro contratto indipendente
stipulato con RIM ivi applicabile. NESSUNA AFFERMAZIONE CONTENUTA NELLA PRESENTE DOCUMENTAZIONE PUÒ
SOSTITUIRE CONTRATTI O GARANZIE SCRITTE ESPLICITE FORNITE DA RIM PER PARTI DI PRODOTTI O SERVIZI RIM
DIVERSI DA QUELLI INDICATI NELLA PRESENTE DOCUMENTAZIONE.

Research In Motion Limited


295 Phillip Street
Waterloo, ON N2L 3W8
Canada

Research In Motion UK Limited


Centrum House
36 Station Road
Egham, Surrey TW20 9LF
Regno Unito

Pubblicato in Canada

157