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