Skip to content

Keyman 13.0 to 14.0 Migration

Jump to bottom
Marc Durdin edited this page Feb 3, 2021 · 37 revisions

How to use this document

This document is a work-in-progress capturing changes between 13.0 and 14.0 of Keyman. It will be transferred to help.keyman.com on the release of version 14.0.

Don't worry too much about getting the wording totally consistent. The aim here is to capture the knowledge of changes while they are fresh. We will review and tidy up the document before release.

If a change may introduce issues for other developers, mark it with BREAKING.

This does not necessarily need to correspond to pull request IDs as in many cases there may be many PRs for one issue. If you can do this, then good, but don't stress over it.

You can make good use of HISTORY.md for populating this initially.

Versioning

Keyman 14.0 moves to a synchronized build number across all platforms. This means that for some critical fixes there may be a release that impacts only one platform, but all platforms will have a version bump. We considered the advantages of having consistent versioning outweighed this one situation. The plan going forward is that we will bundle sets of bug fixes across multiple platforms for stable releases, to avoid this situation.

We anticipate renaming the Keyman for Windows and Keyman Developer installers to exclude the final .0, e.g. keyman-14.0.99.exe instead of keymandesktop-14.0.99.0.exe. See Windows section for more on the name of Keyman Desktop.

Significant and Breaking Changes for Developers

Anything that other developers should be aware of should be documented here. This set of people includes:

  • Keyboard developers
  • Developers of websites that use KeymanWeb
  • Developers of apps that embed or interface with Keyman Engine (KAB, FieldWorks, etc)
  • Tool developers, e.g. .kmn language changes may impact other tools

Include major new functionality that they may need to cater to, and anything that changes the way someone may use Keyman from a development perspective. Changes to functionality that impact end users may be documented here, but that is not the core purpose of this document.

All Platforms

  • We have moved to using Sentry for bug reporting.

Windows

  • BREAKING: Keyman Desktop will be known as Keyman for Windows from version 14.0 and later. Some filenames may change as a result. No APIs will change.

  • BREAKING: Keyman for Windows version numbers will be presented with only three components rather than four, matching other platforms. Executable files will continue to use Windows standard resource four-component versions.

  • Keyman for Windows now uses Chromium to host all web-based UI (e.g. Keyman Configuration).

    • Help, Hint dialogs were moved from keyman.exe to kmshell.exe to facilitate this. This means a small change in keyman.exe's shutdown sequence.
    • Hint banners in the On Screen Keyboard were removed. This is a minor loss in functionality.
    • IE-specific weirdisms in the UI .xsl files may need to be resolved for Keyman Engine users.
    • BREAKING: Keyman Engine no longer supports the keyboard usage page (usage.htm). This was a security and architectural decision which we were forced to take when we integrated with Chromium -- keyman.exe necessarily operates in a higher security level (uiAccess=true in the manifest) in order to interop with other process keyboard input. This means that hosting arbitrary web pages (usage.htm) is dangerous and Chromium does not run in this context without modification. However, only one keyboard published in the repository included a usage.htm: sil_euro_latin 'European Latin' (and its variants). This is a loss in functionality for which we are considering ways to address in the future, but it is currently unlikely that we can reintroduce web-based functionality like this.
    • On a more positive note, Keyman Engine now has no dependencies on Chromium or IE. All web-based UI interactions are in kmshell.exe.

  • User interface localization is now managed through Crowdin and updates and new translations are bundled with Keyman for Windows. The old tavultesoft.com-based online localization tool has been retired. Manual editing of the localization files may lead to inconsistencies with the Crowdin sources.

  • BREAKING: The bootstrap installer has been significantly rewritten. It now supports a streamlined download and install experience, with a small initial download that then downloads both the .msi and relevant keyboards. The website will provide this file with a name that allows for a 'bundled' download experience, such as keyman-setup.khmer_angkor.km.exe. (TBD: new command line and file naming experience). Furthermore, the bootstrap installer will locate .kmp files in the same folder as it, and offer them for installation at the same time. Finally, the bootstrap installer will allow the user to pick a specific language to associate with a keyboard at first install; the initial value will also be propagated from the website with the 'bundled' experience noted above. See https://help.keyman-staging.com/kb/35 for more details.

  • Keyman Engine for Windows now supports IKeymanKeyboardsInstalled2, IKeymanKeyboardFile2, IKeymanPackagesInstalled2 and IKeymanPackageFile2, all of which add a single new method Install2. This new method enables installation of a Keyman keyboard without a corresponding install of the input method for the default language, allowing for a single user step install of keyboard + specific language.

