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_9.27
  68    */
  69   enum State
  70   {
  71     DOWN,        ///< Key down @SINCE_1_9.27
  72     UP,          ///< Key up @SINCE_1_9.27
  73   };
  74
  75   /**
  76    * @brief An uninitialized KeyEvent instance.
  77    *
  78    * Calling member functions with an uninitialized KeyEvent handle is not allowed.
  79    * @SINCE_1_0.0
  80    */
  81   KeyEvent();
  82
  83   /**
  84    * @brief Copy constructor.
  85    * @SINCE_1_2.36
  86    * @param[in] rhs A reference to the copied handle
  87    */
  88   KeyEvent( const KeyEvent& rhs );
  89
  90   /**
  91    * @brief Move constructor.
  92    *
  93    * @SINCE_1_9.27
  94    * @param[in] rhs A reference to the moved handle
  95    */
  96   KeyEvent( KeyEvent&& rhs );
  97
  98   /**
  99    * @brief Copy assignment operator.
 100    * @SINCE_1_2.36
 101    * @param[in] rhs A reference to the copied handle
 102    * @return A reference to this
 103    */
 104   KeyEvent& operator=( const KeyEvent& rhs );
 105
 106   /**
 107    * @brief Move assignment operator.
 108    *
 109    * @SINCE_1_9.27
 110    * @param[in] rhs A reference to the moved handle
 111    * @return A reference to this
 112    */
 113   KeyEvent& operator=( KeyEvent&& rhs );
 114
 115   /**
 116    * @brief Destructor.
 117    * @SINCE_1_0.0
 118    */
 119   ~KeyEvent();
 120
 121   /**
 122    * @brief Checks to see if Shift key modifier has been supplied.
 123    *
 124    * @SINCE_1_0.0
 125    * @return True if shift modifier
 126    */
 127   bool IsShiftModifier() const;
 128
 129   /**
 130    * @brief Checks to see if Ctrl (control) key modifier has been supplied.
 131    *
 132    * @SINCE_1_0.0
 133    * @return True if ctrl modifier
 134    */
 135   bool IsCtrlModifier() const;
 136
 137   /**
 138    * @brief Checks to see if Alt key modifier has been supplied.
 139    *
 140    * @SINCE_1_0.0
 141    * @return True if alt modifier
 142    */
 143   bool IsAltModifier() const;
 144
 145   /**
 146    * @brief Get the key compose string.
 147    *
 148    * @SINCE_1_9.27
 149    * @return The compose string
 150    */
 151   const std::string& GetCompose() const;
 152
 153   /**
 154    * @brief Get the device name the key event originated from.
 155    *
 156    * @SINCE_1_9.27
 157    * @return The device name
 158    */
 159   const std::string& GetDeviceName() const;
 160
 161   /**
 162    * @brief Get the device class the key event originated from.
 163    *
 164    * The device class type is classification type of the input device of event received
 165    * @SINCE_1_2.60
 166    * @return The type of the device class
 167    */
 168   Device::Class::Type GetDeviceClass() const;
 169
 170   /**
 171    * @brief Get the device subclass the key event originated from.
 172    *
 173    * The device subclass type is subclassification type of the input device of event received.
 174    * @SINCE_1_2.60
 175    * @return The type of the device subclass
 176    */
 177   Device::Subclass::Type GetDeviceSubclass() const;
 178
 179   /**
 180    * @brief Get the name given to the key pressed or command from the IMF
 181    *
 182    * @SINCE_1_9.27
 183    * @return The name given to the key pressed.
 184    */
 185   const std::string& GetKeyName() const;
 186
 187   /**
 188    * @brief Get the actual string of input characters that should be used for input editors.
 189    *
 190    * @SINCE_1_9.27
 191    * @return The actual string of input characters
 192    */
 193   const std::string& GetKeyString() const;
 194
 195   /**
 196    * @brief Gets the logical key string.
 197    *
 198    * For example, when the user presses 'shift' key and '1' key together, the logical key is "exclamation".
 199    * Plus, the key name is "1", and the key string is "!".
 200    *
 201    * @SINCE_1_9.27
 202    * @return The logical key symbol
 203    */
 204   const std::string& GetLogicalKey() const;
 205
 206   /**
 207    * @brief Get the unique key code for the key pressed.
 208    *
 209    * @SINCE_1_9.27
 210    * @return The unique key code for the key pressed
 211    *
 212    * @remarks We recommend not to use this key code value directly because its meaning
 213    * might be changed in the future. Currently, it means a platform-specific key code.
 214    * You need to use IsKey() to know what a key event means instead of direct comparison
 215    * of key code value.
 216    */
 217   int32_t GetKeyCode() const;
 218
 219   /**
 220    * @brief Return the key modifier for special keys like Shift, Alt and Ctrl which modify the next key pressed.
 221    *
 222    * @SINCE_1_9.27
 223    * @return The key modifier
 224    */
 225   int32_t GetKeyModifier() const;
 226
 227   /**
 228    * @brief Get the time (in ms) that the key event occurred.
 229    *
 230    * @SINCE_1_9.27
 231    * @return The time (in ms)
 232    */
 233   unsigned long GetTime() const;
 234
 235   /**
 236    * @brief Get the state of the key event.
 237    *
 238    * @see State
 239    *
 240    * @SINCE_1_9.27
 241    * @return The state of the key event
 242    */
 243   State GetState() const;
 244
 245 public: // Not intended for application developers
 246
 247   /// @cond internal
 248   /**
 249    * @brief This constructor is used internally to Create an initialized KeyEvent handle.
 250    *
 251    * @SINCE_1_9.27
 252    * @param[in] keyEvent A pointer to a newly allocated Dali resource
 253    */
 254   explicit DALI_INTERNAL KeyEvent( Internal::KeyEvent* keyEvent );
 255   /// @endcond
 256 };
 257
 258 /**
 259  * @}
 260  */
 261 } // namespace Dali
 262
 263 #endif // DALI_KEY_EVENT_H