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

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