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

   1 #ifndef __DALI_KEY_EVENT_H__
   2 #define __DALI_KEY_EVENT_H__
   3
   4 /*
   5  * Copyright (c) 2018 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/events/device.h>
  28
  29 namespace Dali
  30 {
  31 /**
  32  * @addtogroup dali_core_events
  33  * @{
  34  */
  35
  36 /**
  37  * @brief The key event structure is used to store a key press.
  38  *
  39  * It facilitates processing of these key presses and passing to other
  40  * libraries like Toolkit. The keyString is the actual character you
  41  * might want to display while the key name is just a descriptive
  42  * name.  There is a key modifier which relates to keys like alt,
  43  * shift and control functions are supplied to check if they have been
  44  * pressed.
  45  *
  46  * Currently KeyEvent is also being used to relay messages from the
  47  * IMF(Input Method Framework) keyboard to the internal core. In future IMF may communicate via its own
  48  * module.
  49  * @SINCE_1_0.0
  50  */
  51 struct DALI_CORE_API KeyEvent
  52 {
  53   // Enumerations
  54
  55   /**
  56    * @brief Enumeration for specifying the state of the key event.
  57    * @SINCE_1_0.0
  58    */
  59   enum State
  60   {
  61     Down,        ///< Key down @SINCE_1_0.0
  62     Up,          ///< Key up @SINCE_1_0.0
  63     Last
  64   };
  65
  66   /**
  67    * @brief Default constructor.
  68    * @SINCE_1_0.0
  69    */
  70   KeyEvent();
  71
  72   /**
  73    * @brief Constructor.
  74    *
  75    * @SINCE_1_0.0
  76    * @param[in] keyName The name of the key pressed or command from the IMF, if later then the some following parameters will be needed
  77    * @param[in] keyString A string of input characters or key pressed
  78    * @param[in] keyCode The unique key code for the key pressed
  79    * @param[in] keyModifier The key modifier for special keys like shift and alt
  80    * @param[in] timeStamp The time (in ms) that the key event occurred
  81    * @param[in] keyState The state of the key event
  82    */
  83   KeyEvent(const std::string& keyName, const std::string& keyString, int32_t keyCode, int32_t keyModifier, unsigned long timeStamp, const State& keyState);
  84
  85   /**
  86    * @brief Copy constructor.
  87    * @SINCE_1_2.36
  88    * @param[in] rhs A reference to the copied handle
  89    */
  90   KeyEvent( const KeyEvent& rhs );
  91
  92   /**
  93    * @brief Assignment operator.
  94    * @SINCE_1_2.36
  95    * @param[in] rhs A reference to the copied handle
  96    * @return A reference to this
  97    */
  98   KeyEvent& operator=( const KeyEvent& rhs );
  99
 100   /**
 101    * @brief Destructor.
 102    * @SINCE_1_0.0
 103    */
 104   ~KeyEvent();
 105
 106   /**
 107    * @brief Checks to see if Shift key modifier has been supplied.
 108    *
 109    * @SINCE_1_0.0
 110    * @return True if shift modifier
 111    */
 112   bool IsShiftModifier() const;
 113
 114   /**
 115    * @brief Checks to see if Ctrl (control) key modifier has been supplied.
 116    *
 117    * @SINCE_1_0.0
 118    * @return True if ctrl modifier
 119    */
 120   bool IsCtrlModifier() const;
 121
 122   /**
 123    * @brief Checks to see if Alt key modifier has been supplied.
 124    *
 125    * @SINCE_1_0.0
 126    * @return True if alt modifier
 127    */
 128   bool IsAltModifier() const;
 129
 130   /**
 131    * @brief Get the key compose string.
 132    *
 133    * @SINCE_1_3.22
 134    * @return The compose string
 135    */
 136   std::string GetCompose() const;
 137
 138   /**
 139    * @brief Get the device name the key event originated from.
 140    *
 141    * @SINCE_1_2.60
 142    * @return The device name
 143    */
 144   std::string GetDeviceName() const;
 145
 146   /**
 147    * @brief Get the device class the key event originated from.
 148    *
 149    * The device class type is classification type of the input device of event received
 150    * @SINCE_1_2.60
 151    * @return The type of the device class
 152    */
 153   Device::Class::Type GetDeviceClass() const;
 154
 155   /**
 156    * @brief Get the device subclass the key event originated from.
 157    *
 158    * The device subclass type is subclassification type of the input device of event received.
 159    * @SINCE_1_2.60
 160    * @return The type of the device subclass
 161    */
 162   Device::Subclass::Type GetDeviceSubclass() const;
 163
 164   // Data
 165
 166   /**
 167    * @brief Name given to the key pressed.
 168    */
 169   std::string keyPressedName;
 170
 171   /**
 172    * @brief The actual string returned that should be used for input editors.
 173    */
 174   std::string keyPressed;
 175
 176   /**
 177    * @brief Keycode for the key pressed.
 178    *
 179    * @remarks We recommend not to use this key code value
 180    * directly because its meaning might be changed in the future. Currently, it means a
 181    * platform-specific key code. You need to use IsKey() to know what a key event means
 182    * instead of direct comparison of key code value.
 183    */
 184   int32_t keyCode;
 185
 186   /**
 187    * @brief special keys like shift, alt and control which modify the next key pressed.
 188    */
 189   int32_t keyModifier;
 190
 191   /**
 192    * @brief The time (in ms) that the key event occurred.
 193    */
 194   unsigned long time;
 195
 196   /**
 197    * @brief State of the key event.
 198    *
 199    * @see State
 200    */
 201   State state;
 202
 203 };
 204
 205 /**
 206  * @}
 207  */
 208 } // namespace Dali
 209
 210 #endif // __DALI_KEY_EVENT_H__