dali/devel-api/adaptor-framework/window-devel.h

   1 #ifndef DALI_WINDOW_DEVEL_H
   2 #define DALI_WINDOW_DEVEL_H
   3
   4 /*
   5  * Copyright (c) 2021 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 <memory>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/adaptor-framework/window-enumerations.h>
  26 #include <dali/public-api/adaptor-framework/window.h>
  27 #include <dali/public-api/common/vector-wrapper.h>
  28
  29 namespace Dali
  30 {
  31 class KeyEvent;
  32 class TouchEvent;
  33 class WheelEvent;
  34 class RenderTaskList;
  35 struct TouchPoint;
  36
  37 namespace DevelWindow
  38 {
  39
  40 typedef Signal<void()> EventProcessingFinishedSignalType; ///< Event Processing finished signal type
  41
  42 typedef Signal<void(const KeyEvent&)> KeyEventSignalType; ///< Key event signal type
  43
  44 typedef Signal<void(const TouchEvent&)> TouchEventSignalType; ///< Touch signal type
  45
  46 typedef Signal<void(const WheelEvent&)> WheelEventSignalType; ///< Touched signal type
  47
  48 typedef Signal<void(Window, bool)> VisibilityChangedSignalType; ///< Visibility changed signal type
  49
  50 typedef Signal<void(Window, WindowEffectState, WindowEffectType)> TransitionEffectEventSignalType; ///< Effect signal type and state
  51
  52 typedef Signal<void()> KeyboardRepeatSettingsChangedSignalType; ///< Keyboard repeat settings changed signal type
  53
  54 typedef Signal<void(const std::string&, const std::string&, const Property::Array&)> AuxiliaryMessageSignalType; ///< Auxiliary message signal type
  55
  56 /**
  57  * @brief Creates an initialized handle to a new Window.
  58  *
  59  * @param[in] surface Can be a window or pixmap.
  60  * @param[in] windowPosition The position and size of the Window
  61  * @param[in] name The Window title
  62  * @param[in] isTransparent Whether Window is transparent
  63  * @return A new window
  64  * @note This creates an extra window in addition to the default main window
  65 */
  66 DALI_ADAPTOR_API Window New(Any surface, PositionSize windowPosition, const std::string& name, bool isTransparent = false);
  67
  68 /**
  69  * @brief Creates an initialized handle to a new Window.
  70  *
  71  * @param[in] surface Can be a window or pixmap.
  72  * @param[in] windowPosition The position and size of the Window
  73  * @param[in] name The Window title
  74  * @param[in] className The Window class name
  75  * @param[in] isTransparent Whether Window is transparent
  76  * @note This creates an extra window in addition to the default main window
  77  * @return A new Window
  78  */
  79 DALI_ADAPTOR_API Window New(Any surface, PositionSize windowPosition, const std::string& name, const std::string& className, bool isTransparent = false);
  80
  81 /**
  82  * @brief Sets position and size of the window. This API guarantees that both moving and resizing of window will appear on the screen at once.
  83  *
  84  * @param[in] window The window instance
  85  * @param[in] positionSize The new window position and size
  86  */
  87 DALI_ADAPTOR_API void SetPositionSize(Window window, PositionSize positionSize);
  88
  89 /**
  90  * @brief Retrieve the window that the given actor is added to.
  91  *
  92  * @param[in] actor The actor
  93  * @return The window the actor is added to or an empty handle if the actor is not added to any window.
  94  */
  95 DALI_ADAPTOR_API Window Get(Actor actor);
  96
  97 /**
  98  * @brief This signal is emitted just after the event processing is finished.
  99  *
 100  * @param[in] window The window instance
 101  * @return The signal to connect to
 102  */
 103 DALI_ADAPTOR_API EventProcessingFinishedSignalType& EventProcessingFinishedSignal(Window window);
 104
 105 /**
 106  * @brief This signal is emitted when wheel event is received.
 107  *
 108  * A callback of the following type may be connected:
 109  * @code
 110  *   void YourCallbackName(const WheelEvent& event);
 111  * @endcode
 112  * @param[in] window The window instance
 113  * @return The signal to connect to
 114  */
 115 DALI_ADAPTOR_API WheelEventSignalType& WheelEventSignal(Window window);
 116
 117 /**
 118  * @brief This signal is emitted when the window is shown or hidden.
 119  *
 120  * A callback of the following type may be connected:
 121  * @code
 122  *   void YourCallbackName( Window window, bool visible );
 123  * @endcode
 124  * @param[in] window The window instance
 125  * @return The signal to connect to
 126  */
 127 DALI_ADAPTOR_API VisibilityChangedSignalType& VisibilityChangedSignal(Window window);
 128
 129 /**
 130  * @brief This signal is emitted for transition effect.
 131  *
 132  * The transition animation is appeared when the window is shown/hidden.
 133  * When the animation is started, START signal is emitted.
 134  * Then the animation is ended, END signal is emitted, too.
 135  * A callback of the following type may be connected:
 136  * @code
 137  *   void YourCallbackName( Window window, EffectState state, EffectType type );
 138  * @endcode
 139  * @param[in] window The window instance
 140  * @return The signal to connect to
 141  */
 142 DALI_ADAPTOR_API TransitionEffectEventSignalType& TransitionEffectEventSignal(Window window);
 143
 144 /**
 145  * @brief This signal is emitted just after the keyboard repeat setting is changed globally.
 146  *
 147  * @param[in] window The window instance
 148  * @return The signal to connect to
 149  */
 150 DALI_ADAPTOR_API KeyboardRepeatSettingsChangedSignalType& KeyboardRepeatSettingsChangedSignal(Window window);
 151
 152 /**
 153  * @brief This signal is emitted when window's auxiliary was changed then display server sent the message.
 154  *
 155  * Auxiliary message is sent by display server.
 156  * When client application added the window's auxiliary hint and if the auxiliary is changed,
 157  * display server send the auxiliary message.
 158  * Auxiliary message has the key, value and options.
 159  *
 160  * @param[in] window The window instance
 161  * @return The signal to connect to
 162  */
 163 DALI_ADAPTOR_API AuxiliaryMessageSignalType& AuxiliaryMessageSignal(Window window);
 164
 165 /**
 166  * @brief Sets parent window of the window.
 167  *
 168  * After setting that, these windows do together when raise-up, lower and iconified/deiconified.
 169  * Initially, the window is located on top of the parent. The window can go below parent by calling Lower().
 170  * If parent's window stack is changed by calling Raise() or Lower(), child windows are located on top of the parent again.
 171  *
 172  * @param[in] window The window instance
 173  * @param[in] parent The parent window instance
 174  */
 175 DALI_ADAPTOR_API void SetParent(Window window, Window parent);
 176
 177 /**
 178  * @brief Sets parent window of the window.
 179  *
 180  * After setting that, these windows do together when raise-up, lower and iconified/deiconified.
 181  * This function has the additional flag whether the child is located above or below of the parent.
 182  *
 183  * @param[in] window The window instance
 184  * @param[in] parent The parent window instance
 185  * @param[in] belowParent The flag is whether the child is located above or below of the parent.
 186  */
 187 DALI_ADAPTOR_API void SetParent(Window window, Window parent, bool belowParent);
 188
 189 /**
 190  * @brief Unsets parent window of the window.
 191  *
 192  * After unsetting, the window is disconnected his parent window.
 193  *
 194  * @param[in] window The window instance
 195  */
 196 DALI_ADAPTOR_API void Unparent(Window window);
 197
 198 /**
 199  * @brief Gets parent window of the window.
 200  *
 201  * @param[in] window The window instance
 202  * @return The parent window of the window
 203  */
 204 DALI_ADAPTOR_API Window GetParent(Window window);
 205
 206 /**
 207  * @brief Downcast sceneHolder to window
 208  *
 209  * @param[in] handle The handle need to downcast
 210  * @return The window cast from SceneHolder
 211  */
 212 DALI_ADAPTOR_API Window DownCast(BaseHandle handle);
 213
 214 /**
 215  * @brief Gets current orientation of the window.
 216  *
 217  * @param[in] window The window instance
 218  * @return The current window orientation if previously set, or none
 219  */
 220 DALI_ADAPTOR_API WindowOrientation GetCurrentOrientation(Window window);
 221
 222 /**
 223  * @brief Gets current physical orientation of the window.
 224  *
 225  * It means current physical rotation angle of the window.
 226  * If the height of the display device's area is greater than the width,
 227  * default current orientation is PORTRAIT and current physical orientation angle is 0.
 228  * If the width of the display device's area is greater than the height,
 229  * default current orientation is LANDSCAPE and current physical orientation angle is 0.
 230  *
 231  * @param[in] window The window instance
 232  * @return The current physical orientation degree of the window. It is one of them as 0, 90, 180 and 270.
 233  */
 234 DALI_ADAPTOR_API int GetPhysicalOrientation(Window window);
 235
 236 /**
 237  * @brief Sets available orientations of the window.
 238  *
 239  * This API is for setting several orientations one time.
 240  *
 241  * @param[in] window The window instance
 242  * @param[in] orientations The available orientation list to add
 243  */
 244 DALI_ADAPTOR_API void SetAvailableOrientations(Window window, const Dali::Vector<WindowOrientation>& orientations);
 245
 246 /**
 247  * @brief Gets current window ID.
 248  *
 249  * @param[in] window The window instance
 250  */
 251 DALI_ADAPTOR_API int32_t GetNativeId(Window window);
 252
 253 /**
 254  * @brief Adds a callback that is called when the frame rendering is done by the graphics driver.
 255  *
 256  * @param[in] window The window instance
 257  * @param[in] callback The function to call
 258  * @param[in] frameId The Id to specify the frame. It will be passed when the callback is called.
 259  *
 260  * @note A callback of the following type may be used:
 261  * @code
 262  *   void MyFunction( int frameId );
 263  * @endcode
 264  * This callback will be deleted once it is called.
 265  *
 266  * @note Ownership of the callback is passed onto this class.
 267  */
 268 DALI_ADAPTOR_API void AddFrameRenderedCallback(Window window, std::unique_ptr<CallbackBase> callback, int32_t frameId);
 269
 270 /**
 271  * @brief Adds a callback that is called when the frame is displayed on the display.
 272  *
 273  * @param[in] window The window instance
 274  * @param[in] callback The function to call
 275  * @param[in] frameId The Id to specify the frame. It will be passed when the callback is called.
 276  *
 277  * @note A callback of the following type may be used:
 278  * @code
 279  *   void MyFunction( int frameId );
 280  * @endcode
 281  * This callback will be deleted once it is called.
 282  *
 283  * @note Ownership of the callback is passed onto this class.
 284  */
 285 DALI_ADAPTOR_API void AddFramePresentedCallback(Window window, std::unique_ptr<CallbackBase> callback, int32_t frameId);
 286
 287 /**
 288  * @brief Sets window position and size for specific orientation.
 289  * This api reserves the position and size per orientation to display server.
 290  * When the device is rotated, the window is moved/resized with the reserved position/size by display server.
 291  *
 292  * @param[in] window The window instance
 293  * @param[in] positionSize The reserved position and size for the orientation
 294  * @param[in] orientation The orientation
 295  *
 296  * @note Currently, it only works when the window's type is WindowType::IME.
 297  * @note To set WindowType::IME, use Application New(... WindowType type), not Window::SetType().
 298  * @note This function is only useful in Tizen world.
 299  */
 300 DALI_ADAPTOR_API void SetPositionSizeWithOrientation(Window window, PositionSize positionSize, WindowOrientation orientation);
 301
 302 /**
 303  * @brief Requests to display server for the window is moved by display server.
 304  *
 305  * This function should be called in mouse down event callback function.
 306  * After this function is called in mouse down event callback function, the window is moved with mouse move event.
 307  * When mouse up event happens, the window moved work is finished.
 308  *
 309  * @param[in] window The window instance
 310  */
 311 DALI_ADAPTOR_API void RequestMoveToServer(Window window);
 312
 313 /**
 314  * @brief Requests to display server for the window is resized by display server.
 315  *
 316  * This function should be called in mouse down event callback function.
 317  * After this function is called in mouse down event callback function, the window is resized with mouse move event.
 318  * The direction is selected one of eight ways.
 319  * When mouse up event happens, the window resized work is finished.
 320  *
 321  * @param[in] window The window instance
 322  * @param[in] direction it is indicated the window's side or edge for starting point.
 323  */
 324 DALI_ADAPTOR_API void RequestResizeToServer(Window window, WindowResizeDirection direction);
 325
 326 /**
 327  * @brief Enables the floating mode of window.
 328  *
 329  * The floating mode is to support making partial size window easliy.
 330  * It is useful to make popup style window and this window is always upper than the other normal window.
 331  * In addition, it is easy to change between popup style and normal style window.
 332  *
 333  * A special display server(as a Tizen display server) supports this mode.
 334  *
 335  * @param[in] window The window instance.
 336  * @param[in] enable Enable floating mode or not.
 337  */
 338 DALI_ADAPTOR_API void EnableFloatingMode(Window window, bool enable);
 339
 340 /**
 341  * @brief Includes input region.
 342  *
 343  * This function inlcudes input regions.
 344  * It can be used multiple times and supports multiple regions.
 345  * It means input region will be extended.
 346  *
 347  * This input is related to mouse and touch event.
 348  * If device has touch screen, this function is useful.
 349  * Otherwise device does not have that, we can use it after connecting mouse to the device.
 350  *
 351  * @param[in] window The window instance.
 352  * @param[in] inputRegion The added region to accept input events.
 353  */
 354 DALI_ADAPTOR_API void IncludeInputRegion(Window window, const Rect<int>& inputRegion);
 355
 356 /**
 357  * @brief Excludes input region.
 358  *
 359  * This function excludes input regions.
 360  * It can be used multiple times and supports multiple regions.
 361  * It means input region will be reduced.
 362  * Nofice, should be set input area by IncludeInputRegion() before this function is used.
 363  *
 364  * This input is related to mouse and touch event.
 365  * If device has touch screen, this function is useful.
 366  * Otherwise device does not have that, we can use it after connecting mouse to the device.
 367  *
 368  * @param[in] window The window instance.
 369  * @param[in] inputRegion The subtracted region to except input events.
 370  */
 371 DALI_ADAPTOR_API void ExcludeInputRegion(Window window, const Rect<int>& inputRegion);
 372
 373 /**
 374  * @brief Sets the necessary for window rotation Acknowledgement.
 375  * After this function called, SendRotationCompletedAcknowledgement() should be called to complete window rotation.
 376  *
 377  * This function is supprot that application has the window rotation acknowledgement's control.
 378  * It means display server waits when application's rotation work is finished.
 379  * It is useful application has the other rendering engine which works asynchronous.
 380  * For instance, GlView.
 381  * It only works on Tizen device.
 382  *
 383  * @param[in] window The window instance.
 384  * @param[in] needAcknowledgement the flag is true if window rotation acknowledge is sent.
 385  */
 386 DALI_ADAPTOR_API void SetNeedsRotationCompletedAcknowledgement(Window window, bool needAcknowledgement);
 387
 388 /**
 389  * @brief send the Acknowledgement to complete window rotation.
 390  * For this function, SetNeedsRotationCompletedAcknowledgement should be already called with true.
 391  *
 392  * @param[in] window The window instance.
 393  */
 394 DALI_ADAPTOR_API void SendRotationCompletedAcknowledgement(Window window);
 395
 396 /**
 397  * @brief Feed (Send) touch event to window
 398  * @param[in] window The window instance
 399  * @param[in] point The touch point
 400  * @param[in] timeStamp The time stamp
 401  */
 402 DALI_ADAPTOR_API void FeedTouchPoint(Window window, const Dali::TouchPoint& point, int32_t timeStamp);
 403
 404 /**
 405  * @brief Feed (Send) wheel event to window
 406  * @param[in] window The window instance
 407  * @param[in] wheelEvent The wheel event
 408  */
 409 DALI_ADAPTOR_API void FeedWheelEvent(Window window, const Dali::WheelEvent& wheelEvent);
 410
 411 /**
 412  * @brief Feed (Send) key event to window
 413  * @param[in] window The window instance
 414  * @param[in] keyEvent The key event holding the key information.
 415  */
 416 DALI_ADAPTOR_API void FeedKeyEvent(Window window, const Dali::KeyEvent& keyEvent);
 417
 418 /**
 419  * @brief Maximizes window's size.
 420  * If this function is called with true, window will be resized with screen size.
 421  * Otherwise window will be resized with previous size.
 422  * It is for the window's MAX button in window's border.
 423  *
 424  * It is for client application.
 425  * If window border is supported by display server, it is not necessary.
 426  *
 427  * @param[in] window The window instance.
 428  * @param[in] maximize If window is maximized or unmaximized.
 429  */
 430 DALI_ADAPTOR_API void Maximize(Window window, bool maximize);
 431
 432 /**
 433  * @brief Returns whether the window is maximized or not.
 434  *
 435  * @param[in] window The window instance.
 436  * @return True if the window is maximized, false otherwise.
 437  */
 438 DALI_ADAPTOR_API bool IsMaximized(Window window);
 439
 440 /**
 441  * @brief Minimizes window's size.
 442  * If this function is called with true, window will be iconified.
 443  * Otherwise window will be activated.
 444  * It is for the window's MIN button in window border.
 445  *
 446  * It is for client application.
 447  * If window border is supported by display server, it is not necessary.
 448  *
 449  * @param[in] window The window instance.
 450  * @param[in] minimize If window is minimized or unminimized(activated).
 451  */
 452 DALI_ADAPTOR_API void Minimize(Window window, bool minimize);
 453
 454 /**
 455  * @brief Returns whether the window is minimized or not.
 456  *
 457  * @param[in] window The window instance.
 458  * @return True if the window is minimized, false otherwise.
 459  */
 460 DALI_ADAPTOR_API bool IsMinimized(Window window);
 461
 462 } // namespace DevelWindow
 463
 464 } // namespace Dali
 465
 466 #endif // DALI_WINDOW_DEVEL_H