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

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