├── virtualkeyboardspec.md ├── .DS_Store ├── images ├── example.png ├── numberKeyboard.png ├── standardKeyboard.png ├── dual-screen-device.png ├── keyboard-occluding-content.png ├── single-touch-screen-device.png └── spreadsheet-example.svg ├── tidyconfig.txt ├── w3c.json ├── LICENSE.md ├── CODE_OF_CONDUCT.md ├── ECHIDNA ├── README.md ├── .github └── workflows │ └── auto-publish.yml ├── CONTRIBUTING.md └── index.html /virtualkeyboardspec.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.DS_Store: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/virtual-keyboard/HEAD/.DS_Store -------------------------------------------------------------------------------- /images/example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/virtual-keyboard/HEAD/images/example.png -------------------------------------------------------------------------------- /images/numberKeyboard.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/virtual-keyboard/HEAD/images/numberKeyboard.png -------------------------------------------------------------------------------- /images/standardKeyboard.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/virtual-keyboard/HEAD/images/standardKeyboard.png -------------------------------------------------------------------------------- /images/dual-screen-device.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/virtual-keyboard/HEAD/images/dual-screen-device.png -------------------------------------------------------------------------------- /tidyconfig.txt: -------------------------------------------------------------------------------- 1 | char-encoding: utf8 2 | indent: yes 3 | wrap: 80 4 | tidy-mark: no 5 | newline: LF 6 | custom-tags: yes 7 | -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": ["131776"] 3 | , "contacts": ["siusin"] 4 | , "repo-type": "rec-track" 5 | } 6 | -------------------------------------------------------------------------------- /images/keyboard-occluding-content.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/virtual-keyboard/HEAD/images/keyboard-occluding-content.png -------------------------------------------------------------------------------- /images/single-touch-screen-device.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/virtual-keyboard/HEAD/images/single-touch-screen-device.png -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All documents in this Repository are licensed by contributors 2 | under the 3 | [W3C Software and Document License](http://www.w3.org/Consortium/Legal/copyright-software). 4 | 5 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/). 4 | -------------------------------------------------------------------------------- /ECHIDNA: -------------------------------------------------------------------------------- 1 | index.html?specStatus=WD&shortName=virtual-keyboard respec 2 | images/dual-screen-device.png 3 | images/single-touch-screen-device.png 4 | images/example.png 5 | images/spreadsheet-example.svg 6 | images/keyboard-occluding-content.png 7 | images/standardKeyboard.png 8 | images/numberKeyboard.png 9 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | This repository is the home of the **[VirtualKeyboard API](https://www.w3.org/TR/virtual-keyboard/)** specification being worked on by 2 | the [Web Editing Working Group](https://www.w3.org/2021/06/web-editing-wg-charter.html). 3 | 4 | ## Useful links 5 | * [Explainer](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/VirtualKeyboardAPI/explainer.md) 6 | * [The VirtualKeyboard API specification](https://www.w3.org/TR/virtual-keyboard/) 7 | * [Web Editing WG homepage](https://www.w3.org/groups/wg/webediting) 8 | * [Meetings and Participation](https://github.com/w3c/editing#meetings) -------------------------------------------------------------------------------- /.github/workflows/auto-publish.yml: -------------------------------------------------------------------------------- 1 | name: Node CI 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | pull_request: {} 8 | 9 | jobs: 10 | validate-and-publish: 11 | name: Validate and Publish 12 | runs-on: ubuntu-latest # only linux supported at present 13 | steps: 14 | - uses: actions/checkout@v2 15 | - uses: w3c/spec-prod@v2 16 | with: 17 | TOOLCHAIN: respec 18 | VALIDATE_LINKS: true 19 | W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }} 20 | W3C_WG_DECISION_URL: "https://lists.w3.org/Archives/Public/public-editing-tf/2021Sep/0013.html" 21 | W3C_NOTIFICATIONS_CC: "${{ secrets.CC }}" 22 | W3C_BUILD_OVERRIDE: | 23 | specStatus: WD 24 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Web Editing Working Group 2 | 3 | Contributions to this repository are intended to become part of Recommendation-track documents governed by the 4 | [W3C Patent Policy](http://www.w3.org/Consortium/Patent-Policy-20040205/) and 5 | [Software and Document License](http://www.w3.org/Consortium/Legal/copyright-software). To make substantive contributions to specifications, you must participate 6 | in this W3C Working Group or make a non-member patent licensing commitment. 7 | 8 | If you are not the sole contributor to a contribution (pull request), please identify all 9 | contributors in the pull request comment. 10 | 11 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 12 | 13 | ``` 14 | +@github_username 15 | ``` 16 | 17 | If you added a contributor by mistake, you can remove them in a comment with: 18 | 19 | ``` 20 | -@github_username 21 | ``` 22 | 23 | If you are making a pull request on behalf of someone else but you had no part in designing the 24 | feature, you can remove yourself with the above syntax. 25 | -------------------------------------------------------------------------------- /images/spreadsheet-example.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | VirtualKeyboard API 6 | 7 | 33 | 34 | 35 | 36 |
37 |

