xtd - Reference Guide  0.1.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Public Member Functions | List of all members
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.

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_charThe 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
handledtrue 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_charThe 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: