dali/public-api/events/key-event.h

   1 #ifndef DALI_KEY_EVENT_H
   2 #define DALI_KEY_EVENT_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <string>
  23 #include <cstdint> // int32_t
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/common/dali-common.h>
  27 #include <dali/public-api/object/base-handle.h>
  28 #include <dali/public-api/events/device.h>
  29
  30 namespace Dali
  31 {
  32
  33 namespace Internal DALI_INTERNAL
  34 {
  35 class KeyEvent;
  36 }
  37
  38 /**
  39  * @addtogroup dali_core_events
  40  * @{
  41  */
  42
  43 /**
  44  * @brief The key event class is used to store a key press.
  45  *
  46  * It facilitates processing of these key presses and passing to other
  47  * libraries like Toolkit. The keyString is the actual character you
  48  * might want to display while the key name is just a descriptive
  49  * name.  There is a key modifier which relates to keys like alt,
  50  * shift and control functions are supplied to check if they have been
  51  * pressed.
  52  *
  53  * Currently KeyEvent is also being used to relay messages from the
  54  * IMF(Input Method Framework) keyboard to the internal core. In future IMF may communicate via its own
  55  * module.
  56  * @SINCE_1_0.0
  57  */
  58 class DALI_CORE_API KeyEvent : public BaseHandle
  59 {
  60
  61 public:
  62
  63   // Enumerations
  64
  65   /**
  66    * @brief Enumeration for specifying the state of the key event.
  67    * @SINCE_1_0.0
  68    */
  69   enum State
  70   {
  71     Down,        ///< Key down @SINCE_1_0.0
  72     Up,          ///< Key up @SINCE_1_0.0
  73     Last
  74   };
  75
  76   /**
  77    * @brief An uninitialized KeyEvent instance.
  78    *
  79    * Calling member functions with an uninitialized KeyEvent handle is not allowed.
  80    * @SINCE_1_0.0
  81    */
  82   KeyEvent();
  83
  84   /**
  85    * @brief Copy constructor.
  86    * @SINCE_1_2.36
  87    * @param[in] rhs A reference to the copied handle
  88    */
  89   KeyEvent( const KeyEvent& rhs );
  90
  91   /**
  92    * @brief Move constructor.
  93    *
  94    * @SINCE_1_9.27
  95    * @param[in] rhs A reference to the moved handle
  96    */
  97   KeyEvent( KeyEvent&& rhs );
  98
  99   /**
 100    * @brief Copy assignment operator.
 101    * @SINCE_1_2.36
 102    * @param[in] rhs A reference to the copied handle
 103    * @return A reference to this
 104    */
 105   KeyEvent& operator=( const KeyEvent& rhs );
 106
 107   /**
 108    * @brief Move assignment operator.
 109    *
 110    * @SINCE_1_9.27
 111    * @param[in] rhs A reference to the moved handle
 112    * @return A reference to this
 113    */
 114   KeyEvent& operator=( KeyEvent&& rhs );
 115
 116   /**
 117    * @brief Destructor.
 118    * @SINCE_1_0.0
 119    */
 120   ~KeyEvent();
 121
 122   /**
 123    * @brief Checks to see if Shift key modifier has been supplied.
 124    *
 125    * @SINCE_1_0.0
 126    * @return True if shift modifier
 127    */
 128   bool IsShiftModifier() const;
 129
 130   /**
 131    * @brief Checks to see if Ctrl (control) key modifier has been supplied.
 132    *
 133    * @SINCE_1_0.0
 134    * @return True if ctrl modifier
 135    */
 136   bool IsCtrlModifier() const;
 137
 138   /**
 139    * @brief Checks to see if Alt key modifier has been supplied.
 140    *
 141    * @SINCE_1_0.0
 142    * @return True if alt modifier
 143    */
 144   bool IsAltModifier() const;
 145
 146   /**
 147    * @brief Get the key compose string.
 148    *
 149    * @SINCE_1_9.27
 150    * @return The compose string
 151    */
 152   const std::string& GetCompose() const;
 153
 154   /**
 155    * @brief Get the device name the key event originated from.
 156    *
 157    * @SINCE_1_9.27
 158    * @return The device name
 159    */
 160   const std::string& GetDeviceName() const;
 161
 162   /**
 163    * @brief Get the device class the key event originated from.
 164    *
 165    * The device class type is classification type of the input device of event received
 166    * @SINCE_1_2.60
 167    * @return The type of the device class
 168    */
 169   Device::Class::Type GetDeviceClass() const;
 170
 171   /**
 172    * @brief Get the device subclass the key event originated from.
 173    *
 174    * The device subclass type is subclassification type of the input device of event received.
 175    * @SINCE_1_2.60
 176    * @return The type of the device subclass
 177    */
 178   Device::Subclass::Type GetDeviceSubclass() const;
 179
 180   /**
 181    * @brief Get the name given to the key pressed or command from the IMF
 182    *
 183    * @SINCE_1_9.27
 184    * @return The name given to the key pressed.
 185    */
 186   const std::string& GetKeyName() const;
 187
 188   /**
 189    * @brief Get the actual string of input characters that should be used for input editors.
 190    *
 191    * @SINCE_1_9.27
 192    * @return The actual string of input characters
 193    */
 194   const std::string& GetKeyString() const;
 195
 196   /**
 197    * @brief Gets the logical key string.
 198    *
 199    * For example, when the user presses 'shift' key and '1' key together, the logical key is "exclamation".
 200    * Plus, the key name is "1", and the key string is "!".
 201    *
 202    * @SINCE_1_9.27
 203    * @return The logical key symbol
 204    */
 205   const std::string& GetLogicalKey() const;
 206
 207   /**
 208    * @brief Get the unique key code for the key pressed.
 209    *
 210    * @SINCE_1_9.27
 211    * @return The unique key code for the key pressed
 212    *
 213    * @remarks We recommend not to use this key code value directly because its meaning
 214    * might be changed in the future. Currently, it means a platform-specific key code.
 215    * You need to use IsKey() to know what a key event means instead of direct comparison
 216    * of key code value.
 217    */
 218   int32_t GetKeyCode() const;
 219
 220   /**
 221    * @brief Return the key modifier for special keys like Shift, Alt and Ctrl which modify the next key pressed.
 222    *
 223    * @SINCE_1_9.27
 224    * @return The key modifier
 225    */
 226   int32_t GetKeyModifier() const;
 227
 228   /**
 229    * @brief Get the time (in ms) that the key event occurred.
 230    *
 231    * @SINCE_1_9.27
 232    * @return The time (in ms)
 233    */
 234   unsigned long GetTime() const;
 235
 236   /**
 237    * @brief Get the state of the key event.
 238    *
 239    * @see State
 240    *
 241    * @SINCE_1_9.27
 242    * @return The state of the key event
 243    */
 244   State GetState() const;
 245
 246 public: // Not intended for application developers
 247
 248   /// @cond internal
 249   /**
 250    * @brief This constructor is used internally to Create an initialized KeyEvent handle.
 251    *
 252    * @SINCE_1_9.27
 253    * @param[in] keyEvent A pointer to a newly allocated Dali resource
 254    */
 255   explicit DALI_INTERNAL KeyEvent( Internal::KeyEvent* keyEvent );
 256   /// @endcond
 257 };
 258
 259 /**
 260  * @}
 261  */
 262 } // namespace Dali
 263
 264 #endif // DALI_KEY_EVENT_H