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

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