App shortcuts

Gli app shortcuts possono essere considerati una sorta di menu "esterno" all'applicazione Android. Possono essere attivati con un click prolungato
sull'icona dell'app e appaiono come un elenco di voci:

Il loro scopo è quello di invocare rapidamente funzionalità dell'app senza doverla aprire e navigarne i menu. Solitamente vengono impiegati per
attivare operazioni particolari (mostrare un indice di argomenti, un elenco di "preferiti" o aggiornamenti quotidiani, etc.) o permettere all'utente di proseguire un'attività
che aveva lasciato in sospeso.

Esistono shortcut di tre tipologie:

• Statici: gli app shortcut statici sono definiti in una risorsa XML e direttamente collegati all'applicazione;
• Dinamici: la versione dinamica può essere caricata e gestita in ogni aspetto esclusivamente a runtime;
• Pinned: possono essere aggiunti in launcher che li supportano a patto che l'utente conceda le necessarie permission.

Vale la pena inoltre notare che il numero di shortcuts permessi è limitato: il massimo consentito contemporaneamente è di cinque anche
se alcuni launcher si fermano ad accettarne quattro.

Creare app shortcut statici

Come esempio, possiamo realizzare un'app shortcut statico. Il tutto consta di due passaggi essenziali:

• creazione della risorsa XML: nella cartella /res/xml (se non esiste la creeremo in Android Studio) creiamo un file XML caratterizzato da un nodo root di
  tipo <shortcuts> che rappresenta l'elenco di shortcut legati all'app. Al suo interno creeremo tanti nodi <shortcut> quante sono le voci che vorremo far apparire: ognuna
  di queste disporrà di un Intent per l'attivazione della funzionalità relativa;
• collegamento della risorsa XML al file AndroidManifest.xml: per rendere effettivo il file XML creato dovremo legarlo all'AndroidManifest.xml dove inseriremo un apposito
  tag <meta-data> nel nodo dell'Activity principale.

Questo è un esempio di risorsa XML per configurare gli app Shortcut (supporremo nel seguito che questo file sia /res/xml/appshortcuts.xml):

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
<shortcut
android:shortcutId="shortcut1"
android:enabled="true"
android:shortcutShortLabel="@string/breve1"
android:shortcutLongLabel="@string/lunga1"
android:icon="@drawable/action_icon"
android:shortcutDisabledMessage="@string/disabilitato1">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="it.html.esempioappshortcuts"
android:targetClass="it.html.esempioappshortcuts.FirstActivity" />
<categories android:name="android.shortcut.conversation" />
</shortcut>
</shortcuts>

Al suo interno è collocato un solo nodo <shortcut> pertanto di voce legata all'app ne sarà disponibile solo una ma sarà sufficiente creare ulteriori nodi
di questo tipo per aggiungere ulteriori voci. Tutta la configurazione è affidata ai vari attributi che appaiono:

• shortcutId è l'identificativo con cui potremo fare riferimento a questo shortcut dal codice Java;
• shortcutShortLabel e shortcutLongLabel costituiscono le descrizioni dello shortcut, in pratica il testo che contraddistinguerà
  la voce. Sono due versioni differenti in quanto la prima è breve (massimo 10 caratteri) e la seconda lunga (non oltre le 25 lettere) ma rappresentano lo stesso concetto:
  in base allo spazio a disposizione verrà deciso quale mostrare. Devono essere indicate come risorse stringa;
• enabled è un valore booleano che indica se la voce è abilitata. Quando disabilitata, a seconda del launcher che si sta utilizzando, la voce
  potrebbe non apparire affatto o mostrare il testo esposto nell'attributo shortcutDisabledMessage;
• icon permette di associare un'icona, come risorsa drawable, alla voce.

L'Intent integrato nel nodo rappresenta l'azione da attivare che in questo caso consiste nell'avvio dell'Activity di classe FirstActivity collocata
nel package it.html.esempioappshortcuts.

Una volta configurata tale risorsa va collegata al manifest dell'app inserendola come <meta-data> nel nodo <activity> principale ossia quello caratterizzato da
action android.intent.action.MAIN e categoria android.intent.category.LAUNCHER. Nel seguente codice, lo si vede collocato proprio consecutivamente al nodo <intent-filter>.

<manifest
xmlns:android="http://schemas.android.com/apk/res/android"
package="it.html.esempioappshortcuts">
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/AppTheme">
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<meta-data android:name="android.app.shortcuts"
android:resource="@xml/appshorcuts" />
</activity>
...
...
</application>
</manifest>

Classi per la gestione degli App Shortcut

Android mette a disposizione classi per la gestione dinamica degli app Shortcut ed in particolare due di esse hanno un ruolo centrale:

• ShortcutManager: è il servizio di sistema che permette di impartire configurazioni agli shortcut. Viene attivato tramite Context
  sfruttando il metodo getSystemService;
• ShortcutInfo è il tipo di oggetto che raccoglie tutte le informazioni relative ad una voce di shortcut e mediante metodi
  setter/getter le imposta o le legge.

Tali classi rivestono un ruolo fondamentale per la gestione dei Dynamic Shortcut, l'equivalente dinamico di quanto abbiamo creato nel paragrafo precedente.
Per ottenere un riferimento allo ShortcutManager utilizziamo la seguente invocazione (tutto il codice che segue si considera eseguito dall'interno di una Activity):

ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);

Per creare un nuovo shortcut dovremo configurarlo mediante ShortcutInfo.Builder:

// il riferimento this costituisce il Context in quanto supponiamo che il codice sia stato eseguito in un'Activity
ShortcutInfo shortcut = new ShortcutInfo.Builder(this, "shortcut_id")
.setShortLabel("Ultime notizie")
.setLongLabel("Consulta le ultime notizie")
.setIcon(Icon.createWithResource(this, android.R.drawable.news_icon))
.setIntent(intent) // oggetto Intent precedentemente configurato
.build();

Mediante i metodi della classe abbiamo potuto assegnare le peculiarità di cui abbiamo parlato in precedenza (etichetta corta, lunga, id, etc.) mentre
per attivare gli shortcut configurati invochiamo il metodo setDynamicShortcuts dell'oggetto ShortcutManager al quale passeremo come argomento la lista
di ShortcutInfo che abbiamo creato (uno solo in questo caso):

shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));

Qualora volessimo disattivare uno o più shortcut ne passeremo la lista di id al metodo disableShortcuts sempre dell'oggetto ShortcutManager:

shortcutManager.disableShortcuts(Arrays.asList("shortcut_id"));