CAPI_KeyEvent.h

Go to the documentation of this file.

///
/// Copyright (C) 2026 Ultralight, Inc. All rights reserved.
/// A license is required for commercial use. https://ultralig.ht
///
 
///
/// @file CAPI_KeyEvent.h
///
/// Key event interface.
///
/// `#include <Ultralight/CAPI/CAPI_KeyEvent.h>`
///
/// This file defines the C API for various key events.
///
#ifndef ULTRALIGHT_CAPI_KEYEVENT_H
#define ULTRALIGHT_CAPI_KEYEVENT_H
 
#include <Ultralight/CAPI/CAPI_Defines.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/******************************************************************************
 * Key Event
 ******************************************************************************/
 
///
/// Create a key event.
///
/// @param  type              The type of key event (see ULKeyEventType).
/// @param  modifiers         Keyboard modifiers, a bitwise OR of ULKeyEventModifiers values.
/// @param  virtual_key_code  The virtual key-code associated with this event (see KeyCodes.h).
/// @param  native_key_code   The platform-specific key-code generated by the OS.
/// @param  text              The text generated by this key event (usually a single character).
///                           Pass an empty ULString if not applicable.
/// @param  unmodified_text   The text generated before all modifiers except Shift are applied.
///                           Used internally for shortcut key processing.
/// @param  is_keypad         Whether this is a keypad event.
/// @param  is_auto_repeat    Whether this event was generated by holding down a key.
/// @param  is_system_key     Whether the pressed key is a "system key" (Windows only, set false
///                           on other platforms).
///
/// @note  The key identifier is derived for you from `virtual_key_code` for every type except
///        kKeyEventType_Char, which leaves it empty. You don't need to call
///        ulGetKeyIdentifierFromVirtualKeyCode() yourself.
///
/// @return  A new ULKeyEvent instance. You must call ulDestroyKeyEvent() when finished (typically
///          after passing it to ulViewFireKeyEvent()).
///
ULExport ULKeyEvent ulCreateKeyEvent(ULKeyEventType type, unsigned int modifiers,
                                     int virtual_key_code, int native_key_code, ULString text,
                                     ULString unmodified_text, bool is_keypad, bool is_auto_repeat,
                                     bool is_system_key);
 
#ifdef _WIN32
///
/// Create a key event from native Windows event.
///
/// @return  A new ULKeyEvent instance. You must call ulDestroyKeyEvent() when finished.
///
ULExport ULKeyEvent ulCreateKeyEventWindows(ULKeyEventType type, uintptr_t wparam, intptr_t lparam,
                                            bool is_system_key);
#endif
 
#ifdef __OBJC__
///
/// Create a key event from native macOS event.
///
/// @return  A new ULKeyEvent instance. You must call ulDestroyKeyEvent() when finished.
///
ULExport ULKeyEvent ulCreateKeyEventMacOS(NSEvent* evt);
#endif
 
///
/// Destroy a key event created by ulCreateKeyEvent() or a platform-specific variant.
///
ULExport void ulDestroyKeyEvent(ULKeyEvent evt);
 
///
/// Get the type of a key event.
///
/// @param  evt  The key event.
///
/// @return  Returns the type of key event (see ULKeyEventType).
///
ULExport ULKeyEventType ulKeyEventGetType(ULKeyEvent evt);
 
///
/// Get the keyboard modifiers of a key event.
///
/// @param  evt  The key event.
///
/// @return  Returns a bitwise OR of ULKeyEventModifiers values.
///
ULExport unsigned int ulKeyEventGetModifiers(ULKeyEvent evt);
 
///
/// Get the virtual key-code of a key event.
///
/// @param  evt  The key event.
///
/// @return  Returns the virtual key-code associated with this event (see KeyCodes.h).
///
ULExport int ulKeyEventGetVirtualKeyCode(ULKeyEvent evt);
 
///
/// Get the platform-specific key-code of a key event.
///
/// @param  evt  The key event.
///
/// @return  Returns the key-code generated by the OS.
///
ULExport int ulKeyEventGetNativeKeyCode(ULKeyEvent evt);
 
///
/// Get the key identifier of a key event (eg, "Enter" or "U+0041").
///
/// @param  evt  The key event.
///
/// @return  Returns the key identifier (empty for a kKeyEventType_Char event).
///
/// @note  Don't destroy the returned string, it is owned by the event. It stays valid until you
///        destroy the event (for an event passed to a callback, until the callback returns). Copy
///        it with ulCreateStringFromCopy() to keep it longer.
///
ULExport ULString ulKeyEventGetKeyIdentifier(ULKeyEvent evt);
 
///
/// Get the text generated by a key event (usually a single character).
///
/// @param  evt  The key event.
///
/// @return  Returns the text, or an empty string if the event generated none.
///
/// @note  Don't destroy the returned string, it is owned by the event. It stays valid until you
///        destroy the event (for an event passed to a callback, until the callback returns). Copy
///        it with ulCreateStringFromCopy() to keep it longer.
///
ULExport ULString ulKeyEventGetText(ULKeyEvent evt);
 
///
/// Get the text a key event generated before all modifiers except Shift were applied.
///
/// @param  evt  The key event.
///
/// @return  Returns the unmodified text, or an empty string if the event generated none.
///
/// @note  Don't destroy the returned string, it is owned by the event. It stays valid until you
///        destroy the event (for an event passed to a callback, until the callback returns). Copy
///        it with ulCreateStringFromCopy() to keep it longer.
///
ULExport ULString ulKeyEventGetUnmodifiedText(ULKeyEvent evt);
 
///
/// Whether or not a key event came from the keypad.
///
/// @param  evt  The key event.
///
/// @return  Returns true if this is a keypad event.
///
ULExport bool ulKeyEventIsKeypad(ULKeyEvent evt);
 
///
/// Whether or not a key event was generated by holding down a key.
///
/// @param  evt  The key event.
///
/// @return  Returns true if this event is an auto-repeat.
///
ULExport bool ulKeyEventIsAutoRepeat(ULKeyEvent evt);
 
///
/// Whether or not the pressed key is a "system key" (a Windows-only concept).
///
/// @param  evt  The key event.
///
/// @return  Returns true if this is a system key event (always false on other platforms).
///
ULExport bool ulKeyEventIsSystemKey(ULKeyEvent evt);
 
///
/// Get a key identifier string from a virtual key-code.
///
/// @param  virtual_key_code  The virtual key-code to generate the key identifier from.
///
/// @return  A ULString containing the key identifier. You must call ulDestroyString() when
///          finished.
///
ULExport ULString ulGetKeyIdentifierFromVirtualKeyCode(int virtual_key_code);
 
///
/// Get a key string from a virtual key-code.
///
/// @param  virtual_key_code  The virtual key-code to generate the key string from.
/// @param  shift             Whether or not the shift key is currently pressed.
///
/// @return  A ULString containing the key string. You must call ulDestroyString() when finished.
///
/// @note  This function assumes US keyboard layout.
///
ULExport ULString ulGetKeyFromVirtualKeyCode(int virtual_key_code, bool shift);
 
#ifdef __cplusplus
} // extern "C"
#endif
 
#endif // ULTRALIGHT_CAPI_KEYEVENT_H