Questa pagina è stata tradotta dall'API Cloud Translation.

File delle mappe dei caratteri chiave

I file di mappatura dei caratteri chiave (file .kcm ) sono responsabili della mappatura delle combinazioni di codici chiave Android con modificatori su caratteri Unicode.

I file di layout dei tasti specifici del dispositivo sono necessari per tutti i dispositivi di input interni (incorporati) dotati di tasti, se non altro per indicare al sistema che il dispositivo è solo per scopi speciali (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 di caratteri chiave generica adatta a molte tastiere esterne.

Se non è disponibile alcun file di layout dei tasti specifico del dispositivo, il sistema ne sceglierà invece uno predefinito.

Posizione

I file della mappa dei caratteri chiave vengono individuati in base al fornitore USB, all'ID del 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 si costruisce 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 di mappa dei caratteri chiave generico

Il sistema fornisce uno speciale file di mappatura dei caratteri chiave integrato chiamato Generic.kcm . Questa mappa dei caratteri chiave è destinata a supportare una varietà di tastiere esterne standard.

Non modificare la mappa dei caratteri chiave generica!

File della mappa dei caratteri della chiave virtuale

Il sistema fornisce uno speciale file di mappatura dei caratteri dei tasti integrato denominato Virtual.kcm 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 possa essere utilizzato per inserire sequenze di tasti nelle applicazioni dall'IME o dalla strumentazione di test, anche per i dispositivi che non dispongono di tastiere integrate.

Si presuppone che la tastiera virtuale abbia un layout QWERTY completo uguale su tutti i dispositivi. Ciò consente alle applicazioni di inserire sequenze di tasti utilizzando la tastiera virtuale e ottenere sempre gli stessi risultati.

Non modificare la mappa dei caratteri dei tasti virtuali!

Sintassi

Un file di mappa dei caratteri chiave è un file di testo semplice costituito da una dichiarazione del tipo di tastiera e un insieme di dichiarazioni di tasti.

Dichiarazione del tipo di tastiera

Una dichiarazione del tipo di tastiera descrive il comportamento generale della tastiera. Un file di mappa caratteri deve contenere una dichiarazione del tipo di tastiera. Per chiarezza, viene spesso posizionato all'inizio del file.

type FULL

Sono riconosciuti i seguenti tipi di tastiera:

NUMERIC : tastiera numerica (12 tasti).
Una tastiera numerica supporta l'immissione di testo utilizzando un approccio multi-tap. Potrebbe essere necessario toccare più volte un tasto per generare la lettera o il simbolo desiderato.
Questo tipo di tastiera è generalmente progettata per la digitazione con il pollice.
Corrisponde a KeyCharacterMap.NUMERIC .
PREDICTIVE : Una tastiera con tutte le lettere, ma con più di una lettera per tasto.
Questo tipo di tastiera è generalmente progettata per la digitazione con il pollice.
Corrisponde a KeyCharacterMap.PREDICTIVE .
ALPHA : Una tastiera con tutte le lettere e forse alcuni numeri.
Una tastiera alfabetica supporta direttamente l'immissione di testo ma può avere un layout ridotto 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 fornisce funzionalità speciali per le tastiere alfabetiche come la capitalizzazione automatica e i tasti SHIFT e ALT attivati/bloccati.
Questo tipo di tastiera è generalmente progettata per la digitazione con il pollice.
FULL : una tastiera completa in stile PC.
Una tastiera completa si comporta come la tastiera di un PC. È possibile accedere a tutti i simboli direttamente premendo i tasti sulla tastiera senza supporto sullo schermo o vantaggi come la capitalizzazione automatica.
Questo tipo di tastiera è generalmente progettata per la digitazione completa a due mani.
SPECIAL_FUNCTION : una tastiera utilizzata solo per eseguire funzioni di controllo del sistema anziché per la digitazione.
Una tastiera con funzioni speciali è costituita solo da tasti non stampabili come HOME e POWER che non vengono effettivamente utilizzati per la digitazione.

Le mappe dei caratteri chiave Generic.kcm e Virtual.kcm sono entrambe tastiere FULL .

Dichiarazioni chiave

Ciascuna dichiarazione di chiave è costituita dalla parola chiave key seguita da un nome in 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à chiave stabilisce una mappatura da una chiave a un comportamento. Per rendere più compatti i file della mappa dei caratteri chiave, è possibile mappare diverse proprietà sullo stesso comportamento separandole con una virgola.

Nell'esempio precedente, alla proprietà label viene assegnato il comportamento 'A' . Allo stesso modo, alle proprietà ctrl , alt e meta viene assegnato contemporaneamente il comportamento none .

Vengono riconosciute le seguenti proprietà:

label : Specifica l'etichetta che viene fisicamente stampata sulla chiave, quando è composta da un solo carattere. Questo è il valore restituito dal metodo KeyCharacterMap.getDisplayLabel .
number : specifica il comportamento (carattere che deve essere digitato) quando è attiva una visualizzazione di testo numerico, ad esempio quando l'utente digita un numero di telefono.
Le tastiere compatte spesso combinano più simboli in un unico tasto, in modo tale che lo stesso tasto possa essere utilizzato per digitare '1' e 'a' o '#' e 'q' , forse. Per questi tasti, la proprietà number deve 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 che deve essere digitato) quando non vengono premuti modificatori.
<modificatore> o <modificatore1> + <modificatore2> + ...: specifica il comportamento (carattere che deve essere digitato) quando viene premuto il tasto e tutti i modificatori specificati sono attivi.
Ad esempio, la proprietà del modificatore shift specifica un comportamento che si applica quando viene premuto il modificatore SHIFT SINISTRO o SHIFT DESTRO.
Allo stesso modo, la proprietà del modificatore rshift+ralt specifica un comportamento che si applica quando i modificatori SHIFT DESTRO e ALT DESTRO vengono premuti insieme.

