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

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