38 | The {{VirtualKeyboard}} API provides authors with greater control over the visibility of the virtual keyboard (VK), and greater ability to adapt the layout of web pages when VK visibility changes. 39 |

40 |
41 |
42 |

43 |

44 |
45 |
46 |

Introduction

47 |

This section is non-normative.

48 |

49 | The Virtual Keyboard (VK) is the on-screen keyboard used for input in scenarios where a hardware keyboard may not be available. 50 | User agents respond to the presence of the VK, without any exposure of this information to web developers in the following way: 51 | 1. Repositioning the user agent above the VK 52 | 2. Reducing the size of the layout viewport so the VK doesn't occlude it 53 | 3. Reducing the size of the visual viewport and padding the layout viewport to ensure it can be shifted above the VK 54 | 55 | This API provides a fourth option that allows the user agent to leave its layout and visual viewports unchanged and instead 56 | provide information about the intersection of the VK and layout viewport so that the author can adapt the layout of their web 57 | pages using JavaScript or CSS environment variables. 58 | 59 |

60 | Figure showing virtual keyboard on dual screen device 61 | Figure showing virtual keyboard on dual screen device 62 |

63 | 64 |

65 | Figure showing virtual keyboard on single-touch screen device 66 | Figure showing virtual keyboard on single-touch screen device 67 |

68 |

69 |
70 |
71 |

72 | This specification defines conformance criteria that apply to a single 73 | product: the user agent that implements the interfaces that 74 | it contains. 75 |

76 |

77 | Conformance requirements phrased as algorithms or specific steps may be 78 | implemented in any manner, so long as the end result is equivalent. (In 79 | particular, the algorithms defined in this specification are intended 80 | to be easy to follow, and not intended to be performant.) 81 |

82 |
83 |
84 |

The VirtualKeyboard Interface

85 | 
 86 |             partial interface Navigator {
 87 |                 [SecureContext, SameObject] readonly attribute VirtualKeyboard virtualKeyboard;
 88 |             };
 89 | 
 90 |             [Exposed=Window, SecureContext]
 91 |             interface VirtualKeyboard : EventTarget {
 92 |                 undefined show();
 93 |                 undefined hide();
 94 |                 readonly attribute DOMRect boundingRect;
 95 |                 attribute boolean overlaysContent;
 96 |                 attribute EventHandler ongeometrychange;
 97 |             };
 98 |
99 |

100 | The {{VirtualKeyboard}} object has an associated: 101 |

102 | boundingRect 103 |

104 | A {{DOMRect}}, initially has zero values. 105 |

106 | overlaysContent 107 |

108 | A boolean, initially `false`. When this attribute is set to `true`, a user agent MUST NOT resize its [=document=]'s viewport or visual viewport. 109 |

110 |
111 |
112 | show() method 113 |
114 |
115 |

116 | The method must follow these steps: 117 |

118 |
    119 |
  1. 120 | Let |window| be [=this=]'s [=relevant global object=]. Assert that |window| is a {{Window}} object. 121 |
    2. 122 |
  2. 123 | If |window| does not have [=sticky activation=], abort these steps. 124 |
    3. 125 |
  3. 126 | If the focused element is not a form control (such as the value of the [=textarea=] element), or an [=editing host=] (e.g., using contenteditable) then abort these steps. 127 |
    4. 128 |
  4. 129 | If the {{ElementContentEditable/virtualKeyboardPolicy}} is not {{manual}} or inputMode's attribute value is none then abort these steps. 130 |
    5. 131 |
  5. 132 | Call the system API to show the VK. 133 |
    6. 134 |
  6. 135 | [=In parallel=], follow these steps: 136 |
      137 |
    1. Wait for the virtual keyboard to be shown by the system.
      2. 138 |
    2. Call {{VirtualKeyboard/set the virtual keyboard bounding rect}} with the keyboard's OS reported bounding rectangle and the [=document=]'s viewport rectangle.
      3. 139 |
    3. [=Fire an event=] named "geometrychange" at [=this=].
      4. 140 |
    141 |
    7. 142 |