I seguenti modificatori sono riconosciuti nelle proprietà del modificatore:

shift : si applica quando viene premuto il modificatore LEFT SHIFT o RIGHT SHIFT.
lshift : si applica quando viene premuto il modificatore SHIFT SINISTRO.
rshift : si applica quando viene premuto il modificatore RIGHT SHIFT.
alt : si applica quando viene premuto il modificatore LEFT ALT o RIGHT ALT.
lalt : si applica quando viene premuto il modificatore LEFT ALT.
ralt : si applica quando viene premuto il modificatore ALT DESTRA.
ctrl : si applica quando viene premuto il modificatore CONTROL 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 LEFT META o RIGHT META.
lmeta : si applica quando viene premuto il modificatore LEFT META.
rmeta : si applica quando viene premuto il modificatore RIGHT META.
sym : si applica quando viene premuto il modificatore SIMBOLO.
fn : si applica quando viene premuto il modificatore FUNZIONE.
capslock : si applica quando il modificatore BLOC MAIUSC è bloccato.
numlock : si applica quando il modificatore NUM LOCK è bloccato.
scrolllock : si applica quando il modificatore BLOC SCORR è bloccato.

L'ordine in cui le proprietà sono elencate è significativo. Quando si associa una chiave a un comportamento, il sistema esegue la scansione di tutte le proprietà rilevanti in ordine e restituisce l'ultimo comportamento applicabile trovato.

Di conseguenza, le proprietà specificate successivamente sovrascrivono le proprietà specificate in precedenza per una determinata chiave.

Comportamenti

Ogni proprietà si associa a un comportamento. Il comportamento più comune è digitare un carattere, ma ce ne sono altri.

Vengono riconosciuti i seguenti comportamenti:

none : non digitare un carattere.
Questo comportamento è predefinito quando non viene specificato alcun carattere. Specificare none è facoltativo ma migliora la chiarezza.
'X' : digitare il carattere letterale specificato.
Questo comportamento fa sì che il carattere specificato venga immesso nella visualizzazione del testo focalizzato. Il carattere letterale può essere qualsiasi carattere ASCII o una delle seguenti sequenze di escape:
- '\\' : digitare un carattere barra rovesciata.
- '\n' : Digita un carattere di nuova riga (usalo per INVIO/INVIO).
- '\t' : digita un carattere TAB.
- '\'' : digita un carattere apostrofo.
- '\"' : digitare una virgoletta.
- '\uXXXX' : Digita il carattere Unicode il cui punto di codice è dato in esadecimale da XXXX.
fallback <nome codice chiave Android>: esegue un'azione predefinita se la chiave non viene gestita dall'applicazione.
Questo comportamento fa sì che il sistema simuli la pressione di un tasto diverso quando un'applicazione non gestisce il tasto specificato in modo nativo. Viene utilizzato per supportare il comportamento predefinito per i nuovi tasti che non tutte le applicazioni sanno come gestire, come ESCAPE o i tasti del tastierino numerico (quando non viene premuto il bloc num).
Quando viene eseguito un comportamento di fallback, l'applicazione riceverà due pressioni di tasti: una per il tasto originale e un'altra per il tasto di fallback selezionato. Se l'applicazione gestisce la chiave originale durante l'attivazione della chiave, l'evento della chiave di fallback verrà annullato ( KeyEvent.isCanceled restituirà true ).

Il sistema riserva due caratteri Unicode per eseguire funzioni speciali:

'\uef00' : quando viene eseguito questo comportamento, la visualizzazione testo utilizza 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, la vista testo visualizza una finestra di dialogo di selezione caratteri che contiene simboli vari.

Il sistema riconosce i seguenti caratteri Unicode come combinazione di caratteri diacritici morti:

'\u0300' : accento grave.
'\u0301' : accento acuto.
'\u0302' : accento circonflesso.
'\u0303' : accento tilde.
'\u0308' : accento con umlaut.

Quando viene digitata una chiave morta seguita da un altro carattere, vengono composti la chiave morta e i caratteri successivi. Ad esempio, quando l'utente digita un tasto morto con accento grave seguito dalla lettera "a", il risultato è "à".

Fare riferimento a KeyCharacterMap.getDeadChar per ulteriori informazioni sulla gestione delle chiavi inattive.

Commenti

Le righe di commento iniziano con "#" e continuano fino alla fine della riga. Come questo:

