CAPI_KeyEvent.h

Overview

Key event interface.

#include <Ultralight/CAPI/CAPI_KeyEvent.h>

This file defines the C API for various key events.

Functions
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)
	Create a key event.
void	ulDestroyKeyEvent (ULKeyEvent evt)
	Destroy a key event created by ulCreateKeyEvent() or a platform-specific variant.
ULKeyEventType	ulKeyEventGetType (ULKeyEvent evt)
	Get the type of a key event.
unsigned int	ulKeyEventGetModifiers (ULKeyEvent evt)
	Get the keyboard modifiers of a key event.
int	ulKeyEventGetVirtualKeyCode (ULKeyEvent evt)
	Get the virtual key-code of a key event.
int	ulKeyEventGetNativeKeyCode (ULKeyEvent evt)
	Get the platform-specific key-code of a key event.
ULString	ulKeyEventGetKeyIdentifier (ULKeyEvent evt)
	Get the key identifier of a key event (eg, "Enter" or "U+0041").
ULString	ulKeyEventGetText (ULKeyEvent evt)
	Get the text generated by a key event (usually a single character).
ULString	ulKeyEventGetUnmodifiedText (ULKeyEvent evt)
	Get the text a key event generated before all modifiers except Shift were applied.
bool	ulKeyEventIsKeypad (ULKeyEvent evt)
	Whether or not a key event came from the keypad.
bool	ulKeyEventIsAutoRepeat (ULKeyEvent evt)
	Whether or not a key event was generated by holding down a key.
bool	ulKeyEventIsSystemKey (ULKeyEvent evt)
	Whether or not the pressed key is a "system key" (a Windows-only concept).
ULString	ulGetKeyIdentifierFromVirtualKeyCode (int virtual_key_code)
	Get a key identifier string from a virtual key-code.
ULString	ulGetKeyFromVirtualKeyCode (int virtual_key_code, bool shift)
	Get a key string from a virtual key-code.

Function Documentation

ulCreateKeyEvent()

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 )

Create a key event.

Parameters

type	The type of key event (see ULKeyEventType).
modifiers	Keyboard modifiers, a bitwise OR of ULKeyEventModifiers values.
virtual_key_code	The virtual key-code associated with this event (see KeyCodes.h).
native_key_code	The platform-specific key-code generated by the OS.
text	The text generated by this key event (usually a single character). Pass an empty ULString if not applicable.
unmodified_text	The text generated before all modifiers except Shift are applied. Used internally for shortcut key processing.
is_keypad	Whether this is a keypad event.
is_auto_repeat	Whether this event was generated by holding down a key.
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.

Returns

A new ULKeyEvent instance. You must call ulDestroyKeyEvent() when finished (typically after passing it to ulViewFireKeyEvent()).

ulDestroyKeyEvent()

void ulDestroyKeyEvent

(

ULKeyEvent

evt

)

Destroy a key event created by ulCreateKeyEvent() or a platform-specific variant.

ulGetKeyFromVirtualKeyCode()

ULString ulGetKeyFromVirtualKeyCode	(	int	virtual_key_code,
		bool	shift )

Get a key string from a virtual key-code.

Parameters

virtual_key_code	The virtual key-code to generate the key string from.
shift	Whether or not the shift key is currently pressed.

Returns

A ULString containing the key string. You must call ulDestroyString() when finished.

Note

This function assumes US keyboard layout.

ulGetKeyIdentifierFromVirtualKeyCode()

ULString ulGetKeyIdentifierFromVirtualKeyCode

(

int

virtual_key_code

)

Get a key identifier string from a virtual key-code.

Parameters

virtual_key_code

The virtual key-code to generate the key identifier from.

Returns

A ULString containing the key identifier. You must call ulDestroyString() when finished.

ulKeyEventGetKeyIdentifier()

ULString ulKeyEventGetKeyIdentifier

(

ULKeyEvent

evt

)

Get the key identifier of a key event (eg, "Enter" or "U+0041").

Parameters

evt	The key event.

Returns

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.

ulKeyEventGetModifiers()

unsigned int ulKeyEventGetModifiers

(

ULKeyEvent

evt

)

Get the keyboard modifiers of a key event.

Parameters

evt	The key event.

Returns

Returns a bitwise OR of ULKeyEventModifiers values.

ulKeyEventGetNativeKeyCode()

int ulKeyEventGetNativeKeyCode

(

ULKeyEvent

evt

)

Get the platform-specific key-code of a key event.

Parameters

evt	The key event.

Returns

Returns the key-code generated by the OS.

ulKeyEventGetText()

ULString ulKeyEventGetText

(

ULKeyEvent

evt

)

Get the text generated by a key event (usually a single character).

Parameters

evt	The key event.

Returns

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.

ulKeyEventGetType()

ULKeyEventType ulKeyEventGetType

(

ULKeyEvent

evt

)

Get the type of a key event.

Parameters

evt	The key event.

Returns

Returns the type of key event (see ULKeyEventType).

ulKeyEventGetUnmodifiedText()

ULString ulKeyEventGetUnmodifiedText

(

ULKeyEvent

evt

)

Get the text a key event generated before all modifiers except Shift were applied.

Parameters

evt	The key event.

Returns

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.

ulKeyEventGetVirtualKeyCode()

int ulKeyEventGetVirtualKeyCode

(

ULKeyEvent

evt

)

Get the virtual key-code of a key event.

Parameters

evt	The key event.

Returns

Returns the virtual key-code associated with this event (see KeyCodes.h).

ulKeyEventIsAutoRepeat()

bool ulKeyEventIsAutoRepeat

(

ULKeyEvent

evt

)

Whether or not a key event was generated by holding down a key.

Parameters

evt	The key event.

Returns

Returns true if this event is an auto-repeat.

ulKeyEventIsKeypad()

bool ulKeyEventIsKeypad

(

ULKeyEvent

evt

)

Whether or not a key event came from the keypad.

Parameters

evt	The key event.

Returns

Returns true if this is a keypad event.

ulKeyEventIsSystemKey()

bool ulKeyEventIsSystemKey

(

ULKeyEvent

evt

)

Whether or not the pressed key is a "system key" (a Windows-only concept).

Parameters

evt	The key event.

Returns

Returns true if this is a system key event (always false on other platforms).

Go to the source code of this file.