docs(android): add engine API documentation updates and deprecations

android/docs/engine/KMManager/defaultSuggestionModeForType.md

@@ -0,0 +1,69 @@
+---
+title: KMManager.defaultSuggestionModeForType()
+---
+
+## Summary
+The **defaultSuggestionModeForType()** method determines the appropriate suggestion mode to use when providing
+input to different types of input-receiving `Editable` objects.
+
+## Syntax
+```javascript
+KMManager.defaultSuggestionModeForType(InputType inputType)
+```
+
+### Parameters
+
+`inputType`
+: The current value of the active `Editable`'s `.getInputType()` property.
+
+In addition, the method will retrieve the user's preference for the most-recently activated
+lexical model and adjust the returned `SuggestionType` accordingly.
+
+### Returns
+`SuggestionType`, which may hold one of the following values:
+
+- `SuggestionType.SUGGESTIONS_DISABLED` - disables predictive-text entirely
+    * This is automatically chosen for editables that should not permit
+      predictions, such as password editables and those not intended for plain
+      text.
+    * Selected if the `inputType` value contains one or more of the following
+      flags:
+        * TYPE_TEXT_VARIATION_PASSWORD
+        * TYPE_TEXT_VARIATION_WEB_PASSWORD
+        * TYPE_CLASS_NUMBER
+        * TYPE_CLASS_PHONE
+- `SuggestionType.PREDICTIONS_ONLY` - enables text predictions, but not text
+  correction
+- `SuggestionType.PREDICTIONS_WITH_CORRECTIONS` - enables text predictions and
+  corrections, but does not enable autocorrect.
+    * Selected for editables likely to represent text predictive text cannot
+    adequately predict, such as address fields, URL fields, and names.
+- `SuggestionType.PREDICTIONS_WITH_AUTO_CORRECT`- enables all predictive-text
+  features:  predictions, corrections, and auto-correct.
+    * Enabled when one of the following flags is detected:
+        * TYPE_TEXT_VARIATION_FILTER
+        * TYPE_TEXT_VARIATION_NORMAL
+        * TYPE_TEXT_VARIATION_SHORT_MESSAGE
+        * TYPE_TEXT_VARIATION_LONG_MESSAGE
+        * TYPE_TEXT_VARIATION_EMAIL_SUBJECT
+        * TYPE_TEXT_VARIATION_WEB_EDIT_TEXT
+
+## Description
+Use this method when you need to decide what predictive-text mode should be active.
+
+## Examples
+
+### Example: Using `defaultSuggestionModeForType()`
+The following script illustrates the use of `defaultSuggestionModeForType()`:
+
+```java
+    int inputType = textView.getInputType();
+    SuggestionType suggestionType = KMManager.defaultSuggestionModeForType(inputType);
+    KMManager.setSuggestionType(suggestionType);
+```
+
+## History
+Added syntax in Keyman Engine for Android 19.0.
+
+## See also
+* [setSuggestionType()](setSuggestionType)

android/docs/engine/KMManager/getPredictionsSuspended.md

@@ -1,7 +1,6 @@
 ---
-title: KMManager.getPredictionsSuspended()
+title: KMManager.getPredictionsSuspended() (Deprecated)
 ---
-
 ## Summary
 The **getPredictionsSuspended()** method returns a flag that determines whether predictions are temporarily disabled because the currently selected text field is a hidden password text field or a numeric text field.
 
@@ -24,6 +23,7 @@ Use this method to check if predictions are temporarily disabled because of the
 
 ## History
 Added syntax in Keyman Engine for Android 18.0.
+Deprecated syntax in Keyman Engine for Android 19.0 in favor of [`defaultSuggestionModeForType`](defaultSuggestionModeForType).
 
 ## See also
 * [setPredictionsSuspended](setPredictionsSuspended)

android/docs/engine/KMManager/index.md

@@ -161,8 +161,8 @@ The KMManager is the core class which provides most of the methods and constants
 [`getOrientation()`](getOrientation)
 : returns the device's current orientation (Portrait vs Landscape)
 