# A comment!

Le righe vuote vengono ignorate.

Come le combinazioni di tasti vengono mappate sui comportamenti

Quando l'utente preme un tasto, il sistema cerca il comportamento associato alla combinazione della pressione di quel tasto e dei modificatori attualmente premuti.

MAIUSC+A

Supponiamo che l'utente abbia premuto A e SHIFT insieme. 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 esegue la scansione delle proprietà dalla prima all'ultima e da sinistra a destra, ignorando le proprietà label e number , che sono speciali.

La prima proprietà incontrata è base . La proprietà base si applica sempre a un tasto, indipendentemente dai modificatori premuti. Specifica essenzialmente il comportamento predefinito per la chiave a meno che non venga sovrascritta dalle seguenti proprietà. Poiché la proprietà base si applica alla pressione di questo tasto, il sistema prende nota del fatto che il suo comportamento è 'a' (digitare il carattere a ).

Il sistema continua quindi a scansionare le proprietà successive nel caso in cui qualcuna di esse sia più specifica della base e la sovrascriva. Incontra shift che si applica anche alla pressione del tasto SHIFT + A. Quindi il sistema decide di ignorare il comportamento della proprietà di base e sceglie il comportamento associato alla proprietà shift , che è 'A' (digitare il carattere A ).

Quindi continua a scansionare la tabella, tuttavia nessun'altra proprietà si applica alla pressione di questo tasto (BLOC MAIUSC non è bloccato, non viene premuto il tasto CONTROL, non viene premuto il tasto ALT e non viene premuto il tasto META).

Quindi il comportamento risultante per la combinazione di tasti SHIFT + A è 'A' .

CONTROLLO+A

Consideriamo ora cosa accadrebbe se l'utente premesse A e CONTROL insieme.

Come prima, il sistema analizzerà la tabella delle proprietà. Noterebbe che la proprietà base viene applicata ma continuerà anche la scansione fino a raggiungere la proprietà control . In realtà, la proprietà control appare dopo base , quindi il suo comportamento sovrascrive il comportamento base .

Quindi il comportamento risultante per la combinazione di tasti CONTROL+A è none .

FUGA

Supponiamo ora che l'utente abbia premuto ESCAPE.

key ESCAPE {
    base:                               fallback BACK
    alt, meta:                          fallback HOME
    ctrl:                               fallback MENU
}

Questa volta il sistema ottiene il comportamento fallback BACK , un comportamento di fallback. Poiché non viene visualizzato alcun carattere letterale, non verrà digitato alcun carattere.

Durante l'elaborazione della chiave, il sistema consegnerà prima KEYCODE_ESCAPE all'applicazione. Se l'applicazione non lo gestisce, il sistema riproverà, ma questa volta consegnerà KEYCODE_BACK all'applicazione come richiesto dal comportamento di fallback.

Pertanto le applicazioni che riconoscono e supportano KEYCODE_ESCAPE hanno l'opportunità di gestirlo così com'è, ma altre applicazioni che non lo fanno possono invece eseguire l'azione di fallback trattando la chiave come se fosse KEYCODE_BACK .

NUMPAD_0 con o senza BLOC NUM

I tasti del tastierino numerico hanno interpretazioni molto diverse a seconda che il tasto BLOC NUM sia bloccato.

La seguente dichiarazione di chiave garantisce che KEYCODE_NUMPAD_0 digiti 0 quando viene premuto BLOC NUM. Quando BLOC NUM non viene premuto, la chiave viene consegnata all'applicazione come al solito e, se non viene gestita, viene invece consegnata la chiave di fallback KEYCODE_INSERT .

key NUMPAD_0 {
    label, number:                      '0'
    base:                               fallback INSERT
    numlock:                            '0'
    ctrl, alt, meta:                    none
}

Come possiamo vedere, le dichiarazioni dei tasti di fallback migliorano notevolmente la compatibilità con le applicazioni meno recenti che non riconoscono o non supportano direttamente tutti i tasti presenti su una tastiera completa in stile 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'
}

Tappetino da gioco

# 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 di 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 di file binario ( .kcm.bin ) in fase di creazione.

Sebbene il nuovo formato utilizzi la stessa estensione .kcm , la sintassi è abbastanza diversa (e molto più potente).

A partire da Android Honeycomb 3.0, tutti i file delle mappe dei caratteri dei tasti Android devono utilizzare la nuova sintassi e il formato di file di testo semplice descritti in questo documento. La vecchia sintassi non è supportata e i vecchi file .kcm.bin non vengono riconosciuti dal sistema.

Nota sulla lingua

Android attualmente non supporta le tastiere multilingue. Inoltre, la mappa dei caratteri chiave generica incorporata presuppone un layout di tastiera inglese americano.

Gli OEM sono incoraggiati a fornire mappe di caratteri chiave personalizzate per le loro tastiere se progettate per altre lingue.

Le versioni future di Android potrebbero fornire un supporto migliore per tastiere multilingue o layout di tastiera selezionabili dall'utente.

Validazione

Assicurati di convalidare i file della mappa dei caratteri chiave utilizzando lo strumento Convalida mappe dei tasti .