Linux

  • Known bug: Might not always work with Wayland. Workaround: use X11.

macOS

iOS

Requires linking with Sentry.framework.

  • The On Screen Keyboard for Keyman for iPhone and iPad now loads more quickly, better handles large fonts for key text, and has received numerous other bugfixes.
  • The old LanguageResource protocol has been reworked, with AnyLanguageResource taking its place.
    • LanguageResource still exists, but now uses an associatedtype, which restricts its use in return types and some variable declarations.
    • AnyLanguageResource is equivalent for cases that don't rely upon the specific resource type, perfectly matching the original version of the protocol.
  • New API: ResourceDownloadManager.downloadPackage(withKey:from:withNotifications:completionBlock)
    • This function downloads a package from a known location and automatically parses it (as with KeymanPackage.parse), preparing it for installation or returning errors that arise during such attempts.
    • If the completionBlock parameter's closure declares its first parameter as a specific type of package, downloadPackage will perform error-handling should the package type not match.
    • This pairs well with...
  • New API: ResourceFileManager.install(resourceWithID:from:)
    • Given a parsed/prepared package and the ID of a resource within it it, this function installs that resource within KeymanEngine.
    • It will also examine the contents of the package for potential updates and perform them automatically.
  • The KeymanPackage class is now much more fully fleshed-out, providing many package-oriented properties and methods.
  • The keyboard and lexical model download notifications (such as KeyboardDownloadCompleted have been removed in favor of package-oriented variants (such as PackageDownloadCompleted).
    • They generally return a KeymanPackage.Key identifying the triggering package.
    • As the Completed version represents a successful download, it will instead provide the downloaded KeymanPackage instance.
    • Technically BREAKING, though with low likelihood of actual use. (Did not affect FV apps)
  • User installation of new keyboards should utilize the new KeyboardSearchViewController.

Deprecated APIs (still functional, but designated for future removal)

  • KeymanPackage.parse no longer needs a completion block
    • The new version has been added that is explicitly synchronous and directly returns the old completion block's parameter.
    • The old version is still in-place and functions as before - synchronously.
  • Similarly, multiple ResourceFileManager methods no longer need completion blocks, also directly returning the values they provided.
    • Exception: promptPackageInstall, which is asynchronous due to user interaction.
    • Affects two prepareKMPInstall versions and finalizePackageInstall.
  • Manager:
    • addKeyboard and addLexicalModel deprecated in favor of the new ResourceFileManager.install variants
    • preloadFiles also deprecated in favor of KMP-based installation, which should also use the method listed above.
  • APIKeyboardRepository and related classes/protocols are now deprecated.
  • BREAKING APILexicalModelRepository and related classes/protocols are now outright obsoleted.
    • pending #3402
  • BREAKING LanguageViewController and LanguageDetailViewController, both views previously used by users to install keyboards, are now outright obsoleted.
    • pending #3402

Note that applications using the KeymanEngine framework should consider use of the Migrations.migrate(storage:) method, as the file organization scheme and file lookup patterns used internally by KeymanEngine have changed slightly.

Android

  • The On Screen Keyboard for Keyman for Android now loads more quickly, better handles large fonts for key text, and has received numerous other bugfixes.

  • Keyman now works more reliably with WeChat and Telegram on Android

  • Keyman for Android display language

    • If your device’s locale matches one of the completed translations from https://translate.keyman.com, Keyman for Android will display UI in the same locale.
    • You can also change the display language in the Keyman Settings → “Change DIsplay Language” menu

  • BREAKING: Moved from API 19 to minimum API level 21 (Lollipop / Android 5.0) with corresponding Chromium minimum release M37.

  • BREAKING: Replaced Fabric/Crashlytics with Sentry for crash reporting

    • build.gradle changes: 
      android {
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

dependencies {
  implementation 'io.sentry:sentry-android:2.0.1'
}

  • BREAKING: Additional dependencies needed for 14.0

    • androidx.preference:preferences:1.1.1. (Needed for KMEA to update display language)

  • BREAKING: Deprecated KMManager APIs

    • KMManager.showLanguageList() - KMEA no longer uses cloud keyboard catalog, so showLanguageList() no longer displays. (Embedded browser used to search for keyboards) (Updated)
    • KMManager.KMKey_CustomKeyboard - "Custom" property for keyboards no longer tracked (no change to help.keyman.com)
    • KMManager.KMKey_CustomModel - "Custom" property for lexical models no longer tracked (no change to help.keyman.com)
    • addKeyboard - Deprecate syntax using HashMap<string, string>. Replace with <Keyboard>

  • BREAKING: Changed KMManager APIs

    • [KMManager.getLatestKeyboardFileVersion()] - Syntax may change from (String packageID, String keyboardID) to (String languageID, String keyboardID)

  • Feature: Add getDefaultKeyboard() and setDefaultKeyboard() (wip)

  • Feature: Add action GLOBE_KEY_ACTION_SHOW_SYSTEM_KEYBOARDS that brings up Android input method picker (Updated)

  • Addition: Add getLanguagePredictionPreferenceKey and getLanguageCorrectionPreferenceKey but note they're intended only for KMAPro

  • Use keyboard / lexical model packages instead of standalone .js files

    • Keyboards now strictly installed from .kmp keyboard packages. 3rd party apps should include their "default" keyboard and lexical model packages at the project's assets/ level. KMManager will extract them into assets/packages/ and assets/models/ respectively. (No longer append version string to .js keyboard file and manually copy to assets/cloud/ folder)
      • build.gradle changes:
      android {
  // Don't compress kmp files so they can be copied via AssetManager
  aaptOptions {
    noCompress "kmp"
  }
}
    • KMEA no longer includes sil_euro_latin as a default installed keyboard.

Linux

Web

  • The On Screen Keyboard for KeymanWeb now loads more quickly, better handles large fonts for key text, and has received numerous other bugfixes.

  • BREAKING: Ceased support for Internet Explorer altogether.

  • BREAKING: No longer testing against legacy Edge.

  • DEPRECATED: When language-specific wordbreaking is needed, custom lexical models (dictionaries) should specify a core wordbreaker algorithm that can break all words in a string at once, rather than only the last word in a context.

    • wordbreak will still be useful when running under Keyman 12 and 13.
    • if wordbreak is specified but wordbreaker is not, it will be incompatible with version 14.0's enhanced correction features.

  • 14.0 brings significant enhancements to predictive text when models are able to provide a way to efficiently "traverse" the lexicon.

    • This is handled automatically for compiled wordlist-based models, even those compiled in previous versions of Keyman.
    • Custom models (which are currently not possible to compile within Developer) should refer to the new LexiconTraversal type specified within the @keymanapp/models-types package. Models must implement this type and the related LexicalModel.traverseFromRoot() to be compatible with these enhancements.

Developer and Keyboards

  • Lexical models may now specify the languageUsesCasing flag (and, optionally, an applyCasing function). These will allow predictive-text suggestions to detect and preserve capitalization when appropriate.

  • Added ISO9995 key ids (e.g. + [SHIFT E01] > 'ooh'). These compile down to their US VKeys so there is no change in compiled keyboards, but parsers of .kmn files may need to be aware of this.

  • BREAKING KeymanWeb, Keyman for Android, and Keyman for iOS will no longer inject a U+25CC onto key caps that contain plain diacritics (#3039).

  • KeymanWeb, Keyman for Android, and Keyman for iOS will no longer inject the base key into the popup menu on phone devices (#3718).

  • notany() and context() are now supported for KeymanWeb, iOS, Android (#3816)

  • BCP 47 tags work better in Keyman Developer (#3818, #3819)

  • BREAKING New compiler warnings and errors:

    • The keyman kmx/js compiler now validates the order of nul, if(), baselayout() and platform() statements (#4410)
    • The keyman js compiler now requires option store names to use a restricted set of characters from the following regex: [a-zA-Z0-9_] (#4408)
    • The package compiler now validates BCP 47 tag canonicality, as does the keyboard_info merger.
    • The keyman js compiler now validates that keys with "Special" style caps are marked as "Special" type keys for target versions < 14.

Known Issues

Windows

  • The delineation between Keyman Engine for Windows and Keyman for Windows is currently blurry and needs further work. It is likely that embedders of Keyman Engine will need kmshell.exe for some operations but this has not yet been assessed.
Clone this wiki locally