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