xtd::forms::key_press_event_args Class Reference

#include <key_press_event_args.h>

Definition

Provides data for the key_press event.

Namespace

xtd::forms

Library

xtd.forms

Remarks

A key_press_event_args specifies the character that is composed when the user presses a key. For example, when the user presses SHIFT + K, the key_char property returns an uppercase K.

A key_press event occurs when the user presses a key. Two events that are closely related to the key_press event are key_up and key_down. The key_down event precedes each key_press event when the user presses a key, and a key_up event occurs when the user releases a key. When the user holds down a key, duplicate key_down and key_press events occur each time the character repeats. One key_up event is generated upon release.

With each key_press event, a key_press_event_args is passed. A key_event_args is passed with each key_down and key_up event. A key_event_args specifies whether any modifier keys (CMD, CTRL, SHIFT, or ALT) were pressed along with another key. (This modifier information can also be obtained through the modifier_keys property of the control class.)

Set handled to true to cancel the key_press event. This keeps the control from processing the key press.

Note

Some controls will process certain key strokes on key_down. For example, rich_text_box processes the Enter key before key_press is called. In such cases, you cannot cancel the key_press event, and must cancel the key stroke from key_down instead.

Inherits xtd::event_args.

Public Member Functions
	key_press_event_args ()=default
	Initializes a new instance of the KeyPressEventArgs class. More...
	key_press_event_args (char32_t key_char)
	Initializes a new instance of the KeyPressEventArgs class. More...
bool	handled () const
	Gets a value indicating whether the key_press event was handled. More...
void	handled (bool handled)
	Sets a value indicating whether the key_press event was handled. More...
char32_t	key_char () const
	Gets the character corresponding to the key pressed. More...
void	key_char (char32_t key_char)
	Sets the character corresponding to the key pressed. More...
Public Member Functions inherited from xtd::event_args
	event_args ()=default
	Initializes a new instance of the event_args class. More...
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const
	Gets the type of the current instance. More...
virtual xtd::ustring	to_string () const noexcept
	Returns a std::string that represents the current object. More...

Additional Inherited Members
Static Public Attributes inherited from xtd::event_args
static const event_args	empty
	Provides a value to use with events that do not have event data. More...
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal. More...
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

Constructor & Destructor Documentation

key_press_event_args() [1/2]

xtd::forms::key_press_event_args::key_press_event_args ( )

default

Initializes a new instance of the KeyPressEventArgs class.

Remarks

Use the control::modifier_keys property to get the current state of the modifier keys.

key_press_event_args() [2/2]

xtd::forms::key_press_event_args::key_press_event_args ( char32_t  key_char )

inline

Initializes a new instance of the KeyPressEventArgs class.

Parameters

key_char

The ASCII character corresponding to the key the user pressed.

Remarks

Use the control::modifier_keys property to get the current state of the modifier keys.

Member Function Documentation

handled() [1/2]

bool xtd::forms::key_press_event_args::handled ( ) const

inline

Gets a value indicating whether the key_press event was handled.

Returns

true if the event is handled; otherwise, false.

Remarks

If the event is not handled, it will be sent to the operating system for default processing. Set handled to true to cancel the key_press event.

handled() [2/2]

void xtd::forms::key_press_event_args::handled ( bool  handled )

inline

Sets a value indicating whether the key_press event was handled.

Parameters

handled

true if the event is handled; otherwise, false.

Remarks

If the event is not handled, it will be sent to the operating system for default processing. Set handled to true to cancel the key_press event.

key_char() [1/2]

char32_t xtd::forms::key_press_event_args::key_char ( ) const

inline

Gets the character corresponding to the key pressed.

Returns

The ASCII character that is composed. For example, if the user presses SHIFT + K, this property returns an uppercase K.

Remarks

Use the key_char property to sample keystrokes at run time and to modify keystrokes under special run-time circumstances. For example, you can use key_char to disable non-numeric keypresses when the user enters a ZIP code, change all alphabetical keypresses to uppercase in a data entry field, or monitor the keyboard or other key input device for specific key combinations.

You can get or set the following keys:

• a-z, A-Z.
• CTRL.
• Punctuation marks.
• Number keys, both across the top of the keyboard and on the numeric keypad.
• ENTER.

You cannot get or set the following keys:

• The TAB key
• INSERT and DELETE.
• HOME.
• END.
• PAGE UP and PAGE DOWN.
• F1-F2.
• CMD and ALT.
• Arrow keys.

Note

For information about how to detect any of the non-character keys mentioned above, see the key_event_args class.

key_char() [2/2]

void xtd::forms::key_press_event_args::key_char ( char32_t  key_char )

inline

Sets the character corresponding to the key pressed.

Parameters

key_char

The ASCII character that is composed. For example, if the user presses SHIFT + K, this property returns an uppercase K.

Remarks

Use the key_char property to sample keystrokes at run time and to modify keystrokes under special run-time circumstances. For example, you can use key_char to disable non-numeric keypresses when the user enters a ZIP code, change all alphabetical keypresses to uppercase in a data entry field, or monitor the keyboard or other key input device for specific key combinations.

You can get or set the following keys:

• a-z, A-Z.
• CTRL.
• Punctuation marks.
• Number keys, both across the top of the keyboard and on the numeric keypad.
• ENTER.

You cannot get or set the following keys:

• The TAB key
• INSERT and DELETE.
• HOME.
• END.
• PAGE UP and PAGE DOWN.
• F1-F2.
• CMD and ALT.
• Arrow keys.

Note

For information about how to detect any of the non-character keys mentioned above, see the key_event_args class.

---

The documentation for this class was generated from the following file:

• xtd.forms/include/xtd/forms/key_press_event_args.h