adaptors/devel-api/adaptor-framework/window-devel.h

   1 #ifndef DALI_WINDOW_DEVEL_H
   2 #define DALI_WINDOW_DEVEL_H
   3
   4 /*
   5  * Copyright (c) 2017 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
  26 // INTERNAL INCLUDES
  27 #ifdef DALI_ADAPTOR_COMPILATION  // full path doesn't exist until adaptor is installed so we have to use relative
  28 #include <window.h>
  29 #else
  30 #include <dali/public-api/adaptor-framework/window.h>
  31 #endif
  32
  33 namespace Dali
  34 {
  35
  36 namespace DevelWindow
  37 {
  38
  39 namespace NotificationLevel
  40 {
  41
  42 /**
  43  * @brief An enum of notification window's priority level.
  44  */
  45 enum Type
  46 {
  47   NONE    = -1,    ///< No notification level. Default level. This value makes the notification window place in the layer of the normal window.
  48   BASE    = 10,    ///< Base notification level.
  49   MEDIUM  = 20,    ///< Higher notification level than base.
  50   HIGH    = 30,    ///< Higher notification level than medium.
  51   TOP     = 40     ///< The highest notification level.
  52 };
  53
  54 } // namespace NotificationLevel
  55
  56 namespace ScreenMode
  57 {
  58
  59 /**
  60  * @brief An enum of screen mode.
  61  */
  62 enum Type
  63 {
  64   DEFAULT,      ///< The mode which turns the screen off after a timeout.
  65   ALWAYS_ON     ///< The mode which keeps the screen turned on.
  66 };
  67
  68 } // namespace ScreenMode
  69
  70 /**
  71  * @brief An enum of Window types.
  72  */
  73 enum Type
  74 {
  75   NORMAL,           ///< A default window type. Indicates a normal, top-level window. Almost every window will be created with this type.
  76   NOTIFICATION,     ///< A notification window, like a warning about battery life or a new E-Mail received.
  77   UTILITY,          ///< A persistent utility window, like a toolbox or palette.
  78   DIALOG            ///< Used for simple dialog windows.
  79 };
  80
  81 typedef Uint16Pair WindowSize;          ///< Window size type
  82 typedef Uint16Pair WindowPosition;      ///< Window position type
  83
  84 typedef Signal< void ( bool ) > FocusSignalType;         ///< Window focus signal type
  85 typedef Signal< void ( WindowSize ) > ResizedSignalType; ///< Window resized signal type
  86
  87 /**
  88  * @brief The user should connect to this signal to get a timing when window gains focus or loses focus.
  89  *
  90  * A callback of the following type may be connected:
  91  * @code
  92  *   void YourCallbackName( bool focusIn );
  93  * @endcode
  94  * The parameter is true if window gains focus, otherwise false.
  95  *
  96  * @param[in] window The window to get a signal
  97  * @return The signal to connect to
  98  */
  99 DALI_IMPORT_API FocusSignalType& FocusChangedSignal( Window window );
 100
 101 /**
 102  * @brief Sets whether window accepts focus or not.
 103  *
 104  * @param[in] window The window to accept focus
 105  * @param[in] accept If focus is accepted or not. Default is true.
 106  */
 107 DALI_IMPORT_API void SetAcceptFocus( Window window, bool accept );
 108
 109 /**
 110  * @brief Returns whether window accepts focus or not.
 111  *
 112  * @param[in] window The window to accept focus
 113  * @return True if the window accept focus, false otherwise
 114  */
 115 DALI_IMPORT_API bool IsFocusAcceptable( Window window );
 116
 117 /**
 118  * @brief Shows the window if it is hidden.
 119  * @param[in] window The window to show
 120  */
 121 DALI_IMPORT_API void Show( Window window );
 122
 123 /**
 124  * @brief Hides the window if it is showing.
 125  * @param[in] window The window to hide
 126  */
 127 DALI_IMPORT_API void Hide( Window window );
 128
 129 /**
 130  * @brief Returns whether the window is visible or not.
 131  * @param[in] window The window to query
 132  * @return True if the window is visible, false otherwise.
 133  */
 134 DALI_IMPORT_API bool IsVisible( Window window );
 135
 136 /**
 137  * @brief Gets the count of supported auxiliary hints of the window.
 138  * @param[in] window The window to get the hint count
 139  * @return The number of supported auxiliary hints.
 140  *
 141  * @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.
 142  * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
 143  */
 144 DALI_IMPORT_API unsigned int GetSupportedAuxiliaryHintCount( Window window );
 145
 146 /**
 147  * @brief Gets the supported auxiliary hint string of the window.
 148  * @param[in] window The window to get the hint
 149  * @param[in] index The index of the supported auxiliary hint lists
 150  * @return The auxiliary hint string of the index.
 151  *
 152  * @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.
 153  * If you want to set specific hint to your window, then you should check whether it exists in the supported auxiliary hints.
 154  */
 155 DALI_IMPORT_API std::string GetSupportedAuxiliaryHint( Window window, unsigned int index );
 156
 157 /**
 158  * @brief Creates an auxiliary hint of the window.
 159  * @param[in] window The window to create a hint
 160  * @param[in] hint The auxiliary hint string.
 161  * @param[in] value The value string.
 162  * @return The ID of created auxiliary hint, or @c 0 on failure.
 163  */
 164 DALI_IMPORT_API unsigned int AddAuxiliaryHint( Window window, const std::string& hint, const std::string& value );
 165
 166 /**
 167  * @brief Removes an auxiliary hint of the window.
 168  * @param[in] window The window to remove a hint
 169  * @param[in] id The ID of the auxiliary hint.
 170  * @return True if no error occurred, false otherwise.
 171  */
 172 DALI_IMPORT_API bool RemoveAuxiliaryHint( Window window, unsigned int id );
 173
 174 /**
 175  * @brief Changes a value of the auxiliary hint.
 176  * @param[in] window The window to set a value
 177  * @param[in] id The auxiliary hint ID.
 178  * @param[in] value The value string to be set.
 179  * @return True if no error occurred, false otherwise.
 180  */
 181 DALI_IMPORT_API bool SetAuxiliaryHintValue( Window window, unsigned int id, const std::string& value );
 182
 183 /**
 184  * @brief Gets a value of the auxiliary hint.
 185  * @param[in] window The window to get a value
 186  * @param[in] id The auxiliary hint ID.
 187  * @return The string value of the auxiliary hint ID, or an empty string if none exists.
 188  */
 189 DALI_IMPORT_API std::string GetAuxiliaryHintValue( Window window, unsigned int id );
 190
 191 /**
 192  * @brief Gets a ID of the auxiliary hint string.
 193  * @param[in] window The window to get an ID
 194  * @param[in] hint The auxiliary hint string.
 195  * @return The ID of the auxiliary hint string, or @c 0 if none exists.
 196  */
 197 DALI_IMPORT_API unsigned int GetAuxiliaryHintId( Window window, const std::string& hint );
 198
 199 /**
 200  * @brief Sets a region to accept input events.
 201  * @param[in] window The window to set a region
 202  * @param[in] inputRegion The region to accept input events.
 203  */
 204 DALI_IMPORT_API void SetInputRegion( Window window, const Rect< int >& inputRegion );
 205
 206 /**
 207  * @brief Sets a window type.
 208  * @param[in] window The window to set a type
 209  * @param[in] type The window type.
 210  * @remarks The default window type is NORMAL.
 211  */
 212 DALI_IMPORT_API void SetType( Window window, Type type );
 213
 214 /**
 215  * @brief Gets a window type.
 216  * @param[in] window The window to get a type
 217  * @return A window type.
 218  */
 219 DALI_IMPORT_API Type GetType( Window window );
 220
 221 /**
 222  * @brief Sets a priority level for the specified notification window.
 223  * @param[in] window The window to set a notification level
 224  * @param[in] level The notification window level.
 225  * @return True if no error occurred, false otherwise.
 226  * @PRIVLEVEL_PUBLIC
 227  * @PRIVILEGE_WINDOW_PRIORITY
 228  * @remarks This can be used for a notification type window only. The default level is NotificationLevel::NONE.
 229  */
 230 DALI_IMPORT_API bool SetNotificationLevel( Window window, NotificationLevel::Type level );
 231
 232 /**
 233  * @brief Gets a priority level for the specified notification window.
 234  * @param[in] window The window to get a notification level
 235  * @return The notification window level.
 236  * @remarks This can be used for a notification type window only.
 237  */
 238 DALI_IMPORT_API NotificationLevel::Type GetNotificationLevel( Window window );
 239
 240 /**
 241  * @brief Sets a transparent window's visual state to opaque.
 242  * @details If a visual state of a transparent window is opaque,
 243  * then the window manager could handle it as an opaque window when calculating visibility.
 244  * @param[in] window The window to set a state
 245  * @param[in] opaque Whether the window's visual state is opaque.
 246  * @remarks This will have no effect on an opaque window.
 247  * It doesn't change transparent window to opaque window but lets the window manager know the visual state of the window.
 248  */
 249 DALI_IMPORT_API void SetOpaqueState( Window window, bool opaque );
 250
 251 /**
 252  * @brief Returns whether a transparent window's visual state is opaque or not.
 253  * @param[in] window The window to get a state
 254  * @return True if the window's visual state is opaque, false otherwise.
 255  * @remarks The return value has no meaning on an opaque window.
 256  */
 257 DALI_IMPORT_API bool IsOpaqueState( Window window );
 258
 259 /**
 260  * @brief Sets a window's screen mode.
 261  * @details This API is useful when the application needs to keep the display turned on.
 262  * If the application sets the screen mode to #ScreenMode::ALWAYS_ON to its window and the window is shown,
 263  * the window manager requests the display system to keep the display on as long as the window is shown.
 264  * If the window is no longer shown, then the window manager requests the display system to go back to normal operation.
 265  * @param[in] window The window to set a screen mode
 266  * @param[in] screenMode The screen mode.
 267  * @return True if no error occurred, false otherwise.
 268  * @PRIVLEVEL_PUBLIC
 269  * @PRIVILEGE_DISPLAY
 270  */
 271 DALI_IMPORT_API bool SetScreenMode( Window window, ScreenMode::Type screenMode );
 272
 273 /**
 274  * @brief Gets a screen mode of the window.
 275  * @param[in] window The window to get a screen mode
 276  * @return The screen mode.
 277  */
 278 DALI_IMPORT_API ScreenMode::Type GetScreenMode( Window window );
 279
 280 /**
 281  * @brief Sets preferred brightness of the window.
 282  * @details This API is useful when the application needs to change the brightness of the screen when it is appeared on the screen.
 283  * 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.
 284  * If the window is no longer shown, then the window manager requests the display system to go back to default brightness.
 285  * A value less than 0 results in default brightness and a value greater than 100 results in maximum brightness.
 286  * @param[in] window The window to set a brightness
 287  * @param[in] brightness The preferred brightness (0 to 100).
 288  * @return True if no error occurred, false otherwise.
 289  * @PRIVLEVEL_PUBLIC
 290  * @PRIVILEGE_DISPLAY
 291  */
 292 DALI_IMPORT_API bool SetBrightness( Window window, int brightness );
 293
 294 /**
 295  * @brief Gets preffered brightness of the window.
 296  * @param[in] window The window to get brightness
 297  * @return The preffered brightness.
 298  */
 299 DALI_IMPORT_API int GetBrightness( Window window );
 300
 301 /**
 302  * @brief This signal is emitted when the window is resized.
 303  *
 304  * A callback of the following type may be connected:
 305  * @code
 306  *   void YourCallbackName( int width, int height );
 307  * @endcode
 308  * The parameters are the resized width and height.
 309  *
 310  * @param[in] window The window to get a signal
 311  * @return The signal to connect to
 312  */
 313 DALI_IMPORT_API ResizedSignalType& ResizedSignal( Window window );
 314
 315 /**
 316  * @brief Sets a size of the window.
 317  *
 318  * @param[in] window The window to set a size
 319  * @param[in] size The new window size
 320  */
 321 DALI_IMPORT_API void SetSize( Window window, WindowSize size );
 322
 323 /**
 324  * @brief Gets a size of the window.
 325  *
 326  * @param[in] window The window to get a size
 327  * @return The size of the window
 328  */
 329 DALI_IMPORT_API WindowSize GetSize( Window window );
 330
 331 /**
 332  * @brief Sets a position of the window.
 333  *
 334  * @param[in] window The window to set a position
 335  * @param[in] position The new window position
 336  */
 337 DALI_IMPORT_API void SetPosition( Window window, WindowPosition position );
 338
 339 /**
 340  * @brief Gets a position of the window.
 341  *
 342  * @param[in] window The window to get a position
 343  * @return The position of the window
 344  */
 345 DALI_IMPORT_API WindowPosition GetPosition( Window window );
 346
 347 /**
 348  * @brief Sets whether the window is transparent or not.
 349  *
 350  * @param[in] window The window to set transparency
 351  * @param[in] transparent Whether the window is transparent
 352  */
 353 DALI_IMPORT_API void SetTransparency( Window window, bool transparent );
 354
 355 } // namespace DevelWindow
 356
 357 } // namespace Dali
 358
 359 #endif // DALI_WINDOW_DEVEL_H