Onscreen keyboard : API to obtain dimensions & presence of the keyboard


There are a number of scenarios in web development on touch devices where particular content may be obscured or behave differently when there is an onscreen keyboard present. This becomes particularly prevalent in the case of web text editors such as TinyMCE, when content that is being written by a user falls behind the onscreen keyboard. The only non-browser-implemented solutions thus far can be described as hacks at best, and tend to break on Operating System or browser updates.

With coordinates and sizes of onscreen onscreen keyboard components, a developer could create functionality that adapted to their presence.

#Proposed API (rough) window.keyboard: Object attributes & functions:

  • window.keyboard.type : String The type of keyboard being used by the browser. It is proposed this returns virtual if there is an onscreen/virtual keyboard or physical if there is a hardware keyboard being used
  • window.keyboard.visible : Boolean. Returns true if there is a virtual keyboard in an ‘up’ state (i.e. the keyboard can be seen, and is focused on an element). Returns false if the keyboard cannot be seen, or null if a physical keyboard is attached
  • window.keyboard.getDimensions : function. When called, returns an array of Rect objects (similar to the HTML canvas implementation), where top and left are the coordinates of the keyboard fragment relative to the browser window
  • If no keyboard is visible, the coordinates of the last positions of the onscreen keyboard when it was shown are returned
  • If a hardware keyboard is connected, an empty array ([]) is returned
  • This function would cater for the use-case where there is an onscreen keyboard that has been split

window DOM events:

  • keyboardVisibilityChanged - Fired when the keyboard is shown or hidden. The event should contain reference to the keybard visibility variable (window.keyboard.visible)
  • keyboardDimensionsChanged- Fired when the keyboard’s dimensions change- this may occur when a user switches keyboard types to a 3rd party keyboard, or when they split the keyboard into several segments).
  • keyboardTypeChange - Fired when a hardware keyboard is connected or disconnected. The event should contain reference to the keyboard type (window.keyboard.type)

##About us We’re Ephox, developers of Textbox.io, and TinyMCE - The world’s most popular WYSIWYG HTML editor component.

I can’t comment on iOS, but on Android the API has a limitation where even the native applications (which includes browsers) have to do a “best effort hack” by taking a wild guess based on the window size.

I think adding a name as general as keyboard to window would be bad. It seems like this would be more appropriate on navigator.

Sorry if I’m missing something, but isn’t this precisely what the IME API is supposed to address?

AFAICT IME is about the composer UIs, not the basic on-screen keyboard.

But should we distinguish the two? In native UI toolkits various parts can collaborate to not overlap. If your screen gets cluttered with on screen keyboards, composition UIs, spellchecking, etc. it would be nice if you could position your own components accordingly.

We’re exploring these scenarios on the chromium input team, but its more complex than this proposal allows. Often if an app wants to know where the keyboard is, it also wants things to stick just above it while its animating in/out. To make that work reliably, you can’t just have an API that gives the current position. We’ve talked about exposing an animation curve, but that’s not implementable on all platforms. I think something like IE’s “position: device-fixed” is probably the best tradeoff.

Separately, being able to tell if there is a physical or virtual keyboard (maybe via a media query) is definitely goodness.

As I see it, this problem not only holds true for on-screen keyboards. There are other system-wide flyouts or dropdowns in Android and iOS too. So finding a solution that only targets on-screen keyboards feels short-sighted to me.

Maybe the API in discussion could be more general and return the left-over visible view-port inside a navigator, subtracting things from the screen-size like status bars too…

1 Like