xtd::forms::key_press_event_args Class Reference

Inheritance diagram for xtd::forms::key_press_event_args:

Definition

Provides data for the xtd::forms::control::key_press event.

Header

#include <xtd/forms/key_press_event_args> 

Namespace

xtd::forms

Library

xtd.forms

Remarks

A xtd::forms::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 xtd::forms::control::key_press event occurs when the user presses a key. Two events that are closely related to the xtd::forms::control::key_press event are xtd::forms::control::key_up and xtd::forms::control::key_down. The xtd::forms::control::key_down event precedes each xtd::forms::control::key_press event when the user presses a key, and a xtd::forms::control::key_up event occurs when the user releases a key. When the user holds down a key, duplicate xtd::forms::control::key_down and xtd::forms::control::key_press events occur each time the character repeats. One xtd::forms::control::key_up event is generated upon release.

With each xtd::forms::control::key_press event, a xtd::forms::key_press_event_args is passed. A key_event_args is passed with each xtd::forms::control::key_down and xtd::forms::control::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 xtd::forms::control::key_press event. This keeps the control from processing the key press.

Note

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

Examples

calculator.cpp, key_events.cpp, and numeric_text_box.cpp.

Public Constructors
	key_press_event_args ()=default
	Initializes a new instance of the KeyPressEventArgs class.
	key_press_event_args (char32 key_char)
	Initializes a new instance of the KeyPressEventArgs class.

Public Properties
bool	handled () const noexcept
	Gets a value indicating whether the xtd::forms::control::key_press event was handled.
void	handled (bool handled)
	Sets a value indicating whether the xtd::forms::control::key_press event was handled.
char32	key_char () const noexcept
	Gets the character corresponding to the key pressed.
void	key_char (char32 key_char)
	Sets the character corresponding to the key pressed.

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.
Public Member Functions inherited from xtd::event_args
	event_args ()=default
	Initializes a new instance of the event_args class.
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object.
virtual xtd::ustring	to_string () const noexcept
	Returns a sxd::ustring that represents the current object.
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.
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance.

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  key_char )

inlineexplicit

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

inlinenoexcept

Gets a value indicating whether the xtd::forms::control::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 xtd::forms::control::key_press event.

handled() [2/2]

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

inline

Sets a value indicating whether the xtd::forms::control::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 xtd::forms::control::key_press event.

key_char() [1/2]

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

inlinenoexcept

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  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