inc/FShellNotificationRequest.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FShellNotificationRequest.h
  20  * @brief               This is the header file for the %NotificationRequest class.
  21  *
  22  * This header file contains the declarations of the %NotificationRequest class.
  23  */
  24
  25 #ifndef _FSHELL_NOTIFICATION_REQUEST_H_
  26 #define _FSHELL_NOTIFICATION_REQUEST_H_
  27
  28 #include <FBase.h>
  29 #include <FShellNotificationManager.h>
  30
  31 namespace Tizen { namespace Shell
  32 {
  33
  34 /**
  35  * @class               NotificationRequest
  36  * @brief               This class provides methods for handling a notification request.
  37  *
  38  * @since       2.0
  39  *
  40  * @final       This class is not intended for extension.
  41  *
  42  * The %NotificationRequest class provides methods for handling a notification request. The request can contain following
  43  * items:
  44  * -# Constructing element of the notification area such as a notification title or alert text
  45  * -# Information of the indicator area such as an alert text
  46  * -# The path of the sound file to play when user selects the notification message of the notification area
  47  * -# The badge number or badge offset for notification area or main menu
  48  *
  49  * %NotificationRequest are of 2 types: bound to an application or not bound to any application. If %NotificationRequest is bound to an application, then
  50  * the associated application is launched by selecting the item in the notification area. Nothing happens when an unbounded %NotificationRequest is selected from a notification area.
  51  *
  52  * For more information about the class features, see <a href="../org.tizen.native.appprogramming/html/guide/shell/notifications.htm">Notifications</a>.
  53  *
  54  * @see Tizen::Shell::NotificationManager
  55  */
  56 class _OSP_EXPORT_ NotificationRequest
  57         : public Tizen::Base::Object
  58 {
  59
  60 public:
  61         /**
  62          * Initializes this instance of %NotificationRequest with the specified @c appBinding.
  63          *
  64          * @since       2.0
  65          *
  66          * @param[in]   appBinding      Set to @c true to bind %NotificationRequest to the destination application, @n
  67          *                                                      else @c false
  68          * @remarks     Selecting the posted notification in the notification area leads to launch of the associated application
  69          *                      if %NotificationRequest is bound to the destination application.
  70          * @see SetAlertText()
  71          */
  72         explicit NotificationRequest(bool appBinding = true);
  73
  74         /**
  75          * Copying of objects using this copy constructor is allowed.
  76          *
  77          * @since       2.0
  78          *
  79          * @param[in]   rhs     An instance of %NotificationRequest
  80          */
  81         NotificationRequest(const NotificationRequest& rhs);
  82
  83         /**
  84          * Copying of objects using this copy assignment operator is allowed.
  85          *
  86          * @since       2.0
  87          *
  88          * @param[in]   rhs     An instance of %NotificationRequest
  89          */
  90         NotificationRequest& operator =(const NotificationRequest& rhs);
  91
  92         /**
  93          * This destructor overrides Tizen::Base::Object::~Object().
  94          *
  95          * @since       2.0
  96          */
  97         virtual ~NotificationRequest(void);
  98
  99         /**
 100          * Checks whether the specified instance of %NotificationRequest equals the current instance.
 101          *
 102          * @since       2.0
 103          *
 104          * @return      @c true if the specified instance equals the current instance, @n
 105          *              else @c false
 106          * @param[in]   rhs     An instance of %NotificationRequest
 107          * @remarks     This method returns @c false if the specified object is not %NotificationRequest.
 108          */
 109         virtual bool Equals(const Object& rhs) const;
 110
 111         /**
 112          * Gets the hash value of the current instance.
 113          *
 114          * @since       2.0
 115          *
 116          * @return      The hash value of the current instance
 117          */
 118         virtual int GetHashCode(void) const;
 119
 120         /**
 121          * Gets the badge number of a notification message.
 122          *
 123          * @since       2.0
 124          *
 125          * @return              The badge number value
 126          * @remarks     If the badge number is not set, then this method returns @c -1.
 127          */
 128         int GetBadgeNumber(void) const;
 129
 130         /**
 131          * Sets the badge number of a notification message. @n
 132          * %NotificationRequest has either badge number or badge number offset.
 133          * If the badge number is set using %SetBadgeNumber(), then previous badge offset value is set to @c 0.
 134          *
 135          * @since       2.0
 136          *
 137          * @return      An error code
 138          * @param[in]   value   The badge number value
 139          * @exception   E_SUCCESS       The method is successful.
 140          * @exception   E_INVALID_ARG   The specified @c value is less than @c 0 or greater than Shell::MAX_NOTIFICATION_BADGE_NUMBER.
 141          */
 142         result SetBadgeNumber(int value);
 143
 144         /**
 145          * Gets the badge number offset of a notification message.
 146          *
 147          * @since       2.0
 148          *
 149          * @return              The badge offset value
 150          */
 151         int GetBadgeOffset(void) const;
 152
 153         /**
 154          * Sets the badge number offset of the notification message. @n
 155          * %NotificationRequest has either badge number or badge number offset.
 156          * If the badge number offset is set using %SetBadgeOffset(), then previous badge number value is set to @c -1 and ignored. @n
 157          *
 158          * When posting the notification message, badge offset value is added to the current badge number,
 159          * which can be acquired by NotificationManager::GetBadgeNumber(). Setting badge offset to @c 0
 160          * means explicitly specifying not to change the current badge value with the notification message.
 161          *
 162          * @since       2.0
 163          *
 164          * @return      An error code
 165          * @param[in]   value   The badge number value
 166          * @exception   E_SUCCESS       The method is successful.
 167          * @exception   E_INVALID_ARG   The absolute value of the specified @c value is greater than Shell::MAX_NOTIFICATION_BADGE_NUMBER.
 168          * @remarks     Even though this method does not return @c E_INVALID_ARG, it does not guarantee the success of NotificationManager::Notify().
 169          * @see SetBadgeNumber()
 170          */
 171         result SetBadgeOffset(int value);
 172
 173         /**
 174          * Gets the alert text of a notification message.
 175          *
 176          * @since       2.0
 177          *
 178          * @return      The alert text
 179          */
 180         Tizen::Base::String GetAlertText(void) const;
 181
 182         /**
 183          * Sets an alert text of a notification message.
 184          *
 185          * @since       2.0
 186          *
 187          * @return      An error code
 188          * @param[in]   text    The alert text
 189          * @exception   E_SUCCESS       The method is successful.
 190          * @exception   E_INVALID_ARG   The specified @c text is empty or the length of @c text is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
 191          * @remarks
 192          *                              - @c text is displayed according to notification layout, and the length of the @c text depends on the font attributes or the variable font width.
 193          *                              - @c text is mandatory for a notification.
 194          */
 195         result SetAlertText(const Tizen::Base::String& text);
 196
 197         /**
 198          * Gets the application message of a notification message.
 199          *
 200          * @since       2.0
 201          *
 202          * @return The message for application
 203          */
 204         Tizen::Base::String GetAppMessage(void) const;
 205
 206         /**
 207          * Sets the application message of a notification message. @n
 208          * @c appMessage is delivered as the value of the %http://tizen.org/appcontrol/data/notification key
 209          * for Tizen::App::IAppControlProviderEventListener::OnAppControlRequestReceived().
 210          *
 211          * @since       2.0
 212          *
 213          * @return      An error code
 214          * @param[in]   appMessage              The message for the application
 215          * @exception   E_SUCCESS       The method is successful.
 216          * @exception   E_INVALID_ARG   The specified @c appMessage is empty or the length of @c appMessage is greater than Shell::MAX_NOTIFICATION_LAUNCH_ARGUMENTS_LENGTH.
 217          * @exception   E_INVALID_OPERATION     This instance is not bound to the application.
 218          * @remarks     This method returns @c E_INVALID_OPERATION if the %NotificationRequest instance is not bound to the application.
 219          */
 220         result SetAppMessage(const Tizen::Base::String& appMessage);
 221
 222         /**
 223          * Gets the title text of a notification message.
 224          *
 225          * @since       2.0
 226          *
 227          * @return      The title text
 228          */
 229         Tizen::Base::String GetTitleText(void) const;
 230
 231         /**
 232          * Sets the title text of a notification message.
 233          *
 234          * @since       2.0
 235          *
 236          * @return      An error code
 237          * @param[in]   title   The title text
 238          * @exception   E_SUCCESS       The method is successful.
 239          * @exception   E_INVALID_ARG   The specified @c title is empty or the length of @c title is greater than Shell::MAX_NOTIFICATION_TITLE_LENGTH.
 240          * @remarks     If @c title is not set, the application name is displayed.
 241          */
 242         result SetTitleText(const Tizen::Base::String& title);
 243
 244         /**
 245          * Gets the file path of the icon image for a notification message.
 246          *
 247          * @since       2.0
 248          *
 249          * @return      The file path of an icon image
 250          */
 251         Tizen::Base::String GetIconFilePath(void) const;
 252
 253         /**
 254          * Sets the file path of the icon image for a notification message.
 255          *
 256          * @since       2.0
 257          *
 258          * @return      An error code
 259          * @param[in]   iconPath        The file path of the icon image
 260          * @exception   E_SUCCESS       The method is successful.
 261          * @exception   E_INVALID_ARG   The specified path is invalid.
 262          * @remarks     If @c iconPath is not set, the application icon is displayed.
 263          */
 264         result SetIconFilePath(const Tizen::Base::String& iconPath);
 265
 266         /**
 267          * Gets the file path of a sound file that is played for the notification message.
 268          *
 269          * @since       2.0
 270          *
 271          * @return      The file path of the sound file to play
 272          */
 273         Tizen::Base::String GetSoundFilePath(void) const;
 274
 275         /**
 276          * Sets the file path of the sound file that is played for the notification message.
 277          *
 278          * @since       2.0
 279          *
 280          * @return      An error code
 281          * @param[in]   soundPath       The file path of the sound file
 282          * @exception   E_SUCCESS       The method is successful.
 283          * @exception   E_INVALID_ARG   The specified path is invalid.
 284          * @remarks
 285          *                              - If the format of the sound file is not valid, then the sound file is not played properly when the notification message is displayed.
 286          *                              - If @c soundPath is not set, the default sound is played when the %NotificationRequest instance is delivered to the NotificationManager::Notify() method.
 287          */
 288         result SetSoundFilePath(const Tizen::Base::String& soundPath);
 289
 290         /**
 291          * Gets the notification type for the ongoing activity notification.
 292          *
 293          * @since       2.0
 294          *
 295          * @return      The ongoing activity notification type
 296          * @remarks     This information is only meaningful when the %NotificationRequest instance is delivered to the NotificationManager::NotifyOngoingActivity() method.
 297          * @see SetOngoingActivityType()
 298          */
 299         OngoingActivityType GetOngoingActivityType(void) const;
 300
 301         /**
 302          * Sets the notification type for an ongoing activity.
 303          *
 304          * @since       2.0
 305          *
 306          * @return      An error code
 307          * @param[in]   type    The notification type for an ongoing activity
 308          * @exception   E_SUCCESS       The method is successful.
 309          * @exception   E_INVALID_OPERATION     The current progress value is not compatible to the specified @c type.
 310          * @remarks     This information is only meaningful when the %NotificationRequest instance is delivered to the NotificationManager::NotifyOngoingActivity() method.
 311          * @see SetOngoingActivityProgress()
 312          */
 313         result SetOngoingActivityType(OngoingActivityType type = ONGOING_ACTIVITY_TYPE_TEXT);
 314
 315         /**
 316          * Gets the progress value for an ongoing activity notification.
 317          *
 318          * @since       2.0
 319          *
 320          * @return      The progress value
 321          */
 322         int GetOngoingActivityProgress(void) const;
 323
 324         /**
 325          * Sets the progress value with the specified @c value.
 326          *
 327          * @since       2.0
 328          *
 329          * @return      An error code
 330          * @param[in]   value   The progress value
 331          * @exception   E_SUCCESS       The method is successful.
 332          * @exception   E_INVALID_ARG   Either of the following conditions has occurred: @n
 333          *                                                              - The specified @c value is less than @c 0.
 334      *                                                          - The specified @c value does not lie between @c 0 and @c 100 for Shell::ONGOING_ACTIVITY_TYPE_PROGRESS_PERCENTAGE.
 335      *                                                          - The notification type for an ongoing activity is not set.
 336          * @exception   E_INVALID_OPERATION     This instance is in an invalid state. @n
 337          *                                                              OngoingActivityType must be either Shell::ONGOING_ACTIVITY_TYPE_PROGRESS_BYTE or Shell::ONGOING_ACTIVITY_TYPE_PROGRESS_PERCENTAGE.
 338          * @see SetOngoingActivityType()
 339          */
 340         result SetOngoingActivityProgress(int value);
 341
 342         /**
 343          * Gets the style of a notification message.
 344          *
 345          * @since               2.1
 346          *
 347          * @return              The notification style
 348          */
 349         NotificationStyle  GetNotificationStyle(void) const;
 350
 351         /**
 352          * Sets the style of a notification message.
 353          *
 354          * @since               2.1
 355          *
 356          * @return              An error code
 357          * @param[in]   style                   The notification style
 358          * @exception   E_SUCCESS               The method is successful.
 359          * @exception   E_INVALID_ARG   The specified @c style is not valid.
 360          */
 361         result SetNotificationStyle(NotificationStyle style);
 362
 363         /**
 364          * Gets a list of message text for a notification message.
 365          *
 366          * @since               2.1
 367          *
 368          * @return              A string list of message text
 369          */
 370         Tizen::Base::Collection::IList* GetMessageTextListN(void) const;
 371
 372         /**
 373          * Sets a string list of message text for a notification message.
 374          *
 375          * @since               2.1
 376          *
 377          * @return              An error code
 378          * @param[in]   pTextList               A list of message text
 379          * @exception   E_SUCCESS               The method is successful.
 380          * @exception   E_INVALID_ARG   The specified @c pTextList is empty or the length of @c pTextList is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
 381          * @remarks             This information is only meaningful when the notification style is Shell::NOTIFICATION_STYLE_NORMAL. @n
 382          *                              Use the tab(\\t) character to separate the columns.
 383          */
 384         result SetMessageTextList(const Tizen::Base::Collection::IList* pTextList);
 385
 386         /**
 387          * Gets a list of the message thumbnail image absolute file path for a notification message.
 388          *
 389          * @since               2.1
 390          *
 391          * @return              A string list of thumbnail image file path
 392          */
 393         Tizen::Base::Collection::IList* GetMessageThumbnailFilePathListN(void) const;
 394
 395         /**
 396          * Sets a string list of the message thumbnail image absolute file path for a notification message.
 397          *
 398          * @since               2.1
 399          *
 400          * @return              An error code
 401          * @param[in]   pThumbnailPathList      A list of the thumbnail image file path
 402          * @exception   E_SUCCESS                       The method is successful.
 403          * @exception   E_INVALID_ARG           The specified path is invalid.
 404          * @remarks             This information is only meaningful when the notification style is Shell::NOTIFICATION_STYLE_THUMBNAIL.
 405          */
 406         result SetMessageThumbnailFilePathList(const Tizen::Base::Collection::IList* pThumbnailPathList);
 407
 408         /**
 409          * Gets the notification count text of a notification message.
 410          *
 411          * @since               2.1
 412          *
 413          * @return              The notification count text
 414          */
 415         Tizen::Base::String GetNotificationCountText(void) const;
 416
 417         /**
 418          * Sets the notification count text of a notification message.
 419          *
 420          * @since               2.1
 421          *
 422          * @return              An error code
 423          * @param[in]   notificationCountText   The notification count text
 424          * @exception   E_SUCCESS                               The method is successful.
 425          * @exception   E_INVALID_ARG                   The specified @c notificationCountText is empty or the length of @c notificationCountText is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
 426          * @remarks     This information is only meaningful when the notification style is Shell::NOTIFICATION_STYLE_NORMAL.
 427          */
 428         result SetNotificationCountText(const Tizen::Base::String& notificationCountText);
 429
 430         /**
 431          * Gets the absolute file path of the background image for a notification message.
 432          *
 433          * @since               2.1
 434          *
 435          * @return              The file path of a background image file
 436          */
 437         Tizen::Base::String GetBackgroundImageFilePath(void) const;
 438
 439         /**
 440          * Sets the absolute file path of the background image for a notification message.
 441          *
 442          * @since               2.1
 443          *
 444          * @return              An error code
 445          * @param[in]   imagePath               The file path of the background image
 446          * @exception   E_SUCCESS               The method is successful.
 447          * @exception   E_INVALID_ARG   The specified path is invalid.
 448          */
 449         result SetBackgroundImageFilePath(const Tizen::Base::String& imagePath);
 450
 451
 452 private:
 453         class _NotificationRequestImpl* __pNotificationRequestImpl;
 454
 455         friend class _NotificationRequestImpl;
 456 }; // NotificationRequest
 457
 458 } } // Tizen::App
 459
 460 #endif // _FSHELL_NOTIFICATION_REQUEST_H_