1 #ifndef __DALI_WINDOW_H__
2 #define __DALI_WINDOW_H__
5 * Copyright (c) 2018 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>
37 * @addtogroup dali_adaptor_framework
41 typedef Dali::Rect<int> PositionSize;
43 namespace Internal DALI_INTERNAL
51 class DragAndDropDetector;
57 * @brief The window class is used internally for drawing.
59 * A Window has an orientation and indicator properties.
60 * You can get a valid Window handle by calling Dali::Application::GetWindow().
63 class DALI_ADAPTOR_API Window : public BaseHandle
67 typedef Uint16Pair WindowSize; ///< Window size type @SINCE_1_2.60
68 typedef Uint16Pair WindowPosition; ///< Window position type @SINCE_1_2.60
70 typedef Signal< void (bool) > IndicatorSignalType; ///< @DEPRECATED_1_4.9 @brief Indicator state signal type @SINCE_1_0.0
71 typedef Signal< void (bool) > FocusSignalType; ///< Window focus signal type @SINCE_1_2.60
72 typedef Signal< void (WindowSize) > ResizedSignalType; ///< Window resized signal type @SINCE_1_2.60
79 * @brief Enumeration for orientation of the window is the way in which a rectangular page is oriented for normal viewing.
82 enum WindowOrientation
84 PORTRAIT = 0, ///< Portrait orientation. The height of the display area is greater than the width. @SINCE_1_0.0
85 LANDSCAPE = 90, ///< Landscape orientation. A wide view area is needed. @SINCE_1_0.0
86 PORTRAIT_INVERSE = 180, ///< Portrait inverse orientation @SINCE_1_0.0
87 LANDSCAPE_INVERSE = 270 ///< Landscape inverse orientation @SINCE_1_0.0
92 * @brief Enumeration for opacity of the indicator.
95 enum IndicatorBgOpacity
97 OPAQUE = 100, ///< @DEPRECATED_1_4.9 @brief Fully opaque indicator Bg @SINCE_1_0.0
98 TRANSLUCENT = 50, ///< @DEPRECATED_1_4.9 @brief Semi translucent indicator Bg @SINCE_1_0.0
99 TRANSPARENT = 0 ///< @DEPRECATED_1_4.9 @brief Fully transparent indicator Bg @SINCE_1_0.0
104 * @brief Enumeration for visible mode of the indicator.
107 enum IndicatorVisibleMode
109 INVISIBLE = 0, ///< @DEPRECATED_1_4.9 @brief Hide indicator @SINCE_1_0.0
110 VISIBLE = 1, ///< @DEPRECATED_1_4.9 @brief Show indicator @SINCE_1_0.0
111 AUTO = 2 ///< @DEPRECATED_1_4.9 @brief Hide in default, will show when necessary @SINCE_1_0.0
115 * @brief An enum of Window types.
120 NORMAL, ///< A default window type. Indicates a normal, top-level window. Almost every window will be created with this type. @SINCE_1_2.60
121 NOTIFICATION, ///< A notification window, like a warning about battery life or a new E-Mail received. @SINCE_1_2.60
122 UTILITY, ///< A persistent utility window, like a toolbox or palette. @SINCE_1_2.60
123 DIALOG ///< Used for simple dialog windows. @SINCE_1_2.60
127 * @brief An enum of screen mode.
130 struct NotificationLevel
133 * @brief An enum of screen mode.
138 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
139 BASE = 10, ///< Base notification level. @SINCE_1_2.60
140 MEDIUM = 20, ///< Higher notification level than base. @SINCE_1_2.60
141 HIGH = 30, ///< Higher notification level than medium. @SINCE_1_2.60
142 TOP = 40 ///< The highest notification level. @SINCE_1_2.60
147 * @brief An enum of screen mode.
153 * @brief An enum of screen mode.
158 TIMEOUT, ///< The mode which turns the screen off after a timeout. @SINCE_1_2.60
159 NEVER, ///< The mode which keeps the screen turned on. @SINCE_1_2.60
162 static constexpr Type DEFAULT { TIMEOUT }; ///< The default mode. @SINCE_1_2.60
168 * @brief Creates an initialized handle to a new Window.
170 * @param[in] windowPosition The position and size of the Window
171 * @param[in] name The Window title
172 * @param[in] isTransparent Whether Window is transparent
173 * @return A new window
175 static Window New(PositionSize windowPosition, const std::string& name, bool isTransparent = false);
178 * @brief Creates an initialized handle to a new Window.
180 * @param[in] windowPosition The position and size of the Window
181 * @param[in] name The Window title
182 * @param[in] className The Window class name
183 * @param[in] isTransparent Whether Window is transparent
184 * @return A new Window
186 static Window New(PositionSize windowPosition, const std::string& name, const std::string& className, bool isTransparent = false);
189 * @brief Creates an uninitialized handle.
191 * This can be initialized using Dali::Application::GetWindow() or
192 * Dali::Window::New().
200 * This is non-virtual since derived Handle types must not contain data or virtual methods.
206 * @brief This copy constructor is required for (smart) pointer semantics.
209 * @param[in] handle A reference to the copied handle
211 Window(const Window& handle);
214 * @brief This assignment operator is required for (smart) pointer semantics.
217 * @param[in] rhs A reference to the copied handle
218 * @return A reference to this
220 Window& operator=(const Window& rhs);
224 * @brief This sets whether the indicator bar should be shown or not.
226 * @param[in] visibleMode Visible mode for indicator bar, VISIBLE in default
228 void ShowIndicator( IndicatorVisibleMode visibleMode ) DALI_DEPRECATED_API;
232 * @brief This sets the opacity mode of indicator bar.
234 * @param[in] opacity The opacity mode
236 void SetIndicatorBgOpacity( IndicatorBgOpacity opacity ) DALI_DEPRECATED_API;
240 * @brief This sets the orientation of indicator bar.
242 * It does not implicitly show the indicator if it is currently hidden.
244 * @param[in] orientation The orientation
246 void RotateIndicator(WindowOrientation orientation) DALI_DEPRECATED_API;
249 * @brief Sets the window name and class string.
251 * @param[in] name The name of the window
252 * @param[in] klass The class of the window
254 void SetClass(std::string name, std::string klass);
257 * @brief Raises window to the top of Window stack.
263 * @brief Lowers window to the bottom of Window stack.
269 * @brief Activates window to the top of Window stack even it is iconified.
275 * @brief Adds an orientation to the list of available orientations.
277 * @param[in] orientation The available orientation to add
279 void AddAvailableOrientation( WindowOrientation orientation );
282 * @brief Removes an orientation from the list of available orientations.
284 * @param[in] orientation The available orientation to remove
286 void RemoveAvailableOrientation( WindowOrientation orientation );
289 * @brief Sets a preferred orientation.
291 * @param[in] orientation The preferred orientation
292 * @pre Orientation is in the list of available orientations.
294 void SetPreferredOrientation( WindowOrientation orientation );
297 * @brief Gets the preferred orientation.
299 * @return The preferred orientation if previously set, or none
301 WindowOrientation GetPreferredOrientation();
304 * @brief Returns the Drag & drop detector which can be used to receive drag & drop events.
305 * @note Not intended for application developers.
307 * @return A handle to the DragAndDropDetector
309 DragAndDropDetector GetDragAndDropDetector() const;
312 * @brief Gets the native handle of the window.
314 * When users call this function, it wraps the actual type used by the underlying window system.
316 * @return The native handle of the Window or an empty handle
318 Any GetNativeHandle() const;
321 * @brief Sets whether window accepts focus or not.
324 * @param[in] accept If focus is accepted or not. Default is true.
326 void SetAcceptFocus( bool accept );
329 * @brief Returns whether window accepts focus or not.
332 * @return True if the window accept focus, false otherwise
334 bool IsFocusAcceptable() const;
337 * @brief Shows the window if it is hidden.
343 * @brief Hides the window if it is showing.
349 * @brief Returns whether the window is visible or not.
351 * @return True if the window is visible, false otherwise.
353 bool IsVisible() const;
356 * @brief Gets the count of supported auxiliary hints of the window.
358 * @return The number of supported auxiliary hints.
360 * @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.
361 * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
363 unsigned int GetSupportedAuxiliaryHintCount() const;
366 * @brief Gets the supported auxiliary hint string of the window.
368 * @param[in] index The index of the supported auxiliary hint lists
369 * @return The auxiliary hint string of the index.
371 * @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.
372 * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
374 std::string GetSupportedAuxiliaryHint( unsigned int index ) const;
377 * @brief Creates an auxiliary hint of the window.
379 * @param[in] hint The auxiliary hint string.
380 * @param[in] value The value string.
381 * @return The ID of created auxiliary hint, or @c 0 on failure.
383 unsigned int AddAuxiliaryHint( const std::string& hint, const std::string& value );
386 * @brief Removes an auxiliary hint of the window.
388 * @param[in] id The ID of the auxiliary hint.
389 * @return True if no error occurred, false otherwise.
391 bool RemoveAuxiliaryHint( unsigned int id );
394 * @brief Changes a value of the auxiliary hint.
396 * @param[in] id The auxiliary hint ID.
397 * @param[in] value The value string to be set.
398 * @return True if no error occurred, false otherwise.
400 bool SetAuxiliaryHintValue( unsigned int id, const std::string& value );
403 * @brief Gets a value of the auxiliary hint.
405 * @param[in] id The auxiliary hint ID.
406 * @return The string value of the auxiliary hint ID, or an empty string if none exists.
408 std::string GetAuxiliaryHintValue( unsigned int id ) const;
411 * @brief Gets a ID of the auxiliary hint string.
413 * @param[in] hint The auxiliary hint string.
414 * @return The ID of the auxiliary hint string, or @c 0 if none exists.
416 unsigned int GetAuxiliaryHintId( const std::string& hint ) const;
419 * @brief Sets a region to accept input events.
421 * @param[in] inputRegion The region to accept input events.
423 void SetInputRegion( const Rect< int >& inputRegion );
426 * @brief Sets a window type.
428 * @param[in] type The window type.
429 * @remarks The default window type is NORMAL.
431 void SetType( Type type );
434 * @brief Gets a window type.
436 * @return A window type.
438 Type GetType() const;
441 * @brief Sets a priority level for the specified notification window.
443 * @param[in] level The notification window level.
444 * @return True if no error occurred, false otherwise.
446 * @PRIVILEGE_WINDOW_PRIORITY
447 * @remarks This can be used for a notification type window only. The default level is NotificationLevel::NONE.
449 bool SetNotificationLevel( NotificationLevel::Type level );
452 * @brief Gets a priority level for the specified notification window.
454 * @return The notification window level.
455 * @remarks This can be used for a notification type window only.
457 NotificationLevel::Type GetNotificationLevel() const;
460 * @brief Sets a transparent window's visual state to opaque.
461 * @details If a visual state of a transparent window is opaque,
462 * then the window manager could handle it as an opaque window when calculating visibility.
464 * @param[in] opaque Whether the window's visual state is opaque.
465 * @remarks This will have no effect on an opaque window.
466 * It doesn't change transparent window to opaque window but lets the window manager know the visual state of the window.
468 void SetOpaqueState( bool opaque );
471 * @brief Returns whether a transparent window's visual state is opaque or not.
473 * @return True if the window's visual state is opaque, false otherwise.
474 * @remarks The return value has no meaning on an opaque window.
476 bool IsOpaqueState() const;
479 * @brief Sets a window's screen off mode.
480 * @details This API is useful when the application needs to keep the display turned on.
481 * If the application sets the screen mode to #::Dali::Window::ScreenOffMode::NEVER to its window and the window is shown,
482 * the window manager requests the display system to keep the display on as long as the window is shown.
483 * If the window is no longer shown, then the window manager requests the display system to go back to normal operation.
485 * @param[in] screenOffMode The screen mode.
486 * @return True if no error occurred, false otherwise.
490 bool SetScreenOffMode(ScreenOffMode::Type screenOffMode);
493 * @brief Gets a screen off mode of the window.
495 * @return The screen off mode.
497 ScreenOffMode::Type GetScreenOffMode() const;
500 * @brief Sets preferred brightness of the window.
501 * @details This API is useful when the application needs to change the brightness of the screen when it is appeared on the screen.
502 * 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.
503 * If the window is no longer shown, then the window manager requests the display system to go back to default brightness.
504 * A value less than 0 results in default brightness and a value greater than 100 results in maximum brightness.
506 * @param[in] brightness The preferred brightness (0 to 100).
507 * @return True if no error occurred, false otherwise.
511 bool SetBrightness( int brightness );
514 * @brief Gets preferred brightness of the window.
516 * @return The preferred brightness.
518 int GetBrightness() const;
521 * @brief Sets a size of the window.
524 * @param[in] size The new window size
526 void SetSize( WindowSize size );
529 * @brief Gets a size of the window.
532 * @return The size of the window
534 WindowSize GetSize() const;
537 * @brief Sets a position of the window.
540 * @param[in] position The new window position
542 void SetPosition( WindowPosition position );
545 * @brief Gets a position of the window.
548 * @return The position of the window
550 WindowPosition GetPosition() const;
553 * @brief Sets whether the window is transparent or not.
556 * @param[in] transparent Whether the window is transparent
558 void SetTransparency( bool transparent );
563 * @brief The user should connect to this signal to get a timing when indicator was shown / hidden.
565 * @return The signal to connect to
567 IndicatorSignalType& IndicatorVisibilityChangedSignal() DALI_DEPRECATED_API;
570 * @brief The user should connect to this signal to get a timing when window gains focus or loses focus.
572 * A callback of the following type may be connected:
574 * void YourCallbackName( bool focusIn );
576 * The parameter is true if window gains focus, otherwise false.
579 * @return The signal to connect to
581 FocusSignalType& FocusChangedSignal();
584 * @brief This signal is emitted when the window is resized.
586 * A callback of the following type may be connected:
588 * void YourCallbackName( int width, int height );
590 * The parameters are the resized width and height.
593 * @return The signal to connect to
595 ResizedSignalType& ResizedSignal();
597 public: // Not intended for application developers
600 * @brief This constructor is used by Dali::Application::GetWindow().
602 * @param[in] window A pointer to the Window
604 explicit DALI_INTERNAL Window( Internal::Adaptor::Window* window );
613 #endif // __DALI_WINDOW_H__