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