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

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