From 5104914672c11a91308644621d14d3f01bcbf2d0 Mon Sep 17 00:00:00 2001
From: Marc Durdin <marc@durdin.net>
Date: Wed, 7 Sep 2022 10:24:01 +1000
Subject: [PATCH 1/2] feat(core): add km_kbp_event API endpoint

Adds infrastructure required to support caps lock control on keyboard
activation per #5822.

Keyboardprocessor implementation is currently a stub, and engines will
need corresponding updates to support the new API.
---
 core/include/keyman/keyboardprocessor.h | 43 +++++++++++++++++++++++++
 core/src/km_kbp_processevent_api.cpp    | 39 ++++++++++++++++++++++
 core/src/processor.hpp                  |  9 ++++++
 3 files changed, 91 insertions(+)

diff --git a/core/include/keyman/keyboardprocessor.h b/core/include/keyman/keyboardprocessor.h
index 3a6700c833..e49fa4b779 100644
--- a/core/include/keyman/keyboardprocessor.h
+++ b/core/include/keyman/keyboardprocessor.h
@@ -1118,6 +1118,49 @@ KMN_API
 km_kbp_status
 km_kbp_process_queued_actions(km_kbp_state *state);
 
+/*
+```
+### `km_kbp_event`
+##### Description:
+Tell the keyboard processor that an external event has occurred, such as a keyboard
+being activated through the language switching UI.
+##### Return status:
+- `KM_KBP_STATUS_OK`: On success.
+- `KM_KBP_STATUS_NO_MEM`:
+In the event memory is unavailable to allocate internal buffers.
+- `KM_KBP_STATUS_INVALID_ARGUMENT`:
+In the event the `state` pointer is null or an invalid event or data is passed.
+
+The keyboard processor may generate actions which should be processed by the
+consumer of the API.
+
+The action list will be cleared at the start of this call; options and context in
+the state may also be modified.
+
+##### Parameters:
+- __state__: A pointer to the opaque state object.
+- __event__: The event to be processed, from KM_KBP_EVENT enumeration
+- __data__: Additional event-specific data. Currently unused, must be nullptr.
+
+```c
+*/
+KMN_API
+km_kbp_status
+km_kbp_event(
+  km_kbp_state *state,
+  uint32_t event,
+  void* data
+);
+
+enum km_kbp_event_codes {
+  /**
+   * A keyboard has been activated by the user. The processor may use this
+   * event, for example, to switch caps lock state or provide other UX.
+   */
+  KM_KBP_EVENT_KEYBOARD_ACTIVATED = 1,
+  //future: KM_KBP_EVENT_KEYBOARD_DEACTIVATED = 2,
+};
+
 #if defined(__cplusplus)
 } // extern "C"
 #endif
diff --git a/core/src/km_kbp_processevent_api.cpp b/core/src/km_kbp_processevent_api.cpp
index 0a3df41f31..57b9310754 100644
--- a/core/src/km_kbp_processevent_api.cpp
+++ b/core/src/km_kbp_processevent_api.cpp
@@ -12,11 +12,42 @@
 #include "processor.hpp"
 #include "state.hpp"
 
+km_kbp_status
+km_kbp_event(
+  km_kbp_state *state,
+  uint32_t event,
+  void* data
+) {
+  assert(state != nullptr);
+  if(state == nullptr) {
+    return KM_KBP_STATUS_INVALID_ARGUMENT;
+  }
+
+  // event: KM_KBP_EVENT_KEYBOARD_ACTIVATED; data should be nullptr
+  // future event: KM_KBP_EVENT_KEYBOARD_DEACTIVATED
+  switch(event) {
+    case KM_KBP_EVENT_KEYBOARD_ACTIVATED:
+      assert(data == nullptr);
+      if(data == nullptr) {
+        return KM_KBP_STATUS_INVALID_ARGUMENT;
+      }
+      break;
+    default:
+      return KM_KBP_STATUS_INVALID_ARGUMENT;
+  }
+
+  return state->processor().external_event(state, event, data);
+}
+
 km_kbp_status
 km_kbp_process_event(km_kbp_state *state,
                      km_kbp_virtual_key vk,
                      uint16_t modifier_state,
                      uint8_t is_key_down) {
+  assert(state != nullptr);
+  if(state == nullptr) {
+    return KM_KBP_STATUS_INVALID_ARGUMENT;
+  }
   return state->processor().process_event(state, vk, modifier_state, is_key_down);
 }
 
@@ -24,11 +55,19 @@ km_kbp_status
 km_kbp_process_queued_actions(
       km_kbp_state *state
       ) {
+  assert(state != nullptr);
+  if(state == nullptr) {
+    return KM_KBP_STATUS_INVALID_ARGUMENT;
+  }
   return state->processor().process_queued_actions(state);
 }
 
 km_kbp_attr const *
 km_kbp_get_engine_attrs(km_kbp_state const *state)
 {
+  assert(state != nullptr);
+  if(state == nullptr) {
+    return nullptr;
+  }
   return &state->processor().attributes();
 }
diff --git a/core/src/processor.hpp b/core/src/processor.hpp
index d68343ce96..e4095a013d 100644
--- a/core/src/processor.hpp
+++ b/core/src/processor.hpp
@@ -44,6 +44,15 @@ namespace kbp
       uint8_t is_key_down
     ) = 0;
 
+    virtual km_kbp_status
+    external_event(
+      km_kbp_state* state,
+      uint32_t event,
+      void* data
+    ) {
+      return KM_KBP_STATUS_OK;
+    }
+
     virtual km_kbp_attr const & attributes() const = 0;
     virtual km_kbp_status       validate() const = 0;
 

From 8678a0d35b652822fae56dd05b13dc78afad6d63 Mon Sep 17 00:00:00 2001
From: Marc Durdin <marc@durdin.net>
Date: Wed, 7 Sep 2022 10:36:35 +1000
Subject: [PATCH 2/2] chore(core): mark unused parameters

---
 core/src/processor.hpp | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/core/src/processor.hpp b/core/src/processor.hpp
index e4095a013d..7041a72100 100644
--- a/core/src/processor.hpp
+++ b/core/src/processor.hpp
@@ -46,9 +46,9 @@ namespace kbp
 
     virtual km_kbp_status
     external_event(
-      km_kbp_state* state,
-      uint32_t event,
-      void* data
+      km_kbp_state* _kmn_unused(state),
+      uint32_t _kmn_unused(event),
+      void* _kmn_unused(data)
     ) {
       return KM_KBP_STATUS_OK;
     }