Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update API's for adjusting Android longpress delay #1500

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions developer/engine/android/18.0/KMManager/getLongpressDelay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: KMManager.getLongpressDelay()
---

## Summary

The `getLongpressDelay()` method returns from stored preference the number of milliseconds to trigger a longpress gesture.
Defaults to 500 milliseconds.

## Syntax

```java
int KMManager.getLongpressDelay()
```

### Returns
Returns the number of milliseconds to trigger a longpress gesture. This preference is stored at the app level and is applied to all Keyman keyboards.

## Description
Use this method to get details about how long to press a key for longpress keys to appear.

## Examples

### Example: Using `getLongpressDelay()`

The following code illustrates the use of `getLongpressDelay()`:
```java
int currentDelayTimeMS = KMManager.getLongpressDelay();

currentDelayTimeMS += 250; // ms
```

## History
Keyman Engine for Android 18.0: New function.

## See also
* [sendOptionsToKeyboard](sendOptionsToKeyboard)
* [setLongpressDelay](setLongpressDelay)
9 changes: 9 additions & 0 deletions developer/engine/android/18.0/KMManager/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,9 @@ The KMManager is the core class which provides most of the methods and constants
[`getLanguagePredictionPreferenceKey()`](getLanguagePredictionPreferenceKey)
: returns a String to use as a shared preference key to store whether the LMLayer should enable suggestions for a given language.

[`getLongpressDelay()`](getLongpressDelay)
: returns from stored preference the number of milliseconds to trigger a longpress gesture

[`getMaySendCrashReport()`](getMaySendCrashReport)
: returns whether Keyman Engine is allowed to send crash reports over the network to sentry.keyman.com

Expand Down Expand Up @@ -209,6 +212,9 @@ The KMManager is the core class which provides most of the methods and constants
[`removeKeyboardEventListener()`](removeKeyboardEventListener)
: removes the specified listener from the list of keyboard event listeners

[`sendOptionsToKeyboard()`](sendOptionsToKeyboard)
: sends options like longpress delay to the KeymanWeb keyboard

[`setCanAddNewKeyboard()`](setCanAddNewKeyboard)
: sets whether adding a new keyboard is allowed

Expand Down Expand Up @@ -242,6 +248,9 @@ The KMManager is the core class which provides most of the methods and constants
~~`setKeymanLicense()`~~ `(Deprecated)`
: sets the developer license/key pair to unlock Keyman Engine

[`setLongpressDelay()`](setLongpressDelay)
: stores the longpress delay in milliseconds as a preference.

[`setMaySendCrashReport()`](setMaySendCrashReport)
: sets whether Keyman Engine can send crash reports over the network to sentry.keyman.com

Expand Down
41 changes: 41 additions & 0 deletions developer/engine/android/18.0/KMManager/sendOptionsToKeyboard.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
title: KMManager.sendOptionsToKeyboard()
---

## Summary

The `sendOptionsToKeyboard()` method sends options like longpress delay to the KeymanWeb keyboard.

## Syntax

```java
KMManager.sendOptionsToKeyboard()
```

## Description
Use this method to update options in the KeymanWeb keyboard.
* Number of milliseconds to trigger a longpress gesture

This method requires a keyboard to be loaded for the values to take effect.
Comment on lines +16 to +19
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why would this be needed? Why can't KMManager handle this itself internally?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There may be other keyboard preferences that change/get stored.

This API propagates the value to KeymanWeb to use.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

KMManager already knows the value though -- so why can't it be responsible for telling KMW? It seems like exposing internals to have this API at all (and I know I approved the previous PR, just thinking about this a bit more now, sorry!). I think we should review that because it's definitely less than ideal to push this responsibility of managing internal preference updates onto the app.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was waiting on merging this PR to see if we needed a Monday design discussion about the interactions between: Keyman Engine API + KeymanWeb + UI

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you write up a spec document on the various bits and pieces -- where we are at today?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

k, I'll send you a Slack when I've jotted something into the Drive for you to squiz


## Examples

### Example: Using `sendOptionsToKeyboard()`

The following code illustrates the use of `sendOptionsToKeyboard()`:
```java
int currentDelayTimeMS = 250;

// Store currentDelayTimeMS
KMManager.setLongpressDelay(currentDelayTimeMS);

// Apply the keyboard options
KMManager.sendOptionsToKeyboard();
```

## History
Keyman Engine for Android 18.0: New function.

## See also
* [getLongpressDelay](getLongpressDelay)
* [setLongpressDelay](setLongpressDelay)
42 changes: 42 additions & 0 deletions developer/engine/android/18.0/KMManager/setLongpressDelay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: KMManager.setLongpressDelay()
---

## Summary

The `setLongpressDelay()` method sets the number of milliseconds to trigger a longpress gesture as a stored preference.

## Syntax

```java
KMManager.setLongpressDelay(int longpressDelay)
```
### Parameter
`longpressDelay`
: The number of milliseconds

## Description
Use this method to store how many milliseconds to trigger a longpress as a preference.
This preference is stored at the Keyman app level, and is applied to all Keyman keyboards.

## Examples

### Example: Using `setLongpressDelay()`

The following code illustrates the use of `setLongpressDelay()`:
```java
int currentDelayTimeMS = 250;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a min/max range?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Keyman for Android menu has a range of 300ms to 1500 ms. But the API doesn't have any gating on what keyboard developers may use.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was hoping this information would be added to the docs. Also, we should really be putting limits into public API functions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, we can document a range and add gating to KMManager.

300-1500 ms? Or will somebody eventually want a 2000ms delay?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should match what Keyman app supports


// Store currentDelayTimeMS
KMManager.setLongpressDelay(currentDelayTimeMS);

// Apply the keyboard options
KMManager.sendOptionsToKeyboard();
```

## History
Keyman Engine for Android 18.0: New function.

## See also
* [getLongpressDelay](getLongpressDelay)
* [sendOptionsToKeyboard](sendOptionsToKeyboard)