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

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