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