I file mappa dei caratteri chiave (file .kcm) sono responsabili della mappatura delle combinazioni di codici tasti Android con modificatori ai caratteri Unicode.
I file di layout dei tasti specifici del dispositivo sono obbligatori per tutti i dispositivi di input interni (integrati) con tasti, anche solo per indicare al sistema che il dispositivo è solo per uso speciale (non una tastiera completa).
I file di layout dei tasti specifici del dispositivo sono facoltativi per le tastiere esterne e spesso non sono affatto necessari. Il sistema fornisce una mappa dei caratteri delle chiavi generica adatta a molte tastiere esterne.
Se non è disponibile un file di layout dei tasti specifico per il dispositivo, il sistema sceglierà un valore predefinito.
Posizione
I file della mappa dei caratteri principali vengono individuati in base al fornitore USB, all'ID prodotto (e facoltativamente alla versione) o al nome del dispositivo di input.
I seguenti percorsi vengono consultati in ordine.
/odm/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm/vendor/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm/system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm/odm/usr/keychars/Vendor_XXXX_Product_XXXX.kcm/vendor/usr/keychars/Vendor_XXXX_Product_XXXX.kcm/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm/odm/usr/keychars/DEVICE_NAME.kcm/vendor/usr/keychars/DEVICE_NAME.kcm/system/usr/keychars/DEVICE_NAME.kcm/data/system/devices/keychars/DEVICE_NAME.kcm/odm/usr/keychars/Generic.kcm/vendor/usr/keychars/Generic.kcm/system/usr/keychars/Generic.kcm/data/system/devices/keychars/Generic.kcm/odm/usr/keychars/Virtual.kcm/vendor/usr/keychars/Virtual.kcm/system/usr/keychars/Virtual.kcm/data/system/devices/keychars/Virtual.kcm
Quando viene creato un percorso file che contiene il nome del dispositivo, tutti i caratteri nel nome del dispositivo diversi da "0"-"9", "a"-"z", "A"-"Z", "-" o "_" vengono sostituiti da "_".
File della mappa dei caratteri della chiave generica
Il sistema fornisce un file speciale di mappa dei caratteri delle chiavi integrato denominato Generic.kcm.
Questa mappa dei caratteri delle tasti è progettata per supportare una serie di tastiere esterne standard.
Non modificare la mappa dei caratteri delle chiavi generiche.
File della mappa dei caratteri delle chiavi virtuali
Il sistema fornisce un file speciale della mappa dei caratteri dei tasti integrato chiamato Virtual.kcm
che viene utilizzato dai dispositivi con tastiera virtuale.
Il dispositivo tastiera virtuale è un dispositivo di input sintetico il cui ID è -1
(vedi KeyCharacterMap.VIRTUAL_KEYBOARD). È presente su tutti i dispositivi Android
a partire da Android Honeycomb 3.0. Lo scopo del dispositivo tastiera virtuale è fornire un dispositivo di input integrato noto che può essere utilizzato per inserire sequenze di tasti nelle applicazioni dall'IME o dagli strumenti di test, anche per i dispositivi che non dispongono di tastiere integrate.
Si presume che la tastiera virtuale abbia un layout QWERTY completo uguale su tutti i dispositivi. In questo modo, le applicazioni possono iniettare sequenze di tasti utilizzando il dispositivo tastiera virtuale e ottenere sempre gli stessi risultati.
Non modificare la mappa dei caratteri dei tasti virtuali.
Sintassi
Un file di mappa dei caratteri della tastiera è un file di testo normale costituito da una dichiarazione del tipo di tastiera e da un insieme di dichiarazioni delle chiavi.
Dichiarazione del tipo di tastiera
Una dichiarazione del tipo di tastiera descrive il comportamento generale della tastiera. Un file mappa dei caratteri deve contenere una dichiarazione del tipo di tastiera. Per chiarezza, spesso viene posizionato nella parte superiore del file.
type FULL
Sono riconosciuti i seguenti tipi di tastiera:
-
NUMERIC: una tastiera numerica (12 tasti).Una tastiera numerica supporta l'inserimento di testo utilizzando un approccio multi-tocco. Potrebbe essere necessario toccare una tastiera più volte per generare la lettera o il simbolo desiderato.
Questo tipo di tastiera è generalmente progettato per la digitazione con i pollici.
Corrisponde a
KeyCharacterMap.NUMERIC. -
PREDICTIVE: una tastiera con tutte le lettere, ma con più di una lettera per tasto.Questo tipo di tastiera è generalmente progettato per la digitazione con i pollici.
Corrisponde a
KeyCharacterMap.PREDICTIVE. -
ALPHA: una tastiera con tutte le lettere e, forse, alcuni numeri.Una tastiera alfabetica supporta l'inserimento diretto di testo, ma potrebbe avere un layout compatto con un fattore di forma ridotto. A differenza di una tastiera
FULL, alcuni simboli potrebbero essere accessibili solo utilizzando speciali selettori di caratteri sullo schermo. Inoltre, per migliorare la velocità e la precisione della digitazione, il framework offre funzionalità speciali per le tastiere alfabetiche, come la capitalizzazione automatica e i tasti SHIFT e ALT attivati / bloccati.Questo tipo di tastiera è generalmente progettato per la digitazione con i pollici.
-
FULL: una tastiera completa da PC.Una tastiera completa si comporta come una tastiera per PC. Per accedere a tutti i simboli, premere direttamente i tasti sulla tastiera senza assistenza o funzionalità sullo schermo come la capitalizzazione automatica.
Questo tipo di tastiera è generalmente progettato per la digitazione con entrambe le mani.
-
SPECIAL_FUNCTION: una tastiera utilizzata solo per eseguire funzioni di controllo del sistema anziché per digitare.Una tastiera con funzioni speciali è composta solo da tasti che non stampano, come HOME e POWER, che non vengono effettivamente utilizzati per la digitazione.
Le mappe dei caratteri delle chiavi Generic.kcm e Virtual.kcm sono entrambe tastiere FULL.
Dichiarazioni chiave
Le dichiarazioni delle chiavi sono costituite ciascuna dalla parola chiave key seguita da un nome di codice chiave Android, una parentesi graffa aperta, un insieme di proprietà e comportamenti e una parentesi graffa chiusa.
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
Proprietà
Ogni proprietà della chiave stabilisce una mappatura da una chiave a un comportamento. Per rendere più compatti i file della mappa dei caratteri principali, è possibile mappare più proprietà allo stesso comportamento separandole con una virgola.
Nell'esempio precedente, alla proprietà label viene assegnato il comportamento 'A'.
Analogamente, alle proprietà ctrl, alt e meta viene assegnato contemporaneamente il comportamento none.
Sono riconosciute le seguenti proprietà:
-
label: specifica l'etichetta stampata fisicamente sulla chiave, se è composta da un singolo carattere. Questo è il valore restituito dal metodoKeyCharacterMap.getDisplayLabel. -
number: specifica il comportamento (carattere da digitare) quando un visualizzatore di testo numerico ha il focus, ad esempio quando l'utente sta digitando un numero di telefono.Le tastiere compatte spesso combinano più simboli in un'unica chiave, in modo che la stessa chiave possa essere utilizzata per digitare
'1'e'a'o'#'e'q'. Per queste chiavi, la proprietànumberdeve essere impostata per indicare quale simbolo deve essere digitato in un contesto numerico, se presente.Alcuni simboli "numerici" tipici sono le cifre da
'0'a'9','#','+','(',')',','e'.'. -
base: specifica il comportamento (carattere da digitare) quando non vengono premuti tasti di modifica. -
<modificatore> o <modificatore1>
+<modificatore2>+…: specifica il comportamento (carattere da digitare) quando viene premuto il tasto e sono attivi tutti i modificatori specificati.Ad esempio, la proprietà modificatore
shiftspecifica un comportamento che si applica quando viene premuto il modificatore SHIFT SINISTRO o SHIFT DESTRO.Analogamente, la proprietà del modificatore
rshift+raltspecifica un comportamento che si applica quando vengono premuti contemporaneamente i modificatori MAIUSC RIGHT e ALT RIGHT.
Nelle proprietà dei modificatori vengono riconosciuti i seguenti modificatori:
shift: si applica quando viene premuto il modificatore MAIUSC SINISTRA o MAIUSC DESTRA.lshift: si applica quando viene premuto il modificatore MAIUSC SINISTRO.rshift: si applica quando viene premuto il modificatore MAIUSC RETTO.alt: si applica quando viene premuto il modificatore ALT SINISTRO o ALT DESTRO.lalt: si applica quando viene premuto il tasto di modifica ALT SINISTRO.ralt: si applica quando viene premuto il modificatore ALT DESTRO.ctrl: si applica quando viene premuto il modificatore CONTROLLO SINISTRO o CONTROLLO DESTRO.lctrl: si applica quando viene premuto il modificatore CONTROL SINISTRO.rctrl: si applica quando viene premuto il modificatore CONTROLLO DESTRO.meta: si applica quando viene premuto il modificatore META SINISTRA o META DESTRA.lmeta: si applica quando viene premuto il modificatore META SINISTRO.rmeta: si applica quando viene premuto il modificatore META GIUSTO.sym: si applica quando viene premuto il modificatore SIMBOLO.fn: si applica quando viene premuto il modificatore FUNCTION.capslock: si applica quando il modificatore BLOC MAIUSC è bloccato.numlock: si applica quando il modificatore NUM LOCK è bloccato.scrolllock: si applica quando il modificatore SCROLL LOCK è bloccato.
L'ordine in cui sono elencate le proprietà è importante. Quando viene mappata una chiave a un comportamento, il sistema esegue la scansione di tutte le proprietà pertinenti in ordine e restituisce l'ultimo comportamento applicabile trovato.
Di conseguenza, le proprietà specificate in un secondo momento sostituiscono quelle specificate in precedenza per una determinata chiave.
Comportamenti
Ogni proprietà viene associata a un comportamento. Il comportamento più comune è digitare un carattere, ma ne esistono altri.
Sono riconosciuti i seguenti comportamenti:
-
none: non digitare un carattere.Questo comportamento è predefinito quando non viene specificato alcun carattere. La specifica di
noneè facoltativa, ma migliora la chiarezza. -
'X': digita il valore letterale del carattere specificato.Questo comportamento fa sì che il carattere specificato venga inserito nella visualizzazione di testo attiva. Il carattere letterale può essere un carattere ASCII qualsiasi o una delle seguenti sequenze di escape:
'\\': digita un carattere barra rovesciata.'\n': digita un carattere di nuova riga (da utilizzare per INVIO / RETORN).'\t': digita un carattere TAB.'\'': digita un apostrofo.'\"': digita un carattere di virgolette.'\uXXXX': digita il carattere Unicode il cui punto di codice è indicato in esadecimale da XXXX.
-
fallback<nome in codice della chiave Android>: esegui un'azione predefinita se la chiave non viene gestita dall'applicazione.Questo comportamento fa sì che il sistema simuli una pressione di un tasto diverso quando un'applicazione non gestisce la chiave specificata in modo nativo. Viene utilizzato per supportare il comportamento predefinito per le nuove chiavi che non tutte le applicazioni sanno gestire, ad esempio ESCAPE o i tasti del tastierino numerico (quando il tasto Bloc Num non è premuto).
Quando viene eseguito un comportamento di riserva, l'applicazione riceve due pressioni dei tasti: una per la chiave originale e un'altra per la chiave di riserva selezionata. Se l'applicazione gestisce la chiave originale durante l'abilitazione, l'evento della chiave di riserva verrà annullato (
KeyEvent.isCanceledrestituiràtrue).
Il sistema riserva due caratteri Unicode per eseguire funzioni speciali:
-
'\uef00': quando viene eseguito questo comportamento, la visualizzazione di testo consuma e rimuove i quattro caratteri che precedono il cursore, li interpreta come cifre esadecimali e inserisce il punto di codice Unicode corrispondente. -
'\uef01': quando viene eseguito questo comportamento, nella visualizzazione di testo viene visualizzata una finestra di dialogo di selezione dei caratteri contenente simboli vari.
Il sistema riconosce i seguenti caratteri Unicode come caratteri dead key combinati con i segni diacritici:
'\u0300': accento grave.'\u0301': accento acuto.'\u0302': accento circonflesso.'\u0303': accento tilde.'\u0308': accento umlaut.
Quando viene digitata una dead key seguita da un altro carattere, la dead key e i caratteri seguenti vengono composti. Ad esempio, quando l'utente digita un carattere morto con accento grave seguito dalla lettera "a", il risultato è "à".
Per ulteriori informazioni sulla gestione delle chiavi non attive, consulta KeyCharacterMap.getDeadChar.
Commenti
Le righe di commento iniziano con "#" e continuano fino alla fine della riga. in questo modo:
# A comment!
Le righe vuote vengono ignorate.
Come le combinazioni di tasti vengono mappate ai comportamenti
Quando l'utente preme un tasto, il sistema cerca il comportamento associato alla combinazione di quella pressione e dei modificatori attualmente premuti.
Maiusc + A
Supponiamo che l'utente abbia premuto A e SHIFT contemporaneamente. Il sistema individua innanzitutto
l'insieme di proprietà e comportamenti associati a KEYCODE_A.
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
Il sistema le analizza dalla prima all'ultima e da sinistra a destra, ignorando le proprietà label e number, che sono speciali.
La prima proprietà trovata è base. La proprietà base si applica sempre a una chiave, indipendentemente dai modificatori premuti. In sostanza, specifica il comportamento predefinito per la chiave, a meno che non venga sostituito dalle proprietà seguenti.
Poiché la proprietà base si applica a questa pressione del tasto, il sistema prende nota del fatto che il suo comportamento è 'a' (digita il carattere a).
Il sistema continua quindi a eseguire la scansione delle proprietà successive nel caso in cui una di queste sia più specifica di base e la sostituisca. Trova shift, che si applica anche alla pressione dei tasti SHIFT + A. Pertanto, il sistema decide di ignorare il comportamento della proprietà base e sceglie il comportamento associato alla proprietà shift, ovvero 'A' (digita il carattere A).
Poi continua a scansionare la tabella, ma a questa pressione del tasto non vengono applicate altre proprietà (il tasto Maiusc non è bloccato, non è premuto il tasto Ctrl, non è premuto il tasto Alt e non è premuto il tasto Meta).
Di conseguenza, il comportamento risultante per la combinazione di tasti MAIUSC+A è 'A'.
CTRL + A
Ora considera cosa succederebbe se l'utente premesse A e CONTROL contemporaneamente.
Come in precedenza, il sistema eseguirà la scansione della tabella delle proprietà. Noterebbe che la proprietà base è stata applicata, ma continuerebbe anche la scansione fino a raggiungere la proprietà control. La proprietà control
viene visualizzata dopo base, pertanto il suo comportamento sostituisce quello di base.
Di conseguenza, il comportamento risultante per la combinazione di tasti Ctrl+A è none.
ESC
Ora supponiamo che l'utente abbia premuto ESC.
key ESCAPE {
base: fallback BACK
alt, meta: fallback HOME
ctrl: fallback MENU
}
Questa volta il sistema ottiene il comportamento fallback BACK, un comportamento di riserva.
Poiché non viene visualizzato alcun carattere letterale, non verrà digitato alcun carattere.
Durante l'elaborazione della chiave, il sistema invierà prima KEYCODE_ESCAPE all'applicazione. Se l'applicazione non lo gestisce, il sistema riproverà, ma questa volta invierà KEYCODE_BACK all'applicazione come richiesto dal comportamento di riserva.
Pertanto, le applicazioni che riconoscono e supportano KEYCODE_ESCAPE hanno la possibilità di gestirlo così com'è, ma altre applicazioni che non lo supportano possono invece eseguire l'azione di riserva di trattare la chiave come se fosse KEYCODE_BACK.
NUMPAD_0 con o senza NUM LOCK
I tasti del tastierino numerico hanno interpretazioni molto diverse a seconda che il tasto NUM LOCK sia bloccato.
La seguente dichiarazione della chiave assicura che KEYCODE_NUMPAD_0 digiti 0
quando è premuto NUM LOCK. Quando il tasto NUM LOCK non è premuto, il tasto viene inviato all'applicazione come di consueto e, se non viene gestito, viene inviata la tastiera di riserva KEYCODE_INSERT.
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
Come possiamo vedere, le dichiarazioni delle chiavi di riserva migliorano notevolmente la compatibilità con le applicazioni precedenti che non riconoscono o supportano direttamente tutte le chiavi presenti su una tastiera completa per PC.
Esempi
Tastiera completa
# This is an example of part of a key character map file for a full keyboard
# include a few fallback behaviors for special keys that few applications
# handle themselves.
type FULL
key C {
label: 'C'
base: 'c'
shift, capslock: 'C'
alt: '\u00e7'
shift+alt: '\u00c7'
ctrl, meta: none
}
key SPACE {
label: ' '
base: ' '
ctrl: none
alt, meta: fallback SEARCH
}
key NUMPAD_9 {
label, number: '9'
base: fallback PAGE_UP
numlock: '9'
ctrl, alt, meta: none
}
Tastiera alfanumerica
# This is an example of part of a key character map file for an alphanumeric
# thumb keyboard. Some keys are combined, such as `A` and `2`. Here we
# specify `number` labels to tell the system what to do when the user is
# typing a number into a dial pad.
#
# Also note the special character '\uef01' mapped to ALT+SPACE.
# Pressing this combination of keys invokes an on-screen character picker.
type ALPHA
key A {
label: 'A'
number: '2'
base: 'a'
shift, capslock: 'A'
alt: '#'
shift+alt, capslock+alt: none
}
key SPACE {
label: ' '
number: ' '
base: ' '
shift: ' '
alt: '\uef01'
shift+alt: '\uef01'
}
Game pad
# This is an example of part of a key character map file for a game pad.
# It defines fallback actions that enable the user to navigate the user interface
# by pressing buttons.
type SPECIAL_FUNCTION
key BUTTON_A {
base: fallback BACK
}
key BUTTON_X {
base: fallback DPAD_CENTER
}
key BUTTON_START {
base: fallback HOME
}
key BUTTON_SELECT {
base: fallback MENU
}
Nota sulla compatibilità
Prima di Android Honeycomb 3.0, la mappa dei caratteri chiave di Android veniva specificata
utilizzando una sintassi molto diversa ed era compilata in un formato file binario
(.kcm.bin) in fase di compilazione.
Sebbene il nuovo formato utilizzi la stessa estensione .kcm, la sintassi è molto diversa (e molto più potente).
A partire da Android Honeycomb 3.0, tutti i file delle mappe dei caratteri principali di Android devono utilizzare la nuova sintassi e il formato file di testo normale descritti in questo documento.
La vecchia sintassi non è supportata e i vecchi file .kcm.bin non sono riconosciuti dal sistema.
Nota sulla lingua
Al momento Android non supporta le tastiere multilingue. Inoltre, la mappa dei caratteri dei tasti generici incorporata presuppone un layout della tastiera in inglese americano.
Gli OEM sono invitati a fornire mappe dei caratteri dei tasti personalizzate per le loro tastiere se sono progettate per altre lingue.
Le versioni future di Android potrebbero offrire un supporto migliore per le tastiere multilingue o per i layout della tastiera selezionabili dall'utente.
Convalida
Assicurati di convalidare i file delle mappe dei caratteri principali utilizzando lo strumento Convalida mappe tasti.