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