adaptors/wayland/input/text/text-input-interface.h

   1 #ifndef __DALI_INTERNAL_ADAPTOR_TEXT_INPUT_INTERFACE_H__
   2 #define __DALI_INTERNAL_ADAPTOR_TEXT_INPUT_INTERFACE_H__
   3
   4 /*
   5  * Copyright (c) 2016 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 <wl-types.h>
  23
  24
  25 namespace Dali
  26 {
  27
  28 namespace Internal
  29 {
  30
  31 namespace Adaptor
  32 {
  33
  34 class Seat;
  35
  36 /**
  37  * @brief interface used to wrap events that come form the Tizen specific Text input interface (wl_text_input_listener).
  38  *
  39  * wayland-extension/protocol/text.xml has been used for the callback descriptions
  40  *
  41  * The events are for from a specific seat & surface combination.
  42  *
  43  * Once the text input interface is enabled, all key presses come from it
  44  * except for specifc hardware keys ( volume up / down ) which still get routed
  45  * to the wl_keyboard interface.
  46  *
  47  *
  48  */
  49 class TextInputInterface
  50 {
  51
  52 public:
  53
  54   /**
  55    * @brief Notify the text input has received focus. Typically in response to an activate request.
  56    *
  57    * @param[in] seat the seat that produced the event
  58    * @param[in] serial  serial number
  59    */
  60   virtual void Enter( Seat* seat, WlSurface* surface ) = 0;
  61
  62   /**
  63    * @brief Notify the text input when it lost focus.
  64    * Either in response to a deactivate request or when the assigned surface lost focus or was destroyed.
  65    * @param[in] seat the seat that produced the event
  66    */
  67   virtual void Leave( Seat* seat ) = 0;
  68
  69   /**
  70    * @brief key modifiers names.
  71    * The position in the array is the index of the modifier as used in the modifiers
  72    * bitmask in the keysym event
  73    * @param[in] seat the seat that produced the event
  74    * @param[in] map modifier map
  75    */
  76   virtual void ModifiersMap( Seat* seat, WlArray *map ) = 0;
  77
  78   /**
  79    * @brief called when the input panel state changes
  80    * @param[in] seat the seat that produced the event
  81    * @param[in] state 0 == panel hidden, 1 == panel visible
  82    */
  83   virtual void InputPanelState( Seat* seat, uint32_t state ) = 0;
  84
  85   /**
  86    * @brief pre-edit string
  87    * Notify when a new composing text (pre-edit) should be set around the
  88    * current cursor position. Any previously set composing text should
  89    * be removed.
  90    * The commit text can be used to replace the preedit text on reset
  91    * (for example on unfocus).
  92    *
  93    * The text input should also handle all preedit_style and preedit_cursor
  94    * events occurring directly before preedit_string.
  95    * @param[in] seat the seat that produced the event
  96    * @param[in] serial of the latest known text input state
  97    * @param [in] text text
  98    * @param [in] commit  commit text
  99    *
 100    */
 101   virtual void PreeditString( Seat* seat, uint32_t serial, const char *text, const char *commit ) = 0;
 102
 103   /**
 104    * @brief Set styling information on composing text.
 105    * The style is applied for length bytes from index relative to the beginning of the composing
 106    * text (as byte offset). Multiple styles can be applied to a composing
 107    * text by sending multiple preedit_styling events.
 108    * this event occurs with a preedit_string event.
 109    *
 110    * @param[in] seat the seat that produced the event
 111    * @param[in] index start of the text style
 112    * @param[in] length of the text style
 113    * @param[in] style text style
 114    */
 115   virtual void PreeditStyling( Seat* seat, uint32_t index, uint32_t length, uint32_t style ) = 0;
 116
 117   /**
 118    * @brief Set the cursor position inside the composing text (as byte offset)
 119    * relative to the start of the composing text.
 120    * When index is a negative number no cursor is shown.
 121    *
 122    * this event occurs with a preedit_string event.
 123    * @param[in] seat the seat that produced the event
 124    * @param[in] index start of the text style
 125    */
 126   virtual void PreeditCursor( Seat* seat, int32_t index ) = 0;
 127
 128   /**
 129    * @brief Notify when text should be inserted into a DALi text control.
 130    * The text to commit could be either just a single character after a key press or the
 131    * result of some composing (pre-edit). It could be also an empty text
 132    * when some text should be removed (see delete_surrounding_text) or when
 133    * the input cursor should be moved (see cursor_position).
 134    * Any previously set composing text should be removed.
 135    *
 136    * @param[in] seat the seat that produced the event
 137    * @param[in] serial of the latest known text input state
 138    */
 139   virtual void CommitString( Seat* seat, uint32_t serial, const char *text ) = 0;
 140
 141   /**
 142    * @brief  Notify when the cursor or anchor position should be modified.
 143    * This event should be handled as part of a following commit_string event.
 144    *
 145    * @param[in] seat the seat that produced the event
 146    * @param[in] index relative to the current cursor (in bytes).
 147    * @param[in] anchor cursor anchor
 148    */
 149   virtual void CursorPosition( Seat* seat, int32_t index, int32_t anchor) = 0;
 150
 151   /**
 152    * @brief  Notify when the text around the current cursor position should be deleted.
 153    * Index is relative to the current cursor (in bytes).
 154    * Length is the length of deleted text (in bytes).
 155    * This event should be handled as part of a following commit_string event.
 156    * @param[in] seat the seat that produced the event
 157    * @param[in] index relative to the current cursor (in bytes).
 158    * @param[in] length length of the text to be deleted
 159    */
 160   virtual void DeleteSurroundingText( Seat* seat, int32_t index,  uint32_t length ) = 0;
 161
 162
 163   /**
 164    * @brief Notify when a key event was sent
 165    * Key events should not be used for normal text input operations,
 166    * which should be done with commit_string, delete_surrounding_text, etc.
 167    * The key event follows the wl_keyboard key event convention.
 168    * Sym is a XKB keysym, state a wl_keyboard key_state.
 169    * Modifiers are a mask for effective modifiers
 170    * (where the modifier indices are set by the modifiers_map event)
 171    * @param[in] seat the seat that produced the event
 172    * @param[in] serial of the latest known text input state
 173    */
 174   virtual void Keysym( Seat* seat,
 175                        uint32_t serial,
 176                        uint32_t time,
 177                        uint32_t sym,
 178                        uint32_t state,
 179                        uint32_t modifiers) = 0;
 180
 181   /**
 182    * @brief Set the language of the input text.
 183    * @param[in] seat the seat that produced the event
 184    * @param[in] serial of the latest known text input state
 185    * @param[in] The "language" argument is a RFC-3066 format language tag.
 186    */
 187   virtual void Language( Seat* seat, uint32_t serial, const char *language ) = 0;
 188
 189   /**
 190    * @brief Set the text direction of input text.
 191    *
 192    * It is mainly needed for showing input cursor on correct side of the
 193    * editor when there is no input yet done and making sure neutral
 194    * direction text is laid out properly.
 195     *
 196    * @param[in] seat the seat that produced the event
 197    * @param[in] direction ( see text_direction enum in wayland-extension/protocol/text.xml )
 198    */
 199   virtual void TextDirection( Seat* seat, uint32_t serial, uint32_t direction ) = 0;
 200
 201   /**
 202    * @brief Notify when the input panels ask to select the characters
 203    * from the start cursor position to the end cursor position.
 204    *
 205    * @param[in] seat the seat that produced the event
 206    * @param[in] serial of the latest known text input state
 207    * @param[in] start index
 208    * @param[in] start index
 209    */
 210   virtual void SelectionRegion( Seat* seat, uint32_t serial, int32_t start, int32_t end) = 0;
 211
 212   /**
 213    * @brief Notify when the input panels ask to send private command
 214    * @param[in] seat the seat that produced the event
 215    * @param[in] serial of the latest known text input state
 216    * @param[in] start index
 217    */
 218   virtual void PrivateCommand( Seat* seat, uint32_t serial, const char *command) = 0;
 219
 220   /**
 221    * @ Notify when the geometry of the input panel changed.
 222    * @param[in] x position
 223    * @param[in] y position
 224    * @param[in] width panel width
 225    * @param[in] height panel height
 226    */
 227   virtual void InputPanelGeometry( Seat* seat,
 228                                    uint32_t x,
 229                                    uint32_t y,
 230                                    uint32_t width,
 231                                    uint32_t height) = 0;
 232
 233 public: // Helper functions used to find the seat associated with the keyboard/pointer/touch device
 234
 235   /**
 236    * @brief get the seat that contains the keyboard interface
 237    * @param[in] keyboard wayland keyboard interface
 238    * @return the seat the keyboard belongs to
 239    */
 240   virtual Seat* GetSeat( const WlTextInput* textInput) = 0;
 241
 242 protected:
 243
 244   /**
 245    * @brief Constructor
 246    */
 247   TextInputInterface()
 248   {
 249   }
 250
 251   /**
 252    * @brief destructor
 253    */
 254   virtual ~TextInputInterface()
 255   {
 256   }
 257
 258   // Undefined copy constructor.
 259   TextInputInterface( const TextInputInterface& );
 260
 261   // Undefined assignment operator.
 262   TextInputInterface& operator=( const TextInputInterface& );
 263 };
 264
 265
 266
 267 } // Internal
 268 } // Adaptor
 269 } // Dali
 270
 271 #endif  //__DALI_INTERNAL_ADAPTOR_TEXT_INPUT_INTERFACE_H__