Skip to main content

Keypad API

Overview​

The Keypad API provides functionality to interact with the devices's Keypad or other input types really (knob, sensor, touchbar). It allows you to retrieve key events, get information about keys, and convert between key positions and IDs.

The KeyInfo API might see some changes in the future to support complex dynamic input types.

The header file for this API is part of os/MatrixOS.h and the implementation is in os/system/KeyPad.cpp.

MatrixOS::KEYPAD::Get​

bool Get([`KeyEvent`](./Types/KeyEvent/)* keyEvent_dest, uint32_t timeout_ms = 0);

Fetches the next available key event. If no event is available, the function waits for the specified timeout.

Parameters:

  • keyEvent_dest (KeyEvent*): Destination pointer to store the retrieved key event.
  • timeout_ms (uint32_t, optional): Maximum time to wait for an event in milliseconds. Defaults to 0.

Returns:

  • bool: true if a key event was retrieved, otherwise false.

MatrixOS::KEYPAD::GetKey (by Position)​

[`KeyInfo`](./Types/KeyInfo/)* GetKey(Point keyXY);

Gets information about the key located at the specified position.

Parameters:

  • keyXY (Point): Position of the key.

Returns:

  • KeyInfo*: Pointer to the key information. Returns nullptr if no key is found.

MatrixOS::KEYPAD::GetKey (by ID)​

[`KeyInfo`](./Types/KeyInfo/)* GetKey(uint16_t keyID);

Gets information about the key with the specified ID.

Parameters:

  • keyID (uint16_t): ID of the key.

Returns:

  • KeyInfo*: Pointer to the key information. Returns nullptr if no key is found.

MatrixOS::KEYPAD::Clear​

void Clear();

Clears the current key state and suppresses further events (e.g., Release, Hold) for all keys until their next Press event.

MatrixOS::KEYPAD::ClearList​

void ClearList();

Clears the current KeyEvent queue. No events will remain in the queue after this call.

MatrixOS::KEYPAD::XY2ID​

uint16_t XY2ID(Point xy);

Converts a key position to its corresponding key ID.

Parameters:

  • xy (Point): The position of the key.

Returns:

  • uint16_t: The key ID associated with the position. Returns UINT16_MAX if no key ID is assigned to the given position.

MatrixOS::KEYPAD::ID2XY​

Point ID2XY(uint16_t keyID);

Converts a key ID to its corresponding position.

Parameters:

  • keyID (uint16_t): The ID of the key.

Returns:

  • Point: The position of the key. Returns Point::Invalid() if no position is found for the given ID. You can then do bool(Point) to check if the point is valid.

Comments