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

   1 #ifndef __DALI_KEY_EVENT_H__
   2 #define __DALI_KEY_EVENT_H__
   3
   4 /*
   5  * Copyright (c) 2015 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
  27 namespace Dali
  28 {
  29 /**
  30  * @addtogroup dali_core_events
  31  * @{
  32  */
  33
  34 /**
  35  * @brief The key event structure is used to store a key press.
  36  *
  37  * It facilitates processing of these key presses and passing to other
  38  * libraries like Toolkit. The keyString is the actual character you
  39  * might want to display while the key name is just a descriptive
  40  * name.  There is a key modifier which relates to keys like alt,
  41  * shift and control functions are supplied to check if they have been
  42  * pressed.
  43  *
  44  * Currently KeyEvent is also being used to relay messages from the
  45  * IMF(Input Method Framework) keyboard to the internal core. In future IMF may communicate via its own
  46  * module.
  47  * @SINCE_1_0.0
  48  */
  49 struct DALI_IMPORT_API KeyEvent
  50 {
  51   // Enumerations
  52
  53   /**
  54    * @brief Enumeration for specifying the state of the key event.
  55    * @SINCE_1_0.0
  56    */
  57   enum State
  58   {
  59     Down,        ///< Key down @SINCE_1_0.0
  60     Up,          ///< Key up @SINCE_1_0.0
  61     Last
  62   };
  63
  64   /**
  65    * @brief Default constructor.
  66    * @SINCE_1_0.0
  67    */
  68   KeyEvent();
  69
  70   /**
  71    * @brief Constructor.
  72    *
  73    * @SINCE_1_0.0
  74    * @param[in] keyName The name of the key pressed or command from the IMF, if later then the some following parameters will be needed
  75    * @param[in] keyString A string of input characters or key pressed
  76    * @param[in] keyCode The unique key code for the key pressed
  77    * @param[in] keyModifier The key modifier for special keys like shift and alt
  78    * @param[in] timeStamp The time (in ms) that the key event occurred
  79    * @param[in] keyState The state of the key event
  80    */
  81   KeyEvent(const std::string& keyName, const std::string& keyString, int keyCode, int keyModifier, unsigned long timeStamp, const State& keyState);
  82
  83   /**
  84    * @brief Destructor.
  85    * @SINCE_1_0.0
  86    */
  87   ~KeyEvent();
  88
  89   /**
  90    * @brief Checks to see if Shift key modifier has been supplied.
  91    *
  92    * @SINCE_1_0.0
  93    * @return True if shift modifier
  94    */
  95   bool IsShiftModifier() const;
  96
  97   /**
  98    * @brief Checks to see if Ctrl (control) key modifier has been supplied.
  99    *
 100    * @SINCE_1_0.0
 101    * @return True if ctrl modifier
 102    */
 103   bool IsCtrlModifier() const;
 104
 105   /**
 106    * @brief Checks to see if Alt key modifier has been supplied.
 107    *
 108    * @SINCE_1_0.0
 109    * @return True if alt modifier
 110    */
 111   bool IsAltModifier() const;
 112
 113   // Data
 114
 115   /**
 116    * @brief Name given to the key pressed.
 117    */
 118   std::string keyPressedName;
 119
 120   /**
 121    * @brief The actual string returned that should be used for input editors.
 122    */
 123   std::string keyPressed;
 124
 125   /**
 126    * @brief Keycode for the key pressed.
 127    *
 128    * @remarks We recommend not to use this key code value
 129    * directly because its meaning might be changed in the future. Currently, it means a
 130    * platform-specific key code. You need to use IsKey() to know what a key event means
 131    * instead of direct comparison of key code value.
 132    */
 133   int  keyCode;
 134
 135   /**
 136    * @brief special keys like shift, alt and control which modify the next key pressed.
 137    */
 138   int  keyModifier;
 139
 140   /**
 141    * @brief The time (in ms) that the key event occurred.
 142    */
 143   unsigned long time;
 144
 145   /**
 146    * @brief State of the key event.
 147    *
 148    * @see State
 149    */
 150   State state;
 151
 152 };
 153
 154 /**
 155  * @}
 156  */
 157 } // namespace Dali
 158
 159 #endif // __DALI_KEY_EVENT_H__