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