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

   1 #ifndef DALI_WINDOW_H
   2 #define DALI_WINDOW_H
   3
   4 /*
   5  * Copyright (c) 2023 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 <dali/public-api/adaptor-framework/window-data.h>
  23 #include <dali/public-api/adaptor-framework/window-enumerations.h>
  24 #include <dali/public-api/math/int-pair.h>
  25 #include <dali/public-api/math/rect.h>
  26 #include <dali/public-api/math/uint-16-pair.h>
  27 #include <dali/public-api/math/vector2.h>
  28 #include <dali/public-api/math/vector4.h>
  29 #include <dali/public-api/object/any.h>
  30 #include <dali/public-api/object/base-handle.h>
  31 #include <dali/public-api/signals/dali-signal.h>
  32 #include <string>
  33
  34 // INTERNAL INCLUDES
  35 #include <dali/public-api/dali-adaptor-common.h>
  36
  37 #undef OPAQUE
  38 #undef TRANSPARENT
  39
  40 namespace Dali
  41 {
  42 /**
  43  * @addtogroup dali_adaptor_framework
  44  * @{
  45  */
  46
  47 typedef Dali::Rect<int> PositionSize;
  48
  49 namespace Internal DALI_INTERNAL
  50 {
  51 namespace Adaptor
  52 {
  53 class Window;
  54 }
  55 } // namespace DALI_INTERNAL
  56
  57 class DragAndDropDetector;
  58 class Orientation;
  59 class Actor;
  60 class Layer;
  61 class RenderTaskList;
  62 class TouchEvent;
  63 class KeyEvent;
  64
  65 /**
  66  * @brief The window class is used internally for drawing.
  67  *
  68  * A Window has an orientation and indicator properties.
  69  * You can get a valid Window handle by calling Dali::Application::GetWindow().
  70  * @SINCE_1_0.0
  71  */
  72 class DALI_ADAPTOR_API Window : public BaseHandle
  73 {
  74 public:
  75   using WindowSize     = Uint16Pair; ///< Window size type @SINCE_1_2.60
  76   using WindowPosition = Int32Pair;  ///< Window position type @SINCE_2_1.45
  77
  78   using FocusChangeSignalType = Signal<void(Window, bool)>;       ///< Window focus signal type @SINCE_1_4.35
  79   using ResizeSignalType      = Signal<void(Window, WindowSize)>; ///< Window resized signal type @SINCE_1_4.35
  80   using KeyEventSignalType    = Signal<void(const KeyEvent&)>;    ///< Key event signal type @SINCE_1_9.21
  81   using TouchEventSignalType  = Signal<void(const TouchEvent&)>;  ///< Touch signal type @SINCE_1_9.28
  82
  83 public:
  84   // Methods
  85
  86   /**
  87    * @brief Creates an initialized handle to a new Window.
  88    * @SINCE_1_0.0
  89    * @param[in] windowPosition The position and size of the Window
  90    * @param[in] name The Window title
  91    * @param[in] isTransparent Whether Window is transparent
  92    * @return A new window
  93    * @note This creates an extra window in addition to the default main window
  94    */
  95   static Window New(PositionSize windowPosition, const std::string& name, bool isTransparent = false);
  96
  97   /**
  98    * @brief Creates an initialized handle to a new Window.
  99    * @SINCE_1_0.0
 100    * @param[in] windowPosition The position and size of the Window
 101    * @param[in] name The Window title
 102    * @param[in] className The Window class name
 103    * @param[in] isTransparent Whether Window is transparent
 104    * @note This creates an extra window in addition to the default main window
 105    * @return A new Window
 106    */
 107   static Window New(PositionSize windowPosition, const std::string& name, const std::string& className, bool isTransparent = false);
 108
 109   /**
 110    * @brief Creates an initialized handle to a new Window.
 111    * @SINCE_2_2.33
 112    * @param[in] name The Window title
 113    * @param[in] className The Window class name
 114    * @param[in] windowData The window data
 115    * @note This creates an extra window in addition to the default main window
 116    * @return A new Window
 117    */
 118   static Window New(const std::string& name, const std::string& className, const WindowData& windowData);
 119
 120   /**
 121    * @brief Creates an uninitialized handle.
 122    *
 123    * This can be initialized using Dali::Application::GetWindow() or
 124    * Dali::Window::New().
 125    * @SINCE_1_0.0
 126    */
 127   Window();
 128
 129   /**
 130    * @brief Destructor.
 131    *
 132    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 133    * @SINCE_1_0.0
 134    */
 135   ~Window();
 136
 137   /**
 138    * @brief This copy constructor is required for (smart) pointer semantics.
 139    *
 140    * @SINCE_1_0.0
 141    * @param[in] handle A reference to the copied handle
 142    */
 143   Window(const Window& handle);
 144
 145   /**
 146    * @brief This assignment operator is required for (smart) pointer semantics.
 147    *
 148    * @SINCE_1_0.0
 149    * @param[in] rhs A reference to the copied handle
 150    * @return A reference to this
 151    */
 152   Window& operator=(const Window& rhs);
 153
 154   /**
 155    * @brief Move constructor.
 156    *
 157    * @SINCE_1_9.24
 158    * @param[in] rhs A reference to the moved handle
 159    */
 160   Window(Window&& rhs) noexcept;
 161
 162   /**
 163    * @brief Move assignment operator.
 164    *
 165    * @SINCE_1_9.24
 166    * @param[in] rhs A reference to the moved handle
 167    * @return A reference to this handle
 168    */
 169   Window& operator=(Window&& rhs) noexcept;
 170
 171   /**
 172    * @brief Downcast sceneHolder to window
 173    *
 174    * @SINCE_2_1.46
 175    * @param[in] handle The handle need to downcast
 176    * @return Whether it's a valid window or not
 177    */
 178   static Window DownCast(BaseHandle handle);
 179
 180   /**
 181    * @brief Adds a child Actor to the Window.
 182    *
 183    * The child will be referenced.
 184    *
 185    * @SINCE_1_4.19
 186    * @param[in] actor The child
 187    * @pre The actor has been initialized.
 188    * @pre The actor does not have a parent.
 189    */
 190   void Add(Actor actor);
 191
 192   /**
 193    * @brief Removes a child Actor from the Window.
 194    *
 195    * The child will be unreferenced.
 196    *
 197    * @SINCE_1_4.19
 198    * @param[in] actor The child
 199    * @pre The actor has been added to the stage.
 200    */
 201   void Remove(Actor actor);
 202
 203   /**
 204    * @brief Sets the background color of the Window.
 205    *
 206    * @SINCE_1_4.19
 207    * @param[in] color The new background color
 208    */
 209   void SetBackgroundColor(const Vector4& color);
 210
 211   /**
 212    * @brief Gets the background color of the Window.
 213    *
 214    * @SINCE_1_4.19
 215    * @return The background color
 216    */
 217   Vector4 GetBackgroundColor() const;
 218
 219   /**
 220    * @brief Returns the root Layer of the Window.
 221    *
 222    * @SINCE_1_4.19
 223    * @return The root layer
 224    */
 225   Layer GetRootLayer() const;
 226
 227   /**
 228    * @brief Returns the overlay Layer of the Window.
 229    * If there isn't overlay layer yet, this method create overlay layer and
 230    * exclusive render task internally.
 231    *
 232    * @SINCE_2_2.10
 233    * @return The root layer
 234    */
 235   Layer GetOverlayLayer();
 236
 237   /**
 238    * @brief Queries the number of on-scene layers in the Window.
 239    *
 240    * Note that a default layer is always provided (count >= 1).
 241    *
 242    * @SINCE_1_4.19
 243    * @return The number of layers
 244    */
 245   uint32_t GetLayerCount() const;
 246
 247   /**
 248    * @brief Retrieves the layer at a specified depth in the Window.
 249    *
 250    * @SINCE_1_4.19
 251    * @param[in] depth The depth
 252    * @return The layer found at the given depth
 253    * @pre Depth is less than layer count; see GetLayerCount().
 254    */
 255   Layer GetLayer(uint32_t depth) const;
 256
 257   /**
 258    * @brief Retrieves the DPI of the window.
 259    *
 260    * @SINCE_1_9.21
 261    * @return The DPI of the window
 262    */
 263   Uint16Pair GetDpi() const;
 264
 265   /**
 266    * @brief Sets the window name and class string.
 267    * @SINCE_1_0.0
 268    * @param[in] name The name of the window
 269    * @param[in] klass The class of the window
 270    */
 271   void SetClass(std::string name, std::string klass);
 272
 273   /**
 274    * @brief Raises window to the top of Window stack.
 275    * @SINCE_1_0.0
 276    */
 277   void Raise();
 278
 279   /**
 280    * @brief Lowers window to the bottom of Window stack.
 281    * @SINCE_1_0.0
 282    */
 283   void Lower();
 284
 285   /**
 286    * @brief Activates window to the top of Window stack even it is iconified.
 287    * @SINCE_1_0.0
 288    */
 289   void Activate();
 290
 291   /**
 292    * @brief Adds an orientation to the list of available orientations.
 293    * @SINCE_1_0.0
 294    * @param[in] orientation The available orientation to add
 295    */
 296   void AddAvailableOrientation(WindowOrientation orientation);
 297
 298   /**
 299    * @brief Removes an orientation from the list of available orientations.
 300    * @SINCE_1_0.0
 301    * @param[in] orientation The available orientation to remove
 302    */
 303   void RemoveAvailableOrientation(WindowOrientation orientation);
 304
 305   /**
 306    * @brief Sets a preferred orientation.
 307    * @SINCE_1_0.0
 308    * @param[in] orientation The preferred orientation
 309    * @pre Orientation is in the list of available orientations.
 310    *
 311    * @note To unset the preferred orientation, orientation should be set NO_ORIENTATION_PREFERENCE.
 312    */
 313   void SetPreferredOrientation(WindowOrientation orientation);
 314
 315   /**
 316    * @brief Gets the preferred orientation.
 317    * @SINCE_1_0.0
 318    * @return The preferred orientation if previously set, or none
 319    */
 320   WindowOrientation GetPreferredOrientation();
 321
 322   /**
 323    * @brief Gets the native handle of the window.
 324    *
 325    * When users call this function, it wraps the actual type used by the underlying window system.
 326    * @SINCE_1_0.0
 327    * @return The native handle of the Window or an empty handle
 328    */
 329   Any GetNativeHandle() const;
 330
 331   /**
 332    * @brief Sets whether window accepts focus or not.
 333    *
 334    * @SINCE_1_2.60
 335    * @param[in] accept If focus is accepted or not. Default is true.
 336    */
 337   void SetAcceptFocus(bool accept);
 338
 339   /**
 340    * @brief Returns whether window accepts focus or not.
 341    *
 342    * @SINCE_1_2.60
 343    * @return True if the window accept focus, false otherwise
 344    */
 345   bool IsFocusAcceptable() const;
 346
 347   /**
 348    * @brief Shows the window if it is hidden.
 349    * @SINCE_1_2.60
 350    */
 351   void Show();
 352
 353   /**
 354    * @brief Hides the window if it is showing.
 355    * @SINCE_1_2.60
 356    */
 357   void Hide();
 358
 359   /**
 360    * @brief Returns whether the window is visible or not.
 361    * @SINCE_1_2.60
 362    * @return True if the window is visible, false otherwise.
 363    */
 364   bool IsVisible() const;
 365
 366   /**
 367    * @brief Gets the count of supported auxiliary hints of the window.
 368    * @SINCE_1_2.60
 369    * @return The number of supported auxiliary hints.
 370    *
 371    * @note The window auxiliary hint is the value which is used to decide which actions should be made available to the user by the window manager.
 372    * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
 373    */
 374   unsigned int GetSupportedAuxiliaryHintCount() const;
 375
 376   /**
 377    * @brief Gets the supported auxiliary hint string of the window.
 378    * @SINCE_1_2.60
 379    * @param[in] index The index of the supported auxiliary hint lists
 380    * @return The auxiliary hint string of the index.
 381    *
 382    * @note The window auxiliary hint is the value which is used to decide which actions should be made available to the user by the window manager.
 383    * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
 384    */
 385   std::string GetSupportedAuxiliaryHint(unsigned int index) const;
 386
 387   /**
 388    * @brief Creates an auxiliary hint of the window.
 389    * @SINCE_1_2.60
 390    * @param[in] hint The auxiliary hint string.
 391    * @param[in] value The value string.
 392    * @return The ID of created auxiliary hint, or @c 0 on failure.
 393    */
 394   unsigned int AddAuxiliaryHint(const std::string& hint, const std::string& value);
 395
 396   /**
 397    * @brief Removes an auxiliary hint of the window.
 398    * @SINCE_1_2.60
 399    * @param[in] id The ID of the auxiliary hint.
 400    * @return True if no error occurred, false otherwise.
 401    */
 402   bool RemoveAuxiliaryHint(unsigned int id);
 403
 404   /**
 405    * @brief Changes a value of the auxiliary hint.
 406    * @SINCE_1_2.60
 407    * @param[in] id The auxiliary hint ID.
 408    * @param[in] value The value string to be set.
 409    * @return True if no error occurred, false otherwise.
 410    */
 411   bool SetAuxiliaryHintValue(unsigned int id, const std::string& value);
 412
 413   /**
 414    * @brief Gets a value of the auxiliary hint.
 415    * @SINCE_1_2.60
 416    * @param[in] id The auxiliary hint ID.
 417    * @return The string value of the auxiliary hint ID, or an empty string if none exists.
 418    */
 419   std::string GetAuxiliaryHintValue(unsigned int id) const;
 420
 421   /**
 422    * @brief Gets a ID of the auxiliary hint string.
 423    * @SINCE_1_2.60
 424    * @param[in] hint The auxiliary hint string.
 425    * @return The ID of the auxiliary hint string, or @c 0 if none exists.
 426    */
 427   unsigned int GetAuxiliaryHintId(const std::string& hint) const;
 428
 429   /**
 430    * @brief Sets a region to accept input events.
 431    * @SINCE_1_2.60
 432    * @param[in] inputRegion The region to accept input events.
 433    */
 434   void SetInputRegion(const Rect<int>& inputRegion);
 435
 436   /**
 437    * @brief Sets a window type.
 438    * @@SINCE_2_0.0
 439    * @param[in] type The window type.
 440    * @remarks The default window type is NORMAL.
 441    */
 442   void SetType(WindowType type);
 443
 444   /**
 445    * @brief Gets a window type.
 446    * @@SINCE_2_0.0
 447    * @return A window type.
 448    */
 449   WindowType GetType() const;
 450
 451   /**
 452    * @brief Sets a priority level for the specified notification window.
 453    * @@SINCE_2_0.0
 454    * @param[in] level The notification window level.
 455    * @return The result of the window operation.
 456    * @PRIVLEVEL_PUBLIC
 457    * @PRIVILEGE_WINDOW_PRIORITY
 458    * @remarks This can be used for a notification type window only. The default level is NotificationLevel::NONE.
 459    */
 460   WindowOperationResult SetNotificationLevel(WindowNotificationLevel level);
 461
 462   /**
 463    * @brief Gets a priority level for the specified notification window.
 464    * @@SINCE_2_0.0
 465    * @return The notification window level.
 466    * @remarks This can be used for a notification type window only.
 467    */
 468   WindowNotificationLevel GetNotificationLevel() const;
 469
 470   /**
 471    * @brief Sets a transparent window's visual state to opaque.
 472    * @details If a visual state of a transparent window is opaque,
 473    * then the window manager could handle it as an opaque window when calculating visibility.
 474    * @SINCE_1_2.60
 475    * @param[in] opaque Whether the window's visual state is opaque.
 476    * @remarks This will have no effect on an opaque window.
 477    * It doesn't change transparent window to opaque window but lets the window manager know the visual state of the window.
 478    */
 479   void SetOpaqueState(bool opaque);
 480
 481   /**
 482    * @brief Returns whether a transparent window's visual state is opaque or not.
 483    * @SINCE_1_2.60
 484    * @return True if the window's visual state is opaque, false otherwise.
 485    * @remarks The return value has no meaning on an opaque window.
 486    */
 487   bool IsOpaqueState() const;
 488
 489   /**
 490    * @brief Sets a window's screen off mode.
 491    * @details This API is useful when the application needs to keep the display turned on.
 492    * If the application sets the screen mode to #::Dali::WindowScreenOffMode::NEVER to its window and the window is shown,
 493    * the window manager requests the display system to keep the display on as long as the window is shown.
 494    * If the window is no longer shown, then the window manager requests the display system to go back to normal operation.
 495    * @@SINCE_2_0.0
 496    * @param[in] screenOffMode The screen mode.
 497    * @return The result of the window operation.
 498    * @PRIVLEVEL_PUBLIC
 499    * @PRIVILEGE_DISPLAY
 500    */
 501   WindowOperationResult SetScreenOffMode(WindowScreenOffMode screenOffMode);
 502
 503   /**
 504    * @brief Gets a screen off mode of the window.
 505    * @@SINCE_2_0.0
 506    * @return The screen off mode.
 507    */
 508   WindowScreenOffMode GetScreenOffMode() const;
 509
 510   /**
 511    * @brief Sets preferred brightness of the window.
 512    * @details This API is useful when the application needs to change the brightness of the screen when it is appeared on the screen.
 513    * If the brightness has been set and the window is shown, the window manager requests the display system to change the brightness to the provided value.
 514    * If the window is no longer shown, then the window manager requests the display system to go back to default brightness.
 515    * A value less than 0 results in default brightness and a value greater than 100 results in maximum brightness.
 516    * @SINCE_1_2.60
 517    * @param[in] brightness The preferred brightness (0 to 100).
 518    * @return The result of the window operation.
 519    * @PRIVLEVEL_PUBLIC
 520    * @PRIVILEGE_DISPLAY
 521    */
 522   WindowOperationResult SetBrightness(int brightness);
 523
 524   /**
 525    * @brief Gets preferred brightness of the window.
 526    * @SINCE_1_2.60
 527    * @return The preferred brightness.
 528    */
 529   int GetBrightness() const;
 530
 531   /**
 532    * @brief Sets a size of the window.
 533    *
 534    * @SINCE_1_2.60
 535    * @param[in] size The new window size
 536    */
 537   void SetSize(WindowSize size);
 538
 539   /**
 540    * @brief Gets a size of the window.
 541    *
 542    * @SINCE_1_2.60
 543    * @return The size of the window
 544    */
 545   WindowSize GetSize() const;
 546
 547   /**
 548    * @brief Sets a position of the window.
 549    *
 550    * @SINCE_1_2.60
 551    * @param[in] position The new window position
 552    */
 553   void SetPosition(WindowPosition position);
 554
 555   /**
 556    * @brief Gets a position of the window.
 557    *
 558    * @SINCE_1_2.60
 559    * @return The position of the window
 560    */
 561   WindowPosition GetPosition() const;
 562
 563   /**
 564    * @brief Sets the layout of the window.
 565    *
 566    * This method sets the layout of the window based on the specified number of columns and rows,
 567    * as well as the position and size of the window within that layout.
 568    *
 569    * @param numCols The number of columns in the layout.
 570    * @param numRows The number of rows in the layout.
 571    * @param column The column number of the window within the layout.
 572    * @param row The row number of the window within the layout.
 573    * @param colSpan The number of columns the window should span within the layout.
 574    * @param rowSpan The number of rows the window should span within the layout.
 575    * @SINCE_2_2.20
 576    */
 577   void SetLayout(unsigned int numCols, unsigned int numRows, unsigned int column, unsigned int row, unsigned int colSpan, unsigned int rowSpan);
 578
 579   /**
 580    * @brief Sets whether the window is transparent or not.
 581    *
 582    * @SINCE_1_2.60
 583    * @param[in] transparent Whether the window is transparent
 584    */
 585   void SetTransparency(bool transparent);
 586
 587   /**
 588    * @brief Retrieves the list of render-tasks in the window.
 589    *
 590    * @SINCE_1_9.21
 591    * @return A valid handle to a RenderTaskList
 592    */
 593   RenderTaskList GetRenderTaskList();
 594
 595   /**
 596    * @brief Keeps rendering for at least the given amount of time.
 597    *
 598    * By default, Dali will stop rendering when no Actor positions are being set, and when no animations are running etc.
 599    * This method is useful to force screen refreshes.
 600    *
 601    * @SINCE_2_2.29
 602    * @param[in] durationSeconds Time to keep rendering, 0 means render at least one more frame
 603    */
 604   void KeepRendering(float durationSeconds);
 605
 606   /**
 607    * @brief Sets whether the window will update partial area or full area.
 608    *
 609    * @SINCE_2_2.33
 610    * @param[in] enabled True if the window should update partial area
 611    * @note This doesn't change the global value which is set by the environment variable.
 612    * This works when partial update is enabled by the environment variable. If the partial update is disabled by the environment variable, it changes nothing.
 613    */
 614   void SetPartialUpdateEnabled(bool enabled);
 615
 616   /**
 617    * @brief Queries whether the window will update partial area.
 618    *
 619    * @SINCE_2_2.33
 620    * @return True if the window should update partial area
 621    */
 622   bool IsPartialUpdateEnabled() const;
 623
 624 public: // Signals
 625   /**
 626    * @brief The user should connect to this signal to get a timing when window gains focus or loses focus.
 627    *
 628    * A callback of the following type may be connected:
 629    * @code
 630    *   void YourCallbackName( Window window, bool focusIn );
 631    * @endcode
 632    * The parameter is true if window gains focus, otherwise false.
 633    * and window means this signal was called from what window
 634    *
 635    * @SINCE_1_4.35
 636    * @return The signal to connect to
 637    */
 638   FocusChangeSignalType& FocusChangeSignal();
 639
 640   /**
 641    * @brief This signal is emitted when the window is resized.
 642    *
 643    * A callback of the following type may be connected:
 644    * @code
 645    *   void YourCallbackName( Window window, int width, int height );
 646    * @endcode
 647    * The parameters are the resized width and height.
 648    * and window means this signal was called from what window
 649    *
 650    * @SINCE_1_4.35
 651    * @return The signal to connect to
 652    */
 653   ResizeSignalType& ResizeSignal();
 654
 655   /**
 656    * @brief This signal is emitted when key event is received.
 657    *
 658    * A callback of the following type may be connected:
 659    * @code
 660    *   void YourCallbackName(const KeyEvent& event);
 661    * @endcode
 662    *
 663    * @SINCE_1_9.21
 664    * @return The signal to connect to
 665    */
 666   KeyEventSignalType& KeyEventSignal();
 667
 668   /**
 669    * @brief This signal is emitted when the screen is touched and when the touch ends
 670    * (i.e. the down & up touch events only).
 671    *
 672    * If there are multiple touch points, then this will be emitted when the first touch occurs and
 673    * then when the last finger is lifted.
 674    * An interrupted event will also be emitted (if it occurs).
 675    * A callback of the following type may be connected:
 676    * @code
 677    *   void YourCallbackName(const TouchEvent& event);
 678    * @endcode
 679    *
 680    * @SINCE_1_9.28
 681    * @return The touch signal to connect to
 682    *
 683    * @note Motion events are not emitted.
 684    */
 685   TouchEventSignalType& TouchedSignal();
 686
 687 public: // Not intended for application developers
 688   /// @cond internal
 689   /**
 690    * @brief This constructor is used by Dali::Application::GetWindow().
 691    * @SINCE_1_0.0
 692    * @param[in] window A pointer to the Window
 693    */
 694   explicit DALI_INTERNAL Window(Internal::Adaptor::Window* window);
 695   /// @endcond
 696 };
 697
 698 /**
 699  * @}
 700  */
 701 } // namespace Dali
 702
 703 #endif // __DALI_WINDOW_H__