5 * Copyright (c) 2022 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.
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>
34 #include <dali/public-api/dali-adaptor-common.h>
42 * @addtogroup dali_adaptor_framework
46 typedef Dali::Rect<int> PositionSize;
48 namespace Internal DALI_INTERNAL
54 } // namespace DALI_INTERNAL
56 class DragAndDropDetector;
65 * @brief The window class is used internally for drawing.
67 * A Window has an orientation and indicator properties.
68 * You can get a valid Window handle by calling Dali::Application::GetWindow().
71 class DALI_ADAPTOR_API Window : public BaseHandle
74 using WindowSize = Uint16Pair; ///< Window size type @SINCE_1_2.60
75 using WindowPosition = Int32Pair; ///< Window position type @SINCE_2_1.45
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
86 * @brief Creates an initialized handle to a new Window.
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
94 static Window New(PositionSize windowPosition, const std::string& name, bool isTransparent = false);
97 * @brief Creates an initialized handle to a new Window.
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
106 static Window New(PositionSize windowPosition, const std::string& name, const std::string& className, bool isTransparent = false);
109 * @brief Creates an uninitialized handle.
111 * This can be initialized using Dali::Application::GetWindow() or
112 * Dali::Window::New().
120 * This is non-virtual since derived Handle types must not contain data or virtual methods.
126 * @brief This copy constructor is required for (smart) pointer semantics.
129 * @param[in] handle A reference to the copied handle
131 Window(const Window& handle);
134 * @brief This assignment operator is required for (smart) pointer semantics.
137 * @param[in] rhs A reference to the copied handle
138 * @return A reference to this
140 Window& operator=(const Window& rhs);
143 * @brief Move constructor.
146 * @param[in] rhs A reference to the moved handle
148 Window(Window&& rhs) noexcept;
151 * @brief Move assignment operator.
154 * @param[in] rhs A reference to the moved handle
155 * @return A reference to this handle
157 Window& operator=(Window&& rhs) noexcept;
160 * @brief Downcast sceneHolder to window
163 * @param[in] handle The handle need to downcast
164 * @return Whether it's a valid window or not
166 static Window DownCast(BaseHandle handle);
169 * @brief Adds a child Actor to the Window.
171 * The child will be referenced.
174 * @param[in] actor The child
175 * @pre The actor has been initialized.
176 * @pre The actor does not have a parent.
178 void Add(Actor actor);
181 * @brief Removes a child Actor from the Window.
183 * The child will be unreferenced.
186 * @param[in] actor The child
187 * @pre The actor has been added to the stage.
189 void Remove(Actor actor);
192 * @brief Sets the background color of the Window.
195 * @param[in] color The new background color
197 void SetBackgroundColor(const Vector4& color);
200 * @brief Gets the background color of the Window.
203 * @return The background color
205 Vector4 GetBackgroundColor() const;
208 * @brief Returns the root Layer of the Window.
211 * @return The root layer
213 Layer GetRootLayer() const;
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.
221 * @return The root layer
223 Layer GetOverlayLayer();
226 * @brief Queries the number of on-scene layers in the Window.
228 * Note that a default layer is always provided (count >= 1).
231 * @return The number of layers
233 uint32_t GetLayerCount() const;
236 * @brief Retrieves the layer at a specified depth in the Window.
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().
243 Layer GetLayer(uint32_t depth) const;
246 * @brief Retrieves the DPI of the window.
249 * @return The DPI of the window
251 Uint16Pair GetDpi() const;
254 * @brief Sets the window name and class string.
256 * @param[in] name The name of the window
257 * @param[in] klass The class of the window
259 void SetClass(std::string name, std::string klass);
262 * @brief Raises window to the top of Window stack.
268 * @brief Lowers window to the bottom of Window stack.
274 * @brief Activates window to the top of Window stack even it is iconified.
280 * @brief Adds an orientation to the list of available orientations.
282 * @param[in] orientation The available orientation to add
284 void AddAvailableOrientation(WindowOrientation orientation);
287 * @brief Removes an orientation from the list of available orientations.
289 * @param[in] orientation The available orientation to remove
291 void RemoveAvailableOrientation(WindowOrientation orientation);
294 * @brief Sets a preferred orientation.
296 * @param[in] orientation The preferred orientation
297 * @pre Orientation is in the list of available orientations.
299 * @note To unset the preferred orientation, orientation should be set NO_ORIENTATION_PREFERENCE.
301 void SetPreferredOrientation(WindowOrientation orientation);
304 * @brief Gets the preferred orientation.
306 * @return The preferred orientation if previously set, or none
308 WindowOrientation GetPreferredOrientation();
311 * @brief Gets the native handle of the window.
313 * When users call this function, it wraps the actual type used by the underlying window system.
315 * @return The native handle of the Window or an empty handle
317 Any GetNativeHandle() const;
320 * @brief Sets whether window accepts focus or not.
323 * @param[in] accept If focus is accepted or not. Default is true.
325 void SetAcceptFocus(bool accept);
328 * @brief Returns whether window accepts focus or not.
331 * @return True if the window accept focus, false otherwise
333 bool IsFocusAcceptable() const;
336 * @brief Shows the window if it is hidden.
342 * @brief Hides the window if it is showing.
348 * @brief Returns whether the window is visible or not.
350 * @return True if the window is visible, false otherwise.
352 bool IsVisible() const;
355 * @brief Gets the count of supported auxiliary hints of the window.
357 * @return The number of supported auxiliary hints.
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.
362 unsigned int GetSupportedAuxiliaryHintCount() const;
365 * @brief Gets the supported auxiliary hint string of the window.
367 * @param[in] index The index of the supported auxiliary hint lists
368 * @return The auxiliary hint string of the index.
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.
373 std::string GetSupportedAuxiliaryHint(unsigned int index) const;
376 * @brief Creates an auxiliary hint of the window.
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.
382 unsigned int AddAuxiliaryHint(const std::string& hint, const std::string& value);
385 * @brief Removes an auxiliary hint of the window.
387 * @param[in] id The ID of the auxiliary hint.
388 * @return True if no error occurred, false otherwise.
390 bool RemoveAuxiliaryHint(unsigned int id);
393 * @brief Changes a value of the auxiliary hint.
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.
399 bool SetAuxiliaryHintValue(unsigned int id, const std::string& value);
402 * @brief Gets a value of the auxiliary hint.
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.
407 std::string GetAuxiliaryHintValue(unsigned int id) const;
410 * @brief Gets a ID of the auxiliary hint string.
412 * @param[in] hint The auxiliary hint string.
413 * @return The ID of the auxiliary hint string, or @c 0 if none exists.
415 unsigned int GetAuxiliaryHintId(const std::string& hint) const;
418 * @brief Sets a region to accept input events.
420 * @param[in] inputRegion The region to accept input events.
422 void SetInputRegion(const Rect<int>& inputRegion);
425 * @brief Sets a window type.
427 * @param[in] type The window type.
428 * @remarks The default window type is NORMAL.
430 void SetType(WindowType type);
433 * @brief Gets a window type.
435 * @return A window type.
437 WindowType GetType() const;
440 * @brief Sets a priority level for the specified notification window.
442 * @param[in] level The notification window level.
443 * @return The result of the window operation.
445 * @PRIVILEGE_WINDOW_PRIORITY
446 * @remarks This can be used for a notification type window only. The default level is NotificationLevel::NONE.
448 WindowOperationResult SetNotificationLevel(WindowNotificationLevel level);
451 * @brief Gets a priority level for the specified notification window.
453 * @return The notification window level.
454 * @remarks This can be used for a notification type window only.
456 WindowNotificationLevel GetNotificationLevel() const;
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.
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.
467 void SetOpaqueState(bool opaque);
470 * @brief Returns whether a transparent window's visual state is opaque or not.
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.
475 bool IsOpaqueState() const;
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.
484 * @param[in] screenOffMode The screen mode.
485 * @return The result of the window operation.
489 WindowOperationResult SetScreenOffMode(WindowScreenOffMode screenOffMode);
492 * @brief Gets a screen off mode of the window.
494 * @return The screen off mode.
496 WindowScreenOffMode GetScreenOffMode() const;
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.
505 * @param[in] brightness The preferred brightness (0 to 100).
506 * @return The result of the window operation.
510 WindowOperationResult SetBrightness(int brightness);
513 * @brief Gets preferred brightness of the window.
515 * @return The preferred brightness.
517 int GetBrightness() const;
520 * @brief Sets a size of the window.
523 * @param[in] size The new window size
525 void SetSize(WindowSize size);
528 * @brief Gets a size of the window.
531 * @return The size of the window
533 WindowSize GetSize() const;
536 * @brief Sets a position of the window.
539 * @param[in] position The new window position
541 void SetPosition(WindowPosition position);
544 * @brief Gets a position of the window.
547 * @return The position of the window
549 WindowPosition GetPosition() const;
552 * @brief Sets the layout of the window.
554 * This method sets the layout of the window based on the specified number of columns and rows,
555 * as well as the position and size of the window within that layout.
557 * @param numCols The number of columns in the layout.
558 * @param numRows The number of rows in the layout.
559 * @param column The column number of the window within the layout.
560 * @param row The row number of the window within the layout.
561 * @param colSpan The number of columns the window should span within the layout.
562 * @param rowSpan The number of rows the window should span within the layout.
565 void SetLayout(unsigned int numCols, unsigned int numRows, unsigned int column, unsigned int row, unsigned int colSpan, unsigned int rowSpan);
568 * @brief Sets whether the window is transparent or not.
571 * @param[in] transparent Whether the window is transparent
573 void SetTransparency(bool transparent);
576 * @brief Retrieves the list of render-tasks in the window.
579 * @return A valid handle to a RenderTaskList
581 RenderTaskList GetRenderTaskList();
585 * @brief The user should connect to this signal to get a timing when window gains focus or loses focus.
587 * A callback of the following type may be connected:
589 * void YourCallbackName( Window window, bool focusIn );
591 * The parameter is true if window gains focus, otherwise false.
592 * and window means this signal was called from what window
595 * @return The signal to connect to
597 FocusChangeSignalType& FocusChangeSignal();
600 * @brief This signal is emitted when the window is resized.
602 * A callback of the following type may be connected:
604 * void YourCallbackName( Window window, int width, int height );
606 * The parameters are the resized width and height.
607 * and window means this signal was called from what window
610 * @return The signal to connect to
612 ResizeSignalType& ResizeSignal();
615 * @brief This signal is emitted when key event is received.
617 * A callback of the following type may be connected:
619 * void YourCallbackName(const KeyEvent& event);
623 * @return The signal to connect to
625 KeyEventSignalType& KeyEventSignal();
628 * @brief This signal is emitted when the screen is touched and when the touch ends
629 * (i.e. the down & up touch events only).
631 * If there are multiple touch points, then this will be emitted when the first touch occurs and
632 * then when the last finger is lifted.
633 * An interrupted event will also be emitted (if it occurs).
634 * A callback of the following type may be connected:
636 * void YourCallbackName(const TouchEvent& event);
640 * @return The touch signal to connect to
642 * @note Motion events are not emitted.
644 TouchEventSignalType& TouchedSignal();
646 public: // Not intended for application developers
649 * @brief This constructor is used by Dali::Application::GetWindow().
651 * @param[in] window A pointer to the Window
653 explicit DALI_INTERNAL Window(Internal::Adaptor::Window* window);
662 #endif // __DALI_WINDOW_H__