1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 <html> 4 5 <head> 6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 7 <meta http-equiv="Content-Language" content="en-us"> 8 <link rel="stylesheet" href="http://www.unicode.org/reports/reports.css" 9 type="text/css"> 10 <title>UTS #35: Unicode LDML: Keyboards</title> 11 <style type="text/css"> 12 <!-- 13 .dtd { 14 font-family: monospace; 15 font-size: 90%; 16 background-color: #CCCCFF; 17 border-style: dotted; 18 border-width: 1px; 19 } 20 21 .xmlExample { 22 font-family: monospace; 23 font-size: 80% 24 } 25 26 .blockedInherited { 27 font-style: italic; 28 font-weight: bold; 29 border-style: dashed; 30 border-width: 1px; 31 background-color: #FF0000 32 } 33 34 .inherited { 35 font-weight: bold; 36 border-style: dashed; 37 border-width: 1px; 38 background-color: #00FF00 39 } 40 41 .element { 42 font-weight: bold; 43 color: red; 44 } 45 46 .attribute { 47 font-weight: bold; 48 color: maroon; 49 } 50 51 .attributeValue { 52 font-weight: bold; 53 color: blue; 54 } 55 56 li, p { 57 margin-top: 0.5em; 58 margin-bottom: 0.5em 59 } 60 61 h2, h3, h4, table { 62 margin-top: 1.5em; 63 margin-bottom: 0.5em; 64 } 65 --> 66 </style> 67 </head> 68 69 <body> 70 71 <table class="header" width="100%"> 72 <tr> 73 <td class="icon"><a href="http://unicode.org"> <img 74 alt="[Unicode]" src="http://unicode.org/webscripts/logo60s2.gif" 75 width="34" height="33" 76 style="vertical-align: middle; border-left-width: 0px; border-bottom-width: 0px; border-right-width: 0px; border-top-width: 0px;"></a> 77 <a class="bar" href="http://www.unicode.org/reports/">Technical 78 Reports</a></td> 79 </tr> 80 <tr> 81 <td class="gray"> </td> 82 </tr> 83 </table> 84 <div class="body"> 85 <h2 style="text-align: center"> 86 Unicode Technical 87 Standard #35 88 </h2> 89 <h1> 90 Unicode Locale Data Markup Language (LDML)<br>Part 7: Keyboards 91 </h1> 92 93 <!-- At least the first row of this header table should be identical across the parts of this UTS. --> 94 <table border="1" cellpadding="2" cellspacing="0" class="wide"> 95 <tr> 96 <td>Version</td> 97 <td>34</td> 98 </tr> 99 <tr> 100 <td>Editors</td> 101 <td>Steven Loomis (<a href="mailto:srl (a] icu-project.org">srl (a] icu-project.org</a>) 102 and <a href="tr35.html#Acknowledgments">other CLDR committee 103 members</a></td> 104 </tr> 105 </table> 106 107 <p> 108 For the full header, summary, and status, see <a href="tr35.html"> 109 Part 1: Core</a> 110 </p> 111 112 <h3> 113 <i>Summary</i> 114 </h3> 115 <p> 116 This document describes parts of an XML format (<i>vocabulary</i>) 117 for the exchange of structured locale data. This format is used in 118 the <a href="http://cldr.unicode.org/">Unicode Common Locale Data 119 Repository</a>. 120 </p> 121 122 <p> 123 This is a partial document, describing keyboard mappings. For the 124 other parts of the LDML see the <a href="tr35.html">main LDML 125 document</a> and the links above. 126 </p> 127 128 <h3> 129 <i>Status</i> 130 </h3> 131 132 <!-- NOT YET APPROVED 133 <p> 134 <i class="changed">This is a<b><font color="#ff3333"> 135 draft </font></b>document which may be updated, replaced, or superseded by 136 other documents at any time. Publication does not imply endorsement 137 by the Unicode Consortium. This is not a stable document; it is 138 inappropriate to cite this document as other than a work in 139 progress. 140 </i> 141 </p> 142 END NOT YET APPROVED --> 143 <!-- APPROVED --> 144 <p> 145 <i>This document has been reviewed by Unicode members and other 146 interested parties, and has been approved for publication by the 147 Unicode Consortium. This is a stable document and may be used as 148 reference material or cited as a normative reference by other 149 specifications.</i> 150 </p> 151 <!-- END APPROVED --> 152 153 <blockquote> 154 <p> 155 <i><b>A Unicode Technical Standard (UTS)</b> is an independent 156 specification. Conformance to the Unicode Standard does not imply 157 conformance to any UTS.</i> 158 </p> 159 </blockquote> 160 <p> 161 <i>Please submit corrigenda and other comments with the CLDR bug 162 reporting form [<a href="tr35.html#Bugs">Bugs</a>]. Related 163 information that is useful in understanding this document is found 164 in the <a href="tr35.html#References">References</a>. For the latest 165 version of the Unicode Standard see [<a href="tr35.html#Unicode">Unicode</a>]. 166 For a list of current Unicode Technical Reports see [<a 167 href="tr35.html#Reports">Reports</a>]. For more information about 168 versions of the Unicode Standard, see [<a href="tr35.html#Versions">Versions</a>]. 169 </i> 170 </p> 171 172 <h2> 173 <a name="Parts" href="#Parts">Parts</a> 174 </h2> 175 176 <!-- This section of Parts should be identical in all of the parts of this UTS. --> 177 <p>The LDML specification is divided into the following parts:</p> 178 <ul class="toc"> 179 <li>Part 1: <a href="tr35.html#Contents">Core</a> (languages, 180 locales, basic structure) 181 </li> 182 <li>Part 2: <a href="tr35-general.html#Contents">General</a> 183 (display names & transforms, etc.) 184 </li> 185 <li>Part 3: <a href="tr35-numbers.html#Contents">Numbers</a> 186 (number & currency formatting) 187 </li> 188 <li>Part 4: <a href="tr35-dates.html#Contents">Dates</a> (date, 189 time, time zone formatting) 190 </li> 191 <li>Part 5: <a href="tr35-collation.html#Contents">Collation</a> 192 (sorting, searching, grouping) 193 </li> 194 <li>Part 6: <a href="tr35-info.html#Contents">Supplemental</a> 195 (supplemental data) 196 </li> 197 <li>Part 7: <a href="tr35-keyboards.html#Contents">Keyboards</a> 198 (keyboard mappings) 199 </li> 200 </ul> 201 <h2> 202 <a name="Contents" href="#Contents">Contents of Part 7, Keyboards</a> 203 </h2> 204 <!-- START Generated TOC: CheckHtmlFiles --> 205 <ul class="toc"> 206 <li>1 <a href="#Introduction">Keyboards</a></li> 207 <li>2 <a href="#Goals_and_Nongoals">Goals and Nongoals</a></li> 208 <li>3 <a href="#Definitions">Definitions</a></li> 209 <li>4 <a href="#File_and_Dir_Structure">File and Directory 210 Structure</a></li> 211 <li>5 <a href="#Element_Heirarchy_Layout_File">Element 212 Hierarchy - Layout File</a> 213 <ul class="toc"> 214 <li>5.1 <a href="#Element_Keyboard">Element: keyboard</a></li> 215 <li>5.2 <a href="#Element_version">Element: version</a></li> 216 <li>5.3 <a href="#Element_generation">Element: generation</a></li> 217 <li>5.4 <a href="#Element_names">Element: names</a></li> 218 <li>5.5 <a href="#Element_name">Element: name</a></li> 219 <li>5.6 <a href="#Element_settings">Element: settings</a></li> 220 <li>5.7 <a href="#Element_keyMap">Element: keyMap</a> 221 <ul class="toc"> 222 <li>Table: <a href="#Possible_Modifier_Keys">Possible 223 Modifier Keys</a></li> 224 </ul> 225 </li> 226 <li>5.8 <a href="#Element_map">Element: map</a></li> 227 <li>5.9 <a href="#Element_import">Element: 228 import</a></li> 229 <li>5.10 <a href="#Element_displayMap">Element: 230 displayMap</a></li> 231 <li>5.11 <a href="#Element_display">Element: 232 display</a></li> 233 <li>5.12 <a href="#Element_layer">Element: 234 layer</a></li> 235 <li>5.13 <a href="#Element_row">Element: 236 row</a></li> 237 <li>5.14 <a href="#Element_switch">Element: 238 switch</a></li> 239 <li>5.15 <a href="#Element_vkeys">Element: 240 vkeys</a></li> 241 <li>5.16 <a href="#Element_vkey">Element: 242 vkey</a></li> 243 <li>5.17 <a href="#Element_transforms">Element: 244 transforms</a></li> 245 <li>5.18 <a href="#Element_transform">Element: 246 transform</a></li> 247 <li>5.19 <a href="#Element_reorder">Element: 248 reorder</a></li> 249 <li>5.20 <a href="#Element_final">Element: 250 final</a></li> 251 <li>5.21 <a href="#Element_backspaces">Element: 252 backspaces</a></li> 253 <li>5.22 <a href="#Element_backspace">Element: 254 backspace</a></li> 255 </ul> 256 </li> 257 <li>6 <a href="#Element_Heirarchy_Platform_File">Element 258 Hierarchy - Platform File</a> 259 <ul class="toc"> 260 <li>6.1 <a href="#Element_platform">Element: platform</a></li> 261 <li>6.2 <a href="#Element_hardwareMap">Element: 262 hardwareMap</a></li> 263 <li>6.3 <a href="#Element_hardwareMap_map">Element: map</a></li> 264 </ul> 265 </li> 266 <li>7 <a href="#Invariants">Invariants</a></li> 267 <li>8 <a href="#Data_Sources">Data Sources</a> 268 <ul class="toc"> 269 <li>Table: <a href="#Key_Map_Data_Sources">Key Map Data 270 Sources</a></li> 271 </ul> 272 </li> 273 <li>9 <a href="#Keyboard_IDs">Keyboard IDs</a> 274 <ul class="toc"> 275 <li>9.1 <a href="#Principles_for_Keyboard_Ids">Principles 276 for Keyboard Ids</a></li> 277 </ul> 278 </li> 279 <li>10 <a href="#Platform_Behaviors_in_Edge_Cases">Platform 280 Behaviors in Edge Cases</a></li> 281 </ul> 282 <!-- END Generated TOC: CheckHtmlFiles --> 283 <h2> 284 1 <a name="Introduction" href="#Introduction">Keyboards</a><a 285 name="Keyboards" href="#Keyboards"></a> 286 </h2> 287 288 <p>The CLDR keyboard format provides for the communication of 289 keyboard mapping data between different modules, and the comparison 290 of data across different vendors and platforms. The standardized 291 identifier for keyboards can be used to communicate, internally or 292 externally, a request for a particular keyboard mapping that is to be 293 used to transform either text or keystrokes. The corresponding data 294 can then be used to perform the requested actions.</p> 295 <p>For example, a web-based virtual keyboard may transform text in 296 the following way. Suppose the user types a key that produces a 297 "W" on a qwerty keyboard. A web-based tool using an azerty 298 virtual keyboard can map that text ("W") to the text that 299 would have resulted from typing a key on an azerty keyboard, by 300 transforming "W" to "Z". Such transforms are in 301 fact performed in existing web applications.</p> 302 <p>The data can also be used in analysis of the capabilities of 303 different keyboards. It also allows better interoperability by making 304 it easier for keyboard designers to see which characters are 305 generally supported on keyboards for given languages.</p> 306 <p>To illustrate this specification, here is an abridged layout 307 representing the English US 101 keyboard on the Mac OSX operating 308 system (with an inserted long-press example). For more complete 309 examples, and information collected about keyboards, see keyboard 310 data in XML.</p> 311 <pre><keyboard locale="en-t-k0-osx"><br> <version platform="10.4" number="$Revision: 8294 $" /><br> <names><br> <name value="U.S." /><br> </names><br> <keyMap><br> <map iso="E00" to="`" /><br> <map iso="E01" to="1" /><br> <map iso="D01" to="q" /><br> <map iso="D02" to="w" /><br> <map iso="D03" to="e" longPress=" " /><br> <br> </keyMap><br> <keyMap modifiers="caps"><br> <map iso="E00" to="`" /><br> <map iso="E01" to="1" /><br> <map iso="D01" to="Q" /><br> <map iso="D02" to="W" /><br> <br> </keyMap><br> <keyMap modifiers="opt"><br> <map iso="E00" to="`" /><br> <map iso="E01" to="" /> <!-- key=1 --><br> <map iso="D01" to="" /> <!-- key=Q --><br> <map iso="D02" to="" /> <!-- key=W --><br> <br> </keyMap><br> <transforms type="simple"><br> <transform from="` " to="`" /><br> <transform from="`a" to="" /><br> <transform from="`A" to="" /><br> <transform from=" " to="" /><br> <transform from="a" to="" /><br> <transform from="A" to="" /><br> <transform from=" " to="" /><br> <transform from="a" to="" /><br> <transform from="A" to="" /><br> <br> </transforms><br></keyboard></pre> 312 <p>And its associated platform file (which includes the hardware 313 mapping):</p> 314 <pre><platform id="osx"><br> <hardwareMap><br> <map keycode="0" iso="C01" /><br> <map keycode="1" iso="C02" /><br> <map keycode="6" iso="B01" /><br> <map keycode="7" iso="B02" /><br> <map keycode="12" iso="D01" /><br> <map keycode="13" iso="D02" /><br> <map keycode="18" iso="E01" /><br> <map keycode="50" iso="E00" /><br> </hardwareMap><br></platform></pre> 315 <h2> 316 2 <a name="Goals_and_Nongoals" href="#Goals_and_Nongoals">Goals 317 and Nongoals</a> 318 </h2> 319 <p>Some goals of this format are:</p> 320 <ol> 321 <li>Make the XML as readable as possible.</li> 322 <li>Represent faithfully keyboard data from major platforms: it 323 should be possible to create a functionally-equivalent data file 324 (such that given any input, it can produce the same output).</li> 325 <li>Make as much commonality in the data across platforms as 326 possible to make comparison easy.</li> 327 </ol> 328 <p>Some non-goals (outside the scope of the format) currently are:</p> 329 <ol> 330 <li>Display names or symbols for keycaps (eg, the German name 331 for "Return"). If that were added to LDML, it would be in a 332 different structure, outside the scope of this section.</li> 333 <li>Advanced IME features, handwriting recognition, etc.</li> 334 <li>Roundtrip mappingsthe ability to recover precisely the same 335 format as an original platform's representation. In particular, the 336 internal structure may have no relation to the internal structure of 337 external keyboard source data, the only goal is functional 338 equivalence.</li> 339 <li>More sophisticated transforms, such as for Indic character 340 rearrangement. It is anticipated that these would be added to a 341 future version, after working out a reasonable representation.</li> 342 </ol> 343 <p>Note: During development of this section, it was considered 344 whether the modifier RAlt (=AltGr) should be merged with Option. In 345 the end, they were kept separate, but for comparison across platforms 346 implementers may choose to unify them.</p> 347 <p> 348 Note that in parts of this document, the format <strong>@x</strong> 349 is used to indicate the <em>attribute</em> <strong>x</strong>. 350 </p> 351 <h2> 352 3 <a name="Definitions" href="#Definitions">Definitions</a> 353 </h2> 354 <p> 355 <b>Arrangement</b> is the term used to describe the relative position 356 of the rectangles that represent keys, either physically or 357 virtually. A physical keyboard has a static arrangement while a 358 virtual keyboard may have a dynamic arrangement that changes per 359 language and/or layer. While the arrangement of keys on a keyboard 360 may be fixed, the mapping of those keys may vary. 361 </p> 362 <p> 363 <b>Base character:</b> The character emitted by a particular key when 364 no modifiers are active. In ISO terms, this is group 1, level 1. 365 </p> 366 <p> 367 <b>Base map:</b> A mapping from the ISO positions to the base 368 characters. There is only one base map per layout. The characters on 369 this map can be output by not using any modifier keys. 370 </p> 371 <p> 372 <b>Core keyboard layout:</b> also known as alpha block. The primary 373 set of key values on a keyboard that are used for typing the target 374 language of the keyboard. For example, the three rows of letters on a 375 standard US QWERTY keyboard (QWERTYUIOP, ASDFGHJKL, ZXCVBNM) together 376 with the most significant punctuation keys. Usually this equates to 377 the minimal keyset for a language as seen on mobile phone keyboards. 378 </p> 379 <p> 380 <b>Hardware map:</b> A mapping between key codes and ISO layout 381 positions. 382 </p> 383 <p> 384 <b>Input Method Editor (IME):</b> a component or program that 385 supports input of large character sets. Typically, IMEs employ 386 contextual logic and candidate UI to identify the Unicode characters 387 intended by the user. 388 </p> 389 <p> 390 <b>ISO position:</b> The corresponding position of a key using the 391 ISO layout convention where rows are identified by letters and 392 columns are identified by numbers. For example, "D01" corresponds to 393 the "Q" key on a US keyboard. For the purposes of this document, an 394 ISO layout position is depicted by a one-letter row identifier 395 followed by a two digit column number (like "B03", "E12" or "C00"). 396 The following diagram depicts a typical US keyboard layout 397 superimposed with the ISO layout indicators (it is important to note 398 that the number of keys and their physical placement relative to 399 each-other in this diagram is irrelevant, rather what is important is 400 their logical placement using the ISO convention):<img 401 src="images/keyPositions.png" 402 alt="keyboard layout example showing ISO key numbering"> 403 </p> 404 <p>One may also extend the notion of the ISO layout to support 405 keys that don't map directly to the diagram above (such as the 406 Android device - see diagram). Per the ISO standard, the space bar is 407 mapped to "A03", so the period and comma keys are mapped to "A02" and 408 "A04" respectively based on their relative position to the space bar. 409 Also note that the "E" row does not exist on the Android keyboard.</p> 410 <p> 411 <img src="images/androidKeyboard.png" 412 alt="keyboard layout example showing extension of ISO key numbering"> 413 </p> 414 <p>If it becomes necessary in the future, the format could extend 415 the ISO layout to support keys that are located to the left of the 416 "00" column by using negative column numbers "-01", "-02" and so on, 417 or 100's complement "99", "98",...</p> 418 <p> 419 <b>Key:</b> A key on a physical keyboard. 420 </p> 421 <p> 422 <b>Key code:</b> The integer code sent to the application on pressing 423 a key. 424 </p> 425 <p> 426 <b>Key map:</b> The basic mapping between ISO positions and the 427 output characters for each set of modifier combinations associated 428 with a particular layout. There may be multiple key maps for each 429 layout. 430 </p> 431 <p> 432 <b>Keyboard:</b> The physical keyboard. 433 </p> 434 <p> 435 <b>Keyboard layout:</b> A layout is the 436 overall keyboard configuration for a particular locale. Within a 437 keyboard layout, there is a single base map, one or more key maps and 438 zero or 439 more transforms. 440 </p> 441 <p> 442 <b>Layer</b> is an arrangement of keys on a virtual keyboard. Since 443 it is often not intended to use two hands on a visual keyboard to 444 allow the pressing of modifier keys. Modifier keys are made sticky in 445 that one presses one, the visual representation, and even 446 arrangement, of the keys change, and you press the key. This visual 447 representation is a layer. Thus a virtual keyboard is made up of a 448 set of layers. 449 </p> 450 <p> 451 <b>Long-press key:</b> also known as a child key. A secondary key 452 that is invoked from a top level key on a software keyboard. 453 Secondary keys typically provide access to variants of the top level 454 key, such as accented variants (a => , , , ) 455 </p> 456 <p> 457 <b>Modifier:</b> A key that is held to change the behavior of a 458 keyboard. For example, the "Shift" key allows access to upper-case 459 characters on a US keyboard. Other modifier keys include but is not 460 limited to: Ctrl, Alt, Option, Command and Caps Lock. 461 </p> 462 <p> 463 <b>Physical keyboard</b> is a keyboard that has individual keys that 464 are pressed. Each key has a unique identifier and the arrangement 465 doesn't change, even if the mapping of those keys does. 466 </p> 467 <p> 468 <b>Transform:</b>A transform is an 469 element that specifies a set of conversions from sequences of code 470 points into one (or more) other code points. For example, in most 471 latin keyboards hitting the "^" dead-key followed by the "e" key 472 produces "". 473 </p> 474 <p> 475 <b>Virtual keyboard</b> is a keyboard that is rendered on a, 476 typically, touch surface. It has a dynamic arrangement and contrasts 477 with a physical keyboard. This term has many synonyms: touch 478 keyboard, software keyboard, SIP (Software Input Panel). This 479 contrasts with other uses of the term virtual keyboard as an 480 on-screen keyboard for reference or accessibility data entry. 481 </p> 482 <h2> 483 4 <a name="File_and_Dir_Structure" href="#File_and_Dir_Structure">File 484 and Directory Structure</a> 485 </h2> 486 <p>Each platform has its own directory, where a "platform" is a 487 designation for a set of keyboards available from a particular 488 source, such as Windows or Chromeos. This directory name is the 489 platform name (see Table 2 located further in the document). Within 490 this directory there are two types of files:</p> 491 <ol> 492 <li>A single platform file (see XML structure for Platform 493 file), this file includes a mapping of hardware key codes to the ISO 494 layout positions. This file is also open to expansion for any 495 configuration elements that are valid across the whole platform and 496 that are not layout specific. This file is simply called 497 _platform.xml.</li> 498 <li>Multiple layout files named by their locale identifiers. 499 (eg. lt-t-k0-chromeos.xml or ne-t-k0-windows.xml).</li> 500 </ol> 501 <p>Keyboard data that is not supported on a given platform, but 502 intended for use with that platform, may be added to the directory 503 /und/. For example, there could be a file /und/lt-t-k0-chromeos.xml, 504 where the data is intended for use with ChromeOS, but does not 505 reflect data that is distributed as part of a standard ChromeOS 506 release.</p> 507 <h2> 508 5 <a name="Element_Heirarchy_Layout_File" 509 href="#Element_Heirarchy_Layout_File">Element Hierarchy - Layout 510 File</a> 511 </h2> 512 <h3> 513 5.1 <a name="Element_Keyboard" href="#Element_Keyboard">Element: 514 keyboard</a> 515 </h3> 516 <p>This is the top level element. All other elements defined below 517 are under this element.</p> 518 <p>Syntax</p> 519 <p><keyboard locale="{locale ID}"></p> 520 <p>{definition of the layout as described by the elements defined 521 below}</p> 522 <p></keyboard></p> 523 <dl> 524 <dt>Attribute: locale (required)</dt> 525 <dd> 526 This mandatory attribute represents the locale of the keyboard using 527 Unicode locale identifiers (see <a href="tr35.html">LDML</a>) - for 528 example 'el' for Greek. Sometimes, the locale may not 529 specify the base language. For example, a Devanagari keyboard for 530 many languages could be specified by BCP-47 code: 'und-Deva'. For 531 details, see <a href="#Keyboard_IDs">Keyboard IDs</a> . 532 </dd> 533 </dl> 534 <p>Examples (for illustrative purposes only, not indicative of the 535 real data)</p> 536 <pre><keyboard locale="ka-t-k0-qwerty-windows"> 537 538 </keyboard> 539 <keyboard locale="fr-CH-t-k0-android"> 540 541 </keyboard></pre> 542 <hr> 543 <h3> 544 5.2 <a name="Element_version" href="#Element_version">Element: 545 version</a> 546 </h3> 547 <p> 548 Element used to keep track of the source data version.<br> <br> 549 Syntax 550 </p> 551 <p> 552 <version platform=".." revision=".."><br> 553 </p> 554 <dl> 555 <dt>Attribute: platform (required)</dt> 556 <dd>The platform source version. Specifies what version of the 557 platform the data is from. For example, data from Mac OSX 10.4 would 558 be specified as platform="10.4". For platforms that have 559 unstable version numbers which change frequently (like Linux), this 560 field is set to an integer representing the iteration of the data 561 starting with "1". This number would only increase if there were any 562 significant changes in the keyboard data.</dd> 563 </dl> 564 <dl> 565 <dt>Attribute: number (required)</dt> 566 <dd>The data revision version.</dd> 567 </dl> 568 <dl> 569 <dt>Attribute: cldrVersion (fixed by DTD)</dt> 570 <dd>The CLDR specification version that is associated with this 571 data file. This value is fixed and is inherited from the DTD file 572 and therefore does not show up directly in the XML file.</dd> 573 </dl> 574 <p>Example</p> 575 <p><keyboard locale="..-osx"></p> 576 <p></p> 577 <p><version platform="10.4" number="1"/></p> 578 <p></p> 579 <p></keyboard></p> 580 <hr> 581 <h3> 582 5.3 <a name="Element_generation" href="#Element_generation">Element: 583 generation</a> 584 </h3> 585 <p> 586 The generation element is now deprecated. It was used to keep track 587 of the generation date of the data. 588 </p> 589 590 <hr> 591 <h3> 592 5.4 <a name="Element_names" href="#Element_names">Element: names</a> 593 </h3> 594 <p> 595 Element used to store any names given to the layout by the platform.<br> 596 <br> Syntax 597 </p> 598 <p><names></p> 599 <p>{set of name elements}</p> 600 <p> 601 </names><br> 602 </p> 603 <h3> 604 5.5 <a name="Element_name" href="#Element_name">Element: name</a> 605 </h3> 606 <p> 607 A single name given to the layout by the platform.<br> <br> 608 Syntax 609 </p> 610 <p> 611 <name value=".."><br> 612 </p> 613 <dl> 614 <dt>Attribute: value (required)</dt> 615 <dd>The name of the layout.</dd> 616 </dl> 617 <p>Example</p> 618 <p><keyboard 619 locale="bg-t-k0-windows-phonetic-trad"></p> 620 <p></p> 621 <p><names></p> 622 <p><name value="Bulgarian (Phonetic 623 Traditional)"/></p> 624 <p></names></p> 625 <p></p> 626 <p></keyboard></p> 627 <hr> 628 <h3> 629 5.6 <a name="Element_settings" href="#Element_settings">Element: 630 settings</a> 631 </h3> 632 <p> 633 An element used to keep track of layout specific settings. This 634 element may or may not show up on a layout. These settings reflect 635 the normal practice on the platform. However, an implementation using 636 the data may customize the behavior. For example, for 637 transformFailures the implementation could ignore the setting, or 638 modify the text buffer in some other way (such as by emitting 639 backspaces).<br> <br> Syntax 640 </p> 641 <p> 642 <settings [fallback="omit"] 643 [transformFailure="omit"] 644 [transformPartial="hide"]><br> 645 </p> 646 <dl> 647 <dt>Attribute: fallback="omit" (optional)</dt> 648 <dd>The presence of this attribute means that when a modifier 649 key combination goes unmatched, no output is produced. The default 650 behavior (when this attribute is not present) is to fallback to the 651 base map when the modifier key combination goes unmatched.</dd> 652 </dl> 653 <p>If this attribute is present, it must have a value of omit.</p> 654 <dl> 655 <dt>Attribute: transformFailure="omit" (optional)</dt> 656 <dd>This attribute describes the behavior of a transform when it 657 is escaped (see the transform element in the Layout file for more 658 information). A transform is escaped when it can no longer continue 659 due to the entry of an invalid key. For example, suppose the 660 following set of transforms are valid:</dd> 661 </dl> 662 <blockquote> 663 <p>^e </p> 664 <p>^a </p> 665 </blockquote> 666 <p>Suppose a user now enters the "^" key then "^" is now stored in 667 a buffer and may or may not be shown to the user (see the partial 668 attribute).</p> 669 <p>If a user now enters d, then the transform has failed and there 670 are two options for output.</p> 671 <p>1. default behavior - "^d"</p> 672 <p>2. omit - "" (nothing and the buffer is cleared)</p> 673 <p>The default behavior (when this attribute is not present) is to 674 emit the contents of the buffer upon failure of a transform.</p> 675 <p>If this attribute is present, it must have a value of omit.</p> 676 <dl> 677 <dt>Attribute: transformPartial="hide" (optional)</dt> 678 <dd>This attribute describes the behavior the system while in a 679 transform. When this attribute is present then don't show the values 680 of the buffer as the user is typing a transform (this behavior can 681 be seen on Windows or Linux platforms).</dd> 682 </dl> 683 <p>By default (when this attribute is not present), show the 684 values of the buffer as the user is typing a transform (this behavior 685 can be seen on the Mac OSX platform).</p> 686 <p>If this attribute is present, it must have a value of hide.</p> 687 <p>Example</p> 688 <p><keyboard 689 locale="bg-t-k0-windows-phonetic-trad"></p> 690 <p></p> 691 <p><settings fallback="omit" 692 transformPartial="hide"></p> 693 <p></p> 694 <p></keyboard></p> 695 <p>Indicates that:</p> 696 <ol> 697 <li>When a modifier combination goes unmatched, do not output 698 anything when a key is pressed.</li> 699 <li>If a transform is escaped, output the contents of the 700 buffer.</li> 701 <li>During a transform, hide the contents of the buffer as the 702 user is typing.</li> 703 </ol> 704 <hr> 705 <h3> 706 5.7 <a name="Element_keyMap" href="#Element_keyMap">Element: 707 keyMap</a> 708 </h3> 709 <p>This element defines the group of mappings for all the keys 710 that use the same set of modifier keys. It contains one or more map 711 elements.</p> 712 <p>Syntax</p> 713 <p><keyMap [modifiers="{Set of Modifier 714 Combinations}"]></p> 715 <p>{a set of map elements}</p> 716 <p></keyMap></p> 717 <dl> 718 <dt>Attribute: modifiers (optional)</dt> 719 <dd> 720 A set of modifier combinations that cause this key map to be 721 "active". Each combination is separated by a space. The 722 interpretation is that there is a match if any of the combinations 723 match, that is, they are ORed. Therefore, the order of the 724 combinations within this attribute does not matter.<br> <br> 725 A combination is simply a concatenation of words to represent the 726 simultaneous activation of one or more modifier keys. The order of 727 the modifier keys within a combination does not matter, although 728 don't care cases are generally added to the end of the string for 729 readability (see next paragraph). For example: "cmd+caps" represents 730 the Caps Lock and Command modifier key combination. Some keys have 731 right or left variant keys, specified by a 'R' or 'L' suffix. For 732 example: "ctrlR+caps" would represent the Right-Control and Caps 733 Lock combination. For simplicity, the presence of a modifier without 734 a 'R' or 'L' suffix means that either its left or right variants are 735 valid. So "ctrl+caps" represents the same as "ctrlL+ctrlR?+caps 736 ctrlL?+ctrlR+caps" 737 </dd> 738 </dl> 739 <p>A modifier key may be further specified to be in a "don't care" 740 state using the '?' suffix. The "don't care" state simply means that 741 the preceding modifier key may be either ON or OFF. For example 742 "ctrl+shift?" could be expanded into "ctrl ctrl+shift".</p> 743 <p>Within a combination, the presence of a modifier WITHOUT the 744 '?' suffix indicates this key MUST be on. The converse is also true, 745 the absence of a modifier key means it MUST be off for the 746 combination to be active.</p> 747 <p>Here is an exhaustive list of all possible modifier keys:</p> 748 <p>Possible Modifier Keys</p> 749 <table> 750 <caption> 751 <a name="Possible_Modifier_Keys" href="#Possible_Modifier_Keys">Possible 752 Modifier Keys</a> 753 </caption> 754 <tbody> 755 <tr> 756 <td><p>Modifier Keys</p></td> 757 <td> </td> 758 <td><p>Comments</p></td> 759 </tr> 760 <tr> 761 <td><p>altL</p></td> 762 <td><p>altR</p></td> 763 <td><p>xAlty xAltR+AltL? xAltR?AltLy</p></td> 764 </tr> 765 <tr> 766 <td><p>ctrlL</p></td> 767 <td><p>ctrlR</p></td> 768 <td><p>ditto for Ctrl</p></td> 769 </tr> 770 <tr> 771 <td><p>shiftL</p></td> 772 <td><p>shiftR</p></td> 773 <td><p>ditto for Shift</p></td> 774 </tr> 775 <tr> 776 <td><p>optL</p></td> 777 <td><p>optR</p></td> 778 <td><p>ditto for Opt</p></td> 779 </tr> 780 <tr> 781 <td><p>caps</p></td> 782 <td> </td> 783 <td><p>Caps Lock</p></td> 784 </tr> 785 <tr> 786 <td><p>cmd</p></td> 787 <td> </td> 788 <td><p>Command on the Mac</p></td> 789 </tr> 790 </tbody> 791 </table> 792 <p>All sets of modifier combinations within a layout are disjoint 793 with no-overlap existing between the key maps. That is, for every 794 possible modifier combination, there is at most a single match within 795 the layout file. There are thus never multiple matches. If no exact 796 match is available, the match falls back to the base map unless the 797 fallback="omit" attribute in the settings element is set, 798 in which case there would be no output at all.</p> 799 <p>To illustrate, the following example produces an invalid layout 800 because pressing the "Ctrl" modifier key produces an indeterminate 801 result:</p> 802 <p><keyMap modifiers="ctrl+shift?"></p> 803 <p></p> 804 <p></keyMap></p> 805 <p><keyMap modifiers="ctrl"></p> 806 <p></p> 807 <p></keyMap></p> 808 <p>Modifier Examples:</p> 809 <p><keyMap modifiers="cmd?+opt+caps?+shift" /></p> 810 <p>Caps-Lock may be ON or OFF, Option must be ON, Shift must be ON 811 and Command may be ON or OFF.</p> 812 <p><keyMap modifiers="shift caps" 813 fallback="true" /></p> 814 <p>Caps-Lock must be ON OR Shift must be ON. Is also the fallback 815 key map.</p> 816 <p>If the modifiers attribute is not present on a keyMap then that 817 particular key map is the base map.</p> 818 <hr> 819 <h3> 820 5.8 <a name="Element_map" href="#Element_map">Element: map</a> 821 </h3> 822 <p>This element defines a mapping between the base character and 823 the output for a particular set of active modifier keys. This element 824 must have the keyMap element as its parent.</p> 825 <p>If a map element for a particular ISO layout position has not 826 been defined then if this key is pressed, no output is produced.</p> 827 <p>Syntax</p> 828 <pre><map 829 iso="{the iso position}" 830 to="{the output}" 831 [longPress="{long press keys}"] 832 [transform="no"] 833 /><!-- {Comment to improve readability (if needed)} --></pre> 834 <dl> 835 <dt>Attribute: iso (exactly one of base and iso is required)</dt> 836 <dd>The iso attribute represents the ISO layout position of the 837 key (see the definition at the beginning of the document for more 838 information).</dd> 839 </dl> 840 <dl> 841 <dt>Attribute: to (required)</dt> 842 <dd>The to attribute contains the output sequence of characters 843 that is emitted when pressing this particular key. Control 844 characters, whitespace (other than the regular space character) and 845 combining marks in this attribute are escaped using the \u{...} 846 notation.</dd> 847 </dl> 848 <dl> 849 <dt>Attribute: longPress (optional)</dt> 850 <dd>The longPress attribute contains any characters that can be 851 emitted by "long-pressing" a key, this feature is prominent in 852 mobile devices. The possible sequences of characters that can be 853 emitted are whitespace delimited. Control characters, combining 854 marks and whitespace (which is intended to be a long-press option) 855 in this attribute are escaped using the \u{...} notation.</dd> 856 </dl> 857 <dl> 858 <dt>Attribute: transform="no" (optional)</dt> 859 <dd>The transform attribute is used to define a key that never 860 participates in a transform but its output shows up as part of a 861 transform. This attribute is necessary because two different keys 862 could output the same characters (with different keys or modifier 863 combinations) but only one of them is intended to be a dead-key and 864 participate in a transform. This attribute value must be no if it is 865 present.</dd> 866 </dl> 867 <dl> 868 <dt>Attribute: multitap (optional)</dt> 869 <dd> 870 A space-delimited list of strings, where each successive element of the list is produced by the corresponding number of quick taps. For example, two taps on the key C01 will produce a c in the following example. <br> 871 <br> <em>Example:</em><br> <br> 872 <map iso="C01" to="a" multitap="bb c d"></dd> 873 </dl> 874 <dl> 875 <dt>Attribute: longPress-status (optional)</dt> 876 <dd> 877 Indicates optional longPress values. Must only occur with a 878 longPress value. May be suppressed or shown, depending on user 879 settings. There can be two map elements that differ only by 880 long-press-status, allowing two different sets of longpress values.<br> 881 <br> <em>Example:</em><br> <br> <map 882 iso="D01" to="a" longPress=" % 883 "/><br> <map iso="D01" to="a" 884 longPress=" " 885 longPress-status="optional"/> 886 887 </dd> 888 </dl> 889 <dl> 890 891 <dt>Attribute: optional (optional)</dt> 892 <dd>Indicates optional mappings. May be suppressed or shown, 893 depending on user settings.</dd> 894 </dl> 895 <dl> 896 <dt>Attribute: hint (optional)</dt> 897 <dd> 898 Indicates a hint as to long-press contents, such as the first 899 character of the longPress value, that can be displayed on the key. 900 May be suppressed or shown, depending on user Settings.<br> <br> 901 <i>Example:</i> where the hint is "{":<br> 902 <div style='text-align: center'> 903 <img alt="keycap hint" src='images/keycapHint.png'> 904 </div> 905 </dd> 906 </dl> 907 <p>For example, suppose there are the following keys, their output 908 and one transform:</p> 909 <blockquote> 910 <p>E00 outputs `</p> 911 <p>Option+E00 outputs ` (the dead-version which participates in 912 transforms).</p> 913 <p>`e </p> 914 </blockquote> 915 <p>Then the first key must be tagged with transform="no" 916 to indicate that it should never participate in a transform.</p> 917 <p>Comment: US key equivalent, base key, escaped output and 918 escaped longpress</p> 919 <p>In the generated files, a comment is included to help the 920 readability of the document. This comment simply shows the English 921 key equivalent (with prefix key=), the base character (base=), the 922 escaped output (to=) and escaped long-press keys (long=). These 923 comments have been inserted strategically in places to improve 924 readability. Not all comments include include all components since 925 some of them may be obvious.</p> 926 <p>Examples</p> 927 <pre><keyboard locale="fr-BE-t-k0-windows"><br> <br> <keyMap modifiers="shift"><br> <map iso="D01" to="A" /> <!-- key=Q --><br> <map iso="D02" to="Z" /> <!-- key=W --><br> <map iso="D03" to="E" /><br> <map iso="D04" to="R" /><br> <map iso="D05" to="T" /><br> <map iso="D06" to="Y" /><br> <br> </keyMap><br> <br></keyboard><br><keyboard locale="ps-t-k0-windows"><br> <br> <keyMap modifiers='altR+caps? ctrl+alt+caps?'><br> <map iso="D04" to="\u{200e}" /> <!-- key=R base= --><br> <map iso="D05" to="\u{200f}" /> <!-- key=T base= --><br> <map iso="D08" to="\u{670}" /> <!-- key=I base= to= --><br> <br> </keyMap><br> <br></keyboard></pre> 928 <h4> 929 5.8.1 <a name="Element_flicks" href="#Element_flicks">Elements: 930 flicks, flick</a></h4> 931 <p class='dtd'><!ELEMENT keyMap ( map | flicks )+ ><br> 932 <!ELEMENT flick EMPTY><br> 933 <!ATTLIST flick directions NMTOKENS><br> 934 <!ATTLIST flick to CDATA><br> 935 <!--@VALUE--></p> 936 <p>The flicks element is used to generate results from a "flick" of the finger on a mobile device. The <strong>directions</strong> attribute value is a space-delimited list of keywords, that describe a path, currently restricted to the cardinal and intercardinal directions {n e s w ne nw se sw}. The <strong>to</strong> attribute value is the result of (one or more) flicks.</p> 937 <p>Example: where a flick to the Northeast then South produces two code points.</p> 938 <pre><flicks iso="C01"> 939 <flick directions=ne s to=\uABCD\uDCBA> 940 </flicks></pre> 941 <hr> 942 <h3> 943 5.9 <a name="Element_import" href="#Element_import">Element: 944 import</a> 945 </h3> 946 <p>The import element references another file of 947 the same type and includes all the subelements of the top level 948 element as though the import element were being replaced by those 949 elements, in the appropriate section of the XML file. For example:</p> 950 <pre> <import path="standard_transforms.xml"></pre> 951 <dl> 952 <dt>Attribute: path (required)</dt> 953 <dd>The value is contains a relative path to the included ldml 954 file. There is a standard set of directories to be searched that an 955 application may provide. This set is always prepended with the 956 directory in which the current file being read, is stored.</dd> 957 </dl> 958 <p>If two identical elements, as described below, 959 are defined, the later element will take precedence. Thus if a 960 hardwareMap/map for the same keycode on the same page is defined 961 twice (for example once in an included file), the later one will be 962 the resulting mapping.</p> 963 <p>Elements are considered to have three 964 attributes that make them unique: the tag of the element, the parent 965 and the identifying attribute. The parent in its turn is a unique 966 element and so on up the chain. If the distinguishing attribute is 967 optional, its non-existence is represented with an empty value. Here 968 is a list of elements and their defining attributes. If an element is 969 not listed then if it is a leaf element, only one occurs and it is 970 merely replaced. If it has children, then the sub elements are 971 considered, in effect merging the element in question.</p> 972 <table> 973 <!-- nocaption --> 974 <tbody> 975 <tr> 976 <td><p>Element</p></td> 977 <td><p>Parent</p></td> 978 <td><p>Distinguishing attribute</p></td> 979 </tr> 980 <tr> 981 <td><p>keyMap</p></td> 982 <td><p>keyboard</p></td> 983 <td><p>@modifiers</p></td> 984 </tr> 985 <tr> 986 <td><p>map</p></td> 987 <td><p>keyMap</p></td> 988 <td><p>@iso</p></td> 989 </tr> 990 <tr> 991 <td><p>display</p></td> 992 <td><p>displayMap</p></td> 993 <td><p>@char (new)</p></td> 994 </tr> 995 <tr> 996 <td><p>layout</p></td> 997 <td><p>layouts</p></td> 998 <td><p>@modifier</p></td> 999 </tr> 1000 </tbody> 1001 </table> 1002 <p>In order to help identify mistakes, it is an 1003 error if a file contains two elements that override each other. All 1004 element overrides must come as a result of an <include> element 1005 either for the element overridden or the element overriding.</p> 1006 <p>The following elements are not imported from 1007 the source file:</p> 1008 <ul> 1009 <li>version</li> 1010 <li>generation</li> 1011 <li>names</li> 1012 <li>settings</li> 1013 </ul> 1014 <hr> 1015 <h3> 1016 5.10 <a name="Element_displayMap" href="#Element_displayMap">Element: 1017 displayMap</a> 1018 </h3> 1019 <p>The displayMap can be used to describe what is 1020 to be displayed on the keytops for various keys. For the most part, 1021 such explicit information is unnecessary since the @char element from 1022 the keyMap/map element can be used. But there are some characters, 1023 such as diacritics, that do not display well on their own and so 1024 explicit overrides for such characters can help. The displayMap 1025 consists of a list of display sub elements.</p> 1026 <p>DisplayMaps are designed to be shared across 1027 many different keyboard layout descriptions, and included in where 1028 needed.</p> 1029 <hr> 1030 <h3> 1031 5.11 <a name="Element_display" href="#Element_display">Element: 1032 display</a> 1033 </h3> 1034 <p>The display element describes how a character, 1035 that has come from a keyMap/map element, should be displayed on a 1036 keyboard layout where such display is possible.</p> 1037 <dl> 1038 <dt>Attribute: mapOutput (required)</dt> 1039 <dd>Specifies the character or character sequence from the 1040 keyMap/map element that is to have a special display.</dd> 1041 </dl> 1042 <dl> 1043 <dt>Attribute: display (required)</dt> 1044 <dd>Required and specifies the character sequence that should be 1045 displayed on the keytop for any key that generates the @mapOutput 1046 sequence. (It is an error if the value of the display attribute is 1047 the same as the value of the char attribute.)</dd> 1048 </dl> 1049 <pre> <keyboard > 1050 <keyboardMap> 1051 <map iso="C01" to="a" longpress="\u0301 \u0300"/> 1052 </keyboardMap> 1053 <displayMap> 1054 <display mapOutput="\u0300" display="u\u02CB"/> 1055 <display mapOutput="\u0301" display="u\u02CA"/> 1056 </displayMap><br> </keyboard ></pre> 1057 <p>To allow displayMaps to be shared across 1058 descriptions, there is no requirement that @mapOutput matches any @to 1059 in any keyMap/map element in the keyboard description.</p> 1060 <hr> 1061 <h3> 1062 5.12 <a name="Element_layer" href="#Element_layer">Element: layer</a> 1063 </h3> 1064 <p>A layer element describes the configuration of 1065 keys on a particular layer of a keyboard. It contains row elements to 1066 describe which keys exist in each row and also switch elements that 1067 describe how keys in the layer switch the layer to another. In 1068 addition, for platforms that require a mapping from a key to a 1069 virtual key (for example Windows or Mac) there is also a vkeys 1070 element to describe the mapping.</p> 1071 <dl> 1072 <dt>Attribute: modifier (required)</dt> 1073 <dd>This has two roles. It acts as an identifier for the layer 1074 element and also provides the linkage into a keyMap. A modifier is a 1075 single modifier combination such that it is matched by one of the 1076 modifier combinations in one of the keyMap/@modifiers attribute. To 1077 indicate that no modifiers apply the reserved name of "none" is 1078 used. For the purposes of fallback vkey mapping, the following 1079 modifier components are reserved: "shift", "ctrl", "alt", "caps", 1080 "cmd", "opt" along with the "L" and "R" optional single suffixes for 1081 the first 3 in that list. There must be a keyMap whose @modifiers 1082 attribute matches the @modifier attribute of the layer element. It 1083 is an error if there is no such keyMap.</dd> 1084 </dl> 1085 <p>The keymap/@modifier often includes multiple 1086 combinations that match. It is not necessary (or prefered) to include 1087 all of these. Instead a minimal matching element should be used, such 1088 that exactly one keymap is matched.</p> 1089 <p>The following are examples of situations where 1090 the @modifiers and @modifier do not match, with a different keymap 1091 definition than above.</p> 1092 <table> 1093 <!-- nocaption --> 1094 <tbody> 1095 <tr> 1096 <th><p>keyMap/@modifiers</p></th> 1097 <th><p>layer/@modifier</p></th> 1098 </tr> 1099 <tr> 1100 <td><p>shiftL</p></td> 1101 <td><p>shift (ambiguous)</p></td> 1102 </tr> 1103 <tr> 1104 <td><p>altR</p></td> 1105 <td><p>alt</p></td> 1106 </tr> 1107 <tr> 1108 <td><p>shiftL?+shiftR</p></td> 1109 <td><p>shift</p></td> 1110 </tr> 1111 </tbody> 1112 </table> 1113 <p>And these do match:</p> 1114 <table> 1115 <!-- nocaption --> 1116 <tbody> 1117 <tr> 1118 <th><p>keyMap/@modifiers</p></th> 1119 <th><p>layer/@modifier</p></th> 1120 </tr> 1121 <tr> 1122 <td><p>shiftL shiftR</p></td> 1123 <td><p>shift</p></td> 1124 </tr> 1125 </tbody> 1126 </table> 1127 <p>The use of @modifier as an identifier for a 1128 layer, is sufficient since it is always unique among the set of layer 1129 elements in a keyboard.</p> 1130 <hr> 1131 <h3> 1132 5.13 <a name="Element_row" href="#Element_row">Element: row</a> 1133 </h3> 1134 <p>A row element describes the keys that are 1135 present in the row of a keyboard. Row elements are ordered within a 1136 layout element with the top visual row being stored first. The row 1137 element introduces the keyId which may be an ISOKey or a specialKey. 1138 More formally:</p> 1139 <pre> keyId = ISOKey | specialKey<br> ISOKey = [A-Z][0-9][0-9]<br> specialKey = [a-z][a-zA-Z0-9]{2,7}</pre> 1140 <p> 1141 ISOKey denotes a key having an <a href="#Definitions">ISO 1142 Position</a>. SpecialKey is used to identify functional keys occurring 1143 on a virtual keyboard layout. 1144 </p> 1145 <dl> 1146 <dt>Attribute: keys (required)</dt> 1147 <dd>This is a string that lists the keyId for each of the keys 1148 in a row. Key ranges may be contracted to firstkey-lastkey but only 1149 for ISOKey type keyIds. The interpolation between the first and last 1150 keys names is entirely numeric. Thus D00-D03 is equivalent to D00 1151 D01 D02 D03. It is an error if the first and last keys do not have 1152 the same alphabetic prefix or the last key numeric component is less 1153 than or equal to the first key numeric component.</dd> 1154 </dl> 1155 <p>specialKey type keyIds may take any value 1156 within their syntactic constraint. But the following specialKeys are 1157 reserved to allow applications to identify them and give them special 1158 handling:</p> 1159 <ul> 1160 <li>"bksp", "enter", "space", "tab", "esc", "sym", "num"</li> 1161 <li>all the reserved modifier names</li> 1162 <li>specialKeys starting with the letter "x" for future reserved 1163 names.</li> 1164 </ul> 1165 <p>Here is an example of a row element:</p> 1166 <pre> <layer modifier="none"> 1167 <row keys="D01-D10"/> 1168 <row keys="C01-C09"/> 1169 <row keys="shift B01-B07 bksp"/> 1170 <row keys="sym A01 smilies A02-A03 enter"/> 1171 </layer> 1172 </pre> 1173 <hr> 1174 <h3> 1175 5.14 <a name="Element_switch" href="#Element_switch">Element: 1176 switch</a> 1177 </h3> 1178 <p>The switch element describes a function key 1179 that has been included in the layout. It specifies which layer 1180 pressing the key switches you to and also what the key looks like.</p> 1181 <dl> 1182 <dt>Attribute: iso (required)</dt> 1183 <dd>The keyId as specified in one of the row elements. This must 1184 be a specialKey and not an ISOKey.</dd> 1185 </dl> 1186 <dl> 1187 <dt>Attribute: layout (required)</dt> 1188 <dd>The modifier attribute of the resulting layout element that 1189 describes the layer the user gets switched to.</dd> 1190 </dl> 1191 <dl> 1192 <dt>Attribute: display (required)</dt> 1193 <dd>A string to be displayed on the key.</dd> 1194 </dl> 1195 <p>Here is an example of a switch element for a 1196 shift key:</p> 1197 <pre> <layer modifier="none"> 1198 <row keys="D01-D10"/> 1199 <row keys="C01-C09"/> 1200 <row keys="shift B01-B07 bksp"/> 1201 <row keys="sym A01 smilies A02-A03 enter"/> 1202 <switch iso="shift" layout="shift" display="&#x21EA;"/> 1203 </layer> 1204 <layer modifier="shift"> 1205 <row keys="D01-D10"/> 1206 <row keys="C01-C09"/> 1207 <row keys="shift B01-B07 bksp"/> 1208 <row keys="sym A01 smilies A02-A03 enter"/> 1209 <switch iso="shift" layout="none" display="&#x21EA;"/> 1210 </layer></pre> 1211 <hr> 1212 <h3> 1213 5.15 <a name="Element_vkeys" href="#Element_vkeys">Element: vkeys</a> 1214 </h3> 1215 <p>On some architectures, applications may 1216 directly interact with keys before they are converted to characters. 1217 The keys are identified using a virtual key identifier or vkey. The 1218 mapping between a physical keyboard key and a vkey is keyboard-layout 1219 dependent. For example, a French keyboard would identify the D01 key 1220 as being an 'a' with a vkey of 'a' as opposed to 'q' on a US English 1221 keyboard. While vkeys are layout dependent, they are not modifier 1222 dependent. A shifted key always has the same vkey as its unshifted 1223 counterpart. In effect, a key is identified by its vkey and the 1224 modifiers active at the time the key was pressed.</p> 1225 <p>For a physical keyboard there is a layout 1226 specific default mapping of keys to vkeys. These are listed in a 1227 vkeys element which takes a list of vkey element mappings and is 1228 identified by a type. There are different vkey mappings required for 1229 different platforms. While type="windows" vkeys are very similar to 1230 type="osx" vkeys, they are not identical and require their own 1231 mapping.</p> 1232 <p>The most common model for specifying vkeys is 1233 to import a standard mapping, say to the US layout, and then to add a 1234 vkeys element to change the mapping appropriately for the specific 1235 layout.</p> 1236 <p>In addition to describing physical keyboards, 1237 vkeys also get used in virtual keyboards. Here the vkey mapping is 1238 local to a layer and therefore a vkeys element may occur within a 1239 layout element. In the case where a layout element has no vkeys 1240 element then the resulting mapping may either be empty (none of the 1241 keys represent keys that have vkey identifiers) or may fallback to 1242 the layout wide vkeys mapping. Fallback only occurs if the layout's 1243 modifier attribute consists only of standard modifiers as listed as 1244 being reserved in the description of the layout/@modifier attribute, 1245 and if the modifiers are standard for the platform involved. So for 1246 Windows, 'cmd' is a reserved modifier but it is not standard for 1247 Windows. Therefore on Windows the vkey mapping for a layout with 1248 @modifier="cmd" would be empty.</p> 1249 <p>A vkeys element consists of a list of vkey 1250 elements.</p> 1251 <hr> 1252 <h3> 1253 5.16 <a name="Element_vkey" href="#Element_vkey">Element: vkey</a> 1254 </h3> 1255 <p>A vkey element describes a mapping between a 1256 key and a vkey for a particular platform.</p> 1257 <dl> 1258 <dt>Attribute: iso (required)</dt> 1259 <dd>The ISOkey being mapped.</dd> 1260 </dl> 1261 <dl> 1262 <dt>Attribute: type</dt> 1263 <dd>Current values: android, chromeos, osx, und, windows.</dd> 1264 </dl> 1265 <dl> 1266 <dt>Attribute: vkey (required)</dt> 1267 <dd>The resultant vkey identifier.</dd> 1268 </dl> 1269 <dl> 1270 <dt>Attribute: modifier</dt> 1271 <dd>This attribute may only be used if the parent vkeys element 1272 is a child of a layout element. If present it allows an unmodified 1273 key from a layer to represent a modified virtual key.</dd> 1274 </dl> 1275 <p>This example shows some of the mappings for a 1276 French keyboard layout:</p> 1277 <pre> <i>shared/win-vkey.xml</i> 1278 <keyboard> 1279 <vkeys type="windows"> 1280 <vkey iso="D01" vkey="VK_Q"/> 1281 <vkey iso="D02" vkey="VK_W"/> 1282 <vkey iso="C01" vkey="VK_A"/> 1283 <vkey iso="B01" vkey="VK_Z"/> 1284 </vkeys> 1285 </keyboard><br> 1286 <i>shared/win-fr.xml</i> 1287 <keyboard> 1288 <import path="shared/win-vkey.xml"> 1289 <keyMap> 1290 <map iso="D01" to="a"/> 1291 <map iso="D02" to="z"/> 1292 <map iso="C01" to="q"/> 1293 <map iso="B01" to="w"/> 1294 </keyMap><br> 1295 <keyMap modifiers="shift"> 1296 <map iso="D01" to="A"/> 1297 <map iso="D02" to="Z"/> 1298 <map iso="C01" to="Q"/> 1299 <map iso="B01" to="W"/> 1300 </keyMap><br> 1301 <vkeys type="windows"> 1302 <vkey iso="D01" vkey="VK_A"/> 1303 <vkey iso="D02" vkey="VK_Z"/> 1304 <vkey iso="C01" vkey="VK_Q"/> 1305 <vkey iso="B01" vkey="VK_W"/> 1306 </vkeys> 1307 </keyboard></pre> 1308 <p>In the context of a virtual keyboard there 1309 might be a symbol layer with the following layout:</p> 1310 <pre> <keyboard> 1311 <keyMap> 1312 <map iso="D01" to="1"/> 1313 <map iso="D02" to="2"/> 1314 ... 1315 <map iso="D09" to="9"/> 1316 <map iso="D10" to="0"/> 1317 <map iso="C01" to="!"/> 1318 <map iso="C02" to="@"/> 1319 ... 1320 <map iso="C09" to="("/> 1321 <map iso="C10" to=")"/> 1322 </keyMap><br> 1323 <layer modifier="sym"> 1324 <row keys="D01-D10"/> 1325 <row keys="C01-C09"/> 1326 <row keys="shift B01-B07 bksp"/> 1327 <row keys="sym A00-A03 enter"/> 1328 <switch iso="sym" layout="none" display="ABC"/> 1329 <switch iso="shift" layout="sym+shift" display="&=/<"/> 1330 <vkeys type="windows"> 1331 <vkey iso="D01" vkey="VK_1"/> 1332 ... 1333 <vkey iso="D10" vkey="VK_0"/> 1334 <vkey iso="C01" vkey="VK_1" modifier="shift"/> 1335 ... 1336 <vkey iso="C10" vkey="VK_0" modifier="shift"/> 1337 </vkeys> 1338 </layer> 1339 </keyboard></pre> 1340 <hr> 1341 <h3> 1342 5.17 <a 1343 name="Element_transforms" href="#Element_transforms">Element: 1344 transforms</a> 1345 </h3> 1346 <p>This element defines a group of one or more transform elements 1347 associated with this keyboard layout. This is used to support 1348 such as dead-keys using a straightforward structure that works for all the 1349 keyboards tested, and that results in readable source data.</p> 1350 <p> 1351 There can be multiple <transforms> elements</p> 1352 <p>Syntax</p> 1353 <p><transforms type="..."></p> 1354 <p>{a set of transform elements}</p> 1355 <p></transforms></p> 1356 <dl> 1357 <dt>Attribute: type (required)</dt> 1358 <dd>Current values: simple, final.</dd> 1359 </dl> 1360 <hr> 1361 <h3> 1362 5.18 <a 1363 name="Element_transform" href="#Element_transform">Element: 1364 transform</a> 1365 </h3> 1366 <p> 1367 This element must have the transforms element as its parent. This 1368 element represents a single transform that may be performed using the 1369 keyboard layout. A transform is an 1370 element that specifies a set of conversions from sequences of code 1371 points into one (or more) other code points.. For example, in most 1372 French keyboards hitting the "^" dead-key followed by the "e" key 1373 produces "". 1374 </p> 1375 <p>Syntax</p> 1376 <p><transform from="{combination of characters}" 1377 to="{output}"></p> 1378 <dl> 1379 <dt>Attribute: from (required)</dt> 1380 <dd> 1381 The from attribute consists of a sequence of elements. Each element 1382 matches one character and may consist of a codepoint or a UnicodeSet 1383 (both as defined in <a 1384 href="http://www.unicode.org/reports/tr35/#Unicode_Sets">UTS#35 1385 section 5.3.3</a>). 1386 </dd> 1387 </dl> 1388 <p>For example, suppose there are the following transforms:</p> 1389 <blockquote> 1390 <p>^e </p> 1391 <p>^a </p> 1392 <p>^o </p> 1393 </blockquote> 1394 <p>If the user types a key that produces "^", the keyboard enters 1395 a dead state. When the user then types a key that produces an "e", 1396 the transform is invoked, and "" is output. Suppose a user presses 1397 keys producing "^" then "u". In this case, there is no match for the 1398 "^u", and the "^" is output if the failure attribute in the transform 1399 element is set to emit. If there is no transform starting with "u", 1400 then it is also output (again only if failure is set to emit) and the 1401 mechanism leaves the "dead" state.</p> 1402 <p>The UI may show an initial sequence of matching characters with 1403 a special format, as is done with dead-keys on the Mac, and modify 1404 them as the transform completes. This behavior is specified in the 1405 partial attribute in the transform element.</p> 1406 <p>Most transforms in practice have only a couple of characters. 1407 But for completeness, the behavior is defined on all strings:</p> 1408 <ol> 1409 <li>If there could be a longer match if the user were to type 1410 additional keys, go into a 'dead' state.</li> 1411 <li>If there could not be a longer match, find the longest 1412 actual match, emit the transformed text (if failure is set to emit), 1413 and start processing again with the remainder.</li> 1414 <li>If there is no possible match, output the first character, 1415 and start processing again with the remainder.</li> 1416 </ol> 1417 <p>Suppose that there is the following transforms:</p> 1418 <blockquote> 1419 <p>ab x</p> 1420 <p>abc y</p> 1421 <p>abef z</p> 1422 <p>bc m</p> 1423 <p>beq n</p> 1424 </blockquote> 1425 <p>Here's what happens when the user types various sequence 1426 characters:</p> 1427 <table> 1428 <!-- nocaption --> 1429 <tbody> 1430 <tr> 1431 <td><p>Input characters</p></td> 1432 <td><p>Result</p></td> 1433 <td><p>Comments</p></td> 1434 </tr> 1435 <tr> 1436 <td><p>ab</p></td> 1437 <td> </td> 1438 <td><p>No output, since there is a longer transform with 1439 this as prefix.</p></td> 1440 </tr> 1441 <tr> 1442 <td><p>abc</p></td> 1443 <td><p>y</p></td> 1444 <td><p>Complete transform match.</p></td> 1445 </tr> 1446 <tr> 1447 <td><p>abd</p></td> 1448 <td><p>xd</p></td> 1449 <td><p>The longest match is "ab", so that is converted and 1450 output. The 'd' follows, since it is not the start of any 1451 transform.</p></td> 1452 </tr> 1453 <tr> 1454 <td><p>abeq</p></td> 1455 <td><p>xeq</p></td> 1456 <td><p>"ab" wins over "beq", since it comes first. That 1457 is, there is no longer possible match starting with 'a'.</p></td> 1458 </tr> 1459 <tr> 1460 <td><p>bc</p></td> 1461 <td><p>m</p></td> 1462 <td> </td> 1463 </tr> 1464 </tbody> 1465 </table> 1466 <p>Control characters, combining marks and whitespace in this 1467 attribute are escaped using the \u{...} notation.</p> 1468 <dl> 1469 <dt>Attribute: to (required)</dt> 1470 <dd> 1471 This attribute represents the characters that are output from the 1472 transform. The output can contain more than one 1473 character, so you could have <transform from="A" 1474 to="Fred"/> 1475 </dd> 1476 </dl> 1477 <p>Control characters, whitespace (other than the regular space 1478 character) and combining marks in this attribute are escaped using 1479 the \u{...} notation.</p> 1480 <p>Examples</p> 1481 <pre><keyboard locale="fr-CA-t-k0-CSA-osx"><br> <transforms type="simple"><br> <transform from="a" to="" /><br> <transform from="A" to="" /><br> <transform from="e" to="" /><br> <transform from="E" to="" /><br> <transform from="i" to="" /><br> <transform from="I" to="" /><br> <transform from="o" to="" /><br> <transform from="O" to="" /><br> <transform from="u" to="" /><br> <transform from="U" to="" /><br> </transforms><br> ...<br></keyboard><br><keyboard locale="nl-BE-t-k0-chromeos"><br> <transforms type="simple"><br> <transform from="\u{30c}a" to="" /> <!-- a --><br> <transform from="\u{30c}A" to="" /> <!-- A --><br> <transform from="\u{30a}a" to="" /> <!-- a --><br> <transform from="\u{30a}A" to="" /> <!-- A --><br> </transforms><br> ...<br></keyboard></pre> 1482 <dl> 1483 <dt>Attribute: before (optional)</dt> 1484 <dd>This attribute consists of a sequence of elements (codepoint 1485 or UnicodeSet) to match the text up to the current position in the 1486 text (this is similar to a regex "look behind" assertion: 1487 (?<=a)b matches a "b" that is preceded by an 1488 "a"). The attribute must match for the transform to apply. 1489 If missing, no before constraint is applied. The attribute value 1490 must not be empty.</dd> 1491 </dl> 1492 <dl> 1493 <dt>Attribute: after (optional)</dt> 1494 <dd>This attribute consists of a sequence of elements (codepoint 1495 or UnicodeSet) and matches as a zero-width assertion after the @from 1496 sequence. The attribute must match for the transform to apply. If 1497 missing, no after constraint is applied. The attribute value must 1498 not be empty. When the transform is applied, the string matched by 1499 the @from attribute is replaced by the string in the @to attribute, 1500 with the text matched by the @after attribute left unchanged. After 1501 the change, the current position is reset to just after the text 1502 output from the @to attribute and just before the text matched by 1503 the @after attribute. Warning: some legacy implementations may not 1504 be able to make such an adjustment and will place the current 1505 position after the @after matched string.</dd> 1506 </dl> 1507 <dl> 1508 <dt>Attribute: error (optional)</dt> 1509 <dd>If set this attribute indicates that the keyboarding 1510 application may indicate an error to the user in some way. 1511 Processing may stop and rewind to any state before the key was 1512 pressed. If processing does stop, no further transforms on the same 1513 input are applied. The @error attribute takes the value "fail", or 1514 must be absent. If processing continues, the @to is used for output 1515 as normal. It thus should contain a reasonable value.</dd> 1516 </dl> 1517 <p>For example:</p> 1518 <blockquote><transform 1519 from="\u037A\u037A" to="\u037A" 1520 error="fail" /></blockquote> 1521 <p>This indicates that it is an error to type two 1522 iota subscripts immediately after each other.</p> 1523 <p>In terms of how these different attributes work 1524 in processing a sequences of transforms, consider the transform:</p> 1525 <blockquote><transform 1526 before="X" from="Y" after="Y" 1527 to="B"/></blockquote> 1528 <p>This would transform the string:</p> 1529 <blockquote>XYZ XBZ</blockquote> 1530 <p>If we mark where the current match position is 1531 before and after the transform we see:</p> 1532 <blockquote>X | Y Z X B | Z</blockquote> 1533 <p>And a subsequent transform could transform the 1534 Z string, looking back (using @before) to match the B.</p> 1535 <p>There are other keying behaviors that are 1536 needed particularly in handling languages and scripts from various 1537 parts of the world. The behaviors intended to be covered by the 1538 transforms are:</p> 1539 <ul> 1540 <li>Reordering combining marks. The order required for 1541 underlying storage may differ considerably from the desired typing 1542 order. In addition, a keyboard may want to allow for different 1543 typing orders.</li> 1544 <li>Error indication. Sometimes a keyboard layout will want to 1545 specify to the application that a particular keying sequence in a 1546 context is in error and that the application should indicate that 1547 that particular keypress is erroneous.</li> 1548 <li>Backspace handling. There are various approaches to handling 1549 the backspace key. An application may treat it as an undo of the 1550 last key input, or it may simply delete the last character in the 1551 currently output text, or it may use transform rules to tell it how 1552 much to delete.</li> 1553 </ul> 1554 <p>We consider each transform type in turn and 1555 consider attributes to the <transforms> element pertinent to 1556 that type.</p> 1557 <hr> 1558 <h3> 1559 5.19 <a name="Element_reorder" href="#Element_reorder">Element: 1560 reorder</a> 1561 </h3> 1562 <p>The reorder transform is applied after all 1563 transform except for those with type=final.</p> 1564 <p>This transform has the job of reordering 1565 sequences of characters that have been typed, from their typed order 1566 to the desired output order. The primary concern in this transform is 1567 to sort combining marks into their correct relative order after a 1568 base, as described in this section. The reorder transforms can be 1569 quite complex, keyboard layouts will almost always import them.</p> 1570 <p>The reordering algorithm consists of four 1571 parts:</p> 1572 <ol> 1573 <li>Create a sort key for each character in the input string. A 1574 sort key has 4 parts: (primary, index, tertiary). 1575 <ul> 1576 <li>The <b>primary weight</b> is the primary order value. 1577 </li> 1578 <li>The <b>secondary weight</b> is the index, a position in 1579 the input string, usually of the character itself, but it may be 1580 of a character earlier in the string. 1581 </li> 1582 <li>The <b>tertiary weight</b> is a tertiary order value 1583 (defaulting to 0). 1584 </li> 1585 <li>The <b>quaternary weight</b> is the index of the character 1586 in the string. This ensures a stable sort for sequences of 1587 characters with the same tertiary weight. 1588 </li> 1589 </ul> 1590 </li> 1591 <li>Mark each character as to whether it is a prebase character, 1592 one that is typed before the base and logically stored after. Thus 1593 it will have a primary order > 0.</li> 1594 <li>Use the sort key and the prebase mark to identify runs. A 1595 run starts with a prefix that contains any prebase characters and a 1596 single base character whose primary and tertiary key is 0. The run 1597 extends until, but not including, the start of the prefix of the 1598 next run or end of the string. 1599 <ul> 1600 <li>run := prebase* (primary=0 && tertiary=0) ((primary0 || 1601 tertiary0) && !prebase)*</li> 1602 </ul> 1603 </li> 1604 <li>Sort the character order of each character in the run based 1605 on its sort key.</li> 1606 </ol> 1607 <p>The primary order of a character with the 1608 Unicode property Combining_Character_Class (ccc) of 0 may well not be 1609 0. In addition, a character may receive a different primary order 1610 dependent on context. For example, in the Devanagari sequence ka 1611 halant ka, the first ka would have a primary order 0 while the halant 1612 ka sequence would give both halant and the second ka a primary order 1613 > 0, for example 2. Note that base character in this discussion 1614 is not a Unicode base character. It is instead a character with 1615 primary=0.</p> 1616 <p>In order to get the characters into the correct 1617 relative order, it is necessary not only to order combining marks 1618 relative to the base character, but also to order some combining 1619 marks in a subsequence following another combining mark. For example 1620 in Devanagari, a nukta may follow consonant character, but it may 1621 also follow a conjunct consisting of a consonant, halant, consonant. 1622 Notice that the second consonant is not, in this model, the start of 1623 a new run because some characters may need to be reordered to before 1624 the first base, for example repha. The repha would get primary < 1625 0, and be sorted before the character with order = 0, which is, in 1626 the case of Devanagari, the initial consonant of the orthographic 1627 syllable.</p> 1628 <p>The reorder transform consists of a single 1629 element type: <reorder> encapsulated in a <reorders> 1630 element. Each is a rule that matches against a string of characters 1631 with the action of setting the various ordering attributes (primary, 1632 tertiary, tertiary_base, prebase) for the matched characters in the 1633 string.</p> 1634 <blockquote> 1635 <p> 1636 <strong>from</strong> This attribute follows the transform/@from 1637 attribute and contains a string of elements. Each element matches 1638 one character and may consist of a codepoint or a UnicodeSet (both 1639 as defined in UTS#35 section 5.3.3). This attribute is required. 1640 </p> 1641 <p> 1642 <strong>before</strong> This attribute follows the transform/@before 1643 attribute and contains the element string that must match the string 1644 immediately preceding the start of the string that the @from 1645 matches. 1646 </p> 1647 <p> 1648 <strong>after</strong> This attribute follows the transform/@after 1649 attribute and contains the element string that must match the string 1650 immediately following the end of the string that the @from matches. 1651 </p> 1652 <p> 1653 <strong>order</strong> This attribute gives the primary order for 1654 the elements in the matched string in the @from attribute. The value 1655 is a simple integer between -128 and +127 inclusive, or a space 1656 separated list of such integers. For a single integer, it is applied 1657 to all the elements in the matched string. Details of such list type 1658 attributes are given after all the attributes are described. If 1659 missing, the order value of all the matched characters is 0. We 1660 consider the order value for a matched character in the string. 1661 </p> 1662 <ul> 1663 <li>If the value is 0 and its tertiary value is 1664 0, then the character is the base of a new run.</li> 1665 <li>If the value is 0 and its tertiary value is 1666 non-zero, then it is a normal character in a run, with ordering 1667 semantics as described in the @tertiary attribute.</li> 1668 <li>If the value is negative, then the 1669 character is a primary character and will reorder to be before the 1670 base of the run.</li> 1671 <li>If the value is positive, then the 1672 character is a primary character and is sorted based on the order 1673 value as the primary key following a previous base character.</li> 1674 </ul> 1675 <p>A character with a zero tertiary value is a 1676 primary character and receives a sort key consisting of:</p> 1677 <ul> 1678 <li>Primary weight is the order value</li> 1679 <li>Secondary weight is the index of the 1680 character. This may be any value (character index, codepoint index) 1681 such that its value is greater than the character before it and 1682 less than the character after it.</li> 1683 <li>Tertiary weight is 0.</li> 1684 <li>Quaternary weight is the same as the 1685 secondary weight.</li> 1686 </ul> 1687 <p> 1688 <strong>tertiary</strong> This attribute gives the tertiary order 1689 value to the characters matched. The value is a simple integer 1690 between -128 and +127 inclusive, or a space separated list of such 1691 integers. If missing, the value for all the characters matched is 0. 1692 We consider the tertiary value for a matched character in the 1693 string. 1694 </p> 1695 <ul> 1696 <li>If the value is 0 then the character is 1697 considered to have a primary order as specified in its order value 1698 and is a primary character.</li> 1699 <li>If the value is non zero, then the order 1700 value must be zero otherwise it is an error. The character is 1701 considered as a tertiary character for the purposes of ordering.</li> 1702 </ul> 1703 <p>A tertiary character receives its primary 1704 order and index from a previous character, which it is intended to 1705 sort closely after. The sort key for a tertiary character consists 1706 of:</p> 1707 <ul> 1708 <li>Primary weight is the primary weight of the 1709 primary character</li> 1710 <li>Secondary weight is the index of the 1711 primary character, not the tertiary character</li> 1712 <li>Tertiary weight is the tertiary value for 1713 the character.</li> 1714 <li>Quaternary weight is the index of the 1715 tertiary character.</li> 1716 </ul> 1717 <p> 1718 <strong>tertiary_base</strong> This attribute is a space separated 1719 list of "true" or "false" values corresponding 1720 to each character matched. It is illegal for a tertiary character to 1721 have a true tertiary_base value. For a primary character it marks 1722 that this character may have tertiary characters moved after it. 1723 When calculating the secondary weight for a tertiary character, the 1724 most recently encountered primary character with a true 1725 tertiary_base attribute is used. Primary characters with an @order 1726 value of 0 automatically are treated as having tertiary_base true 1727 regardless of what is specified for them. 1728 </p> 1729 <p> 1730 <strong>prebase</strong> This attribute gives the prebase attribute 1731 for each character matched. The value may be "true" or 1732 "false" or a space separated list of such values. If 1733 missing the value for all the characters matched is false. It is 1734 illegal for a tertiary character to have a true prebase value. 1735 </p> 1736 <p>If a primary character has a true prebase 1737 value then the character is marked as being typed before the base 1738 character of a run, even though it is intended to be stored after 1739 it. The primary order gives the intended position in the order after 1740 the base character, that the prebase character will end up. Thus 1741 @primary may not be 0. These characters are part of the run prefix. 1742 If such characters are typed then, in order to give the run a base 1743 character after which characters can be sorted, an appropriate base 1744 character, such as a dotted circle, is inserted into the output run, 1745 until a real base character has been typed. A value of 1746 "false" indicates that the character is not a prebase.</p> 1747 </blockquote> 1748 <p>There is no @error attribute.</p> 1749 <p>For @from attributes with a match string length 1750 greater than 1, the sort key information (@order, @tertiary, 1751 @tertiary_base, @prebase) may consist of a space separated list of 1752 values, one for each element matched. The last value is repeated to 1753 fill out any missing values. Such a list may not contain more values 1754 than there are elements in the @from attribute:</p> 1755 <pre> if len(@from) < len(@list) then error<br> else 1756 while len(@from) > len(@list)<br> append lastitem(@list) to @list<br> endwhile 1757 endif</pre> 1758 <p>For example, consider the word Northern Thai 1759 (nod-Lana) word: 'roasted'. This is ideally encoded as the 1760 following:</p> 1761 <table class='simple'> 1762 <tr> 1763 <th>name</th> 1764 <td><em>ka</em></td> 1765 <td><em>asat</em></td> 1766 <td><em>wa</em></td> 1767 <td><em>o</em><em></em></td> 1768 <td><em>t2</em></td> 1769 </tr> 1770 <tr> 1771 <th>code</th> 1772 <td>1A21</td> 1773 <td>1A60</td> 1774 <td>1A45</td> 1775 <td>1A6B<em></em></td> 1776 <td>1A76</td> 1777 </tr> 1778 <tr> 1779 <th>ccc</th> 1780 <td>0</td> 1781 <td>9</td> 1782 <td>0</td> 1783 <td>0<em></em></td> 1784 <td>230</td> 1785 </tr> 1786 1787 </table> 1788 <p>(That sequence is already in NFC format.)</p> 1789 <p>Some users may type the upper component of the 1790 vowel first, and the tone before or after the lower component. Thus 1791 someone might type it as:</p> 1792 <table class='simple'> 1793 <tr> 1794 <th>name</th> 1795 <td><em>ka</em></td> 1796 <td><em>o</em><em></em></td> 1797 <td><em>t2</em></td> 1798 <td><em>asat</em></td> 1799 <td><em>wa</em></td> 1800 </tr> 1801 <tr> 1802 <th>code</th> 1803 <td>1A21</td> 1804 <td>1A6B<em></em></td> 1805 <td>1A76</td> 1806 <td>1A60</td> 1807 <td>1A45</td> 1808 </tr> 1809 <tr> 1810 <th>ccc</th> 1811 <td>0</td> 1812 <td>0<em></em></td> 1813 <td>230</td> 1814 <td>9</td> 1815 <td>0</td> 1816 </tr> 1817 </table> 1818 <p>The Unicode NFC format of that typed value 1819 reorders to:</p> 1820 <table class='simple'> 1821 <tr> 1822 <th>name</th> 1823 <td><em>ka</em></td> 1824 <td><em>o</em><em></em></td> 1825 <td><em>asat</em></td> 1826 <td><em>t2</em></td> 1827 <td><em>wa</em></td> 1828 </tr> 1829 <tr> 1830 <th>code</th> 1831 <td>1A21</td> 1832 <td>1A6B<em></em></td> 1833 <td>1A60</td> 1834 <td>1A76</td> 1835 <td>1A45</td> 1836 </tr> 1837 <tr> 1838 <th>ccc</th> 1839 <td>0</td> 1840 <td>0<em></em></td> 1841 <td>9</td> 1842 <td>230</td> 1843 <td>0</td> 1844 </tr> 1845 </table> 1846 <p> 1847 Finally, the user might also type in the sequence with the tone <em>after</em> 1848 the lower component. 1849 </p> 1850 <table class='simple'> 1851 <tr> 1852 <th>name</th> 1853 <td><em>ka</em></td> 1854 <td><em>o</em><em></em></td> 1855 <td><em>asat</em></td> 1856 <td><em>wa</em></td> 1857 <td><em>t2</em></td> 1858 </tr> 1859 <tr> 1860 <th>code</th> 1861 <td>1A21</td> 1862 <td>1A6B<em></em></td> 1863 <td>1A60</td> 1864 <td>1A45</td> 1865 <td>1A76</td> 1866 </tr> 1867 <tr> 1868 <th>ccc</th> 1869 <td>0</td> 1870 <td>0<em></em></td> 1871 <td>9</td> 1872 <td>0</td> 1873 <td>230</td> 1874 </tr> 1875 </table> 1876 <p>(That sequence is already in NFC format.)</p> 1877 <p>We want all of these sequences to end up 1878 ordered as the first. To do this, we use the following rules:</p> 1879 <pre> <reorder from="\u1A60" order="127"/> <!-- max possible order --> 1880 <reorder from="\u1A6B" order="42"/> 1881 <reorder from="[\u1A75-\u1A7C]" order="55"/><br> <reorder before="\u1A6B" from="\u1A60\u1A45" order="10"/><br> <reorder before="\u1A6B[\u1A75-\u1A7C]" from="\u1A60\u1A45" order="10"/><br> <reorder before="\u1A6B" from="\u1A60[\u1A75-\u1A7C]\u1A45" order="10 55 10"/></pre> 1882 <p> 1883 The first reorder is the default ordering for the <i>asat</i> which 1884 allows for it to be placed anywhere in a sequence, but moves any 1885 non-consonants that may immediately follow it, back before it in the 1886 sequence. The next two rules give the orders for the top vowel 1887 component and tone marks respectively. The next three rules give the 1888 <i>asat</i> and <i>wa</i> characters a primary order that places them 1889 before the <em>o</em>. Notice particularly the final reorder rule 1890 where the <i>asat</i>+<i>wa</i> is split by the tone mark. This rule 1891 is necessary in case someone types into the middle of previously 1892 normalized text. 1893 </p> 1894 <p><reorder> elements are priority ordered 1895 based first on the length of string their @from attribute matches and 1896 then the sum of the lengths of the strings their @before and @after 1897 attributes match.</p> 1898 <p>If a layout has two <transforms> elements 1899 of type reorder, e.g. from importing one and specifying the second, 1900 then <transform> elements are merged. The @from string in a 1901 <reorder> element describes a set of strings that it matches. 1902 This also holds for the @before and @after attributes. The 1903 intersection of two <reorder> elements consists of the 1904 intersections of their @from, @before and @after string sets. It is 1905 illegal for the intersection between any two <reorder> elements 1906 in the same <transforms> element to be non empty, although 1907 implementors are encouraged to have pity on layout authors when 1908 reporting such errors, since they can be hard to track down.</p> 1909 <p>If two <reorder> elements in two 1910 different <transforms> elements have a non empty intersection, 1911 then they are split and merged. They are split such that where there 1912 were two <reorder> elements, there are, in effect (but not 1913 actuality), three elements consisting of:</p> 1914 <ul> 1915 <li>@from, @before, @after that match the 1916 intersection of the two rules. The other attributes are merged, as 1917 described below.</li> 1918 <li>@from, @before, @after that match the set of 1919 strings in the first rule not in the intersection with the other 1920 attributes from the first rule.</li> 1921 <li>@from, @before, @after that match the set of 1922 strings in the second rule not in the intersection, with the other 1923 attributes from the second rule.</li> 1924 </ul> 1925 <p>When merging the other attributes, the second 1926 rule is taken to have priority (occurring later in the layout 1927 description file). Where the second rule does not define the value 1928 for a character but the first does, it is taken from the first rule, 1929 otherwise it is taken from the second rule.</p> 1930 <p>Notice that it is possible for two rules to 1931 match the same string, but for them not to merge because the 1932 distribution of the string across @before, @from, and @after is 1933 different. For example:</p> 1934 <pre> <reorder before="ab" from="cd" after="e"/></pre> 1935 <p>would not merge with:</p> 1936 <pre> <reorder before="a" from="bcd" after="e"/></pre> 1937 <p>When two <reorders> elements merge as the 1938 result of an import, the resulting reorder elements are sorted into 1939 priority order for matching.</p> 1940 <p>Consider this fragment from a shared reordering 1941 for the Myanmar script:</p> 1942 <pre><!-- medial-r --> 1943 <reorder from="\u103C" order="20"/> 1944 1945 <!-- [medial-wa or shan-medial-wa] --> 1946 <reorder from="[\u103D\u1082]" order="25"/> 1947 1948 <!-- [medial-ha or shan-medial-wa]+asat = Mon <i>asat</i> --><br> <reorder from="[\u103E\u1082]\u103A" order="27"/> 1949 1950 <!-- [medial-ha or mon-medial-wa] --><br> <reorder from="[\u103E\u1060]" order="27"/> 1951 1952 <!-- [e-vowel or shan-e-vowel] --><br> <reorder from="[\u1031\u1084]" order="30"/> 1953 <br> <reorder from="[\u102D\u102E\u1033-\u1035\u1071-\u1074\u1085\u109D\uA9E5]" order="35"/></pre> 1954 <p>A particular Myanmar keyboard layout can have 1955 this reorders element:</p> 1956 <pre><reorders type="reorder"><br><!-- Kinzi --> 1957 <reorder from="\u1004\u103A\u1039" order="-1"/> 1958 1959 <!-- e-vowel --> 1960 <reorder from="\u1031" prebase="1"/> 1961 1962 <!-- medial-r --> 1963 <reorder from="\u103C" prebase="1"/><br></reorders></pre> 1964 <p>The effect of this that the <em>e-vowel</em> will be identified as a prebase and will have an order of 30. 1965 Likewise a <em>medial-r</em> will be identified as a prebase and will have an 1966 order of 20. Notice that a <em>shan-e-vowel</em> will not be identified as a prebase 1967 (even if it should be!). The <em>kinzi</em> is described in the layout since 1968 it moves something across a run boundary. By separating such 1969 movements (prebase or moving to in front of a base) from the shared 1970 ordering rules, the shared ordering rules become a self-contained 1971 combining order description that can be used in other keyboards or 1972 even in other contexts than keyboarding. </p> 1973 <hr> 1974 <h3> 1975 5.20 <a name="Element_final" href="#Element_final">Element: final</a> 1976 </h3> 1977 <p>The final transform is applied after the 1978 reorder transform. It executes in a similar way to the simple 1979 transform with the settings ignored, as if there were no settings in 1980 the <settings> element.</p> 1981 <p>This is an example from Khmer where split 1982 vowels are combined after reordering.</p> 1983 <pre> 1984 <transforms type="final"> 1985 <transform from="\u17C1\u17B8" to="\u17BE"/> 1986 <transform from="\u17C1\u17B6" to="\u17C4"/> 1987 </transforms></pre> 1988 <p>Another example allows a keyboard 1989 implementation to alert or stop people typing two lower vowels in a 1990 Burmese cluster:</p> 1991 <pre> <transform from="[\u102F\u1030\u1048\u1059][\u102F\u1030\u1048\u1059]" error="fail"/></pre> 1992 <hr> 1993 <h3> 1994 5.21 <a name="Element_backspaces" href="#Element_backspaces">Element: 1995 backspaces</a> 1996 </h3> 1997 <p>The backspace transform is an optional 1998 transform that is not applied on input of normal characters, but is 1999 only used to perform extra backspace modifications to previously 2000 committed text.</p> 2001 <p>Keyboarding applications typically, but are not 2002 required, to work in one of two modes:</p> 2003 <dl> 2004 <dt> 2005 <b>text entry</b> 2006 </dt> 2007 <dd>text entry happens while a user is typing new text. A user 2008 typically wants the backspace key to undo whatever they last typed, 2009 whether or not they typed things in the 'right' order.</dd> 2010 </dl> 2011 <dl> 2012 <dt> 2013 <b>text editing</b> 2014 </dt> 2015 <dd>text editing happens when a user moves the cursor into some 2016 previously entered text which may have been entered by someone else. 2017 As such, there is no way to know in which order things were typed, 2018 but a user will still want appropriate behaviour when they press 2019 backspace. This may involve deleting more than one character or 2020 replacing a sequence of characters with a different sequence.</dd> 2021 </dl> 2022 <p>In the text entry mode, there is no need for 2023 any special description of backspace behaviour. A keyboarding 2024 application will typically keep a history of previous output states 2025 and just revert to the previous state when backspace is hit.</p> 2026 <p>In text editing mode, different keyboard 2027 layouts may behave differently in the same textual context. The 2028 backspace transform allows the keyboard layout to specify the effect 2029 of pressing backspace in a particular textual context. This is done 2030 by specifying a set of backspace rules that match a string before the 2031 cursor and replace it with another string. The rules are expressed as 2032 backspace elements encapsulated in a backspaces element.</p> 2033 <hr> 2034 <h3> 2035 5.22 <a name="Element_backspace" href="#Element_backspace">Element: 2036 backspace</a> 2037 </h3> 2038 <p>The backspace element has the same @before, 2039 @from, @after, @to, @errors of the transform element. The @to is 2040 optional with backspace.</p> 2041 <p>For example, consider deleting a Devanagari 2042 ksha:</p> 2043 <pre> 2044 <backspaces> 2045 <backspace from="\u0915\u094D\u0936"/> 2046 </backspaces></pre> 2047 <p>Here there is no @to attribute since the whole 2048 string is being deleted. This is not uncommon in the backspace 2049 transforms.</p> 2050 <p>A more complex example comes from a Burmese 2051 visually ordered keyboard:</p> 2052 <pre> <backspaces> 2053 <!-- Kinzi --><br> <backspace from="[\u1004\u101B\u105A]\u103A\u1039"/> 2054 2055 <!-- subjoined consonant --><br> <backspace from="\u1039[\u1000-\u101C\u101E\u1020\u1021\u1050\u1051\u105A-\u105D]"/> 2056 <br><!-- tone mark --> 2057 <backspace from="\u102B\u103A"/> 2058 <br><!-- Handle prebases --> 2059 <!-- diacritics stored before e-vowel --><br> <backspace from="[\u103A-\u103F\u105E-\u1060\u1082]\u1031" to="\u1031"/> 2060 2061 <!-- diacritics stored before medial r --><br> <backspace from="[\u103A-\u103B\u105E-\u105F]\u103C" to="\u103C"/> 2062 <br><!-- subjoined consonant before e-vowel --> 2063 <backspace from="\u1039[\u1000-\u101C\u101E\u1020\u1021]\u1031" to="\u1031"/> 2064 <br><!-- base consonant before e-vowel --> 2065 <backspace from="[\u1000-\u102A\u103F-\u1049\u104E]\u1031" to="\uFDDF\u1031"/> 2066 <br><!-- subjoined consonant before medial r --> 2067 <backspace from="\u1039[\u1000-\u101C\u101E\u1020\u1021]\u103C" to="\u103C"/> 2068 <br><!-- base consonant before medial r --> 2069 <backspace from="[\u1000-\u102A\u103F-\u1049\u104E]\u103C" to="\uFDDF\u103C"/> 2070 <br><!-- delete lone medial r or e-vowel --> 2071 <backspace from="\uFDDF[\u1031\u103C]"/><br></backspaces></pre> 2072 <p>The above example is simplified, and doesn't fully handle the interaction between medial-r and e-vowel.</p> 2073 <p>The character \uFDDF does not represent a 2074 literal character, but is instead a special placeholder, a 2075 "filler string". When a keyboard implementation handles a 2076 user pressing a key that inserts a prebase character, it also has to 2077 insert a special filler string before the prebase to ensure that the 2078 prebase character does not combine with the previous cluster. See the 2079 reorder transform for details. The precise filler string is 2080 implementation dependent. Rather than requiring keyboard layout 2081 designers to know what the filler string is, we reserve a special 2082 character that the keyboard layout designer may use to reference this 2083 filler string. It is up to the keyboard implementation to, in effect, 2084 replace that character with the filler string.</p> 2085 <p>The first three transforms above delete various 2086 ligatures with a single keypress. The other transforms handle prebase 2087 characters. There are two in this Burmese keyboard. The transforms 2088 delete the characters preceding the prebase character up to base 2089 which gets replaced with the prebase filler string, which represents 2090 a null base. Finally the prebase filler string + prebase is deleted 2091 as a unit.</p> 2092 <p>The backspace transform is much like other 2093 transforms except in its processing model. If we consider the same 2094 transform as in the simple transform example, but as a backspace:</p> 2095 <blockquote><backspace 2096 before="X" from="Y" after="Z" 2097 to="B"/></blockquote> 2098 <p>This would transform the string:</p> 2099 <blockquote>XYZ XBZ</blockquote> 2100 <p>If we mark where the current match position is 2101 before and after the transform we see:</p> 2102 <blockquote>X Y | Z X B | Z</blockquote> 2103 <p>Whereas a simple or final transform would then 2104 run other transforms in the transform list, advancing the processing 2105 position until it gets to the end of the string, the backspace 2106 transform only matches a single backspace rule and then finishes.</p> 2107 <hr> 2108 <h2> 2109 6 <a name="Element_Heirarchy_Platform_File" 2110 href="#Element_Heirarchy_Platform_File">Element Hierarchy - 2111 Platform File</a> 2112 </h2> 2113 <p>There is a separate XML structure for platform-specific 2114 configuration elements. The most notable component is a mapping 2115 between the hardware key codes to the ISO layout positions for that 2116 platform.</p> 2117 <h3> 2118 6.1 <a name="Element_platform" href="#Element_platform">Element: 2119 platform</a> 2120 </h3> 2121 <p>This is the top level element. This element contains a set of 2122 elements defined below. A document shall only contain a single 2123 instance of this element.</p> 2124 <p>Syntax</p> 2125 <p><platform></p> 2126 <p>{platform-specific elements}</p> 2127 <p></platform></p> 2128 <h3> 2129 6.2 <a name="Element_hardwareMap" href="#Element_hardwareMap">Element: 2130 hardwareMap</a> 2131 </h3> 2132 <p>This element must have a platform element as its parent. This 2133 element contains a set of map elements defined below. A document 2134 shall only contain a single instance of this element.</p> 2135 <p>Syntax</p> 2136 <pre><platform> 2137 <hardwareMap> 2138 {a set of map elements} 2139 </hardwareMap> 2140 </platform></pre> 2141 <h3> 2142 6.3 <a name="Element_hardwareMap_map" href="#Element_hardwareMap_map">Element: 2143 map</a> 2144 </h3> 2145 <p>This element must have a hardwareMap element as its parent. 2146 This element maps between a hardware keycode and the corresponding 2147 ISO layout position of the key.</p> 2148 <p>Syntax</p> 2149 <p><map keycode="{hardware keycode}" iso="{ISO 2150 layout position}"/></p> 2151 <dl> 2152 <dt>Attribute: keycode (required)</dt> 2153 <dd>The hardware key code value of the key. This value is an 2154 integer which is provided by the keyboard driver.</dd> 2155 </dl> 2156 <dl> 2157 <dt>Attribute: iso (required)</dt> 2158 <dd>The corresponding position of a key using the ISO layout 2159 convention where rows are identified by letters and columns are 2160 identified by numbers. For example, "D01" corresponds to the "Q" key 2161 on a US keyboard. (See the definition at the beginning of the 2162 document for a diagram).</dd> 2163 </dl> 2164 <p>Examples</p> 2165 <pre><platform><br> <hardwareMap><br> <map keycode="2" iso="E01" /><br> <map keycode="3" iso="E02" /><br> <map keycode="4" iso="E03" /><br> <map keycode="5" iso="E04" /><br> <map keycode="6" iso="E05" /><br> <map keycode="7" iso="E06" /><br> <map keycode="41" iso="E00" /><br> </hardwareMap><br></platform></pre> 2166 <h2> 2167 7 <a name="Invariants" href="#Invariants">Invariants</a> 2168 </h2> 2169 <p>Beyond what the DTD imposes, certain other restrictions on the 2170 data are imposed on the data.</p> 2171 <ol> 2172 <li>For a given platform, every map[@iso] value must be in the 2173 hardwareMap if there is one (_keycodes.xml)</li> 2174 <li>Every map[@base] value must also be in base[@base] value</li> 2175 <li>No keyMap[@modifiers] value can overlap with another 2176 keyMap[@modifiers] value. 2177 <ul> 2178 <li>eg you can't have "RAlt Ctrl" in one keyMap, and "Alt 2179 Shift" in another (because Alt = RAltLAlt).</li> 2180 </ul> 2181 </li> 2182 <li>Every sequence of characters in a transform[@from] value 2183 must be a concatenation of two or more map[@to] values. 2184 <ul> 2185 <li>eg with <transform from="xyz" to="q"> there must be 2186 some map values to get there, such as <map... to="xy"> & 2187 <map... to="z"></li> 2188 </ul> 2189 </li> 2190 <li>There must be either 0 or 1 of (keyMap[@fallback] or 2191 baseMap[@fallback]) attributes</li> 2192 <li>If the base and chars values for modifiers="" are all 2193 identical, and there are no longpresses, that keyMap must not appear 2194 (??)</li> 2195 <li>There will never be overlaps among modifier values.</li> 2196 <li>A modifier set will never have ? (optional) on all values 2197 <ul> 2198 <li>eg, you'll never have RCtrl?Caps?LShift?</li> 2199 </ul> 2200 </li> 2201 <li>Every base[@base] value must be unique.</li> 2202 <li>A modifier attribute value will aways be minimal, observing 2203 the following simplification rules. <br> 2204 </li> 2205 </ol> 2206 <table> 2207 <!-- nocaption --> 2208 <tbody> 2209 <tr> 2210 <td><p>Notation</p></td> 2211 <td><p>Notes</p></td> 2212 </tr> 2213 <tr> 2214 <td><p> 2215 Lower case character (eg. <i>x</i> ) 2216 </p></td> 2217 <td><p> 2218 Interpreted as any combination of modifiers.<br> (eg. <i>x</i> 2219 = CtrlShiftOption) 2220 </p></td> 2221 </tr> 2222 <tr> 2223 <td><p> 2224 Upper-case character (eg. <i>Y </i>) 2225 </p></td> 2226 <td><p> 2227 Interpreted as a single modifier key (which may or may not have a 2228 L and R variant)<br> (eg. <i>Y</i> = Ctrl, <i>RY</i> = 2229 RCtrl, etc..) 2230 </p></td> 2231 </tr> 2232 <tr> 2233 <td><p>Y? Y </p> 2234 <p>Y LY RY LYRY</p></td> 2235 <td><p> 2236 Eg. Opt? ROpt LOpt ROptLOpt <br> Eg. Opt ROpt 2237 LOpt ROptLOpt 2238 </p></td> 2239 </tr> 2240 </tbody> 2241 </table> 2242 <table> 2243 <!-- nocaption --> 2244 <tbody> 2245 <tr> 2246 <td><p>Axiom</p></td> 2247 <td><p>Example</p></td> 2248 </tr> 2249 <tr> 2250 <td><p>xY x xY?</p></td> 2251 <td><p>OptCtrlShift OptCtrl OptCtrlShift?</p></td> 2252 </tr> 2253 <tr> 2254 <td><p>xRY xY? xY?</p> 2255 <p>xLY xY? xY?</p></td> 2256 <td><p>OptCtrlRShift OptCtrlShift? OptCtrlShift?</p></td> 2257 </tr> 2258 <tr> 2259 <td><p>xRY? xY xY?</p> 2260 <p>xLY? xY xY?</p></td> 2261 <td><p>OptCtrlRShift? OptCtrlShift OptCtrlShift?</p></td> 2262 </tr> 2263 <tr> 2264 <td><p>xRY? xY? xY?</p> 2265 <p>xLY? xY? xY?</p></td> 2266 <td><p>OptCtrlRShift? OptCtrlShift? OptCtrlShift?</p></td> 2267 </tr> 2268 <tr> 2269 <td><p>xRY xY xY</p> 2270 <p>xLY xY xY</p></td> 2271 <td><p>OptCtrlRShift OptCtrlShift OptCtrlShift?</p></td> 2272 </tr> 2273 <tr> 2274 <td><p>LY?RY?</p></td> 2275 <td><p>OptRCtrl?LCtrl? OptCtrl?</p></td> 2276 </tr> 2277 <tr> 2278 <td><p>xLY? xLY xLY?</p></td> 2279 <td> </td> 2280 </tr> 2281 <tr> 2282 <td><p>xY? xY xY?</p></td> 2283 <td> </td> 2284 </tr> 2285 <tr> 2286 <td><p>xY? x xY?</p></td> 2287 <td> </td> 2288 </tr> 2289 <tr> 2290 <td><p>xLY? x xLY?</p></td> 2291 <td> </td> 2292 </tr> 2293 <tr> 2294 <td><p>xLY x xLY?</p></td> 2295 <td> </td> 2296 </tr> 2297 </tbody> 2298 </table> 2299 <h2> 2300 8 <a name="Data_Sources" href="#Data_Sources">Data Sources</a> 2301 </h2> 2302 <p>Here is a list of the data sources used to generate the initial 2303 key map layouts:</p> 2304 <table> 2305 <caption> 2306 <a name="Key_Map_Data_Sources" href="#Key_Map_Data_Sources">Key 2307 Map Data Sources</a> 2308 </caption> 2309 <tbody> 2310 <tr> 2311 <td><p>Platform</p></td> 2312 <td><p>Source</p></td> 2313 <td><p>Notes</p></td> 2314 </tr> 2315 <tr> 2316 <td><p>Android</p></td> 2317 <td><p> 2318 Android 4.0 - Ice Cream Sandwich<br> (<a 2319 href="http://source.android.com/source/downloading.html">http://source.android.com/source/downloading.html</a>) 2320 </p></td> 2321 <td><p>Parsed layout files located in 2322 packages/inputmethods/LatinIME/java/res</p></td> 2323 </tr> 2324 <tr> 2325 <td><p>ChromeOS</p></td> 2326 <td><p> 2327 XKB (<a href="http://www.x.org/wiki/XKB">http://www.x.org/wiki/XKB</a>) 2328 </p></td> 2329 <td><p>The ChromeOS represents a very small subset of the 2330 keyboards available from XKB.</p></td> 2331 </tr> 2332 <tr> 2333 <td><p>Mac OSX</p></td> 2334 <td><p> 2335 Ukelele bundled System Keyboards (<a 2336 href="http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=ukelele">http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=ukelele</a>) 2337 </p></td> 2338 <td><p>These layouts date from Mac OSX 10.4 and are 2339 therefore a bit outdated</p></td> 2340 </tr> 2341 <tr> 2342 <td><p>Windows</p></td> 2343 <td><p> 2344 Generated .klc files from the Microsoft Keyboard Layout Creator (<a 2345 href="http://msdn.microsoft.com/en-us/goglobal/bb964665">http://msdn.microsoft.com/en-us/goglobal/bb964665</a>) 2346 </p></td> 2347 <td><p> 2348 For interactive layouts, see also <a 2349 href="http://msdn.microsoft.com/en-us/goglobal/bb964651">http://msdn.microsoft.com/en-us/goglobal/bb964651</a> 2350 </p></td> 2351 </tr> 2352 </tbody> 2353 </table> 2354 <h2> 2355 9 <a name="Keyboard_IDs" href="#Keyboard_IDs">Keyboard IDs</a> 2356 </h2> 2357 <p>There is a set of subtags that help identify the keyboards. 2358 Each of these are used after the "t-k0" subtags to help identify the 2359 keyboards. The first tag appended is a mandatory platform tag 2360 followed by zero or more tags that help differentiate the keyboard 2361 from others with the same locale code.</p> 2362 <h3> 2363 9.1 <a name="Principles_for_Keyboard_Ids" 2364 href="#Principles_for_Keyboard_Ids">Principles for Keyboard Ids</a> 2365 </h3> 2366 <p>The following are the design principles for the ids.</p> 2367 <ol> 2368 <li>BCP47 compliant. 2369 <ol> 2370 <li>Eg, "en-t-k0-extended".</li> 2371 </ol> 2372 </li> 2373 <li>Use the minimal language id based on likelySubtags. 2374 <ol> 2375 <li>Eg, instead of en-US-t-k0-xxx, use en-t-k0-xxx. Because 2376 there is <likelySubtag from="en" 2377 to="en_Latn_US"/>, en-US en.</li> 2378 <li>The data is in <a 2379 href="http://unicode.org/repos/cldr/tags/latest/common/supplemental/likelySubtags.xml">http://unicode.org/repos/cldr/tags/latest/common/supplemental/likelySubtags.xml</a></li> 2380 </ol> 2381 </li> 2382 <li>The platform goes first, if it exists. If a keyboard on the 2383 platform changes over time, both are dated, eg 2384 bg-t-k0-chromeos-2011. When selecting, if there is no date, it means 2385 the latest one.</li> 2386 <li>Keyboards are only tagged that differ from the "standard for 2387 each platform". That is, for each language on a platform, there will 2388 be a keyboard with no subtags other than the platform.Subtags with a 2389 common semantics across platforms are used, such as '-extended', 2390 -phonetic, -qwerty, -qwertz, -azerty, </li> 2391 <li>In order to get to 8 letters, abbreviations are reused that 2392 are already in <a 2393 href="http://unicode.org/repos/cldr/tags/latest/common/bcp47/">bcp47</a> 2394 -u/-t extensions and in <a 2395 href="http://www.iana.org/assignments/language-subtag-registry">language-subtag-registry</a> 2396 variants, eg for Traditional use "-trad" or "-traditio" (both exist 2397 in <a href="http://unicode.org/repos/cldr/tags/latest/common/bcp47/">bcp47</a>). 2398 </li> 2399 <li>Multiple languages cannot be indicated, so the predominant 2400 target is used. 2401 <ol> 2402 <li>For Finnish + Sami, use fi-t-k0-smi or extended-smi</li> 2403 </ol> 2404 </li> 2405 <li>In some cases, there are multiple subtags, like 2406 en-US-t-k0-chromeos-intl-altgr.xml</li> 2407 <li>Otherwise, platform names are used as a guide.</li> 2408 </ol> 2409 <h2> 2410 10 <a name="Platform_Behaviors_in_Edge_Cases" 2411 href="#Platform_Behaviors_in_Edge_Cases">Platform Behaviors in 2412 Edge Cases</a> 2413 </h2> 2414 <table> 2415 <!-- nocaption --> 2416 <tbody> 2417 <tr> 2418 <td><p>Platform</p></td> 2419 <td><p>No modifier combination match is available</p></td> 2420 <td><p>No map match is available for key position</p></td> 2421 <td><p>Transform fails (ie. if ^d is pressed when that 2422 transform does not exist)</p></td> 2423 </tr> 2424 <tr> 2425 <td><p>ChromeOS</p></td> 2426 <td><p>Fall back to base</p></td> 2427 <td><p> 2428 Fall back to character in a keyMap with same "level" of modifier 2429 combination. If this character does not exist, fall back to (n-1) 2430 level. (This is handled data-generation side).<br> In the 2431 spec: No output 2432 </p></td> 2433 <td><p>No output at all</p></td> 2434 </tr> 2435 <tr> 2436 <td><p>Mac OSX</p></td> 2437 <td><p>Fall back to base (unless combination is some sort 2438 of keyboard shortcut, eg. cmd-c)</p></td> 2439 <td><p>No output</p></td> 2440 <td><p>Both keys are output separately</p></td> 2441 </tr> 2442 <tr> 2443 <td><p>Windows</p></td> 2444 <td><p>No output</p></td> 2445 <td><p>No output</p></td> 2446 <td><p>Both keys are output separately</p></td> 2447 </tr> 2448 </tbody> 2449 </table> 2450 <p> </p> 2451 2452 <hr> 2453 <p class="copyright"> 2454 Copyright 20012018 Unicode, Inc. All Rights Reserved. The Unicode 2455 Consortium makes no expressed or implied warranty of any kind, and 2456 assumes no liability for errors or omissions. No liability is assumed 2457 for incidental and consequential damages in connection with or 2458 arising out of the use of the information or programs contained or 2459 accompanying this technical report. The Unicode <a 2460 href="http://unicode.org/copyright.html">Terms of Use</a> apply. 2461 </p> 2462 <p class="copyright">Unicode and the Unicode logo are trademarks 2463 of Unicode, Inc., and are registered in some jurisdictions.</p> 2464 </div> 2465 2466 </body> 2467 </html>