143 |
144 |
145 | hide() method 146 |
147 |
148 |

149 | The method must follow these steps: 150 |

151 |
    152 |
  1. 153 | Let |window| be [=this=]'s [=relevant global object=]. Assert that |window| is a {{Window}} object. 154 |
    2. 155 |
  2. 156 | If |window| does not have [=sticky activation=], abort these steps. 157 |
    3. 158 |
  3. 159 | If the focused element's {{ElementContentEditable/virtualKeyboardPolicy}} is not {{manual}} or inputMode's attribute value is none then abort these steps. 160 |
    4. 161 |
  4. 162 | Call the system API to hide the VK. 163 |
    5. 164 |
  5. 165 | [=In parallel=], follow these steps: 166 |
      167 |
    1. Wait for the virtual keyboard to be hidden by the system.
      2. 168 |
    2. Call {{VirtualKeyboard/set the virtual keyboard bounding rect}} with the keyboard's OS reported bounding rectangle (which has all 0 values) and the [=document=]'s viewport rectangle.
      3. 169 |
    3. [=Fire an event=] named "geometrychange" at [=this=].
      4. 170 |
    171 |
    6. 172 |
173 |

174 | Platform heuristics may impose additional restrictions on VK {{VirtualKeyboard/show()}} and {{VirtualKeyboard/hide()}}. e.g., on Windows the pointer type MUST be touch or pen. 175 |

176 |

177 | A few people have expressed concerns around {{VirtualKeyboard/show()}} and {{VirtualKeyboard/hide()}} methods not being promise-based, but we believe it is a better design for web developers to use {{VirtualKeyboard/ongeometrychange}} event since it is fired when VK visibility changes, making the return values unnecessary. 178 |

179 |
180 |
181 |

{{VirtualKeyboard/overlaysContent}}

182 |
183 |
184 |

185 | The {{VirtualKeyboard/overlaysContent}} getter steps are to return [=this=]'s {{VirtualKeyboard/overlaysContent}}. 186 |

187 |

188 | The {{VirtualKeyboard/overlaysContent}} setter steps are to set [=this=]'s {{VirtualKeyboard/overlaysContent}} to the given value. 189 |

190 |
191 |
192 |

{{VirtualKeyboard/boundingRect}}

193 |
194 |
195 |

196 | The attribute reports the intersection of the VK with the [=document=]'s viewport in client coordinates. Call {{VirtualKeyboard/set the virtual keyboard bounding rect}}. 197 |

198 |

set the virtual keyboard bounding rect

