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

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