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 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 Assignment operator.
  92    * @SINCE_1_2.36
  93    * @param[in] rhs A reference to the copied handle
  94    * @return A reference to this
  95    */
  96   KeyEvent& operator=( const KeyEvent& rhs );
  97
  98   /**
  99    * @brief Destructor.
 100    * @SINCE_1_0.0
 101    */
 102   ~KeyEvent();
 103
 104   /**
 105    * @brief Checks to see if Shift key modifier has been supplied.
 106    *
 107    * @SINCE_1_0.0
 108    * @return True if shift modifier
 109    */
 110   bool IsShiftModifier() const;
 111
 112   /**
 113    * @brief Checks to see if Ctrl (control) key modifier has been supplied.
 114    *
 115    * @SINCE_1_0.0
 116    * @return True if ctrl modifier
 117    */
 118   bool IsCtrlModifier() const;
 119
 120   /**
 121    * @brief Checks to see if Alt key modifier has been supplied.
 122    *
 123    * @SINCE_1_0.0
 124    * @return True if alt modifier
 125    */
 126   bool IsAltModifier() const;
 127
 128   // Data
 129
 130   /**
 131    * @brief Name given to the key pressed.
 132    */
 133   std::string keyPressedName;
 134
 135   /**
 136    * @brief The actual string returned that should be used for input editors.
 137    */
 138   std::string keyPressed;
 139
 140   /**
 141    * @brief Keycode for the key pressed.
 142    *
 143    * @remarks We recommend not to use this key code value
 144    * directly because its meaning might be changed in the future. Currently, it means a
 145    * platform-specific key code. You need to use IsKey() to know what a key event means
 146    * instead of direct comparison of key code value.
 147    */
 148   int  keyCode;
 149
 150   /**
 151    * @brief special keys like shift, alt and control which modify the next key pressed.
 152    */
 153   int  keyModifier;
 154
 155   /**
 156    * @brief The time (in ms) that the key event occurred.
 157    */
 158   unsigned long time;
 159
 160   /**
 161    * @brief State of the key event.
 162    *
 163    * @see State
 164    */
 165   State state;
 166
 167 };
 168
 169 /**
 170  * @}
 171  */
 172 } // namespace Dali
 173
 174 #endif // __DALI_KEY_EVENT_H__