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

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