init function
Summary
Initializes KeymanWeb and configures KeymanWeb Options.
Note that this is an asynchronous operation.
keyman.init()
is automatically called after the page loads, with default
options, if it has not already been called by scripts on the page. It is safe to
call keyman.init()
once more in this situation, in order to set additional
options.
The keyman.initialized
property may be checked to determine the
current initialization state of Keyman Engine for Web.
You should not call functions other than keyman.init()
until Keyman
initialization is complete. As keyman.init()
returns a Promise, the Promise
fulfilment callback is the appropriate place to perform post-init steps.
Syntax
keyman.init(initOptions);
Parameters
initOptions
Type:
Object
.See the Description section below for the necessary object specification.
Return Value
Promise
: A JavaScript Promise
fulfilled upon full initialization.
Initialization Options
The initOptions
object may contain the following members:
ui
string|object
optionalThe user interface to be used on desktop devices. Default value:
'float'
. Please see below for the specification of this parameter if using an object value.root
string
optionalThe folder KeymanWeb should consider root. Default value:
undefined
, which setsroot
to the base folder where keymanweb.js is located.resources
string
optionalThe image folder URL for UI resources. Default value:
[root]/resources
.keyboards
string
optionalThe folder containing local keyboard resources if utilized. Default value:
[root]/keyboards
.fonts
string
optionalFolder containing any embedded fonts required for keyboards or the OSK. Default value:
[root]
.attachType
string
optionalMust be
undefined
,'auto'
, or'manual'
. Specifies the default behavior for attaching KeymanWeb to any input elements on the webpage.- If
undefined
, KeymanWeb will default to 'manual' for mobile devices and 'auto' for other devices. - If
'auto'
, KeymanWeb will automatically attach to every non-disabled control, even those added after page initialization. - If
'manual'
, KeymanWeb must be instructed to attached manually to each control it should handle input for.
- If
setActiveOnRegister
boolean
optionalSpecifies whether KeymanWeb will set the newly registered keyboard as active. Default value
true
.- If
true
, KeymanWeb will automatically activate a keyboard when registered. - If
false
, KeymanWeb will not activate a keyboard when registered.
Note: Changed from
string
type toboolean
type in KeymanWeb 17.0 (#8458).- If
useAlerts
boolean
optionalSpecifies whether KeymanWeb's alert feedback should be enabled. Default value
true
.- If
true
, KeymanWeb will display its default alerts. - If
false
, KeymanWeb will not display its default alerts. Choose this if you wish to disable them or would prefer to customize your site's error feedback. - In either case, any calls your page makes to
keyman.util.alert()
will not be blocked. This only affects calls built into KeymanWeb itself.
- If
spacebarText
com.keyman.SpacebarText
optionalIf present, must be one of the following four constants:
KEYBOARD /*'keyboard'*/
- show the keyboard name in the spacebarLANGUAGE /*'language'*/
- show the language name in the spacebarLANGUAGE_KEYBOARD /*'languageKeyboard'*/
- show both language and keyboard name in the spacebar, separated by hyphenBLANK /*'blank'*/
- keep the spacebar blank
Note that this may be overridden on a per-keyboard basis with the registration property
displayName
.Default value:
LANGUAGE_KEYBOARD
.
If setting initOptions.ui
with an object value, it should be specified as
follows:
name
string
- The name of the ui to utilize for non-mobile devices.
right
boolean
optional- A Float-UI-only option. Sets right-alignment of the UI. Defaults to false.