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