diff --git a/apps/kbmatry/ChangeLog b/apps/kbmatry/ChangeLog new file mode 100644 index 000000000..98d0187ab --- /dev/null +++ b/apps/kbmatry/ChangeLog @@ -0,0 +1,7 @@ +1.00: New keyboard +1.01: Change swipe interface to taps, speed up responses (efficiency tweaks). +1.02: Generalize drawing and letter scaling. Allow custom and auto-generated character sets. Improve documentation. +1.03: Attempt to improve keyboard load time. +1.04: Make code asynchronous and improve load time. +1.05: Fix layout issue and rename library +1.06: Touch up readme, prep for IPO, add screenshots \ No newline at end of file diff --git a/apps/kbmatry/README.md b/apps/kbmatry/README.md new file mode 100644 index 000000000..73767828d --- /dev/null +++ b/apps/kbmatry/README.md @@ -0,0 +1,119 @@ +# Matryoshka Keyboard + +![icon](icon.png) + +![screenshot](screenshot.png) ![screenshot](screenshot6.png) + +![screenshot](screenshot5.png) ![screenshot](screenshot2.png) +![screenshot](screenshot3.png) ![screenshot](screenshot4.png) + +Nested key input utility. + +## How to type + +Press your finger down on the letter group that contains the character you would like to type, then tap the letter you +want to enter. Once you are touching the letter you want, release your +finger. + +![help](help.png) + +Press "shft" or "caps" to access alternative characters, including upper case letters, punctuation, and special +characters. +Pressing "shft" also reveals a cancel button if you would like to terminate input without saving. + +Press "ok" to finish typing and send your text to whatever app called this keyboard. + +Press "del" to delete the leftmost character. + +## Themes and Colors + +This keyboard will attempt to use whatever theme or colorscheme is being used by your Bangle device. + +## How to use in a program + +This was developed to match the interface implemented for kbtouch, kbswipe, etc. + +In your app's metadata, add: + +```json + "dependencies": {"textinput": "type"} +``` + +From inside your app, call: + +```js +const textInput = require("textinput"); + +textInput.input({text: ""}) + .then(result => { + console.log("The user entered: ", result); + }); +``` + +Alternatively, if you want to improve the load time of the keyboard, you can pre-generate the data the keyboard needs +to function and render like so: + +```js +const textInput = require("textinput"); + +const defaultKeyboard = textInput.generateKeyboard(textInput.defaultCharSet); +const defaultShiftKeyboard = textInput.generateKeyboard(textInput.defaultCharSetShift); +// ... +textInput.input({text: "", keyboardMain: defaultKeyboard, keyboardShift: defaultShiftKeyboard}) + .then(result => { + console.log("The user entered: ", result); + // And it was faster! + }); +``` + +This isn't required, but if you are using a large character set, and the user is interacting with the keyboard a lot, +it can really smooth the experience. + +The default keyboard has a full set of alphanumeric characters as well as special characters and buttons in a +pre-defined layout. If your application needs something different, or you want to have a custom layout, you can do so: + +```js +const textInput = require("textinput"); + +const customKeyboard = textInput.generateKeyboard([ + ["1", "2", "3", "4"], ["5", "6", "7", "8"], ["9", "0", ".", "-"], "ok", "del", "cncl" +]); +// ... +textInput.input({text: "", keyboardMain: customKeyboard}) + .then(result => { + console.log("The user entered: ", result); + // And they could only enter numbers, periods, and dashes! + }); +``` + +This will give you a keyboard with six buttons. The first three buttons will open up a 2x2 keyboard. The second three +buttons are special keys for submitting, deleting, and cancelling respectively. + +Finally if you are like, super lazy, or have a dynamic set of keys you want to be using at any given time, you can +generate keysets from strings like so: + +```js +const textInput = require("textinput"); + +const customKeyboard = textInput.generateKeyboard(createCharSet("ABCDEFGHIJKLMNOP", ["ok", "shft", "cncl"])); +const customShiftKeyboard = textInput.generateKeyboard(createCharSet("abcdefghijklmnop", ["ok", "shft", "cncl"])); +// ... +textInput.input({text: "", keyboardMain: customKeyboard, keyboardShift: customShiftKeyboard}) + .then(result => { + console.log("The user entered: ", result); + // And the keyboard was automatically generated to include "ABCDEFGHIJKLMNOP" plus an OK button, a shift button, and a cancel button! + }); +``` + +The promise resolves when the user hits "ok" on the input or if they cancel. If the user cancels, undefined is +returned, although the user can hit "OK" with an empty string as well. If you define a custom character set and +do not include the "ok" button your user will be soft-locked by the keyboard. Fair warning! + +At some point I may add swipe-for-space and swipe-for-delete as well as swipe-for-submit and swipe-for-cancel +however I want to have a good strategy for the touch screen +[affordance](https://careerfoundry.com/en/blog/ux-design/affordances-ux-design/). + +## Secret features + +If you long press a key with characters on it, that will enable "Shift" mode. + diff --git a/apps/kbmatry/app-icon.js b/apps/kbmatry/app-icon.js new file mode 100644 index 000000000..a4b0ecc16 --- /dev/null +++ b/apps/kbmatry/app-icon.js @@ -0,0 +1 @@ +require("heatshrink").decompress(atob("mEwwcBkmSpICVz//ABARGCBIRByA/Dk+AAgUH8AECgP4kmRCwX4n+PAoXH8YEC+IRC4HguE4/+P/EfCIXwgARHn4RG+P/j4RDJwgRBGQIRIEYNxCIRECGpV/CIXAgY1P4/8v41JOgeOn4RDGo4jER5Y1FCJWQg4RDYpeSNIQAMkmTCBwRBz4IG9YRIyA8COgJHBhMgI4+QyVJAYJrC9Mkw5rHwFAkEQCImSCJvAhIRBpazFGo3HEYVJkIjGCIIUCAQu/CKGSGo4jPLIhHMNayPLYo6zBYozpH9MvdI+TfaGSv4KHCI+Qg4GDI4IABg5HGyIYENYIAB45rGyPACKIIDx/4gF/CIPx/8fCIY1F4H8CJPA8BtCa4I1DCJFxCIYXBCILXBGpXHGplwn5HPuE4NaH4n6PLyC6CgEnYpeSpICDdJYRFz4RQARQ")) \ No newline at end of file diff --git a/apps/kbmatry/help.png b/apps/kbmatry/help.png new file mode 100644 index 000000000..6eef5694b Binary files /dev/null and b/apps/kbmatry/help.png differ diff --git a/apps/kbmatry/icon.png b/apps/kbmatry/icon.png new file mode 100644 index 000000000..058df4487 Binary files /dev/null and b/apps/kbmatry/icon.png differ diff --git a/apps/kbmatry/lib.js b/apps/kbmatry/lib.js new file mode 100644 index 000000000..6c32e5a81 --- /dev/null +++ b/apps/kbmatry/lib.js @@ -0,0 +1,489 @@ +/** + * Attempt to lay out a set of characters in a logical way to optimize the number of buttons with the number + * of characters per button. Useful if you need to dynamically (or frequently) change your character set + * and don't want to create a layout for ever possible combination. + * @param text The text you want to parse into a character set. + * @param specials Any special buttons you want to add to the keyboard (must match hardcoded special string values) + * @returns {*[]} + */ +function createCharSet(text, specials) { + specials = specials || []; + const mandatoryExtraKeys = specials.length; + const preferredNumChars = [1, 2, 4, 6, 9, 12]; + const preferredNumKeys = [4, 6, 9, 12].map(num => num - mandatoryExtraKeys); + let keyIndex = 0, charIndex = 0; + let keySpace = preferredNumChars[charIndex] * preferredNumKeys[keyIndex]; + while (keySpace < text.length) { + const numKeys = preferredNumKeys[keyIndex]; + const numChars = preferredNumChars[charIndex]; + const nextNumKeys = preferredNumKeys[keyIndex]; + const nextNumChars = preferredNumChars[charIndex]; + if (numChars <= numKeys) { + charIndex++; + } else if ((text.length / nextNumChars) < nextNumKeys) { + charIndex++; + } else { + keyIndex++; + } + keySpace = preferredNumChars[charIndex] * preferredNumKeys[keyIndex]; + } + const charsPerKey = preferredNumChars[charIndex]; + let charSet = []; + for (let i = 0; i < text.length; i += charsPerKey) { + charSet.push(text.slice(i, i + charsPerKey) + .split("")); + } + charSet = charSet.concat(specials); + return charSet; +} + +/** + * Given the width, height, padding (between chars) and number of characters that need to fit horizontally / + * vertically, this function attempts to select the largest font it can that will still fit within the bounds when + * drawing a grid of characters. Does not handle multi-letter entries well, assumes we are laying out a grid of + * single characters. + * @param width The total width available for letters (px) + * @param height The total height available for letters (px) + * @param padding The amount of space required between characters (px) + * @param gridWidth The number of characters wide the rendering is going to be + * @param gridHeight The number of characters high the rendering is going to be + * @returns {{w: number, h: number, font: string}} + */ +function getBestFont(width, height, padding, gridWidth, gridHeight) { + let font = "4x6"; + let w = 4; + let h = 6; + const charMaxWidth = width / gridWidth - padding * gridWidth; + const charMaxHeight = height / gridHeight - padding * gridHeight; + if (charMaxWidth >= 6 && charMaxHeight >= 8) { + w = 6; + h = 8; + font = "6x8"; + } + if (charMaxWidth >= 12 && charMaxHeight >= 16) { + w = 12; + h = 16; + font = "6x8:2"; + } + if (charMaxWidth >= 12 && charMaxHeight >= 20) { + w = 12; + h = 20; + font = "12x20"; + } + if (charMaxWidth >= 20 && charMaxHeight >= 20) { + font = "Vector" + Math.floor(Math.min(charMaxWidth, charMaxHeight)); + const dims = g.setFont(font) + .stringMetrics("W"); + w = dims.width + h = dims.height; + } + return {w, h, font}; +} + + +/** + * Generate a set of key objects given an array of arrays of characters to make available for typing. + * @param characterArrays + * @returns {Promise} + */ +function getKeys(characterArrays) { + if (Array.isArray(characterArrays)) { + return Promise.all(characterArrays.map((chars, i) => generateKeyFromChars(characterArrays, i))); + } else { + return generateKeyFromChars(characterArrays, 0); + } +} + +function generateKeyFromChars(chars, i) { + return new Promise((resolve, reject) => { + let special; + if (!Array.isArray(chars[i]) && chars[i].length > 1) { + // If it's not an array we assume it's a string. Fingers crossed I guess, lol. Be nice to my functions! + special = chars[i]; + } + const key = getKeyByIndex(chars, i, special); + if (!special) { + key.chars = chars[i]; + } + if (key.chars.length > 1) { + key.pendingSubKeys = true; + key.getSubKeys = () => getKeys(key.chars); + resolve(key) + } else { + resolve(key); + } + }) +} + + +/** + * Given a set of characters (or sets of characters) get the position and dimensions of the i'th key in that set. + * @param charSet An array where each element represents a key on the hypothetical keyboard. + * @param i The index of the key in the set you want to get dimensions for. + * @param special The special property of the key - for example "del" for a key used for deleting characters. + * @returns {{special, bord: number, pad: number, w: number, x: number, h: number, y: number, chars: *[]}} + */ +function getKeyByIndex(charSet, i, special) { + // Key dimensions + const keyboardOffsetY = 40; + const margin = 3; + const padding = 4; + const border = 2; + const gridWidth = Math.ceil(Math.sqrt(charSet.length)); + const gridHeight = Math.ceil(charSet.length / gridWidth); + const keyWidth = Math.floor((g.getWidth()) / gridWidth) - margin; + const keyHeight = Math.floor((g.getHeight() - keyboardOffsetY) / gridHeight) - margin; + const gridx = i % gridWidth; + const gridy = Math.floor(i / gridWidth) % gridWidth; + const x = gridx * (keyWidth + margin); + const y = gridy * (keyHeight + margin) + keyboardOffsetY; + const w = keyWidth; + const h = keyHeight; + // internal Character spacing + const numChars = charSet[i].length; + const subGridWidth = Math.ceil(Math.sqrt(numChars)); + const subGridHeight = Math.ceil(numChars / subGridWidth); + const bestFont = getBestFont(w - padding, h - padding, 0, subGridWidth, subGridHeight); + const letterWidth = bestFont.w; + const letterHeight = bestFont.h; + const totalWidth = (subGridWidth - 1) * (w / subGridWidth) + padding + letterWidth + 1; + const totalHeight = (subGridHeight - 1) * (h / subGridHeight) + padding + letterHeight + 1; + const extraPadH = (w - totalWidth) / 2; + const extraPadV = (h - totalHeight) / 2; + return { + x, + y, + w, + h, + pad : padding, + bord : border, + chars: [], + special, + subGridWidth, + subGridHeight, + extraPadH, + extraPadV, + font : bestFont.font + }; +} + + +/** + * This is probably the most intense part of this keyboard library. If you don't do it ahead of time, it will happen + * when you call the keyboard, and it can take up to 1.5 seconds for a full keyboard. Not a super great user experience + * SO if you have a tiny keyset, don't worry about it so much, but if you want to maximize performance, generate + * a keyboard ahead of time and pass it into the "keyboard" argument of the object in the "input" function. + * @param charSets + * @returns {Promise} + */ +function generateKeyboard(charSets) { + if (!Array.isArray(charSets)) { + // User passed a string. We will divvy it up into a real set of subdivided characters. + charSets = createCharSet(charSets, ["ok", "del", "shft"]); + } + return getKeys(charSets); +} + +const defaultCharSet = [ + ["a", "b", "c", "d", "e", "f", "g", "h", "i"], + ["j", "k", "l", "m", "n", "o", "p", "q", "r"], + ["s", "t", "u", "v", "w", "x", "y", "z", "0"], + ["1", "2", "3", "4", "5", "6", "7", "8", "9"], + [" ", "`", "-", "=", "[", "]", "\\", ";", "'"], + [",", ".", "/"], + "ok", + "shft", + "del" +]; + +const defaultCharSetShift = [ + ["A", "B", "C", "D", "E", "F", "G", "H", "I"], + ["J", "K", "L", "M", "N", "O", "P", "Q", "R"], + ["S", "T", "U", "V", "W", "X", "Y", "Z", ")"], + ["!", "@", "#", "$", "%", "^", "&", "*", "("], + ["~", "_", "+", "{", "}", "|", ":", "\"", "<"], + [">", "?"], + "ok", + "shft", + "del" +]; + +/** + * Given initial options, allow the user to type a set of characters and return their entry in a promise. If you do not + * submit your own character set, a default alphanumeric keyboard will display. + * @param options The object containing initial options for the keyboard. + * @param {string} options.text The initial text to display / edit in the keyboard + * @param {array[]|string[]} [options.keyboardMain] The primary keyboard generated with generateKeyboard() + * @param {array[]|string[]} [options.keyboardShift] Like keyboardMain, but displayed when shift / capslock is pressed. + * @returns {Promise} + */ +function input(options) { + options = options || {}; + let typed = options.text || ""; + let resolveFunction = () => {}; + let shift = false; + let caps = false; + let activeKeySet; + + const offsetX = 0; + const offsetY = 40; + + E.showMessage("Loading..."); + let keyboardPromise; + if (options.keyboardMain) { + keyboardPromise = Promise.all([options.keyboardMain, options.keyboardShift || Promise.resolve([])]); + } else { + keyboardPromise = Promise.all([generateKeyboard(defaultCharSet), generateKeyboard(defaultCharSetShift)]) + } + + let mainKeys; + let mainKeysShift; + + /** + * Draw an individual keyboard key - handles special formatting and the rectangle pad, followed by the character + * rendering. Returns a promise so that you can do many of these in a loop without blocking the thread. + * @param key + */ + function drawKey(key) { + let bgColor = g.theme.bg; + if (key.special) { + if (key.special === "ok") bgColor = "#0F0"; + if (key.special === "cncl") bgColor = "#F00"; + if (key.special === "del") bgColor = g.theme.bg2; + if (key.special === "spc") bgColor = g.theme.bg2; + if (key.special === "shft") { + bgColor = shift ? g.theme.bgH : g.theme.bg2; + } + if (key.special === "caps") { + bgColor = caps ? g.theme.bgH : g.theme.bg2; + } + g.setColor(bgColor) + .fillRect({x: key.x, y: key.y, w: key.w, h: key.h}); + } + g.setColor(g.theme.fg) + .drawRect({x: key.x, y: key.y, w: key.w, h: key.h}); + drawChars(key); + } + + /** + * Draw the characters for a given key - this handles the layout of all characters needed for the key, whether the + * key has 12 characters, 1, or if it represents a special key. + * @param key + */ + function drawChars(key) { + const numChars = key.chars.length; + if (key.special) { + g.setColor(g.theme.fg) + .setFont("12x20") + .setFontAlign(-1, -1) + .drawString(key.special, key.x + key.w / 2 - g.stringWidth(key.special) / 2, key.y + key.h / 2 - 10, false); + } else { + g.setColor(g.theme.fg) + .setFont(key.font) + .setFontAlign(-1, -1); + for (let i = 0; i < numChars; i++) { + const gridX = i % key.subGridWidth; + const gridY = Math.floor(i / key.subGridWidth) % key.subGridWidth; + const charOffsetX = gridX * (key.w / key.subGridWidth); + const charOffsetY = gridY * (key.h / key.subGridHeight); + const posX = key.x + key.pad + charOffsetX + key.extraPadH; + const posY = key.y + key.pad + charOffsetY + key.extraPadV; + g.drawString(key.chars[i], posX, posY, false); + } + } + } + + /** + * Get the key set corresponding to the indicated shift state. Allows easy switching between capital letters and + * lower case by just switching the boolean passed here. + * @param shift + * @returns {*[]} + */ + function getMainKeySet(shift) { + return shift ? mainKeysShift : mainKeys; + } + + /** + * Draw all the given keys on the screen. + * @param keys + */ + function drawKeys(keys) { + keys.forEach(key => { + drawKey(key); + }); + } + + /** + * Draw the text that the user has typed so far, includes a cursor and automatic truncation when the string is too + * long. + * @param text + * @param cursorChar + */ + function drawTyped(text, cursorChar) { + let visibleText = text; + let ellipsis = false; + const maxWidth = 176 - 40; + while (g.setFont("12x20") + .stringWidth(visibleText) > maxWidth) { + ellipsis = true; + visibleText = visibleText.slice(1); + } + if (ellipsis) { + visibleText = "..." + visibleText; + } + g.setColor(g.theme.bg2) + .fillRect(5, 5, 171, 30); + g.setColor(g.theme.fg2) + .setFont("12x20") + .drawString(visibleText + cursorChar, 15, 10, false); + } + + /** + * Clear the space on the screen that the keyboard occupies (not the text the user has written). + */ + function clearKeySpace() { + g.setColor(g.theme.bg) + .fillRect(offsetX, offsetY, 176, 176); + } + + /** + * Based on a touch even, determine which key was pressed by the user. + * @param touchEvent + * @param keys + * @returns {*} + */ + function getTouchedKey(touchEvent, keys) { + return keys.find((key) => { + let relX = touchEvent.x - key.x; + let relY = touchEvent.y - key.y; + return relX > 0 && relX < key.w && relY > 0 && relY < key.h; + }) + } + + /** + * On a touch event, determine whether a key is touched and take appropriate action if it is. + * @param button + * @param touchEvent + */ + function keyTouch(button, touchEvent) { + const pressedKey = getTouchedKey(touchEvent, activeKeySet); + if (pressedKey == null) { + // User tapped empty space. + swapKeySet(getMainKeySet(shift !== caps)); + return; + } + if (pressedKey.pendingSubKeys) { + // We have to generate the subkeys for this key still, but we decided to wait until we needed it! + pressedKey.pendingSubKeys = false; + pressedKey.getSubKeys() + .then(subkeys => { + pressedKey.subKeys = subkeys; + keyTouch(undefined, touchEvent); + }) + return; + } + // Haptic feedback + Bangle.buzz(25, 1); + if (pressedKey.subKeys) { + // Hold press for "shift!" + if (touchEvent.type > 1) { + shift = !shift; + swapKeySet(getMainKeySet(shift !== caps)); + } else { + swapKeySet(pressedKey.subKeys); + } + } else { + if (pressedKey.special) { + evaluateSpecialFunctions(pressedKey); + } else { + typed = typed + pressedKey.chars; + shift = false; + drawTyped(typed, ""); + swapKeySet(getMainKeySet(shift !== caps)); + } + } + } + + /** + * Manage setting, generating, and rendering new keys when a key set is changed. + * @param newKeys + */ + function swapKeySet(newKeys) { + activeKeySet = newKeys; + clearKeySpace(); + drawKeys(activeKeySet); + } + + /** + * Determine if the key contains any of the special strings that have their own special behaviour when pressed. + * @param key + */ + function evaluateSpecialFunctions(key) { + switch (key.special) { + case "ok": + setTimeout(() => resolveFunction(typed), 50); + break; + case "del": + typed = typed.slice(0, -1); + drawTyped(typed, ""); + break; + case "shft": + shift = !shift; + swapKeySet(getMainKeySet(shift !== caps)); + break; + case "caps": + caps = !caps; + swapKeySet(getMainKeySet(shift !== caps)); + break; + case "cncl": + setTimeout(() => resolveFunction(), 50); + break; + case "spc": + typed = typed + " "; + break; + } + } + + let isCursorVisible = true; + + const blinkInterval = setInterval(() => { + if (!activeKeySet) return; + isCursorVisible = !isCursorVisible; + if (isCursorVisible) { + drawTyped(typed, "_"); + } else { + drawTyped(typed, ""); + } + }, 200); + + + /** + * We return a promise but the resolve function is assigned to a variable in the higher function scope. That allows + * us to return the promise and resolve it after we are done typing without having to return the entire scope of the + * application within the promise. + */ + return new Promise((resolve, reject) => { + g.clear(true); + resolveFunction = resolve; + keyboardPromise.then((result) => { + mainKeys = result[0]; + mainKeysShift = result[1]; + swapKeySet(getMainKeySet(shift !== caps)); + Bangle.setUI({ + mode: "custom", touch: keyTouch + }); + Bangle.setLocked(false); + }) + }).then((result) => { + g.clearRect(Bangle.appRect); + clearInterval(blinkInterval); + Bangle.setUI(); + return result; + }); +} + +exports.input = input; +exports.generateKeyboard = generateKeyboard; +exports.defaultCharSet = defaultCharSet; +exports.defaultCharSetShift = defaultCharSetShift; +exports.createCharSet = createCharSet; \ No newline at end of file diff --git a/apps/kbmatry/metadata.json b/apps/kbmatry/metadata.json new file mode 100644 index 000000000..793286180 --- /dev/null +++ b/apps/kbmatry/metadata.json @@ -0,0 +1,14 @@ +{ "id": "kbmatry", + "name": "Matryoshka Keyboard", + "version":"1.06", + "description": "A library for text input via onscreen keyboard. Easily enter characters with nested keyboards.", + "icon": "icon.png", + "type":"textinput", + "tags": "keyboard", + "supports" : ["BANGLEJS2"], + "screenshots": [{"url":"screenshot.png"},{"url":"screenshot6.png"},{"url":"screenshot2.png"},{"url":"screenshot3.png"},{"url":"screenshot4.png"},{"url":"screenshot5.png"},{"url": "help.png"}], + "readme": "README.md", + "storage": [ + {"name":"textinput","url":"lib.js"} + ] +} diff --git a/apps/kbmatry/screenshot.png b/apps/kbmatry/screenshot.png new file mode 100644 index 000000000..08bb366e4 Binary files /dev/null and b/apps/kbmatry/screenshot.png differ diff --git a/apps/kbmatry/screenshot2.png b/apps/kbmatry/screenshot2.png new file mode 100644 index 000000000..21874244d Binary files /dev/null and b/apps/kbmatry/screenshot2.png differ diff --git a/apps/kbmatry/screenshot3.png b/apps/kbmatry/screenshot3.png new file mode 100644 index 000000000..1f0c73265 Binary files /dev/null and b/apps/kbmatry/screenshot3.png differ diff --git a/apps/kbmatry/screenshot4.png b/apps/kbmatry/screenshot4.png new file mode 100644 index 000000000..de2f90bee Binary files /dev/null and b/apps/kbmatry/screenshot4.png differ diff --git a/apps/kbmatry/screenshot5.png b/apps/kbmatry/screenshot5.png new file mode 100644 index 000000000..b860c8438 Binary files /dev/null and b/apps/kbmatry/screenshot5.png differ diff --git a/apps/kbmatry/screenshot6.png b/apps/kbmatry/screenshot6.png new file mode 100644 index 000000000..20de7ddc1 Binary files /dev/null and b/apps/kbmatry/screenshot6.png differ