Keymaps and Keyboard Input | Android Open Source

This document describes how keyboard input gets translated into Android actions and how you can customize key layout and key character maps to match the ... Home Source Porting Compatibility Community About Android.com SetupandBuilding BuildSystem ConfiguringaNewProduct BuildCookbook ReleaseKeysandSigningBuilds Customization Customization AndroidUser'sGuide System Bringup Connectivity Bluetooth GPS Wi-Fi DisplayDrivers InputDevices KeymapsandKeyboard Lights Multimedia Audio Camera/Video PowerManagement Sensors Telephony RadioInterfaceLayer SIMToolkitApplication(STK) DalvikVirtualMachine PortingDalvik TestingandDebugging InstrumentationTesting DebuggingwithGDB DebuggingNativeCode Debuggingwithtcpdump   KeymapsandKeyboardInput Inthisdocument Functionality KeyLayoutMap KeyCharacterMap ImplementingYourOwnDriver(DriverTemplate) SampleImplementation ThisdocumentdescribeshowkeyboardinputgetstranslatedintoAndroidactionsandhowyoucancustomizekeylayoutandkeycharactermapstomatchtheneedsofyourowndevice. AndroidusesthestandardLinuxinputeventdevice(/dev/event0)anddriverasdescribedinthelinux/input.hkernelheaderfile.FormoreinformationregardingstandardLinuxinputdrivers,pleaseseeLinuxInputdriversathttp://kernel.org. Functionality Android'sinputeventdeviceisstructuredaroundaninterruptorpollingroutinethatcapturesthedevice-specificscancodeandconvertsittoastandardformacceptabletoLinux(asdefinedininput.h)beforepassingittothekernelwithinput_event(). Thekeymapdriver'sotherprimaryfunctionistoestablishaprobefunctionthatsetsuptheinterruptorpollingfunction,handleshardwareinitialization,andattachesthedrivertotheinputsubsystemwithinput_register_device(). Thetablebelowdescribesthestepsrequiredtotranslatefromkeyboardinputtoapplicationaction: Step Action Explanation 1. WindowmanagerreadskeyeventfromLinuxkeyboarddriver. Eventsaretypicallypositional.Forexample,thetop-leftpositiononakeypadreturns16regardlessofwhetherthatkeyisprintedwithaQ(asonaQWERTYkeypad)oranA(asonanAZERTYkeypads).ThisfirstconversionbytheLinuxKeyboardDriveryieldsascancode(forexample,16). 2. Windowmanagermapsscancodetokeycode. Whenthewindowmanagerreadsakeyeventoutofthedriver,itmapsthescancodetoakeycodeusingakeylayoutmapfile.Typically,thekeycodeistheprimarysymbolscreen-printedonakey.Forexample,KEYCODE_DPAD_CENTERisthecenterbuttononthefive-waynavigationcontrol.EventhoughALT+Ggeneratesa"?"character,KEYCODE_Gisthekeycode. 3. Windowmanagersendsboththescancodeandthekeycodetotheapplication. Boththescancodeandkeycodearehandledbytheviewwithfocus. Howtheapplicationinterpretsbothdependontheapplication. KeyLayoutMap SelectionofaKeyLayoutMap Keylayoutmapsareinstalledin/system/usr/keylayoutand/data/usr/keylayout. Foreachkeyboarddevicexxx,settheandroid.keylayout.xxxsystemproperty(seeBuildingNewDeviceforhelpsettingsystemproperties).Ifyoudon'tspecifyakeylayoutfile,Androidwilldefaultto/system/usr/keylayout/qwerty.kl. FileFormat KeylayoutmapsarestoredonthedeviceasUTF-8textfilesandhavethefollowingcharacteristics: Comments:Thepoundsymbol(#)denotesacommentandeverythingafterthepoundsymbolonalineisignored. Whitespace:Allemptylinesareignored. Keydefinitions:KeydefinitionsfollowthesyntaxkeySCANCODEKEYCODE[FLAGS...],whereSCANCODEisanumber,KEYCODEisdefinedinyourspecifickeylayoutfile(android.keylayout.xxx),andpotentialFLAGSaredefinedasfollows: SHIFT:Whilepressed,theshiftkeymodifierisset ALT:Whilepressed,thealtkeymodifierisset CAPS:Whilepressed,thecapslockkeymodifierisset WAKE:Whenthiskeyispressedwhilethedeviceisasleep,thedevicewillwakeupandthekeyeventgetssenttotheapp. WAKE_DROPPED:Whenthiskeyispressedwhilethedeviceisasleep,thedevicewillwakeupandthekeyeventdoesnotgetsenttotheapp. ExampleofaKeyLayoutMapFile Thefollowingcodecomesfromandroid/src/device/product/generic/tuttle2.klandisanexampleofacompletekeylayoutfile: #Copyright2007GoogleInc. key21 key32 key43 key54 key65 key76 key87 key98 key109 key110 key158BACKWAKE_DROPPED key230SOFT_RIGHTWAKE key60SOFT_RIGHTWAKE key107ENDCALLWAKE_DROPPED key62ENDCALLWAKE_DROPPED key229MENUWAKE_DROPPED key59MENUWAKE_DROPPED key228POUND key227STAR key231CALLWAKE_DROPPED key61CALLWAKE_DROPPED key232DPAD_CENTERWAKE_DROPPED key108DPAD_DOWNWAKE_DROPPED key103DPAD_UPWAKE_DROPPED key102HOMEWAKE key105DPAD_LEFTWAKE_DROPPED key106DPAD_RIGHTWAKE_DROPPED key115VOLUME_UP key114VOLUME_DOWN key116POWERWAKE key212SLASH key16Q key17W key18E key19R key20T key21Y key22U key23I key24O key25P key30A key31S key32D key33F key34G key35H key36J key37K key38L key14DEL key44Z key45X key46C key47V key48B key49N key50M key51COMMA key52PERIOD key28NEWLINE key56ALT_LEFT key42SHIFT_LEFT key215AT key57SPACE key53SLASH key127SYM key100ALT_LEFT key399GRAVE KeyCharacterMap SelectionofaKeyCharacterMap Keycharactermapsareinstalledin/system/usr/keycharsand/data/usr/keychars. Foreachkeyboarddevicexxx,settheandroid.keychar.xxxsystempropertytothefullpathofthedesiredkeycharfile.Ifyoudon'tspecifyakeycharfile,Androidwilldefaultto/system/usr/keychar/qwerty.kl. FileFormat Keycharactermapsarestoredonthedeviceasbinaryresourcesinordertoreduceloadingtime.Keycharactermapshavethefollowingcharacteristics: Comments:Thepoundsymbol(#)denotesacommentandeverythingafterthepoundsymbolonalineisignored. Whitespace:Allemptylinesareignored. Columndefinitions:ColumndefinitionsfollowthesyntaxcolumnsMODIFIERS[...],whereMODIFIERSaredefinedasfollows: CharacterinMODIFIERS Correspondingbitinthemodifiers O nomodifiers S MODIFIER_SHIFT C MODIFIER_CONTROL L MODIFIER_CAPS_LOCK A MODIFIER_ALT Keydefinitions:KeydefinitionshavethesyntaxkeySCANCODECHARACTER[...]whereSCANCODEisanumberandCHARACTERvaluesareeitherUTF-8charactersinquotationmarks(forexample,"a")oranumericvaluethatstrtolcanparse. ExampleofaKeyCharacterMapFile Thefollowingcodecomesfromandroid/src/device/product/generic/tuttle2.kcmandrepresentsacompletekeycharacterfile: Thetypelineindicateswhatkindofkeyboardyourdeviceimplements.Possibletypesinclude: NUMERIC:Anumeric(12-key)keyboard. Q14:Akeyboardthatincludesalllettersbutmultiplelettersperkey. QWERTY:Akeyboardwithalllettersandpossiblynumbers.Thisoptionappliestoallfullkeyboardconfigurations,suchasAZERTY. #Copyright2007GoogleInc. [type=QWERTY] #keycodebasecapsfncaps_fnnumberdisplay_label A'a''A''%'0x00'%''A' B'b''B''='0x00'=''B' C'c''C''8'0x00E7'8''C' D'd''D''5'0x00'5''D' E'e''E''2'0x0301'2''E' F'f''F''6'0x00A5'6''F' G'g''G''-''_''-''G' H'h''H''[''{''[''H' I'i''I''$'0x0302'$''I' J'j''J'']''}'']''J' K'k''K''"''~''"''K' L'l''L'''''`'''''L' M'm''M''>'0x00'>''M' N'n''N'' ResourceBinaryFileFormat Thefilesnippetabovegetsconvertedtothefollowingbythemakekcharmaptoolaspartofthebuildprocess.Youcanmmapthisfileinandsharetheapproximately4kofmemorythatitusesbetweenprocessestominimizeloadtime. Offset Size(bytes) Description 0x00-0x0b Theasciivalue"keycharmap1"includingthenullcharacter 0x0c-0x0f padding 0x10-0x13 Thenumberofentriesinthemodifierstable(COLS) 0x14-0x17 Thenumberofentriesinthecharacterstable(ROWS) 0x18-0x1f padding 4*COLS Modifierstable.Themodifiermaskvaluesthateachofthe columnsinthecharacterstablecorrespondto. paddingtothenext16byteboundary 4*COLS*ROWS Characterstable.Themodifiermaskvaluesthateachofthe columnscorrespondto. ImplementingYourOwnDriver(DriverTemplate) Thefollowingfile,pguide_events.c,illustrateshowtoimplementanAndroidkeymapdriver. /* *pguide_events.c * *ANDROIDPORTINGGUIDE:INPUTEVENTSDRIVERTEMPLATE * *Thistemplateisdesignedtoanexampleofthefunctionality *necessaryforAndroidtorecieveinputevents.ThePGUIDE_EVENT *macrosaremeantaspointersindicatingwheretoimplementthe *hardwarespecificcodenecessaryforthenewdevice.Theexistence *ofthemacrosisnotmeanttotrivializetheworkrequired,justas *anindicationofwheretheworkneedstobedone. * *Copyright2007,GoogleInc. *Basedongoldfish-events.c * */ #include #include #include #include #include #include #include #include #include #definePGUIDE_EVENTS_INTERRUPTdo{}while(0) #definePGUIDE_EVENTS_PROBEdo{}while(0) structevent_dev{ structinput_dev*input; intirq; }; staticirqreturn_tpguide_events_interrupt(intirq,void*dev_id) { structevent_dev*edev=dev_id; unsignedtype=0,code=0,value=0; /*Setuptype,code,andvalueperinput.h */ PGUIDE_EVENTS_INTERRUPT; input_event(edev->input,type,code,value); returnIRQ_HANDLED; } staticintpguide_events_probe(structplatform_device*pdev) { structinput_dev*input_dev; structevent_dev*edev; printk("***pguideeventsprobe***\n"); edev=kzalloc(sizeof(structevent_dev),GFP_KERNEL); input_dev=input_allocate_device(); /*Setupedev->irqanddoanyhardwareinit*/ PGUIDE_EVENTS_PROBE; if(request_irq(edev->irq,pguide_events_interrupt,0, "pguide_events",edev)<0){ gotofail; } /*indicatethatwegeneratekeyevents*/ set_bit(EV_KEY,input_dev->evbit); set_bit(EV_REL,input_dev->evbit); set_bit(EV_ABS,input_dev->evbit); /*indicatethatwegenerate*any*keyevent*/ bitmap_fill(input_dev->keybit,KEY_MAX); bitmap_fill(input_dev->relbit,REL_MAX); bitmap_fill(input_dev->absbit,ABS_MAX); platform_set_drvdata(pdev,edev); input_dev->name="pguide_events"; input_dev->private=edev; input_dev->cdev.dev=&pdev->dev; input_register_device(input_dev); return0; fail: kfree(edev); input_free_device(input_dev); return-EINVAL; } staticstructplatform_driverpguide_events_driver={ .probe=pguide_events_probe, .driver={ .name="pguide_events", }, }; staticint__devinitpguide_events_init(void) { returnplatform_driver_register(&pguide_events_driver); } staticvoid__exitpguide_events_exit(void) { } module_init(pguide_events_init); module_exit(pguide_events_exit); MODULE_DESCRIPTION("PguideEventDevice"); MODULE_LICENSE("GPL"); SampleImplementation Assumethefollowingforthesetupofanewkeypaddevice: android.keylayout.partnerxx_keypad=/system/usr/keylayout/partnerxx_keypad.kl android.keychar.partnerxx_keypad=/system/usr/keychars/partnerxx.kcm Thefollowingexamplelogfileindicatesthatyouhavecorrectlyregisteredthenewkeypad: I/EventHub(1548):Newdevice:path=/dev/input/event0name=partnerxx_keypadid=0x10000(of0x1)index=1fd=30 I/EventHub(1548):newkeyboardinputdeviceadded,name=partnerxx_keypad D/WindowManager(1548):Startinginputthread. D/WindowManager(1548):Startupcomplete! I/EventHub(1548):Newkeyboard:name=partnerxx_keypad keymap=partnerxx_keypad.kl keymapPath=/system/usr/keychars/partnerxx_keypad.kcm.bin I/ServiceManager(1535):ServiceManager:addService(window,0x13610) I/EventHub(1548):Reportingdeviceopened:id=0x10000,name=/dev/input/event0 I/KeyInputQueue(1548):Deviceadded:id=0x10000,name=partnerxx_keypad,classes=1 I/KeyInputQueue(1548):Keymap:partnerxx_keypad.kl Thesnippetabovecontainsartificiallinebreakstomaintainaprint-friendlydocument. ↑Gototop SiteTermsofService- PrivacyPolicy