scl/include/sclui.h

   1 /*
   2  * Copyright 2012-2013 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Flora License, Version 1.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://floralicense.org/license/
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  *
  16  */
  17
  18 #ifndef __SCL_UI_H__
  19 #define __SCL_UI_H__
  20
  21 #include "scltypes.h"
  22 #include "sclstructs.h"
  23 #include "scleventcallback.h"
  24
  25 //SCL_BEGIN_DECLS
  26
  27 namespace scl
  28 {
  29
  30 /* To use pimpl idiom */
  31 class CSCLUIImpl;
  32
  33 /**
  34  * @brief The base class to work as a soft-based keyboard
  35  *
  36  * This class implements all functions for working as a soft-based keyboard
  37  * In side of ISE developer, they can modify it by their requirements.
  38  */
  39 class CSCLUI
  40 {
  41 public:
  42     CSCLUI();
  43     ~CSCLUI();
  44
  45     /*
  46      * @brief This API initializes SCL library and creates new SCL context
  47      * @param[in] main_window a pointer to main window object
  48      * @param[in] parser_type decides which parser should be selected for parsing SCL UI resource file
  49      * @param[in] entry_filepath a file path to SCL's UI resource entry file
  50      * @return non-zero value is returned when successful
  51      */
  52     sclboolean init(sclwindow main_window, SCLParserType parser_type, const sclchar *entry_filepath);
  53
  54     /**
  55      * @brief This API requests SCL library to show the S/W keyboard on the screen
  56      * @param[in] auto_relocate Indicates whether the SCL library should relocate the keyboard window automatically
  57      *            When set to FALSE, the developer should move the window to its expected position.
  58      */
  59     //void show(sclboolean auto_relocate = TRUE);
  60     void show();
  61
  62     /**
  63      * @brief This API requests SCL library to hide the S/W keyboard from the screen
  64      * @param[in] ctx target SCL context
  65      */
  66     void hide();
  67
  68
  69     /**
  70      * @brief This API registers a callback interface, to handle the events generated by SCL library
  71      * @param[in] callback a pointer to ISCLEventCallback interface implementation class
  72      * @param[in] input_mode when given not NULL, this callback processes event on that input_mode only.
  73      */
  74     void set_ui_event_callback(ISCLUIEventCallback *callback, const sclchar *input_mode = NULL);
  75
  76     /**
  77      * @brief This API requests SCL library to rotate the window to given degree
  78      * @param[in] degree an SCLRotation value for rotating the keyboard
  79      * @return non-zero value is returned when successful
  80      */
  81     sclboolean set_rotation(SCLRotation degree);
  82
  83     /**
  84      * @brief This API returns the current rotation degree
  85      * @return current rotation value
  86      */
  87     SCLRotation get_rotation();
  88
  89     /**
  90      * @brief This API checks if the current display mode is portrait or landscape
  91      * @return current display mode
  92      */
  93     SCLDisplayMode get_display_mode();
  94
  95     /**
  96      * @brief This API request SCL library to change to given input mode
  97      * @param[in] input_mode the name of the desired input mode
  98      * @return non-zero value is returned when successful
  99      */
 100     sclboolean set_input_mode(const sclchar *input_mode);
 101
 102     /**
 103      * @brief This API retrieves the current input mode
 104      * @return a string pointer that indicates the name of current input mode
 105      */
 106     const sclchar* get_input_mode();
 107
 108     /**
 109      * @brief This API request SCL library to suspend screen updates
 110      * @param[in] pend whether to suspend screen updates
 111      */
 112     void set_update_pending(sclboolean pend);
 113
 114     /**
 115      * @brief This API request SCL library to change a specific key with user customized values, with different parameters
 116      * @param[in] custom_id the name of the key to be reset
 117      * @param[in] label the string to be displayed on the button
 118      * @param[in] label the file path to button's label image
 119      * @param[in] imagebg the file path to button's background image
 120      * @param[in] key_event a numeric value to be emitted when this button is clicked
 121      * @param[in] key_value a string value to be emitted when this button is clicked
 122      * @param[in] redraw whether to redraw the key right after updating detailed information
 123      * @return internal private key index
 124      */
 125     sclint set_private_key(const sclchar* custom_id, sclchar* label, sclchar* imagelabel[SCL_BUTTON_STATE_MAX], sclchar* imagebg[SCL_BUTTON_STATE_MAX], sclulong key_event, sclchar *key_value, sclboolean redraw);
 126
 127     /**
 128      * @brief This API request SCL library to reset a key to its original configuration
 129      * @param[in] custom_id the name of the key to be reset
 130      */
 131     void unset_private_key(const sclchar* custom_id);
 132
 133     /**
 134      * @brief This API request SCL library to enable a button with given ID
 135      * @param[in] custom_id the name of the key to be enabled
 136      * @param[in] enabled whether this button should be enabled or not
 137      */
 138     void enable_button(const sclchar* custom_id, sclboolean enabled);
 139
 140     /**
 141      * @brief This API sets the name of the current theme to change the look and feel of S/W keyboard
 142      * @param[in] themename the name of the theme to be applied
 143      * @return non-zero value is returned when successful
 144      */
 145     sclboolean set_cur_themename(const sclchar *themename);
 146
 147     /**
 148      * @brief This API sets the name of the desired predefined sub-layout, which changes only some part of current layout
 149      * @param[in] themename the name of the theme to be applied
 150      * @return non-zero value is returned when successful
 151      */
 152     sclboolean set_cur_sublayout(const sclchar *sub_layout_name);
 153
 154     /**
 155      * @brief This API retrieves the name of current selected sub-layout
 156      * @return the string pointer that indicates the name of current sub-layout
 157      */
 158     const sclchar* get_cur_sublayout();
 159
 160     /**
 161      * @brief This API sets the current shift state
 162      * @param[in] state the SCLShiftState value for desired shift state
 163      */
 164     void set_shift_state(SCLShiftState state);
 165
 166     /**
 167      * @brief This API retrieves the current shift state
 168      * @return current shift state
 169      */
 170     SCLShiftState get_shift_state();
 171
 172     /**
 173      * @brief This API notifies the SCL library that the application's focus was moved to another input context
 174      */
 175     void notify_app_focus_changed();
 176
 177     /**
 178      * @brief This API request SCL library to reset the timer, which closes all popup windows when expired
 179      */
 180     void reset_popup_timeout();
 181
 182     /**
 183      * @brief This API request SCL library to close all opened popup windows
 184      */
 185     void close_all_popups();
 186
 187     /*
 188      * @brief This API acquires the size of main window
 189      * @param[out] rect the geometry information of main window
 190      */
 191     SclRectangle get_main_window_rect();
 192
 193     /**
 194      * @brief This API retrieves the current input mode
 195      * @param[in] input_mode the name of the desired input mode
 196      * @param[in] display_mode desired display mode value
 197      * @return a size struct contains the input_mode's size in given display_mode
 198      */
 199     SclSize get_input_mode_size(const sclchar *input_mode, SCLDisplayMode display_mode);
 200
 201     /**
 202      * @brief This API acquires the screen size of current device
 203      * @param[out] width the x-axis size of screen
 204      * @param[out] height the y-axis size of screem
 205      */
 206     void get_screen_resolution(sclint *width, sclint *height);
 207
 208     /**
 209      * @brief This API request SCL library to scale the input value,
 210               by calculating the rate of target screen size and current screen size
 211      * @param[in] x the value that needs to be scaled
 212      * @return scaled value
 213      */
 214     scl16 get_scale_x(scl16 x);
 215
 216     /**
 217      * @brief This API request SCL library to scale the input value,
 218               by calculating the rate of target screen size and current screen size
 219      * @param[in] y the value that needs to be scaled
 220      * @return scaled value
 221      */
 222     scl16 get_scale_y(scl16 y);
 223
 224     /**
 225      * @brief This API returns the smaller scale rate, between x and y
 226      * @return scale rate
 227      */
 228     sclfloat get_scale_rate();
 229
 230     /**
 231      * @brief This API returns the number of current multi touch contexts,
 232      *        which means how many fingers are currently pressing the touch device
 233      * @return number of touch contexts
 234      */
 235     sclint get_multi_touch_context_num();
 236
 237     /**
 238      * @brief This API retrieves the descriptor for the nth multi touch context, for processing multi touch events
 239      * @param[in] seqorder the sequence order of currently requesting multi touch context
 240      * @param[out] desc a pointer to SclKeyEventDesc struct, to be filled with given multi touch context's detailed information
 241      * @return non-zero value is returned when successful
 242      */
 243     sclboolean get_multi_touch_event(sclint seqorder, SclUIEventDesc *desc);
 244
 245     /**
 246      * @brief This API requests SCL library to start working in debug mode
 247      */
 248     void set_debug_mode(SCLDebugMode mode);
 249
 250     /**
 251      * @brief This API retrieves the current debug mode of SCL library
 252      */
 253     SCLDebugMode get_debug_mode();
 254
 255     /**
 256      * @brief This API sets the timeout value for recognizing long press event
 257      * @param[in] msc the time before the system waits until it determines the press event is long press event
 258      * @return non-zero value is returned when successful
 259      */
 260     sclboolean set_longkey_duration(scllong msc);
 261
 262     /**
 263      * @brief This API sets the threshold value for recognizing long press event
 264      * @param[in] dist maximum distance, in pixels.
 265                   the move event should not go beyond this distance from its initial pressed ponit
 266      * @return non-zero value is returned when successful
 267      */
 268     sclboolean set_longkey_cancel_dist(sclshort dist);
 269
 270     /**
 271      * @brief This API sets the timeout value for emitting repeat key event
 272      * @param[in] msc the time that SCL library has to wait before emitting next repeat key even
 273      * @return non-zero value is returned when successful
 274      */
 275     sclboolean set_repeatkey_duration(scllong msc);
 276
 277     /**
 278      * @brief This API sets the timeout value for recognizing long press event, if current button supports hidden text popup
 279      * @param[in] msc the time before the system waits until it determines the press event is long press event
 280      * @return non-zero value is returned when successful
 281      */
 282     sclboolean set_autopoup_key_duration(scllong msc);
 283
 284     /**
 285      * @brief This API sets the timeout value before it reverts the ui feedback of button press event
 286      * @param[in] msc the time before the system waits until it resets the pressed key to its normal state
 287      * @return non-zero value is returned when successful
 288      */
 289     sclboolean set_button_delay_duration(scllong msc);
 290
 291     /**
 292      * @brief This API requests SCL library to enable/disable magnifier window
 293      * @param[in] enabled indicates whether mangifier window should be displayed or not
 294      */
 295     void enable_magnifier(sclboolean enabled);
 296
 297     /**
 298      * @brief This API requests SCL library to enable/disable sound feedback
 299      * @param[in] enabled indicates whether sound feedback should be played or not, when a key is pressed
 300      */
 301     void enable_sound(sclboolean enabled);
 302
 303     /**
 304      * @brief This API requests SCL library to enable/disable vibration feedback
 305      * @param[in] enabled indicates whether vibration feedback should be played or not, when a key is pressed
 306      */
 307     void enable_vibration(sclboolean enabled);
 308
 309     /**
 310      * @brief This API requests SCL library to enable/disable tts feedback
 311      * @param[in] enabled indicates whether tts feedback should be played or not, when a key is pressed
 312      */
 313     void enable_tts(sclboolean enabled);
 314
 315     /**
 316      * @brief This API requests SCL library to enable/disable shift multi touch action
 317      * @param[in] enabled indicates whether shift button should provide multi touch action
 318      */
 319     void enable_shift_multi_touch(sclboolean enabled);
 320
 321     /**
 322      * @brief This API requests SCL library to apply the touch offset adjustment
 323      * @param[in] enabled indicates whether the touch offset adjustment should applied or not
 324      */
 325     void enable_touch_offset(sclboolean enabled);
 326
 327     /**
 328      * @brief This API requests SCL library to ignore any events raised from the keyboard window
 329      * @param[in] enabled indicates whether the keyboard window should ignore any touch events it receives
 330      */
 331     void disable_input_events(sclboolean disabled);
 332
 333     /**
 334      * @brief This API requests SCL library to change the content of magnifier window that will be displayed
 335      * @param[in] touch_id indicates which multi touch context this customization should be applied to
 336      * @param[in] index indicates the index of magnifier window's label
 337      * @param[in] label the string to be displayed on the magnfier window
 338      */
 339     void set_custom_magnifier_label(scltouchdevice touch_id, sclint index, const sclchar* label);
 340
 341     /**
 342      * @brief This API requests SCL library to substitute a string with given one when displaying it
 343      * @param[in] original indicates the string that should be substituted from
 344      * @param[in] substitute indicates the string that should be substituted to
 345      */
 346     void set_string_substitution(const sclchar *original, const sclchar *substitute);
 347
 348     /**
 349      * @brief This API requests SCL library to reset substitution for the given string
 350      * @param[in] original indicates the string that was registered to be substituted from
 351      */
 352     void unset_string_substitution(const sclchar *original);
 353
 354     sclint get_caps_mode();
 355     void set_caps_mode(sclint);
 356 private:
 357     CSCLUIImpl *m_impl;
 358 };
 359
 360 }
 361
 362 //SCL_END_DECLS
 363
 364 #endif //__SCL_CORE_H__