From 43977b103d0db2be3637cc123086e8f567f83676 Mon Sep 17 00:00:00 2001 From: "Joshua A. Horton" Date: Fri, 22 Mar 2019 08:46:52 +0700 Subject: [PATCH] Adds PR docs as JS docs for BannerManager. --- web/source/osk/bannerManager.ts | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/web/source/osk/bannerManager.ts b/web/source/osk/bannerManager.ts index 3857408b48..f1af802820 100644 --- a/web/source/osk/bannerManager.ts +++ b/web/source/osk/bannerManager.ts @@ -9,6 +9,30 @@ namespace com.keyman.osk { export type BannerType = "blank" | "image" | "suggestion"; + /** + * The `BannerManager` module is designed to serve as a manager for the different `Banner` types. + * To facilitate this, it will provide a root element property that serves as a container for any active `Banner`, + * helping KMW to avoid needless DOM element shuffling. + * + * Goals for the `BannerManager`: + * + * * It will be exposed as `keyman.osk.banner` and will provide the following API: + * * `getOptions`, `setOptions` - refer to the `BannerOptions` class for details. + * * This provides a persistent point that the web page designers and our model apps can utilize and can communicate with. + * * These API functions are designed for live use and will allow _hot-swapping_ the `Banner` instance; they're not initialization-only. + * * Disabling the `Banner` (even for suggestions) outright with `enablePredictions == false` will auto-unload any loaded predictive model + * from `ModelManager` and setting it to `true` will revert this. + * * This should help to avoid wasting computational resources. + * * It will listen to ModelManager events and automatically swap Banner instances as appropriate: + * * The option `persistentBanner == true` is designed to replicate current iOS system keyboard behavior. + * * When true, an `ImageBanner` will be displayed. + * * If false, it will be replaced with a `BlankBanner` of zero height, corresponding to our current default lack of banner. + * * It will not automatically set `persistentBanner == true`; this must be set by the iOS app, and only under the following conditions: + * * `keyman.isEmbedded == true` + * * `device.OS == 'ios'` + * * Keyman is being used as the system keyboard within an app that needs to reserve this space (i.e: Keyman for iOS), + * rather than as its standalone app. + */ export class BannerManager { private _options: BannerOptions = {}; private bannerContainer: HTMLDivElement;