BlackBerry Java SDK Integration Guide Version: 7.0 Guida allo sviluppo
SWD-1638866-1215040530-0
Contents 1 Integrazione con le applicazioni BlackBerry Device Software... 6 Richiamo di un'applicazione BlackBerry Device Software... 6 2 Unified Search... 7 Come rendere individuabili i dati... 7 Esposizione dei dati delle applicazioni... 7 Passaggio di query ad altri motori di ricerca... 9 Definizione di una classe EntityBasedSearchable per gli oggetti SearchableEntity... 10 Personalizzazione della modalità di visualizzazione dei dati nei risultati della ricerca... 13 Come specificare un'icona nella classe EntityBasedSearchable o SearchableEntity... 13 Incapsulamento dei dati nella classe SearchableEntity... 14 Specifying what users can do with your data in search results... 15 Specify an operation for a selected search result... 16 Provide an alternate entry point for your application... 17 Expose your UiAction objects... 18 Registrazione dell'oggetto EntityBasedSearchable con il servizio Unified Search... 19 Notifica al servizio Unified Search delle modifiche apportate ai dati... 20 Rilevamento delle risposte del servizio Unified Search... 20 Rimozione dei dati dall'archivio del contenuto... 21 Utilizzo di altri motori di ricerca... 22 Verifica relativa all'esecuzione di una singola istanza dell'applicazione da parte di un dispositivo... 23 Inserimento di dati all'avvio del dispositivo... 25 Ricerca... 25 Configurazione e avvio di una ricerca... 26 Elaborazione dei risultati della ricerca... 27 3 Supporto di interazione del dispositivo... 29 API di funzionalità del dispositivo... 29 Rilevamento della base... 29 Gestione della base... 31 Utilizzo dei sensori di un dispositivo... 32 Verifica di un sensore del dispositivo... 32 Verifica dello stato di un sensore... 33 Invio di una notifica a un'applicazione durante la modifica dello stato di un sensore... 34 Esempio di codice: utilizzo di un sensore... 36 4 Elenco dei messaggi... 38 Creazione di un nuovo SMS vuoto... 38
Creazione di un nuovo SMS compilato... 38 Creazione di un nuovo MMS vuoto... 38 Creazione di un nuovo messaggio e-mail vuoto... 39 Creazione di un nuovo messaggio e-mail compilato... 39 Creazione di un nuovo messaggio PIN vuoto... 39 Creazione di un nuovo messaggio PIN compilato... 40 Ricezione della notifica di un messaggio... 40 Aggiunta di un listener all'archivio dei messaggi... 41 Aggiunta di un listener all'archivio dei messaggi per aggiornamenti in batch... 41 Aggiunta di un listener a una cartella... 42 Recupero del numero totale di messaggi e-mail da leggere in tutte le cartelle nell'archivio... 42 Apertura di un messaggio... 42 Recupero del testo di un messaggio e-mail... 43 Recupero del contenuto in testo normale e HTML nel testo di un messaggio e-mail utilizzando un metodo ricorsivo... 44 Recupero del contenuto in testo normale di un messaggio e-mail... 46 Recupero del contenuto HTML di un messaggio e-mail... 47 Invio a un'applicazione BlackBerry di una notifica circa l'invio di un messaggio e-mail... 49 Invio a un'applicazione BlackBerry di una notifica circa l'invio di un MMS... 50 Invio a un'applicazione BlackBerry di una notifica circa l'invio di un SMS... 51 Invio di un messaggio... 51 Risposta a un messaggio... 53 Inoltro di un messaggio... 54 Utilizzo delle cartelle dei messaggi... 55 5 Messaggi personalizzati... 57 Utilizzo di cartelle e messaggi personalizzati nell'elenco messaggi... 57 Creazione di un modulo per i processi in background... 57 Creazione di un modulo per l'interfaccia utente... 57 Creazione di un modulo per i processi in background... 58 Avvio del modulo per i processi in background o per l'interfaccia utente... 58 Creazione di un'icona per un messaggio personalizzato... 59 Creazione di una cartella personalizzata nell'elenco messaggi... 60 Invio di una notifica durante la modifica di una cartella personalizzata... 61 Creazione di un indicatore personalizzato... 62 Come nascondere un indicatore... 63 Rimozione di un indicatore personalizzato... 63 6 Allegati... 64
Creazione di un handler degli allegati... 64 Recupero dei contenuti di un allegato... 65 Recupero delle informazioni su un allegato... 65 Invio di un messaggio con un allegato... 65 Download automatico degli allegati... 66 7 Calendario... 68 Apertura del calendario... 68 Visualizzazione o modifica di una voce del calendario... 68 Apertura di una nuova voce del calendario compilata... 68 Aggiornamento delle informazioni delle voci di calendario... 69 Recupero delle informazioni per le voci del calendario... 71 Esportazione di una voce del calendario... 72 Importazione di una voce del calendario... 73 Recupero di più elenchi di voci del calendario... 73 Invio di una notifica a un'applicazione BlackBerry circa la modifica di un elenco di voci del calendario... 73 Invio a un'applicazione BlackBerry di una notifica circa la modifica dell'elenco predefinito di voci del calendario... 74 Aggiornamento di una voce del calendario senza notifica... 74 Rimozione di una voce del calendario senza notifica... 76 8 Elenco contatti... 78 Supporto per elenchi di contatti multipli... 78 Apertura dell'applicazione Contatti... 78 Apertura dell'applicazione Contatti utilizzando i dati di contatto... 79 Apertura dell'applicazione Contatti con un elenco contatti specifico... 80 Creazione di un contatto e assegnazione a un elenco contatti... 81 Recupero delle informazioni di contatto... 82 Recupero dell'uid di un elenco contatti... 83 Esportazione di un contatto... 84 Importazione di un contatto... 85 Eliminazione di un contatto... 85 Invio a un'applicazione di una notifica circa la modifica di un elenco di contatti... 86 Creazione e rimozione degli elenchi contatti... 88 Creazione di un elenco contatti... 88 Rimozione di un elenco contatti... 89 Recupero del contatto associato a una chiamata attiva... 90 Recupero del contatto associato a una chiamata completata... 92 Recupero di contatti dal numero di telefono... 92
Collegamento di contatti di terzi a contatti nell'applicazione Contatti... 94 Collegamento di un contatto... 94 Rimozione di un collegamento... 95 Creazione di voci di menu per i contatti collegati... 96 Creazione di voci di menu per i contatti collegati... 97 Creazione di un provider delle informazioni per un contatto collegato... 98 9 Elenco attività... 100 Visualizzazione o modifica di un'attività... 100 Creazione di una nuova attività vuota... 100 Creazione di una nuova attività compilata... 100 Apertura di un elenco delle attività... 101 Creazione di attività... 101 Aggiunta di informazioni sulle attività... 102 Modifica delle informazioni delle attività... 102 Salvataggio di un'attività... 103 Recupero delle informazioni sulle attività... 103 Esportazione di un'attività... 104 Importazione di un'attività... 104 Eliminazione di un'attività... 105 Chiusura dell'elenco delle attività... 105 Invio di una notifica a un'applicazione BlackBerry circa la modifica di un elenco di attività... 106 10 Telefono... 107 Come effettuare una chiamata da un'applicazione BlackBerry... 107 Come effettuare una chiamata da un'applicazione BlackBerry (ambiente a linea singola)... 107 Come effettuare una chiamata da un'applicazione BlackBerry (ambiente a più linee)... 107 Aggiunta di toni DTMF alla coda di invio... 108 Toni DTMF BlackBerry... 108 Ascolto e gestione di eventi telefonici... 108 Ascolto e gestione degli eventi a linea multipla... 109 Recupero delle informazioni sulle chiamate mediante i registri delle chiamate... 110 Recupero di un participante alla chiamata... 110 Recupero delle informazioni di una chiamata... 111 Recupero del numero di telefono di un dispositivo BlackBerry... 111 Recupero di una chiamata in base all'id... 111 Visualizzazione del contenuto sulla schermata di una chiamata... 112 Visualizzazione del contenuto in una schermata Telefono... 113 Esempio di codice: visualizzazione del contenuto su una schermata del telefono... 114
Visualizzazione del contenuto sui dispositivi che funzionano su una rete CDMA... 115 11 BlackBerry Browser... 117 Recupero di una sessione di BlackBerry Browser... 117 Recupero di una sessione di BlackBerry Browser non predefinita... 117 Richiesta di una pagina Web... 117 Supporto avanzato per il contenuto Web nelle applicazioni BlackBerry... 117 Visualizzazione del contenuto HTML in un campo del browser... 118 Visualizzazione del contenuto HTML da una pagina web in un campo del browser... 119 Visualizzazione del contenuto HTML da una risorsa nell'applicazione... 120 Configurazione di un campo del browser... 121 Invio dei dati dei moduli a un indirizzo Web in un campo del browser... 122 12 Voci di menu... 124 Aggiunta di voci di menu alle applicazioni di BlackBerry Device Software... 124 Creazione e registrazione di una voce di menu... 124 Send Menu API... 125 Retrieving Send commands... 127 Creating a Send menu... 128 Create a Send menu... 128 Code sample: Creating a Send menu... 130 Creating a context object... 131 Using context keys... 132 Using context filters... 133 Create a context filter... 133 13 Ulteriori informazioni... 137 14 Glossario... 138 15 Commenti e suggerimenti... 140 16 Cronologia delle revisioni del documento... 141 17 Note legali... 144
Integrazione con le applicazioni BlackBerry Device Software Integrazione con le applicazioni BlackBerry Device Software 1 Questa sezione descrive come richiamare un'applicazione BlackBerry Device Software, ad esempio l'applicazione Contatti, l'applicazione Telefono e l'applicazione Multimedia. Per ulteriori informazioni sull'integrazione dell'applicazione con le applicazioni BlackBerry Device Software, vedere la panoramica della categoria Integrazione delle applicazioni nella documentazione di riferimento sulle API di BlackBerry Java Development Environment. Richiamo di un'applicazione BlackBerry Device Software È possibile creare applicazioni BlackBerry in grado di richiamare applicazioni BlackBerry Device Software, ad esempio l'applicazione Messaggi, l'applicazione Telefono e l'applicazione Multimedia. L'applicazione in uso, quando richiama un'applicazione BlackBerry Device Software, può fare in modo che quest'ultimo esegua un'azione o visualizzi determinate informazioni. import net.rim.blackberry.api.invoke.calendararguments; import net.rim.blackberry.api.invoke.invoke; import net.rim.blackberry.api.invoke.mapsarguments; import net.rim.blackberry.api.invoke.messagearguments; import net.rim.blackberry.api.invoke.phonearguments; 2. Richiamare il metodo Invoke.invokeApplication() e utilizzare i parametri appropriati. Ad esempio: Per avviare l'applicazione Messaggi e creare un nuovo SMS vuoto, richiamare Invoke.invokeApplication() e utilizzare i seguenti parametri: Invoke.APP_TYPE_MESSAGES e un oggetto MessageArguments che utilizza il campo ARG_NEW_SMS. Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES, new MessageArguments( MessageArguments.ARG_NEW_SMS) ); Per avviare il calendario, richiamare Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments). Per avviare l'applicazione Telefono, richiamare Invoke.invokeApplication(APP_TYPE_PHONE,PhoneArguments). Per avviare BlackBerry Maps e visualizzare la mappa predefinita, richiamare Invoke.invokeApplication() e fornire come parametri Invoke.APP_TYPE_MAPS e un nuovo oggetto MapsArguments. Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments() ); Per ulteriori informazioni sulla classe net.rim.blackberry.api.invoke.invoke, vedere la documentazione di riferimento sulle API di BlackBerry Java Development Environment. 6
Unified Search Unified Search 2 Il servizio Unified Search è un motore di ricerca fornito con BlackBerry Device Software 6.0 e versioni successive. Gli utenti BlackBerry interagiscono con il servizio Unified Search principalmente dalla funzionalità di ricerca universale facendo clic sull'icona di ricerca nella schermata iniziale. Gli sviluppatori possono utilizzare il servizio Unified Search tramite l'api del servizio Unified Search. È possibile utilizzare l'api per includere i dati delle applicazioni nell'archivio del contenuto del servizio e cercare l'indice del contenuto dall'applicazione in uso. Ad esempio, supponiamo che l'utente disponga di un'ampia raccolta di libri e li dia frequentemente in prestito. Potrebbe essere utile creare un'applicazione che consenta di catalogare i libri e tenere un elenco delle persone a cui vengono prestati. Se questa applicazione utilizza l'api del servizio Unified Search, è possibile cercare un libro dalla schermata iniziale o da qualsiasi applicazione, per individuare il libro e i dettagli di contatto della persona che ne è in possesso. In qualità di sviluppatore, è possibile controllare se i dati vengono visualizzati nelle ricerche eseguite dagli utenti nella schermata iniziale di un dispositivo BlackBerry, in altre applicazioni del dispositivo o solo nell'applicazione in uso. Inoltre, è possibile cercare i dati di altre applicazioni quando tali dati sono registrati nel servizio Unified Search. Come rendere individuabili i dati Esistono due modalità per includere i dati nei risultati della ricerca del servizio Unified Search. Se si desidera esporre i dati nell'applicazione, è necessario implementare l'interfaccia EntityBasedSearchable. In questo scenario, è necessario riunire i dati in una classe che implementi l'interfaccia SearchableEntity. Se si desidera passare una query di ricerca al proprio motore di ricerca, situato su un server di rete o all'interno dell'applicazione, è necessario implementare l'interfaccia ExternalSearchProvider. I motori di ricerca disponibili su un server potrebbero essere situati dietro un firewall aziendale o costituire un servizio Web pubblico. Esposizione dei dati delle applicazioni Il servizio Unified Search conserva un indice del contenuto di un dispositivo BlackBerry. L'applicazione utilizza le classi SearchRegistry, AppContentManager e AppContentListener per comunicare con il servizio Unified Search. Per rendere individuabili i dati dell'applicazione, è necessario completare cinque attività. Attività Definire una classe EntityBasedSearchable per l'oggetto SearchableEntity. Incapsulare i dati in un oggetto SearchableEntity. Descrizione Un oggetto EntityBasedSearchable rappresenta i dati ricercabili nel servizio Unified Search. Quando si registra EntityBasedSearchable, il servizio richiede all'applicazione di preparare i dati per l'invio richiamando EntityBasedSearchable.load(). Quando i dati delle applicazioni sono pronti per l'invio, è necessario richiamare completed() nel parametro NotificationListenerN passato a load(). Un oggetto SearchableEntity rappresenta l'unità più piccola di dati che un'applicazione possa inviare al servizio Unified Search. L'oggetto EntityBasedSearchable invia gli oggetti SearchableEntity al 7
Come rendere individuabili i dati Attività Registrare l'oggetto EntityBasedSearchable con il servizio Unified Search. Notificare al servizio Unified Search le modifiche apportate ai dati. Rilevare le risposte del servizio Unified Search. Descrizione servizio, quando ciò viene richiesto. È necessario incapsulare i dati delle applicazioni in un oggetto SearchableEntity. Il servizio indicizza i metadati resi visibili da questi oggetti durante le operazioni di ricerca. Inoltre, gli oggetti SearchableEntity vengono restituiti nei risultati della ricerca dal servizio. Il servizio Unified Search potrebbe dover interrompere l'operazione di caricamento se il dispositivo BlackBerry è occupato o dispone di un livello di carica della batteria basso. Se è necessaria un'interruzione, il servizio richiama EntityBasedSearchable.pause(). Quando il servizio rileva che l'operazione può continuare, richiama EntityBasedSearchable.resume(). Rispondere a questi eventi in tempo utile, in modo che l'applicazione non provochi l'interruzione di altre applicazioni del dispositivo. Dopo aver notificato al servizio Unified Search che i dati sono pronti, il servizio richiama EntityBasedSearchable.getSearchableEntities() per indicizzare i dati. Il servizio potrebbe richiamare nuovamente load e getsearchableentities() se rileva che il proprio indice del contenuto e i dati dell'utente non sono sincronizzati. Dopo aver preparato i dati per la ricerca e aver definito le modalità di indicizzazione, è necessario registrare EntityBasedSearchable con il servizio Unified Search. Passare EntityBasedSearchable quando si richiama SearchRegistry.register(). A questo punto, il servizio recupera e indicizza i dati per l'inclusione nei risultati della ricerca. Per notificare all'indice del contenuto le modifiche apportate ai dati delle applicazioni, utilizzare i metodi insert(), delete() e update() nell'oggetto AppContentManager. Quando si notifica al servizio Unified Search le modifiche apportate ai dati delle applicazioni, è necessario specificare un oggetto AppContentListener in cui il servizio possa notificare all'applicazione il risultato della richiesta. Il diagramma seguente illustra la relazione tra i componenti utilizzati nelle attività precedenti. 8
Come rendere individuabili i dati Passaggio di query ad altri motori di ricerca È possibile utilizzare l'interfaccia ExternalSearchProvider per passare query a un altro motore di ricerca. Ad esempio, un'applicazione di un dispositivo BlackBerry in grado di cercare in maniera efficiente i propri dati potrebbe offrire agli utenti e ad altre applicazioni la possibilità di accedere ai propri dati implementando ExternalSearchProvider. In alternativa, una compagnia di assicurazioni potrebbe disporre di un'applicazione che consenta agli addetti alle vendite di effettuare ricerche in un database delle polizze assicurative. La società potrebbe offrire ai propri addetti alle vendite la possibilità di accedere al motore di ricerca delle polizze dietro il firewall, da un dispositivo BlackBerry, implementando ExternalSearchProvider. Gli utenti possono estendere una ricerca in due modi. La funzionalità di ricerca universale nella schermata iniziale elenca i provider di ricerca esterni alla fine dell'elenco dei risultati della ricerca. Se un utente fa clic sull'icona dell'applicazione nel risultato della ricerca, il servizio Unified Search richiama search() dall'oggetto ExternalSearchProvider in uso. L'applicazione è quindi responsabile della creazione di una connessione al provider di ricerca (un'altra applicazione o tramite rete), del passaggio della stringa della query e della visualizzazione dei risultati recuperati dall'utente. Altre applicazioni possono richiamare l'applicazione in modo simile. Il metodo UnifiedSearchServices.getSearchProviders() restituisce un elenco di tutti i provider di ricerca esterni, presenti in un dispositivo BlackBerry. In questo modo, un'applicazione è in grado di individuare e utilizzare ExternalSearchProvider in modo specifico o consentire all'utente di sceglierne uno dall'elenco. Per assicurarsi che l'applicazione venga visualizzata nell'elenco dei provider di ricerca esterni, è necessario registrare ExternalSearchProvider con il servizio Unified Search. Passare l'oggetto ExternalSearchProvider quando si richiama SearchRegistry.register(). Il diagramma seguente mostra la relazione tra alcuni dei componenti richiesti per l'implementazione di ExternalSearchProvider. 9
Definizione di una classe EntityBasedSearchable per gli oggetti SearchableEntity Definizione di una classe EntityBasedSearchable per gli oggetti SearchableEntity L'implementazione dell'interfaccia EntityBasedSearchable consente di gestire la relazione tra il servizio Unified Search e le entità ricercabili create dall'utente. Ogni oggetto EntityBasedSearchable gestisce un gruppo di oggetti SearchableEntity dotati delle stesse proprietà ricercabili. import net.rim.device.api.unifiedsearch.searchfield; import net.rim.device.api.unifiedsearch.searchables.entitybasedsearchable; import net.rim.device.api.unifiedsearch.searchables.searchablecontenttypeconstants; import net.rim.device.api.unifiedsearch.searchables.searchable; 2. Creare le variabili di istanza per memorizzare le informazioni pertinenti a EntityBasedSearchable. private MySearchableEntity[] _myentities; // You will need this in steps 8 and 11 private long _registrationid; private SearchField[] _searchfields; private Image _icon; private final Object _monitor = new Object(); private boolean _wait = false; 3. Nel costruttore, creare una matrice di oggetti SearchField. Ogni SearchField memorizza il nome di una proprietà ricercabile dei dati. Nel seguente esempio di codice, gli oggetti dei dati delle applicazioni, gestiti da questa classe, sono dotati di tre proprietà ricercabili. Ad esempio, se i dati delle applicazioni hanno modellato dei libri, questi campi potrebbero includere il titolo, il distributore e il numero di pagine. class MyEBS implements EntityBasedSearchable _searchfields = new SearchField[3]; 4. Assegnare un nome significativo a ogni SearchField. 10
Definizione di una classe EntityBasedSearchable per gli oggetti SearchableEntity _searchfields[0] = new SearchField("Title"); _searchfields[1] = new SearchField("Publisher"); _searchfields[2] = new SearchField("Number of pages"); 5. Creare un'icona da visualizzare nei risultati della ricerca, che includono le entità ricercabili gestite da questo oggetto EntityBasedSearchable. Per ulteriori informazioni sulla creazione di icone, consultare la sezione "Personalizzazione della modalità di visualizzazione dei dati nei risultati della ricerca". 6. Implementare gettype(). Restituire il tipo di contenuto che corrisponde meglio ai dati delle applicazioni. Per un elenco dei tipi di contenuto validi, vedere l'interfaccia net.rim.device.api.unifiedsearch.searchables.searchablecontenttypeconstants nel riferimento API. public long gettype() return SearchableContentTypeConstants.CONTENT_TYPE_MEMO; 7. Scegliere gli iniziatori della ricerca che devono ricevere i risultati della ricerca dall'applicazione. Per ulteriori informazioni sull'esposizione dei dati per le ricerche, vedere la classe net.rim.device.api.unifiedsearch.entity.exposurelevel nel riferimento API. public int getprivacylevel() return ExposureLevel.LEVEL_PUBLIC; 8. Implementare load(). Se il dispositivo BlackBerry è occupato o il livello di carica della batteria è basso, potrebbe essere necessario interrompere momentaneamente il funzionamento di questo metodo e riprenderlo quando richiesto. a. Per EntityBasedSearchable, determinare il numero di oggetti dati attualmente esistenti nell'applicazione. public void load (NotificationListener observer, int loadtype) Vector myobjects = MyObjectManager.getDataObjects(); if (myobjects!= null) int size = myobjects.size() if(size < 1) _myentities = new MySearchableEntity[0]; else _myentities = new MySearchableEntity[size]; else // handle the condition where you have no data objects b. Utilizzare un loop while per compilare una matrice di entità ricercabili. Enumeration objects = myobjects.elements(); int count = 0; while (objects.hasmoreelements()) c. Verificare se il servizio Unified Search ha inviato un comando pause. In caso affermativo, interrompere momentaneamente l'operazione di compilazione della matrice di entità ricercabili e inviare una notifica al servizio. 11
Definizione di una classe EntityBasedSearchable per gli oggetti SearchableEntity if (_wait) try synchronized(_monitor) observer.partiallycompleted(this, null, NotificationListener.TYPE_SEARCHABLE); _monitor.wait(); catch (InterruptedException e) observer.error(e); return; d. Quando l'applicazione riprende il controllo del thread, continuare a compilare la matrice di entità ricercabili. MyObject dataobject = (MyObject) objects.nextelement(); _myentities[count++] = new MySearchableEntity(dataObject, this); e. Notificare al servizio Unified Search l'avvenuto caricamento dei dati. observer.completed(this, NotificationListener.TYPE_SEARCHABLE); Il servizio Unified Search richiama getsearchableentities() oltre a recuperare la matrice compilata dall'utente. 9. In pause(), impostare la variabile _wait su true. Il servizio Unified Search chiama questo metodo quando desidera che l'applicazione interrompa il caricamento dei dati. public void pause() _wait = true; 10. In resume(), impostare la variabile _wait su false. Inoltre, notificare al metodo load() che può riprendere l'esecuzione. Il servizio Unified Search richiama resume() quando desidera che l'applicazione riprenda il caricamento dei dati. public void resume() _wait = false; synchronized(_monitor) _monitor.notifyall(); 11. In getsearchableentities(), restituire la matrice _myentities creata nel passaggio 8. public SearchableEntity[] getsearchableentities() return _myentities; 12
Definizione di una classe EntityBasedSearchable per gli oggetti SearchableEntity Personalizzazione della modalità di visualizzazione dei dati nei risultati della ricerca Il metodo geticon(), nelle interfacce EntityBasedSearchable e SearchableEntity, consente di specificare l'icona visualizzata nei risultati della ricerca. Nella funzionalità di ricerca universale nella schermata iniziale, i risultati della ricerca sono raggruppati dall'applicazione. Il metodo EntityBasedSearchable.getIcon() consente di specificare l'icona visualizzata per il gruppo. È possibile specificare anche un'icona per categorie diverse di entità ricercabili correlate. Ad esempio, se si crea un'applicazione per la catalogazione di libri, è possibile che si desideri disporre di icone diverse per le diverse categorie di libri, ad esempio best seller, edizioni complete e prime edizioni. Queste categorie corrispondono tutte a tipi di libri, quindi verrebbero logicamente classificate all'interno dell'unico oggetto EntityBasedSearchable utilizzato per la gestione di libri. Tuttavia, un'applicazione in grado di visualizzarli potrebbe offrire un suggerimento visivo per consentire a un utente di stabilire rapidamente se individuare un libro su uno scaffale regolare, uno scaffale di grandi dimensioni o in un ambiente controllato. In questo caso, è possibile creare tre classi SearchableEntity per riunire tre tipi diversi di oggetti-libro, ciascuno con la propria implementazione di geticon(). Tutte e tre le classi sarebbero tuttavia gestite da un singolo oggetto EntityBasedSearchable. Come specificare un'icona nella classe EntityBasedSearchable o SearchableEntity Before you begin: Includere un file grafico adatto all'utilizzo come icona nella cartella delle risorse del progetto. Per ulteriori informazioni sulla progettazione della grafica per i dispositivi BlackBerry, consultare le Istruzioni per l'interfaccia utente. 1. Importare le classi richieste. import net.rim.device.api.ui.image.image; import net.rim.device.api.ui.image.imagefactory; import net.rim.device.api.system.bitmap; 2. Creare una variabile di istanza per memorizzare l'icona. private Image _icon; 3. Importare il grafico nell'applicazione dalla cartella delle risorse. Bitmap img = Bitmap.getBitmapResource("icon.png") 4. Verificare la riuscita dell'importazione, quindi creare un'icona. if(img!= null) _icon = ImageFactory.createImage(img); else _icon = null; 5. In geticon(), restituire l'immagine. 13
Incapsulamento dei dati nella classe SearchableEntity public Image geticon() return _icon; Incapsulamento dei dati nella classe SearchableEntity Il servizio Unified Search indicizza i metadati esposti da un oggetto SearchableEntity. Il servizio restituisce anche un oggetto SearchableEntity come contenuto di un risultato della ricerca. È necessario preparare i dati delle applicazioni per il servizio, incapsulandolo nella classe SearchableEntity. import net.rim.device.api.unifiedsearch.searchfield; import net.rim.device.api.unifiedsearch.searchfieldcriteria; import net.rim.device.api.unifiedsearch.searchfieldcriterialist; import net.rim.device.api.unifiedsearch.entity.searchableentity; import net.rim.device.api.unifiedsearch.searchables.searchable; 2. Recuperare una matrice di oggetti SearchField da EntityBasedSearchable. SearchField[] searchfields = mysearchable.definesupportedsearchfields(); 3. Creare un oggetto SearchFieldCriteria per ciascuna proprietà ricercabile. Nel seguente esempio di codice, l'oggetto dei dati delle applicazioni myobject dispone di un metodo getproperty() che restituisce una stringa per un indice dato. Ad esempio, se myobject conteneva la descrizione di un libro, gli indici 0, 1 e 2 di getproperty() potrebbero restituire il nome, il distributore e il numero di pagine del libro. int size = searchfields.length SearchFieldCriteria[] criteria = new SearchFieldCriteria[size]; for (int i = size -1; i >= 0; --i) criteria[i] = new SearchFieldCriteria(searchfields[i], new String[] myobject.getproperty(i)); 4. Creare e compilare un oggetto SearchFieldCriteriaList per mantenere i criteri del campo di ricerca. SearchFieldCriteriaList _sfcl = new SearchFieldCriteriaList(); for (int i = size -1; i >= 0; --i) sfcl.addcriteria(criteria[i]); 5. Implementare getsearchcriteria() per restituire SearchFieldCriteriaList. pubic SearchFieldCriteriaList getsearchcriteria() return _sfcl; 6. In getdata(), restituire l'oggetto dei dati delle applicazioni. Per continuare con l'esempio del libro, questo metodo restituirebbe un oggetto che rappresenta il libro. public Object getdata() return myobject; 14
Specifying what users can do with your data in search results 7. In gettitle(), assegnare un titolo a questa entità ricercabile. Il testo del titolo viene visualizzato nei risultati della ricerca. Per continuare con l'esempio del libro, myobject.getname() potrebbe restituire il nome di un libro. public String gettitle() return myobject.getname(); 8. In getsummary(), fornire un riepilogo dei dati in questa entità ricercabile. Il testo del riepilogo viene visualizzato nei risultati della ricerca. Continuando con l'esempio del libro, myobject.getdescription() potrebbe restituire una descrizione del libro. public String getsummary() return myobject.getdescription(); 9. Implementare getsearchable(). Recuperare l'oggetto EntityBasedSearchable creato dall'applicazione per gestire questo oggetto e restituirlo. public Searchable getsearchable() return mypublisher.getsearchable(); 10. Definire le opzioni da visualizzare sul menu contestuale quando l'utente BlackBerry fa clic sull'entità in uso in un elenco di risultati della ricerca. Per ulteriori informazioni, consultare la sezione in cui sono specificate le attività di gestione dei dati nei risultati della ricerca consentite agli utenti. 11. Se si desidera che SearchableEntity visualizzi un'icona diversa da quella dell'applicazione in uso, specificare l'icona in geticon(). Per ulteriori informazioni, consultare la sezione "Personalizzazione della modalità di visualizzazione dei dati nei risultati della ricerca". Specifying what users can do with your data in search results When a user selects your search result and presses the menu key, the BlackBerry device displays a list of operations the user can perform with that data. For example, if your application holds recipes, you might want to enable your user to email a recipe or add the ingredients to a shopping list from a list of search results. Each item in a search result represents a SearchableEntity object from an application that registered data with the Unified Search Service. The UiAction class helps you specify an operation that a user or an application can invoke on your SearchableEntity objects. In your application, you must create a UiAction subclass for each operation you want to make available to your user. You can expose your UiAction objects by using the getuiactions(object, UiAction[]) method of your SearchableEntity object. You must configure an alternate entry point for the Unified Search Service to execute the operation a user selects. 15
Specifying what users can do with your data in search results Specify an operation for a selected search result A UiAction subclass defines an operation that is available to users when they select an item in a list of search results provided by the Unified Search Service. The following steps demonstrate how to create a class named DisplayBookInfo that enables a user to display detailed information about a book in an application that stores information about books. 1. Import the required classes and interfaces. import net.rim.device.api.ui.image.image; import net.rim.device.api.ui.uiapplication; import net.rim.device.api.unifiedsearch.action.uiaction; 2. Declare a class that extends UiAction, and create an empty constructor. class DisplayBookInfo extends UiAction DisplayBookInfo () 3. In the runaction() method, retrieve the SearchableEntity object that the user selected from a search result. protected void runaction() BookEntity book = (BookEntity) this.getsearchableentity(); 4. In runaction(), Create an instance of the DisplayBookScreen class to display the book information. Provide the SearchableEntity object that you retrieved to the new screen object. DisplayBookScreen showbook = new DisplayBookScreen(book); 5. Invoke pushscreen() to make the new screen object visible. UiApplication.getUiApplication().pushScreen(showBook); 6. Implement the tostring() method to provide a description of the operation this class performs. public String tostring() return "Show book info"; 7. Implement the geticon() method to associate an icon with this operation. In this task, no icon is provided. public Image geticon() return null; 16
Specifying what users can do with your data in search results 8. In the getuiactions() method of your SearchableEntity class, populate the uiactions parameter with your actions like DisplayBookInfo. Change the uiactions array reference using the Arrays object. If you try to change the array without the Arrays object, you will create a local copy of the array. Your local copy is not passed back to the application that requested your UiAction objects. In the following code sample, the ActionTwo and ActionThree classes were added to provide a more complete example. public UiAction getuiactions(object contextobject, UiAction[] uiactions) ActionOne act1 = new ActionOne(this); Arrays.add(uiActions, act1); Arrays.add(uiActions, new ActionTwo()); Arrays.add(uiActions, new ActionThree()); 9. Return the UiAction object you want to highlight the menu of actions by default. return act1; Provide an alternate entry point for your application Your application must detect when the BlackBerry device activates it using an alternate entry point. The following steps demonstrate how to enable an application to accept an alternate entry point for a UiAction object. Before you begin: Configure an alternate entry point for your application. For more information about declaring an alternate entry point in your project, see Specify the alternate entry point settings for a BlackBerry application project. 1. Import the required classes and interfaces. import net.rim.device.api.ui.uiapplication; 2. Create the application framework by extending the UiApplication class. public class MyApp extends UiApplication public static void main(args[]) public MyApp(String entrypoint) 3. In the main() method, indentify whether a user launched the application from the Home screen of a BlackBerry device, or through a search result. This step assumes that you configured an alternate entry point for your project named uiaction. if( args!= null && args.length > 0 && args[0].equals("uiaction")) 4. Create an application object. Provide the entry point type as a parameter. 17
Specifying what users can do with your data in search results app = new MyApp("uiAction"); else app = new MyApp("user"); 5. Start your application. app.entereventdispatcher; 6. In your application constructor, indentify the entry point used to launch the application. if(entrypoint.equals("normal") 7. If the your appilcation was launched from the Home screen, display your first screen. pushscreen(new MyAppScreen()); 8. If a user launched your application from a search result, do nothing. The application that provided the search result prompts your application to execute the UiAction automatically. else Expose your UiAction objects You must implement the SearchableEntity.getUiActions(Object, UiActions[]) method to expose your UiAction objects. The following steps demonstrate how to expos an object based on a class named DisplayBookInfo, created in Create a UiAction subclass. Before you begin: Create a class that implements the SearchableEntity interface. For more information, see Encapsulate your data in the SearchableEntity class. 1. In your SeachableEntity implementation, import the Arrays class. import net.rim.device.api.util.arrays; 2. In your SearchableEntity.getUiAction(Object, UiAction[]) method, instantiate a DisplayBookInfo object. displayaction = new DisplayBookInfo(); 3. Invoke the setentrypointindex() method and specify a single parameter with a value of 1. This configures the UiAction object to use an alternate entry point for your application. displayaction.setentrypointindex(1); 4. In your SearchableEntity.getUiAction(Object, UiAction[]) method, invoke the Arrays.add() method to add displayaction to the UiAction[] parameter. Arrays.add(uiActions, displayaction); 18