5 * Copyright (c) 2020 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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/base-handle.h>
28 #include <dali/public-api/object/any.h>
29 #include <dali/public-api/signals/dali-signal.h>
32 #include <dali/public-api/dali-adaptor-common.h>
40 * @addtogroup dali_adaptor_framework
44 typedef Dali::Rect<int> PositionSize;
46 namespace Internal DALI_INTERNAL
54 class DragAndDropDetector;
63 * @brief The window class is used internally for drawing.
65 * A Window has an orientation and indicator properties.
66 * You can get a valid Window handle by calling Dali::Application::GetWindow().
69 class DALI_ADAPTOR_API Window : public BaseHandle
73 using WindowSize = Uint16Pair ; ///< Window size type @SINCE_1_2.60
74 using WindowPosition = Uint16Pair; ///< Window position type @SINCE_1_2.60
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
86 * @brief Enumeration for orientation of the window is the way in which a rectangular page is oriented for normal viewing.
88 * This Enumeration is used the available orientation APIs and the preferred orientation.
92 enum WindowOrientation
94 PORTRAIT = 0, ///< Portrait orientation. The height of the display area is greater than the width. @SINCE_1_0.0
95 LANDSCAPE = 90, ///< Landscape orientation. A wide view area is needed. @SINCE_1_0.0
96 PORTRAIT_INVERSE = 180, ///< Portrait inverse orientation @SINCE_1_0.0
97 LANDSCAPE_INVERSE = 270, ///< Landscape inverse orientation @SINCE_1_0.0
98 NO_ORIENTATION_PREFERENCE = -1 ///< No orientation. It is used to initialize or unset the preferred orientation. @SINCE_1_4.51
102 * @brief An enum of Window types.
107 NORMAL, ///< A default window type. Indicates a normal, top-level window. Almost every window will be created with this type. @SINCE_1_2.60
108 NOTIFICATION, ///< A notification window, like a warning about battery life or a new E-Mail received. @SINCE_1_2.60
109 UTILITY, ///< A persistent utility window, like a toolbox or palette. @SINCE_1_2.60
110 DIALOG ///< Used for simple dialog windows. @SINCE_1_2.60
114 * @brief An enum of screen mode.
117 struct NotificationLevel
120 * @brief An enum of screen mode.
125 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
126 BASE = 10, ///< Base notification level. @SINCE_1_2.60
127 MEDIUM = 20, ///< Higher notification level than base. @SINCE_1_2.60
128 HIGH = 30, ///< Higher notification level than medium. @SINCE_1_2.60
129 TOP = 40 ///< The highest notification level. @SINCE_1_2.60
134 * @brief An enum of screen mode.
140 * @brief An enum of screen mode.
145 TIMEOUT, ///< The mode which turns the screen off after a timeout. @SINCE_1_2.60
146 NEVER, ///< The mode which keeps the screen turned on. @SINCE_1_2.60
149 static constexpr Type DEFAULT { TIMEOUT }; ///< The default mode. @SINCE_1_2.60
155 * @brief Creates an initialized handle to a new Window.
157 * @param[in] windowPosition The position and size of the Window
158 * @param[in] name The Window title
159 * @param[in] isTransparent Whether Window is transparent
160 * @return A new window
161 * @note This creates an extra window in addition to the default main window
163 static Window New(PositionSize windowPosition, const std::string& name, bool isTransparent = false);
166 * @brief Creates an initialized handle to a new Window.
168 * @param[in] windowPosition The position and size of the Window
169 * @param[in] name The Window title
170 * @param[in] className The Window class name
171 * @param[in] isTransparent Whether Window is transparent
172 * @note This creates an extra window in addition to the default main window
173 * @return A new Window
175 static Window New(PositionSize windowPosition, const std::string& name, const std::string& className, bool isTransparent = false);
178 * @brief Creates an uninitialized handle.
180 * This can be initialized using Dali::Application::GetWindow() or
181 * Dali::Window::New().
189 * This is non-virtual since derived Handle types must not contain data or virtual methods.
195 * @brief This copy constructor is required for (smart) pointer semantics.
198 * @param[in] handle A reference to the copied handle
200 Window(const Window& handle);
203 * @brief This assignment operator is required for (smart) pointer semantics.
206 * @param[in] rhs A reference to the copied handle
207 * @return A reference to this
209 Window& operator=(const Window& rhs);
212 * @brief Move constructor.
215 * @param[in] rhs A reference to the moved handle
217 Window( Window&& rhs );
220 * @brief Move assignment operator.
223 * @param[in] rhs A reference to the moved handle
224 * @return A reference to this handle
226 Window& operator=( Window&& rhs );
229 * @brief Adds a child Actor to the Window.
231 * The child will be referenced.
234 * @param[in] actor The child
235 * @pre The actor has been initialized.
236 * @pre The actor does not have a parent.
238 void Add( Actor actor );
241 * @brief Removes a child Actor from the Window.
243 * The child will be unreferenced.
246 * @param[in] actor The child
247 * @pre The actor has been added to the stage.
249 void Remove( Actor actor );
252 * @brief Sets the background color of the Window.
255 * @param[in] color The new background color
257 void SetBackgroundColor( const Vector4& color );
260 * @brief Gets the background color of the Window.
263 * @return The background color
265 Vector4 GetBackgroundColor() const;
268 * @brief Returns the root Layer of the Window.
271 * @return The root layer
273 Layer GetRootLayer() const;
276 * @brief Queries the number of on-scene layers in the Window.
278 * Note that a default layer is always provided (count >= 1).
281 * @return The number of layers
283 uint32_t GetLayerCount() const;
286 * @brief Retrieves the layer at a specified depth in the Window.
289 * @param[in] depth The depth
290 * @return The layer found at the given depth
291 * @pre Depth is less than layer count; see GetLayerCount().
293 Layer GetLayer( uint32_t depth ) const;
296 * @brief Retrieves the DPI of the window.
299 * @return The DPI of the window
301 Uint16Pair GetDpi() const;
304 * @brief Sets the window name and class string.
306 * @param[in] name The name of the window
307 * @param[in] klass The class of the window
309 void SetClass(std::string name, std::string klass);
312 * @brief Raises window to the top of Window stack.
318 * @brief Lowers window to the bottom of Window stack.
324 * @brief Activates window to the top of Window stack even it is iconified.
330 * @brief Adds an orientation to the list of available orientations.
332 * @param[in] orientation The available orientation to add
334 void AddAvailableOrientation( WindowOrientation orientation );
337 * @brief Removes an orientation from the list of available orientations.
339 * @param[in] orientation The available orientation to remove
341 void RemoveAvailableOrientation( WindowOrientation orientation );
344 * @brief Sets a preferred orientation.
346 * @param[in] orientation The preferred orientation
347 * @pre Orientation is in the list of available orientations.
349 * @note To unset the preferred orientation, orientation should be set NO_ORIENTATION_PREFERENCE.
351 void SetPreferredOrientation( WindowOrientation orientation );
354 * @brief Gets the preferred orientation.
356 * @return The preferred orientation if previously set, or none
358 WindowOrientation GetPreferredOrientation();
361 * @brief Gets the native handle of the window.
363 * When users call this function, it wraps the actual type used by the underlying window system.
365 * @return The native handle of the Window or an empty handle
367 Any GetNativeHandle() const;
370 * @brief Sets whether window accepts focus or not.
373 * @param[in] accept If focus is accepted or not. Default is true.
375 void SetAcceptFocus( bool accept );
378 * @brief Returns whether window accepts focus or not.
381 * @return True if the window accept focus, false otherwise
383 bool IsFocusAcceptable() const;
386 * @brief Shows the window if it is hidden.
392 * @brief Hides the window if it is showing.
398 * @brief Returns whether the window is visible or not.
400 * @return True if the window is visible, false otherwise.
402 bool IsVisible() const;
405 * @brief Gets the count of supported auxiliary hints of the window.
407 * @return The number of supported auxiliary hints.
409 * @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.
410 * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
412 unsigned int GetSupportedAuxiliaryHintCount() const;
415 * @brief Gets the supported auxiliary hint string of the window.
417 * @param[in] index The index of the supported auxiliary hint lists
418 * @return The auxiliary hint string of the index.
420 * @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.
421 * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
423 std::string GetSupportedAuxiliaryHint( unsigned int index ) const;
426 * @brief Creates an auxiliary hint of the window.
428 * @param[in] hint The auxiliary hint string.
429 * @param[in] value The value string.
430 * @return The ID of created auxiliary hint, or @c 0 on failure.
432 unsigned int AddAuxiliaryHint( const std::string& hint, const std::string& value );
435 * @brief Removes an auxiliary hint of the window.
437 * @param[in] id The ID of the auxiliary hint.
438 * @return True if no error occurred, false otherwise.
440 bool RemoveAuxiliaryHint( unsigned int id );
443 * @brief Changes a value of the auxiliary hint.
445 * @param[in] id The auxiliary hint ID.
446 * @param[in] value The value string to be set.
447 * @return True if no error occurred, false otherwise.
449 bool SetAuxiliaryHintValue( unsigned int id, const std::string& value );
452 * @brief Gets a value of the auxiliary hint.
454 * @param[in] id The auxiliary hint ID.
455 * @return The string value of the auxiliary hint ID, or an empty string if none exists.
457 std::string GetAuxiliaryHintValue( unsigned int id ) const;
460 * @brief Gets a ID of the auxiliary hint string.
462 * @param[in] hint The auxiliary hint string.
463 * @return The ID of the auxiliary hint string, or @c 0 if none exists.
465 unsigned int GetAuxiliaryHintId( const std::string& hint ) const;
468 * @brief Sets a region to accept input events.
470 * @param[in] inputRegion The region to accept input events.
472 void SetInputRegion( const Rect< int >& inputRegion );
475 * @brief Sets a window type.
477 * @param[in] type The window type.
478 * @remarks The default window type is NORMAL.
480 void SetType( Type type );
483 * @brief Gets a window type.
485 * @return A window type.
487 Type GetType() const;
490 * @brief Sets a priority level for the specified notification window.
492 * @param[in] level The notification window level.
493 * @return True if no error occurred, false otherwise.
495 * @PRIVILEGE_WINDOW_PRIORITY
496 * @remarks This can be used for a notification type window only. The default level is NotificationLevel::NONE.
498 bool SetNotificationLevel( NotificationLevel::Type level );
501 * @brief Gets a priority level for the specified notification window.
503 * @return The notification window level.
504 * @remarks This can be used for a notification type window only.
506 NotificationLevel::Type GetNotificationLevel() const;
509 * @brief Sets a transparent window's visual state to opaque.
510 * @details If a visual state of a transparent window is opaque,
511 * then the window manager could handle it as an opaque window when calculating visibility.
513 * @param[in] opaque Whether the window's visual state is opaque.
514 * @remarks This will have no effect on an opaque window.
515 * It doesn't change transparent window to opaque window but lets the window manager know the visual state of the window.
517 void SetOpaqueState( bool opaque );
520 * @brief Returns whether a transparent window's visual state is opaque or not.
522 * @return True if the window's visual state is opaque, false otherwise.
523 * @remarks The return value has no meaning on an opaque window.
525 bool IsOpaqueState() const;
528 * @brief Sets a window's screen off mode.
529 * @details This API is useful when the application needs to keep the display turned on.
530 * If the application sets the screen mode to #::Dali::Window::ScreenOffMode::NEVER to its window and the window is shown,
531 * the window manager requests the display system to keep the display on as long as the window is shown.
532 * If the window is no longer shown, then the window manager requests the display system to go back to normal operation.
534 * @param[in] screenOffMode The screen mode.
535 * @return True if no error occurred, false otherwise.
539 bool SetScreenOffMode(ScreenOffMode::Type screenOffMode);
542 * @brief Gets a screen off mode of the window.
544 * @return The screen off mode.
546 ScreenOffMode::Type GetScreenOffMode() const;
549 * @brief Sets preferred brightness of the window.
550 * @details This API is useful when the application needs to change the brightness of the screen when it is appeared on the screen.
551 * 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.
552 * If the window is no longer shown, then the window manager requests the display system to go back to default brightness.
553 * A value less than 0 results in default brightness and a value greater than 100 results in maximum brightness.
555 * @param[in] brightness The preferred brightness (0 to 100).
556 * @return True if no error occurred, false otherwise.
560 bool SetBrightness( int brightness );
563 * @brief Gets preferred brightness of the window.
565 * @return The preferred brightness.
567 int GetBrightness() const;
570 * @brief Sets a size of the window.
573 * @param[in] size The new window size
575 void SetSize( WindowSize size );
578 * @brief Gets a size of the window.
581 * @return The size of the window
583 WindowSize GetSize() const;
586 * @brief Sets a position of the window.
589 * @param[in] position The new window position
591 void SetPosition( WindowPosition position );
594 * @brief Gets a position of the window.
597 * @return The position of the window
599 WindowPosition GetPosition() const;
602 * @brief Sets whether the window is transparent or not.
605 * @param[in] transparent Whether the window is transparent
607 void SetTransparency( bool transparent );
610 * @brief Retrieves the list of render-tasks in the window.
613 * @return A valid handle to a RenderTaskList
615 RenderTaskList GetRenderTaskList();
620 * @brief The user should connect to this signal to get a timing when window gains focus or loses focus.
622 * A callback of the following type may be connected:
624 * void YourCallbackName( Window window, bool focusIn );
626 * The parameter is true if window gains focus, otherwise false.
627 * and window means this signal was called from what window
630 * @return The signal to connect to
632 FocusChangeSignalType& FocusChangeSignal();
635 * @brief This signal is emitted when the window is resized.
637 * A callback of the following type may be connected:
639 * void YourCallbackName( Window window, int width, int height );
641 * The parameters are the resized width and height.
642 * and window means this signal was called from what window
645 * @return The signal to connect to
647 ResizeSignalType& ResizeSignal();
650 * @brief This signal is emitted when key event is received.
652 * A callback of the following type may be connected:
654 * void YourCallbackName(const KeyEvent& event);
658 * @return The signal to connect to
660 KeyEventSignalType& KeyEventSignal();
663 * @brief This signal is emitted when the screen is touched and when the touch ends
664 * (i.e. the down & up touch events only).
666 * If there are multiple touch points, then this will be emitted when the first touch occurs and
667 * then when the last finger is lifted.
668 * An interrupted event will also be emitted (if it occurs).
669 * A callback of the following type may be connected:
671 * void YourCallbackName(const TouchEvent& event);
675 * @return The touch signal to connect to
677 * @note Motion events are not emitted.
679 TouchEventSignalType& TouchedSignal();
681 public: // Not intended for application developers
684 * @brief This constructor is used by Dali::Application::GetWindow().
686 * @param[in] window A pointer to the Window
688 explicit DALI_INTERNAL Window( Internal::Adaptor::Window* window );
697 #endif // __DALI_WINDOW_H__