199 | To set the virtual keyboard bounding rect, with |osk| (a DOMRect representing the on-screen keyboard rectangle), and |lv| (a DOMRect representing the [=document=]'s viewport rectangle) as inputs, run the following steps: 200 |
    201 |
  1. 202 | Let |osk| be the on-screen keyboard rectangle that is the result of running the algorithm in {{VirtualKeyboard/show()}} or {{VirtualKeyboard/hide()}} on [=this=]. 203 |
    2. 204 |
  2. 205 | Let |lv| be the [=document=]'s viewport that is the result of running the algorithm in {{VirtualKeyboard/show()}} or {{VirtualKeyboard/hide()}} on [=this=]. 206 |
    3. 207 |
  3. 208 | Map |osk| to the coordinate space of |lv|. 209 |
    4. 210 |
  4. 211 | Let |bounds| be a {{DOMRect}} object. 212 |
    5. 213 |
  5. 214 | Update |bounds| by intersecting |lv| with the |osk|. 215 |
    6. 216 |
  6. 217 | Map |bounds| to the coordinate space of |lv|. 218 |
    7. 219 |
  7. 220 | Return |bounds|. 221 |
    8. 222 |
223 |

224 |

225 |

226 | The {{VirtualKeyboard/boundingRect}} getter steps are to return [=this=]'s {{VirtualKeyboard/boundingRect}}. 227 |

228 |
229 |
230 | ongeometrychange 231 |
232 |
233 |

234 | The event is dispatched when the intersection of the VK and the [=document=]'s viewport changes, e.g., in response to the VK being shown or hidden or the browser window being repositioned. 235 |

236 |
237 |
238 |
239 |
240 |

Extensions to the ElementContentEditable mixin

241 | 
242 |             partial interface mixin ElementContentEditable {
243 |                 [CEReactions] attribute DOMString virtualKeyboardPolicy;
244 |            };
245 |
246 |

247 | Add handling of input and textarea. 248 |

249 |

The virtualKeyboardPolicy is an enumerated attribute whose keywords are the empty string, auto, and manual. The IDL attribute must reflect the respective content attributes of the same name. 250 | When specified on an element that is a contenteditable host, auto causes the corresponding editable element to automatically show the VK when it is focused or tapped & manual 251 | decouples focus and tap on the editable element from changes in the VK’s current state - the VK remains as it was. 252 |
253 | The change in setting of any {{ElementContentEditable/virtualKeyboardPolicy}} attribute value, negates currently defined behavior, unless it is a change from auto to empty string or vice versa. 254 |

255 | Specify timing relative to events like focus. 256 |

257 | 268 |

269 | 270 |
271 |
272 |

273 | Virtual Keyboard Visibility Change CSS environment variables. 274 |

275 |

276 | The {{VirtualKeyboard}} API proposes six new CSS environment variables that the web developers can utilize to calculate the virtual keyboard's size and adjust layout in a declarative way. 277 |

278 |

279 | These CSS env should be added to the CSS env variable spec. 280 |

281 |
282 |

Keyboard inset variables

283 | 284 | 285 | 288 | 291 | 294 | 297 | 300 | 303 |
Name 286 | Value 287 |
keyboard-inset-top 289 | length 290 |
keyboard-inset-right 292 | length 293 |
keyboard-inset-bottom 295 | length 296 |
keyboard-inset-left 298 | length 299 |
keyboard-inset-width 301 | length 302 |
keyboard-inset-height 304 | length 305 |
306 | 307 |

The keyboard insets are six environment variables that define a rectangle by 308 | its top, right, bottom, and left insets from the edge of the viewport. Default value of the keyboard insets are "0px" if a fallback value is not provided else it gets updated when {{VirtualKeyboard/boundingRect}} value changes. 309 | The width & height insets are calculated from the remaining insets for developer ergonomics. 310 |

311 |
312 |
313 |
314 |

Examples

315 |
316 |

Example with usage of VK control APIs.

317 | 360 |
361 |
362 |

Examples with usage of overlaysContent and geometry event as a result of VK showing.

363 | 399 |

400 | The figure and markup below are a representation of a canvas-based spreadsheet that repositions the active cell when the VK is shown. The `geometrychange` event triggers a paint request for the canvas. The painting code can then use the `boundingRect` property to render the active cell in the proper location. 401 | Figure showing virtual keyboard on single-touch screen device 402 |

403 | 446 | The figure below represents a map application that presents a map on one window segment and search results on another. 447 | Using the proposal for Window Segments and media queries, the search box shown will increase its bottom margin to remain visible whenever the virtual keyboard appears on the left side of the foldable device. 448 | Figure showing virtual keyboard on single-touch screen device 449 | 506 |
507 |
508 |
509 |

Privacy and Security Considerations

510 | Because VirtualKeyboard APIs may reveal some aspects about layout of user's VK, user agents must ensure that no extra information is exposed 511 | to the script that it already has through existing APIs. 512 | 513 | To mitigate potential security and privacy risks, browsers are expected to follow best practices described below. 514 |
515 | 516 |

{{VirtualKeyboard/hide()}} and {{VirtualKeyboard/show()}} methods

517 |

518 |

526 |

527 |
528 |
529 |

{{VirtualKeyboard/boundingRect}}, {{VirtualKeyboard/overlaysContent}} and {{VirtualKeyboard/ongeometrychange}} attributes

530 | User Agent MUST only allow {{VirtualKeyboard/overlaysContent}} to be set in a secure, [= top-level browsing context=]. 531 |
532 |
533 |
534 | 535 |
536 |
537 |

Contributors

538 |

539 | Add contributors 540 |

541 |
542 |
543 | 544 | 545 | 546 | --------------------------------------------------------------------------------