epic: embed-osk-in-kmx 🔱

android/Tests/KeyboardHarness/app/src/main/assets/keyboardharness.kpj

@@ -7,6 +7,6 @@
     <CompilerWarningsAsErrors>True</CompilerWarningsAsErrors>
     <CheckFilenameConventions>True</CheckFilenameConventions>
     <SkipMetadataFiles>True</SkipMetadataFiles>
-    <ProjectType>lexicalmodel</ProjectType>
+    <ProjectType>keyboard</ProjectType>
   </Options>
 </KeymanDeveloperProject>

common/include/kmx_file.h

@@ -5,7 +5,7 @@
 
 #pragma once
 
-#include <km_types.h>
+#include "km_types.h"
 
 #ifdef KM_CORE_LIBRARY
 // TODO: move this to a common namespace keyman::common::kmx_file or similar in the future
@@ -52,8 +52,10 @@ namespace kmx {
 #define VERSION_160 0x00001000
 #define VERSION_170 0x00001100
 
+#define VERSION_190 0x00001300
+
 #define VERSION_MIN VERSION_50
-#define VERSION_MAX VERSION_170
+#define VERSION_MAX VERSION_190
 
 //
 // Backspace types
@@ -62,6 +64,9 @@ namespace kmx {
 #define BK_DEFAULT    0
 #define BK_DEADKEY    1
 
+// Next character to delete is a Unicode surrogate pair
+#define BK_SURROGATE  4
+
 // Different begin types
 #define BEGIN_ANSI    0
 #define BEGIN_UNICODE 1
@@ -267,14 +272,24 @@ namespace kmx {
 #define C_CODE_IFSYSTEMSTORE(store, val1, val2) U_UC_SENTINEL U_CODE_IFSYSTEMSTORE store val1 val2
 #define C_CODE_SETSYSTEMSTORE(store, val) U_UC_SENTINEL U_CODE_SETSYSTEMSTORE store val
 
+//
+// COMP_KEYBOARD.dwFlags bitfield
+//
+
 #define KF_SHIFTFREESCAPS 0x0001
 #define KF_CAPSONONLY   0x0002
 #define KF_CAPSALWAYSOFF  0x0004
 #define KF_LOGICALLAYOUT  0x0008
 #define KF_AUTOMATICVERSION 0x0010
 
-// 16.0: Support for LDML Keyboards in KMXPlus file format
-#define KF_KMXPLUS  0x0020
+/** 16.0+: A `COMP_KEYBOARD_KMXPLUSINFO` structure is present immediately after `COMP_KEYBOARD` */
+#define KF_KMXPLUS          0x0020
+
+/**
+ * 19.0+: The `COMP_KEYBOARD_KMXPLUSINFO` structure contains a v19 embedded OSK;
+ * may be used with or without KF_KMXPLUS.
+ */
+#define KF_KMXPLUSOSK       0x0040
 
 #define HK_ALT      0x00010000
 #define HK_CTRL     0x00020000
@@ -362,17 +377,17 @@ struct COMP_KEYBOARD_KMXPLUSINFO {
 };
 
 /**
- * Only valid if comp_keyboard.dwFlags&KF_KMXPLUS
+ * Only valid if comp_keyboard.dwFlags&(KF_KMXPLUS|KF_KMXPLUSOSK)
  */
 struct COMP_KEYBOARD_EX {
-  COMP_KEYBOARD             header;    // 0000 see COMP_KEYBOARD
-  COMP_KEYBOARD_KMXPLUSINFO kmxplus;   // 0040 see COMP_KEYBOARD_EXTRA
+  struct COMP_KEYBOARD             header;    // 0000 see COMP_KEYBOARD
+  struct COMP_KEYBOARD_KMXPLUSINFO kmxplus;   // 0040 see COMP_KEYBOARD_EXTRA
 };
 
-typedef COMP_KEYBOARD *PCOMP_KEYBOARD;
-typedef COMP_STORE *PCOMP_STORE;
-typedef COMP_KEY *PCOMP_KEY;
-typedef COMP_GROUP *PCOMP_GROUP;
+typedef struct COMP_KEYBOARD *PCOMP_KEYBOARD;
+typedef struct COMP_STORE *PCOMP_STORE;
+typedef struct COMP_KEY *PCOMP_KEY;
+typedef struct COMP_GROUP *PCOMP_GROUP;
 
 extern const int CODE__SIZE[];
 #define CODE__SIZE_MAX 5
@@ -382,10 +397,10 @@ extern const int CODE__SIZE[];
 #define KEYBOARDFILEGROUP_SIZE  24
 #define KEYBOARDFILEKEY_SIZE    20
 
-static_assert(sizeof(COMP_STORE) == KEYBOARDFILESTORE_SIZE, "COMP_STORE must be KEYBOARDFILESTORE_SIZE bytes");
-static_assert(sizeof(COMP_KEY) == KEYBOARDFILEKEY_SIZE, "COMP_KEY must be KEYBOARDFILEKEY_SIZE bytes");
-static_assert(sizeof(COMP_GROUP) == KEYBOARDFILEGROUP_SIZE, "COMP_GROUP must be KEYBOARDFILEGROUP_SIZE bytes");
-static_assert(sizeof(COMP_KEYBOARD) == KEYBOARDFILEHEADER_SIZE, "COMP_KEYBOARD must be KEYBOARDFILEHEADER_SIZE bytes");
+static_assert(sizeof(struct COMP_STORE) == KEYBOARDFILESTORE_SIZE, "COMP_STORE must be KEYBOARDFILESTORE_SIZE bytes");
+static_assert(sizeof(struct COMP_KEY) == KEYBOARDFILEKEY_SIZE, "COMP_KEY must be KEYBOARDFILEKEY_SIZE bytes");
+static_assert(sizeof(struct COMP_GROUP) == KEYBOARDFILEGROUP_SIZE, "COMP_GROUP must be KEYBOARDFILEGROUP_SIZE bytes");
+static_assert(sizeof(struct COMP_KEYBOARD) == KEYBOARDFILEHEADER_SIZE, "COMP_KEYBOARD must be KEYBOARDFILEHEADER_SIZE bytes");
 
 #ifdef KM_CORE_LIBRARY
 } // namespace kmx

common/test/keyboards/embed_osk/.gitignore

@@ -0,0 +1 @@
+build/

common/test/keyboards/embed_osk/embed_osk.kpj

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<KeymanDeveloperProject>
+  <Options>
+    <BuildPath>$PROJECTPATH\build</BuildPath>
+    <SourcePath>$PROJECTPATH\source</SourcePath>
+    <CompilerWarningsAsErrors>True</CompilerWarningsAsErrors>
+    <WarnDeprecatedCode>True</WarnDeprecatedCode>
+    <CheckFilenameConventions>False</CheckFilenameConventions>
+    <ProjectType>keyboard</ProjectType>
+    <Version>2.0</Version>
+  </Options>
+</KeymanDeveloperProject>

common/test/keyboards/embed_osk/source/embed_osk.kps

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Package>
+  <System>
+    <KeymanDeveloperVersion>19.0.0.0</KeymanDeveloperVersion>
+    <FileVersion>7.0</FileVersion>
+  </System>
+  <Options>
+    <FollowKeyboardVersion/>
+  </Options>
+  <Info>
+    <Version/>
+    <Name>test_v19_kmxplus</Name>
+    <Description>test_v19_kmxplus</Description>
+  </Info>
+  <Files>
+    <File>
+      <Name>..\build\test_v19_kmxplus.kmx</Name>
+      <CopyLocation>0</CopyLocation>
+      <FileType>.kmx</FileType>
+    </File>
+  </Files>
+  <Keyboards>
+    <Keyboard>
+      <Name>test_v19_kmxplus</Name>
+      <ID>test_v19_kmxplus</ID>
+      <Version>1.0</Version>
+      <Languages>
+        <Language ID="en">English</Language>
+      </Languages>
+    </Keyboard>
+  </Keyboards>
+  <Strings/>
+</Package>

common/test/keyboards/embed_osk/source/test_v19_kmxplus.kmn

@@ -0,0 +1,7 @@
+store(&VERSION) '19.0'
+store(&NAME) 'Test KMX+ space reserved in header'
+store(&TARGETS) 'desktop'
+
+begin Unicode > use(main)
+
+group(main) using keys

common/web/types/src/consts/modifier-key-constants.ts

@@ -4,9 +4,16 @@
  * Modifier key bit-flags
  */
 
+import { VisualKeyboardShiftState } from "../kvk/visual-keyboard.js";
+
+/**
+ * This type is declared as a `const` rather than as an `enum` for
+ * historical reasons. Use `ModifierKeyConstant` instead where possible.
+ */
 export const ModifierKeyConstants = {
-  // Define Keyman Developer modifier bit-flags (exposed for use by other modules)
-  // Compare against /common/include/kmx_file.h.  CTRL+F "#define LCTRLFLAG" to find the secton.
+  // Define Keyman Developer modifier bit-flags (exposed for use by other
+  // modules) Compare against /common/include/kmx_file.h.  CTRL+F "#define
+  // LCTRLFLAG" to find the section.
   LCTRLFLAG:      0x0001, // Left Control flag
   RCTRLFLAG:      0x0002, // Right Control flag
   LALTFLAG:       0x0004, // Left Alt flag
@@ -30,4 +37,155 @@ export const ModifierKeyConstants = {
   // Note: OTHER_MODIFIER = 0x10000, used by KMX+ for the
   // other modifier flag in layers, > 16 bit so not available here.
   // See keys_mod_other in keyman_core_ldml.ts
+};
+
+/**
+ * Defines the standard modifier key flags used by Keyman. Note that some keys
+ * are chiral, and toggle key state is ignored if neither the __FLAG nor the
+ * corresponding NOT__FLAG are set.
+ */
+export enum ModifierKeyConstant {
+  NO_MODIFIER =    0,
+  LCTRLFLAG =      0x0001, // Left Control flag
+  RCTRLFLAG =      0x0002, // Right Control flag
+  LALTFLAG =       0x0004, // Left Alt flag
+  RALTFLAG =       0x0008, // Right Alt flag
+  K_SHIFTFLAG =    0x0010, // Either shift flag
+  K_CTRLFLAG =     0x0020, // Either ctrl flag
+  K_ALTFLAG =      0x0040, // Either alt flag
+  K_METAFLAG =     0x0080, // Either Meta-key flag (tentative).  Not usable in keyboard rules;
+                           // Used internally (currently, only by KMW) to ensure Meta-key
+                           // shortcuts safely bypass rules
+                           // Meta key = Command key on macOS, Windows key on Windows/Linux
+  CAPITALFLAG =    0x0100, // Caps lock on
+  NOTCAPITALFLAG = 0x0200, // Caps lock NOT on
+  NUMLOCKFLAG =    0x0400, // Num lock on
+  NOTNUMLOCKFLAG = 0x0800, // Num lock NOT on
+  SCROLLFLAG =     0x1000, // Scroll lock on
+  NOTSCROLLFLAG =  0x2000, // Scroll lock NOT on
+  ISVIRTUALKEY =   0x4000, // It is a Virtual Key Sequence
+  VIRTUALCHARKEY = 0x8000, // Keyman 6.0: Virtual Key Cap Sequence NOT YET
+};
+
+export const LDML_MODIFIER_TO_KVK_MODIFIER = /* @__PURE__ */ (() => {
+  const m = new Map<ModifierKeyConstant, VisualKeyboardShiftState>();
+  m.set(ModifierKeyConstants.LCTRLFLAG,      VisualKeyboardShiftState.KVKS_LCTRL);
+  m.set(ModifierKeyConstants.RCTRLFLAG,      VisualKeyboardShiftState.KVKS_RCTRL);
+  m.set(ModifierKeyConstants.LALTFLAG,       VisualKeyboardShiftState.KVKS_LALT);
+  m.set(ModifierKeyConstants.RALTFLAG,       VisualKeyboardShiftState.KVKS_RALT);
+  m.set(ModifierKeyConstants.K_SHIFTFLAG,    VisualKeyboardShiftState.KVKS_SHIFT);
+  m.set(ModifierKeyConstants.K_CTRLFLAG,     VisualKeyboardShiftState.KVKS_CTRL);
+  m.set(ModifierKeyConstants.K_ALTFLAG,      VisualKeyboardShiftState.KVKS_ALT);
+  return m;
+})();
+
+export const KVK_MODIFIER_TO_LDML_MODIFIER = /* @__PURE__ */ (() => {
+  const m = new Map<VisualKeyboardShiftState, ModifierKeyConstant>();
+  m.set(VisualKeyboardShiftState.KVKS_LCTRL, ModifierKeyConstants.LCTRLFLAG);
+  m.set(VisualKeyboardShiftState.KVKS_RCTRL, ModifierKeyConstants.RCTRLFLAG);
+  m.set(VisualKeyboardShiftState.KVKS_LALT,  ModifierKeyConstants.LALTFLAG);
+  m.set(VisualKeyboardShiftState.KVKS_RALT,  ModifierKeyConstants.RALTFLAG);
+  m.set(VisualKeyboardShiftState.KVKS_SHIFT, ModifierKeyConstants.K_SHIFTFLAG);
+  m.set(VisualKeyboardShiftState.KVKS_CTRL,  ModifierKeyConstants.K_CTRLFLAG);
+  m.set(VisualKeyboardShiftState.KVKS_ALT,   ModifierKeyConstants.K_ALTFLAG);
+  return m;
+})();
+
+export function translateLdmlModifiersToVisualKeyboardShift(modifiers: ModifierKeyConstant): VisualKeyboardShiftState {
+  if(modifiers == ModifierKeyConstant.NO_MODIFIER) {
+    return VisualKeyboardShiftState.KVKS_NORMAL;
+  }
+
+  if(modifiers &
+    (ModifierKeyConstant.CAPITALFLAG | ModifierKeyConstant.NUMLOCKFLAG | ModifierKeyConstant.SCROLLFLAG)
+  ) {
+    // Caps/Num/Scroll are not supported in .kvk, in combination or alone
+    return null;
+  }
+
+  let shift: VisualKeyboardShiftState = 0;
+
+  for(const mod of LDML_MODIFIER_TO_KVK_MODIFIER.keys()) {
+    if(modifiers & mod) {
+      shift |= LDML_MODIFIER_TO_KVK_MODIFIER.get(mod);
+    }
+  }
+
+  return shift;
+}
+
+export function translateVisualKeyboardShiftToLdmlModifiers(shift: VisualKeyboardShiftState): ModifierKeyConstant {
+  if(shift == VisualKeyboardShiftState.KVKS_NORMAL) {
+    return 0;
+  }
+
+  let mod = 0;
+  for(const state of KVK_MODIFIER_TO_LDML_MODIFIER.keys()) {
+    if(shift & state) {
+      mod |= KVK_MODIFIER_TO_LDML_MODIFIER.get(state);
+    }
+  }
+
+  return mod;
+}
+
+
+
+function VkShiftStateToKmxShiftState(ShiftState: number): number {
+
+  interface TVKToKMX {
+    VK: VisualKeyboardShiftState; KMX: ModifierKeyConstant;
+  }
+
+  const Map: TVKToKMX[] = [
+    {VK: VisualKeyboardShiftState.KVKS_SHIFT, KMX: ModifierKeyConstant.K_SHIFTFLAG},
+    {VK: VisualKeyboardShiftState.KVKS_CTRL,  KMX: ModifierKeyConstant.K_CTRLFLAG},
+    {VK: VisualKeyboardShiftState.KVKS_ALT,   KMX: ModifierKeyConstant.K_ALTFLAG},
+    {VK: VisualKeyboardShiftState.KVKS_LCTRL, KMX: ModifierKeyConstant.LCTRLFLAG},
+    {VK: VisualKeyboardShiftState.KVKS_RCTRL, KMX: ModifierKeyConstant.RCTRLFLAG},
+    {VK: VisualKeyboardShiftState.KVKS_LALT,  KMX: ModifierKeyConstant.LALTFLAG},
+    {VK: VisualKeyboardShiftState.KVKS_RALT,  KMX: ModifierKeyConstant.RALTFLAG}
+  ];
+
+  let result = 0;
+  for(let i = 0; i < Map.length; i++) {
+    if (ShiftState & Map[i].VK) {
+      result |= Map[i].KMX;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convert a VK modifier combination bitmask to a hyphen-separated string of
+ * modifier names, e.g. for use in layer names and key identifiers. The name
+ * order matches the bit flag order from ModifierKeyConstant, not the bit flag
+ * order from VisualKeyboardShiftState, for historical reasons.
+ */
+export function visualKeyboardShiftToLayerName(shift: VisualKeyboardShiftState): string {
+
+  // index is ModifierKeyConstant, not VisualKeyboardShiftState
+  const modifierNames: string[] = [
+      'leftctrl',
+      'rightctrl',
+      'leftalt',
+      'rightalt',
+      'shift',
+      'ctrl',
+      'alt'
+    ];
+
+  const mod = VkShiftStateToKmxShiftState(shift);
+  if(mod == 0) {
+    return 'default';
+  }
+
+  let result = '';
+  for(let i = 0; i < modifierNames.length; i++) {
+    if(mod & (1 << i)) {
+      result += modifierNames[i] + '-';
+    }
+  }
+  return result.substring(0, result.length - 1);
 }

common/web/types/src/consts/virtual-key-constants.ts

@@ -141,10 +141,8 @@ export const USVirtualKeyCodes = {
   K_TABFWD:50012
 };
 
-const k = USVirtualKeyCodes;
-
 /** Map a CLDR scancode to a US VKey ala USVirtualKeyCodes */
-export const CLDRScanToUSVirtualKeyCodes = {
+export const CLDRScanToUSVirtualKeyCodes = /* @__PURE__ */ ((k) => ({
   0x02: k.K_1,
   0x03: k.K_2,
   0x04: k.K_3,
@@ -202,7 +200,7 @@ export const CLDRScanToUSVirtualKeyCodes = {
   0x73: k.K_oC1,
   0x7D: k.K_oE2, // << Same as 0x56; found on jis
 
-};
+}))(USVirtualKeyCodes);
 
 export type KeyMap = number[][];
 
@@ -230,3 +228,27 @@ export function CLDRScanToVkey(scan: number, badScans?: Set<number>): number {
   }
 }
 
+const USVirtualKeyCodeNames = new Map<number, string>();
+
+function fillVirtualKeyNames() {
+  Object.keys(USVirtualKeyCodes).forEach(name => {
+    USVirtualKeyCodeNames.set((<any>USVirtualKeyCodes)[name], name);
+  });
+
+  // These three keys have multiple definitions
+  USVirtualKeyCodeNames.set(USVirtualKeyCodes.K_oE2, 'K_oE2');
+  USVirtualKeyCodeNames.set(USVirtualKeyCodes.K_oC1, 'K_oC1');
+  USVirtualKeyCodeNames.set(USVirtualKeyCodes.K_oDF, 'K_oDF');
+}
+
+/**
+ * Get the defined name of a virtual key
+ * @param vk A defined Keyman virtual key
+ * @returns the name of the virtual key, or undefined if not found
+ */
+export function usVirtualKeyName(vk: number): string {
+  if(USVirtualKeyCodeNames.size == 0) {
+    fillVirtualKeyNames();
+  }
+  return USVirtualKeyCodeNames.get(vk);
+}