-#ifndef __DALI_WINDOW_H__
-#define __DALI_WINDOW_H__
+#ifndef DALI_WINDOW_H
+#define DALI_WINDOW_H
/*
- * Copyright (c) 2017 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2022 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
*/
// EXTERNAL INCLUDES
-#include <string>
+#include <dali/public-api/adaptor-framework/window-enumerations.h>
+#include <dali/public-api/math/int-pair.h>
#include <dali/public-api/math/rect.h>
#include <dali/public-api/math/uint-16-pair.h>
#include <dali/public-api/math/vector2.h>
-#include <dali/public-api/object/base-handle.h>
+#include <dali/public-api/math/vector4.h>
#include <dali/public-api/object/any.h>
+#include <dali/public-api/object/base-handle.h>
#include <dali/public-api/signals/dali-signal.h>
+#include <string>
+
+// INTERNAL INCLUDES
+#include <dali/public-api/dali-adaptor-common.h>
+
+#undef OPAQUE
+#undef TRANSPARENT
namespace Dali
{
{
class Window;
}
-}
+} // namespace DALI_INTERNAL
class DragAndDropDetector;
class Orientation;
+class Actor;
+class Layer;
+class RenderTaskList;
+class TouchEvent;
+class KeyEvent;
/**
* @brief The window class is used internally for drawing.
* You can get a valid Window handle by calling Dali::Application::GetWindow().
* @SINCE_1_0.0
*/
-class DALI_IMPORT_API Window : public BaseHandle
+class DALI_ADAPTOR_API Window : public BaseHandle
{
public:
+ using WindowSize = Uint16Pair; ///< Window size type @SINCE_1_2.60
+ using WindowPosition = Int32Pair; ///< Window position type @SINCE_2_1.45
- typedef Uint16Pair WindowSize; ///< Window size type @SINCE_1_2.60
- typedef Uint16Pair WindowPosition; ///< Window position type @SINCE_1_2.60
-
- typedef Signal< void (bool) > IndicatorSignalType; ///< Indicator state signal type @SINCE_1_0.0
- typedef Signal< void (bool) > FocusSignalType; ///< Window focus signal type @SINCE_1_2.60
- typedef Signal< void (WindowSize) > ResizedSignalType; ///< Window resized signal type @SINCE_1_2.60
+ using FocusChangeSignalType = Signal<void(Window, bool)>; ///< Window focus signal type @SINCE_1_4.35
+ using ResizeSignalType = Signal<void(Window, WindowSize)>; ///< Window resized signal type @SINCE_1_4.35
+ using KeyEventSignalType = Signal<void(const KeyEvent&)>; ///< Key event signal type @SINCE_1_9.21
+ using TouchEventSignalType = Signal<void(const TouchEvent&)>; ///< Touch signal type @SINCE_1_9.28
public:
-
- // Enumerations
-
- /**
- * @brief Enumeration for orientation of the window is the way in which a rectangular page is oriented for normal viewing.
- * @SINCE_1_0.0
- */
- enum WindowOrientation
- {
- PORTRAIT = 0, ///< Portrait orientation. The height of the display area is greater than the width. @SINCE_1_0.0
- LANDSCAPE = 90, ///< Landscape orientation. A wide view area is needed. @SINCE_1_0.0
- PORTRAIT_INVERSE = 180, ///< Portrait inverse orientation @SINCE_1_0.0
- LANDSCAPE_INVERSE = 270 ///< Landscape inverse orientation @SINCE_1_0.0
- };
-
- /**
- * @brief Enumeration for opacity of the indicator.
- * @SINCE_1_0.0
- */
- enum IndicatorBgOpacity
- {
- OPAQUE = 100, ///< Fully opaque indicator Bg @SINCE_1_0.0
- TRANSLUCENT = 50, ///< Semi translucent indicator Bg @SINCE_1_0.0
- TRANSPARENT = 0 ///< Fully transparent indicator Bg @SINCE_1_0.0
- };
-
- /**
- * @brief Enumeration for visible mode of the indicator.
- * @SINCE_1_0.0
- */
- enum IndicatorVisibleMode
- {
- INVISIBLE = 0, ///< Hide indicator @SINCE_1_0.0
- VISIBLE = 1, ///< Show indicator @SINCE_1_0.0
- AUTO = 2 ///< Hide in default, will show when necessary @SINCE_1_0.0
- };
-
- /**
- * @brief An enum of Window types.
- * @SINCE_1_2.60
- */
- enum Type
- {
- NORMAL, ///< A default window type. Indicates a normal, top-level window. Almost every window will be created with this type. @SINCE_1_2.60
- NOTIFICATION, ///< A notification window, like a warning about battery life or a new E-Mail received. @SINCE_1_2.60
- UTILITY, ///< A persistent utility window, like a toolbox or palette. @SINCE_1_2.60
- DIALOG ///< Used for simple dialog windows. @SINCE_1_2.60
- };
-
- /**
- * @brief An enum of screen mode.
- * @SINCE_1_2.60
- */
- struct NotificationLevel
- {
- /**
- * @brief An enum of screen mode.
- * @SINCE_1_2.60
- */
- enum Type
- {
- 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
- BASE = 10, ///< Base notification level. @SINCE_1_2.60
- MEDIUM = 20, ///< Higher notification level than base. @SINCE_1_2.60
- HIGH = 30, ///< Higher notification level than medium. @SINCE_1_2.60
- TOP = 40 ///< The highest notification level. @SINCE_1_2.60
- };
- };
-
- /**
- * @brief An enum of screen mode.
- * @SINCE_1_2.60
- */
- struct ScreenOffMode
- {
- /**
- * @brief An enum of screen mode.
- * @SINCE_1_2.60
- */
- enum Type
- {
- TIMEOUT, ///< The mode which turns the screen off after a timeout. @SINCE_1_2.60
- NEVER, ///< The mode which keeps the screen turned on. @SINCE_1_2.60
- };
-
- static constexpr Type DEFAULT { TIMEOUT }; ///< The default mode. @SINCE_1_2.60
- };
-
// Methods
/**
* @param[in] name The Window title
* @param[in] isTransparent Whether Window is transparent
* @return A new window
+ * @note This creates an extra window in addition to the default main window
*/
static Window New(PositionSize windowPosition, const std::string& name, bool isTransparent = false);
* @param[in] name The Window title
* @param[in] className The Window class name
* @param[in] isTransparent Whether Window is transparent
+ * @note This creates an extra window in addition to the default main window
* @return A new Window
*/
static Window New(PositionSize windowPosition, const std::string& name, const std::string& className, bool isTransparent = false);
Window& operator=(const Window& rhs);
/**
- * @brief This sets whether the indicator bar should be shown or not.
- * @SINCE_1_0.0
- * @param[in] visibleMode Visible mode for indicator bar, VISIBLE in default
+ * @brief Move constructor.
+ *
+ * @SINCE_1_9.24
+ * @param[in] rhs A reference to the moved handle
*/
- void ShowIndicator( IndicatorVisibleMode visibleMode );
+ Window(Window&& rhs);
/**
- * @brief This sets the opacity mode of indicator bar.
- * @SINCE_1_0.0
- * @param[in] opacity The opacity mode
+ * @brief Move assignment operator.
+ *
+ * @SINCE_1_9.24
+ * @param[in] rhs A reference to the moved handle
+ * @return A reference to this handle
*/
- void SetIndicatorBgOpacity( IndicatorBgOpacity opacity );
+ Window& operator=(Window&& rhs);
/**
- * @brief This sets the orientation of indicator bar.
+ * @brief Downcast sceneHolder to window
*
- * It does not implicitly show the indicator if it is currently hidden.
- * @SINCE_1_0.0
- * @param[in] orientation The orientation
+ * @SINCE_2_1.46
+ * @param[in] handle The handle need to downcast
+ * @return Whether it's a valid window or not
+ */
+ static Window DownCast(BaseHandle handle);
+
+ /**
+ * @brief Adds a child Actor to the Window.
+ *
+ * The child will be referenced.
+ *
+ * @SINCE_1_4.19
+ * @param[in] actor The child
+ * @pre The actor has been initialized.
+ * @pre The actor does not have a parent.
*/
- void RotateIndicator(WindowOrientation orientation);
+ void Add(Actor actor);
+
+ /**
+ * @brief Removes a child Actor from the Window.
+ *
+ * The child will be unreferenced.
+ *
+ * @SINCE_1_4.19
+ * @param[in] actor The child
+ * @pre The actor has been added to the stage.
+ */
+ void Remove(Actor actor);
+
+ /**
+ * @brief Sets the background color of the Window.
+ *
+ * @SINCE_1_4.19
+ * @param[in] color The new background color
+ */
+ void SetBackgroundColor(const Vector4& color);
+
+ /**
+ * @brief Gets the background color of the Window.
+ *
+ * @SINCE_1_4.19
+ * @return The background color
+ */
+ Vector4 GetBackgroundColor() const;
+
+ /**
+ * @brief Returns the root Layer of the Window.
+ *
+ * @SINCE_1_4.19
+ * @return The root layer
+ */
+ Layer GetRootLayer() const;
+
+ /**
+ * @brief Queries the number of on-scene layers in the Window.
+ *
+ * Note that a default layer is always provided (count >= 1).
+ *
+ * @SINCE_1_4.19
+ * @return The number of layers
+ */
+ uint32_t GetLayerCount() const;
+
+ /**
+ * @brief Retrieves the layer at a specified depth in the Window.
+ *
+ * @SINCE_1_4.19
+ * @param[in] depth The depth
+ * @return The layer found at the given depth
+ * @pre Depth is less than layer count; see GetLayerCount().
+ */
+ Layer GetLayer(uint32_t depth) const;
+
+ /**
+ * @brief Retrieves the DPI of the window.
+ *
+ * @SINCE_1_9.21
+ * @return The DPI of the window
+ */
+ Uint16Pair GetDpi() const;
/**
* @brief Sets the window name and class string.
* @SINCE_1_0.0
* @param[in] orientation The available orientation to add
*/
- void AddAvailableOrientation( WindowOrientation orientation );
+ void AddAvailableOrientation(WindowOrientation orientation);
/**
* @brief Removes an orientation from the list of available orientations.
* @SINCE_1_0.0
* @param[in] orientation The available orientation to remove
*/
- void RemoveAvailableOrientation( WindowOrientation orientation );
+ void RemoveAvailableOrientation(WindowOrientation orientation);
/**
* @brief Sets a preferred orientation.
* @SINCE_1_0.0
* @param[in] orientation The preferred orientation
* @pre Orientation is in the list of available orientations.
+ *
+ * @note To unset the preferred orientation, orientation should be set NO_ORIENTATION_PREFERENCE.
*/
- void SetPreferredOrientation( WindowOrientation orientation );
+ void SetPreferredOrientation(WindowOrientation orientation);
/**
* @brief Gets the preferred orientation.
WindowOrientation GetPreferredOrientation();
/**
- * @brief Returns the Drag & drop detector which can be used to receive drag & drop events.
- * @note Not intended for application developers.
- * @SINCE_1_0.0
- * @return A handle to the DragAndDropDetector
- */
- DragAndDropDetector GetDragAndDropDetector() const;
-
- /**
* @brief Gets the native handle of the window.
*
* When users call this function, it wraps the actual type used by the underlying window system.
* @SINCE_1_2.60
* @param[in] accept If focus is accepted or not. Default is true.
*/
- void SetAcceptFocus( bool accept );
+ void SetAcceptFocus(bool accept);
/**
* @brief Returns whether window accepts focus or not.
* @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.
* If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
*/
- std::string GetSupportedAuxiliaryHint( unsigned int index ) const;
+ std::string GetSupportedAuxiliaryHint(unsigned int index) const;
/**
* @brief Creates an auxiliary hint of the window.
* @param[in] value The value string.
* @return The ID of created auxiliary hint, or @c 0 on failure.
*/
- unsigned int AddAuxiliaryHint( const std::string& hint, const std::string& value );
+ unsigned int AddAuxiliaryHint(const std::string& hint, const std::string& value);
/**
* @brief Removes an auxiliary hint of the window.
* @param[in] id The ID of the auxiliary hint.
* @return True if no error occurred, false otherwise.
*/
- bool RemoveAuxiliaryHint( unsigned int id );
+ bool RemoveAuxiliaryHint(unsigned int id);
/**
* @brief Changes a value of the auxiliary hint.
* @param[in] value The value string to be set.
* @return True if no error occurred, false otherwise.
*/
- bool SetAuxiliaryHintValue( unsigned int id, const std::string& value );
+ bool SetAuxiliaryHintValue(unsigned int id, const std::string& value);
/**
* @brief Gets a value of the auxiliary hint.
* @param[in] id The auxiliary hint ID.
* @return The string value of the auxiliary hint ID, or an empty string if none exists.
*/
- std::string GetAuxiliaryHintValue( unsigned int id ) const;
+ std::string GetAuxiliaryHintValue(unsigned int id) const;
/**
* @brief Gets a ID of the auxiliary hint string.
* @param[in] hint The auxiliary hint string.
* @return The ID of the auxiliary hint string, or @c 0 if none exists.
*/
- unsigned int GetAuxiliaryHintId( const std::string& hint ) const;
+ unsigned int GetAuxiliaryHintId(const std::string& hint) const;
/**
* @brief Sets a region to accept input events.
* @SINCE_1_2.60
* @param[in] inputRegion The region to accept input events.
*/
- void SetInputRegion( const Rect< int >& inputRegion );
+ void SetInputRegion(const Rect<int>& inputRegion);
/**
* @brief Sets a window type.
- * @SINCE_1_2.60
+ * @@SINCE_2_0.0
* @param[in] type The window type.
* @remarks The default window type is NORMAL.
*/
- void SetType( Type type );
+ void SetType(WindowType type);
/**
* @brief Gets a window type.
- * @SINCE_1_2.60
+ * @@SINCE_2_0.0
* @return A window type.
*/
- Type GetType() const;
+ WindowType GetType() const;
/**
* @brief Sets a priority level for the specified notification window.
- * @SINCE_1_2.60
+ * @@SINCE_2_0.0
* @param[in] level The notification window level.
- * @return True if no error occurred, false otherwise.
+ * @return The result of the window operation.
* @PRIVLEVEL_PUBLIC
* @PRIVILEGE_WINDOW_PRIORITY
* @remarks This can be used for a notification type window only. The default level is NotificationLevel::NONE.
*/
- bool SetNotificationLevel( NotificationLevel::Type level );
+ WindowOperationResult SetNotificationLevel(WindowNotificationLevel level);
/**
* @brief Gets a priority level for the specified notification window.
- * @SINCE_1_2.60
+ * @@SINCE_2_0.0
* @return The notification window level.
* @remarks This can be used for a notification type window only.
*/
- NotificationLevel::Type GetNotificationLevel() const;
+ WindowNotificationLevel GetNotificationLevel() const;
/**
* @brief Sets a transparent window's visual state to opaque.
* @remarks This will have no effect on an opaque window.
* It doesn't change transparent window to opaque window but lets the window manager know the visual state of the window.
*/
- void SetOpaqueState( bool opaque );
+ void SetOpaqueState(bool opaque);
/**
* @brief Returns whether a transparent window's visual state is opaque or not.
/**
* @brief Sets a window's screen off mode.
* @details This API is useful when the application needs to keep the display turned on.
- * If the application sets the screen mode to #::Dali::Window::ScreenOffMode::NEVER to its window and the window is shown,
+ * If the application sets the screen mode to #::Dali::WindowScreenOffMode::NEVER to its window and the window is shown,
* the window manager requests the display system to keep the display on as long as the window is shown.
* If the window is no longer shown, then the window manager requests the display system to go back to normal operation.
- * @SINCE_1_2.60
+ * @@SINCE_2_0.0
* @param[in] screenOffMode The screen mode.
- * @return True if no error occurred, false otherwise.
+ * @return The result of the window operation.
* @PRIVLEVEL_PUBLIC
* @PRIVILEGE_DISPLAY
*/
- bool SetScreenOffMode(ScreenOffMode::Type screenOffMode);
+ WindowOperationResult SetScreenOffMode(WindowScreenOffMode screenOffMode);
/**
* @brief Gets a screen off mode of the window.
- * @SINCE_1_2.60
+ * @@SINCE_2_0.0
* @return The screen off mode.
*/
- ScreenOffMode::Type GetScreenOffMode() const;
+ WindowScreenOffMode GetScreenOffMode() const;
/**
* @brief Sets preferred brightness of the window.
* A value less than 0 results in default brightness and a value greater than 100 results in maximum brightness.
* @SINCE_1_2.60
* @param[in] brightness The preferred brightness (0 to 100).
- * @return True if no error occurred, false otherwise.
+ * @return The result of the window operation.
* @PRIVLEVEL_PUBLIC
* @PRIVILEGE_DISPLAY
*/
- bool SetBrightness( int brightness );
+ WindowOperationResult SetBrightness(int brightness);
/**
- * @brief Gets preffered brightness of the window.
+ * @brief Gets preferred brightness of the window.
* @SINCE_1_2.60
- * @return The preffered brightness.
+ * @return The preferred brightness.
*/
int GetBrightness() const;
* @SINCE_1_2.60
* @param[in] size The new window size
*/
- void SetSize( WindowSize size );
+ void SetSize(WindowSize size);
/**
* @brief Gets a size of the window.
* @SINCE_1_2.60
* @param[in] position The new window position
*/
- void SetPosition( WindowPosition position );
+ void SetPosition(WindowPosition position);
/**
* @brief Gets a position of the window.
* @SINCE_1_2.60
* @param[in] transparent Whether the window is transparent
*/
- void SetTransparency( bool transparent );
+ void SetTransparency(bool transparent);
-public: // Signals
/**
- * @brief The user should connect to this signal to get a timing when indicator was shown / hidden.
- * @SINCE_1_0.0
- * @return The signal to connect to
+ * @brief Retrieves the list of render-tasks in the window.
+ *
+ * @SINCE_1_9.21
+ * @return A valid handle to a RenderTaskList
*/
- IndicatorSignalType& IndicatorVisibilityChangedSignal();
+ RenderTaskList GetRenderTaskList();
+public: // Signals
/**
* @brief The user should connect to this signal to get a timing when window gains focus or loses focus.
*
* A callback of the following type may be connected:
* @code
- * void YourCallbackName( bool focusIn );
+ * void YourCallbackName( Window window, bool focusIn );
* @endcode
* The parameter is true if window gains focus, otherwise false.
+ * and window means this signal was called from what window
*
- * @SINCE_1_2.60
+ * @SINCE_1_4.35
* @return The signal to connect to
*/
- FocusSignalType& FocusChangedSignal();
+ FocusChangeSignalType& FocusChangeSignal();
/**
* @brief This signal is emitted when the window is resized.
*
* A callback of the following type may be connected:
* @code
- * void YourCallbackName( int width, int height );
+ * void YourCallbackName( Window window, int width, int height );
* @endcode
* The parameters are the resized width and height.
+ * and window means this signal was called from what window
*
- * @SINCE_1_2.60
+ * @SINCE_1_4.35
* @return The signal to connect to
*/
- ResizedSignalType& ResizedSignal();
+ ResizeSignalType& ResizeSignal();
+
+ /**
+ * @brief This signal is emitted when key event is received.
+ *
+ * A callback of the following type may be connected:
+ * @code
+ * void YourCallbackName(const KeyEvent& event);
+ * @endcode
+ *
+ * @SINCE_1_9.21
+ * @return The signal to connect to
+ */
+ KeyEventSignalType& KeyEventSignal();
+
+ /**
+ * @brief This signal is emitted when the screen is touched and when the touch ends
+ * (i.e. the down & up touch events only).
+ *
+ * If there are multiple touch points, then this will be emitted when the first touch occurs and
+ * then when the last finger is lifted.
+ * An interrupted event will also be emitted (if it occurs).
+ * A callback of the following type may be connected:
+ * @code
+ * void YourCallbackName(const TouchEvent& event);
+ * @endcode
+ *
+ * @SINCE_1_9.28
+ * @return The touch signal to connect to
+ *
+ * @note Motion events are not emitted.
+ */
+ TouchEventSignalType& TouchedSignal();
public: // Not intended for application developers
/// @cond internal
* @SINCE_1_0.0
* @param[in] window A pointer to the Window
*/
- explicit DALI_INTERNAL Window( Internal::Adaptor::Window* window );
+ explicit DALI_INTERNAL Window(Internal::Adaptor::Window* window);
/// @endcond
};