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] surface wayland surface
  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    * @param[in] text the text to commit
 139    */
 140   virtual void CommitString( Seat* seat, uint32_t serial, const char *text ) = 0;
 141
 142   /**
 143    * @brief  Notify when the cursor or anchor position should be modified.
 144    * This event should be handled as part of a following commit_string event.
 145    *
 146    * @param[in] seat the seat that produced the event
 147    * @param[in] index relative to the current cursor (in bytes).
 148    * @param[in] anchor cursor anchor
 149    */
 150   virtual void CursorPosition( Seat* seat, int32_t index, int32_t anchor) = 0;
 151
 152   /**
 153    * @brief  Notify when the text around the current cursor position should be deleted.
 154    * Index is relative to the current cursor (in bytes).
 155    * Length is the length of deleted text (in bytes).
 156    * This event should be handled as part of a following commit_string event.
 157    * @param[in] seat the seat that produced the event
 158    * @param[in] index relative to the current cursor (in bytes).
 159    * @param[in] length length of the text to be deleted
 160    */
 161   virtual void DeleteSurroundingText( Seat* seat, int32_t index,  uint32_t length ) = 0;
 162
 163
 164   /**
 165    * @brief Notify when a key event was sent
 166    * Key events should not be used for normal text input operations,
 167    * which should be done with commit_string, delete_surrounding_text, etc.
 168    * The key event follows the wl_keyboard key event convention.
 169    * Sym is a XKB keysym, state a wl_keyboard key_state.
 170    * Modifiers are a mask for effective modifiers
 171    * (where the modifier indices are set by the modifiers_map event)
 172    * @param[in] seat the seat that produced the event
 173    * @param[in] serial of the latest known text input state
 174    * @param[in] time time stamp
 175    * @param[in] sym symbol
 176    * @param[in] state state
 177    * @param[in] modifiers modifiers
 178    */
 179   virtual void Keysym( Seat* seat,
 180                        uint32_t serial,
 181                        uint32_t time,
 182                        uint32_t sym,
 183                        uint32_t state,
 184                        uint32_t modifiers) = 0;
 185
 186   /**
 187    * @brief Set the language of the input text.
 188    * @param[in] seat the seat that produced the event
 189    * @param[in] serial of the latest known text input state
 190    * @param[in] language The "language" argument is a RFC-3066 format language tag.
 191    */
 192   virtual void Language( Seat* seat, uint32_t serial, const char *language ) = 0;
 193
 194   /**
 195    * @brief Set the text direction of input text.
 196    *
 197    * It is mainly needed for showing input cursor on correct side of the
 198    * editor when there is no input yet done and making sure neutral
 199    * direction text is laid out properly.
 200     *
 201    * @param[in] seat the seat that produced the event
 202    * @param[in] serial of the latest known text input state
 203    * @param[in] direction ( see text_direction enum in wayland-extension/protocol/text.xml )
 204    */
 205   virtual void TextDirection( Seat* seat, uint32_t serial, uint32_t direction ) = 0;
 206
 207   /**
 208    * @brief Notify when the input panels ask to select the characters
 209    * from the start cursor position to the end cursor position.
 210    *
 211    * @param[in] seat the seat that produced the event
 212    * @param[in] serial of the latest known text input state
 213    * @param[in] start start index
 214    * @param[in] end end index
 215    */
 216   virtual void SelectionRegion( Seat* seat, uint32_t serial, int32_t start, int32_t end) = 0;
 217
 218   /**
 219    * @brief Notify when the input panels ask to send private command
 220    * @param[in] seat the seat that produced the event
 221    * @param[in] serial of the latest known text input state
 222    * @param[in] command private command string
 223    */
 224   virtual void PrivateCommand( Seat* seat, uint32_t serial, const char *command) = 0;
 225
 226   /**
 227    * @brief Notify when the geometry of the input panel changed.
 228    * @param[in] seat the seat that produced the event
 229    * @param[in] x position
 230    * @param[in] y position
 231    * @param[in] width panel width
 232    * @param[in] height panel height
 233    */
 234   virtual void InputPanelGeometry( Seat* seat,
 235                                    uint32_t x,
 236                                    uint32_t y,
 237                                    uint32_t width,
 238                                    uint32_t height) = 0;
 239
 240   /**
 241    * @brief Notify when the input panels ask to send input panel data
 242    * Not sure what this is for exactly
 243    * @param[in] seat the seat that produced the event
 244    * @param[in] serial of the latest known text input state
 245    * @param[in] data input panel data
 246    * @param[in] dataLength data length
 247    *
 248    */
 249   virtual void InputPanelData( Seat* seat,
 250                                uint32_t serial,
 251                                const char* data,
 252                                uint32_t dataLength ) = 0;
 253
 254 public: // Helper functions used to find the seat associated with the keyboard/pointer/touch device
 255
 256   /**
 257    * @brief get the seat that contains the text input interface
 258    * @param[in] textInput wayland textinput interface
 259    * @return the seat the keyboard belongs to
 260    */
 261   virtual Seat* GetSeat( const WlTextInput* textInput) = 0;
 262
 263 protected:
 264
 265   /**
 266    * @brief Constructor
 267    */
 268   TextInputInterface()
 269   {
 270   }
 271
 272   /**
 273    * @brief destructor
 274    */
 275   virtual ~TextInputInterface()
 276   {
 277   }
 278
 279   // Undefined copy constructor.
 280   TextInputInterface( const TextInputInterface& );
 281
 282   // Undefined assignment operator.
 283   TextInputInterface& operator=( const TextInputInterface& );
 284 };
 285
 286
 287
 288 } // Internal
 289 } // Adaptor
 290 } // Dali
 291
 292 #endif  //__DALI_INTERNAL_ADAPTOR_TEXT_INPUT_INTERFACE_H__