Merge pull request #7223 from keymanapp/feat/core/add-event-api

feat(core): add `km_kbp_event` API endpoint

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

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();
 }

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* _kmn_unused(state),
+      uint32_t _kmn_unused(event),
+      void* _kmn_unused(data)
+    ) {
+      return KM_KBP_STATUS_OK;
+    }
+
     virtual km_kbp_attr const & attributes() const = 0;
     virtual km_kbp_status       validate() const = 0;