-[`getPredictionsSuspended()`](getPredictionsSuspended)
-: returns whether predictions are temporarily disabled because the currently selected text field is a hidden password text field or a numeric text field. 
+~~`getPredictionsSuspended()`~~ `(Deprecated)`
+: returns whether predictions are temporarily disabled because the currently selected text field is a hidden password text field or a numeric text field.
 
 [`getSpacebarText()`](getSpacebarText)
 : returns the current text display pattern for the spacebar
@@ -269,8 +269,8 @@ The KMManager is the core class which provides most of the methods and constants
 [`setMaySendCrashReport()`](setMaySendCrashReport)
 : sets whether Keyman Engine can send crash reports over the network to Sentry
 
-[`setPredictionsSuspended()`](setPredictionsSuspended)
-: sets whether predictions are temporarily disabled because the currently selected text field is a hidden password text field or a numeric text field. 
+~~`setPredictionsSuspended()`~~ `(Deprecated)`
+: sets whether predictions are temporarily disabled because the currently selected text field is a hidden password text field or a numeric text field.
 
 [`setShouldAllowSetKeyboard()`](setShouldAllowSetKeyboard)
 : sets whether Keyman Engine allows setting a keyboard other than the default keyboard

android/docs/engine/KMManager/setPredictionsSuspended.md

@@ -1,5 +1,5 @@
 ---
-title: KMManager.setPredictionsSuspended()
+title: KMManager.setPredictionsSuspended() (Deprecated)
 ---
 
 ## Summary
@@ -9,7 +9,6 @@ The **setPredictionsSuspended()** method sets a flag to temporarily disable pred
 ```java
 KMManager.setPredictionsSuspended(int inputType, KeyboardType keyboardType)
 ```
-
 ### Parameters
 
 [`inputType`](https://developer.android.com/reference/android/text/InputType)
@@ -31,6 +30,7 @@ Use this method to temporarily disable predictions because of the currently sele
 
 ## History
 Added syntax in Keyman Engine for Android 18.0.
+Deprecated syntax in Keyman Engine for Android 19.0 in favor of [`setSuggestionType`](setSuggestionType).
 
 ## See also
 * [getPredictionsSuspended](getPredictionsSuspended)

android/docs/engine/KMManager/setSuggestionType.md

@@ -0,0 +1,49 @@
+---
+title: KMManager.setSuggestionType()
+---
+
+## Summary
+The **setSuggestionType()** method configures which predictive-text features
+will be presented to the user - which types of suggestions will be offered.
+
+## Syntax
+```java
+KMManager.setSuggestionType(KeyboardType keyboardType, SuggestionType suggestionType)
+```
+
+### Parameters
+
+`keyboardType`
+:   The keyboard type. `KEYBOARD_TYPE_INAPP` or
+    `KEYBOARD_TYPE_SYSTEM`.
+
+`suggestionType`
+:   The type of suggestions to offer.  One of the following:
+    `SuggestionType.SUGGESTIONS_DISABLED`
+    `SuggestionType.PREDICTIONS_ONLY`
+    `SuggestionType.PREDICTIONS_WITH_CORRECTIONS`
+    `SuggestionType.PREDICTIONS_WITH_AUTO_CORRECT`
+
+## Description
+Use this method to configure what types of suggestions may be offered to the
+user.  It cannot force predictions to be available if no lexical model is
+present, but it can be used to restrict types of suggestions from being offered
+in inappropriate contexts.
+
+`suggestionType` may use the result of `defaultSuggestionModeForType` for the
+active `Editable`'s input type, which will be sufficient for most cases.
+
+### Example: Using `setSuggestionType()`
+The following script illustrates the use of `setSuggestionType()`:
+
+```java
+    int inputType = textView.getInputType();
+    SuggestionType suggestionType = KMManager.defaultSuggestionModeForType(inputType);
+    KMManager.setSuggestionType(suggestionType);
+```
+
+## History
+Added syntax in Keyman Engine for Android 19.0.
+
+## See also
+* [defaultSuggestionModeForType](defaultSuggestionModeForType)