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          */
  71         explicit NotificationRequest(bool appBinding = true);
  72
  73         /**
  74          * Copying of objects using this copy constructor is allowed.
  75          *
  76          * @since       2.0
  77          *
  78          * @param[in]   rhs     An instance of %NotificationRequest
  79          */
  80         NotificationRequest(const NotificationRequest& rhs);
  81
  82         /**
  83          * Copying of objects using this copy assignment operator is allowed.
  84          *
  85          * @since       2.0
  86          *
  87          * @param[in]   rhs     An instance of %NotificationRequest
  88          */
  89         NotificationRequest& operator =(const NotificationRequest& rhs);
  90
  91         /**
  92          * This destructor overrides Tizen::Base::Object::~Object().
  93          *
  94          * @since       2.0
  95          */
  96         virtual ~NotificationRequest(void);
  97
  98         /**
  99          * Checks whether the specified instance of %NotificationRequest equals the current instance.
 100          *
 101          * @since       2.0
 102          *
 103          * @return      @c true if the specified instance equals the current instance, @n
 104          *              else @c false
 105          * @param[in]   rhs     An instance of %NotificationRequest
 106          * @remarks     This method returns @c false if the specified object is not %NotificationRequest.
 107          */
 108         virtual bool Equals(const Object& rhs) const;
 109
 110         /**
 111          * Gets the hash value of the current instance.
 112          *
 113          * @since       2.0
 114          *
 115          * @return      The hash value of the current instance
 116          */
 117         virtual int GetHashCode(void) const;
 118
 119         /**
 120          * Gets the badge number of a notification message.
 121          *
 122          * @since       2.0
 123          *
 124          * @return              The badge number value
 125          * @remarks     If the badge number is not set, then this method returns @c -1.
 126          */
 127         int GetBadgeNumber(void) const;
 128
 129         /**
 130          * Sets the badge number of a notification message. @n
 131          * %NotificationRequest has either badge number or badge number offset.
 132          * If the badge number is set using %SetBadgeNumber(), then previous badge offset value is set to @c 0.
 133          *
 134          * @since       2.0
 135          *
 136          * @return      An error code
 137          * @param[in]   value   The badge number value
 138          * @exception   E_SUCCESS       The method is successful.
 139          * @exception   E_INVALID_ARG   The specified @c value is less than @c 0 or greater than Shell::MAX_NOTIFICATION_BADGE_NUMBER.
 140          */
 141         result SetBadgeNumber(int value);
 142
 143         /**
 144          * Gets the badge number offset of a notification message.
 145          *
 146          * @since       2.0
 147          *
 148          * @return              The badge offset value
 149          */
 150         int GetBadgeOffset(void) const;
 151
 152         /**
 153          * Sets the badge number offset of the notification message. @n
 154          * %NotificationRequest has either badge number or badge number offset.
 155          * If the badge number offset is set using %SetBadgeOffset(), then previous badge number value is set to @c -1 and ignored. @n
 156          *
 157          * When posting the notification message, badge offset value is added to the current badge number,
 158          * which can be acquired by NotificationManager::GetBadgeNumber(). Setting badge offset to @c 0
 159          * means explicitly specifying not to change the current badge value with the notification message.
 160          *
 161          * @since       2.0
 162          *
 163          * @return      An error code
 164          * @param[in]   value   The badge number value
 165          * @exception   E_SUCCESS       The method is successful.
 166          * @exception   E_INVALID_ARG   The absolute value of the specified @c value is greater than Shell::MAX_NOTIFICATION_BADGE_NUMBER.
 167          * @remarks     Even though this method does not return @c E_INVALID_ARG, it does not guarantee the success of NotificationManager::Notify().
 168          * @see SetBadgeNumber()
 169          */
 170         result SetBadgeOffset(int value);
 171
 172         /**
 173          * Gets the alert text of a notification message.
 174          *
 175          * @since       2.0
 176          *
 177          * @return      The alert text
 178          */
 179         Tizen::Base::String GetAlertText(void) const;
 180
 181         /**
 182          * Sets an alert text of a notification message.
 183          *
 184          * @since       2.0
 185          *
 186          * @return      An error code
 187          * @param[in]   text    The alert text
 188          * @exception   E_SUCCESS       The method is successful.
 189          * @exception   E_INVALID_ARG   The specified @c text is empty or the length of @c text is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
 190          * @remarks @c text is displayed according to notification layout, and the length of the text is depends on the font attributes or variable font width.
 191          */
 192         result SetAlertText(const Tizen::Base::String& text);
 193
 194         /**
 195          * Gets the application message of a notification message.
 196          *
 197          * @since       2.0
 198          *
 199          * @return The message for application
 200          */
 201         Tizen::Base::String GetAppMessage(void) const;
 202
 203         /**
 204          * Sets the application message of a notification message. @n
 205          * @c appMessage is delivered as the value of the http://tizen.org/appcontrol/data/notification key
 206          * for IAppControlProviderEventListener::OnAppControlRequestReceived().
 207          *
 208          * @since       2.0
 209          *
 210          * @return      An error code
 211          * @param[in]   appMessage              The message for the application
 212          * @exception   E_SUCCESS       The method is successful.
 213          * @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.
 214          * @exception   E_INVALID_OPERATION     This instance is not bound to the application.
 215          * @remarks     This method returns @c E_INVALID_OPERATION if %NotificationRequest instance is not bound to the application.
 216          */
 217         result SetAppMessage(const Tizen::Base::String& appMessage);
 218
 219         /**
 220          * Gets the title text of a notification message.
 221          *
 222          * @since       2.0
 223          *
 224          * @return      The title text
 225          */
 226         Tizen::Base::String GetTitleText(void) const;
 227
 228         /**
 229          * Sets the title text of a notification message.
 230          *
 231          * @since       2.0
 232          *
 233          * @return      An error code
 234          * @param[in]   title   The title text
 235          * @exception   E_SUCCESS       The method is successful.
 236          * @exception   E_INVALID_ARG   The specified @c title is empty or the length of @c title is greater than Shell::MAX_NOTIFICATION_TITLE_LENGTH.
 237          */
 238         result SetTitleText(const Tizen::Base::String& title);
 239
 240         /**
 241          * Gets the file path of the icon image for a notification message.
 242          *
 243          * @since       2.0
 244          *
 245          * @return      The file path of an icon image
 246          */
 247         Tizen::Base::String GetIconFilePath(void) const;
 248
 249         /**
 250          * Sets the file path of the icon image for a notification message.
 251          *
 252          * @since       2.0
 253          *
 254          * @return      An error code
 255          * @param[in]   iconPath        The file path of the icon image
 256          * @exception   E_SUCCESS       The method is successful.
 257          * @exception   E_INVALID_ARG   The specified path is invalid.
 258          */
 259         result SetIconFilePath(const Tizen::Base::String& iconPath);
 260
 261         /**
 262          * Gets the file path of a sound file that is played for the notification message.
 263          *
 264          * @since       2.0
 265          *
 266          * @return      The file path of the sound file to play
 267          */
 268         Tizen::Base::String GetSoundFilePath(void) const;
 269
 270         /**
 271          * Sets the file path of the sound file that is played for the notification message. @n
 272          * The sound file should be in the WAVE file format.
 273          *
 274          * @since       2.0
 275          *
 276          * @return      An error code
 277          * @param[in]   soundPath       The file path of the sound file
 278          * @exception   E_SUCCESS       The method is successful.
 279          * @exception   E_INVALID_ARG   The specified path is invalid.
 280          * @remarks     If the format of the sound file is not valid, then the sound file is not played properly when the notification message is displayed.
 281          */
 282         result SetSoundFilePath(const Tizen::Base::String& soundPath);
 283
 284         /**
 285          * Gets the notification type for the ongoing activity notification.
 286          *
 287          * @since       2.0
 288          *
 289          * @return      The ongoing activity notification type
 290          * @remarks     This information is only meaningful when the %NotificationRequest instance is delivered to the NotificationManager::NotifyOngoingActivity() method.
 291          * @see SetOngoingActivityType()
 292          */
 293         OngoingActivityType GetOngoingActivityType(void) const;
 294
 295         /**
 296          * Sets the notification type for an ongoing activity.
 297          *
 298          * @since       2.0
 299          *
 300          * @return      An error code
 301          * @param[in]   type    The notification type for an ongoing activity
 302          * @exception   E_SUCCESS       The method is successful.
 303          * @exception   E_INVALID_OPERATION     The current progress value is not compatible to the specified @c type.
 304          * @remarks     This information is only meaningful when the %NotificationRequest instance is delivered to the NotificationManager::NotifyOngoingActivity() method.
 305          * @see SetOngoingActivityProgress()
 306          */
 307         result SetOngoingActivityType(OngoingActivityType type = ONGOING_ACTIVITY_TYPE_TEXT);
 308
 309         /**
 310          * Gets the progress value for an ongoing activity notification.
 311          *
 312          * @since       2.0
 313          *
 314          * @return      The progress value
 315          */
 316         int GetOngoingActivityProgress(void) const;
 317
 318         /**
 319          * Sets the progress value with the specified @c value.
 320          *
 321          * @since       2.0
 322          *
 323          * @return      An error code
 324          * @param[in]   value   The progress value
 325          * @exception   E_SUCCESS       The method is successful.
 326          * @exception   E_INVALID_ARG   The specified @c value is less than @c 0, or
 327      *                                                          the specified @c value does not lie between @c 0 and @c 100 for Shell::ONGOING_ACTIVITY_TYPE_PROGRESS_PERCENTAGE.
 328          * @exception   E_INVALID_OPERATION     This instance is in an invalid state. @n
 329          *                                                              OngoingActivityType must be either Shell::ONGOING_ACTIVITY_TYPE_PROGRESS_BYTE or Shell::ONGOING_ACTIVITY_TYPE_PROGRESS_PERCENTAGE.
 330          */
 331         result SetOngoingActivityProgress(int value);
 332
 333         /**
 334          * Gets the style of a notification message.
 335          *
 336          * @since               2.1
 337          *
 338          * @return              The notification style
 339          */
 340         NotificationStyle  GetNotificationStyle(void) const;
 341
 342         /**
 343          * Sets the style of a notification message.
 344          *
 345          * @since               2.1
 346          *
 347          * @return              An error code
 348          * @param[in]   style                   The notification style
 349          * @exception   E_SUCCESS               The method is successful.
 350          * @exception   E_INVALID_ARG   The specified @c style is not valid.
 351          */
 352         result SetNotificationStyle(NotificationStyle style);
 353
 354         /**
 355          * Gets a list of message text for a notification message.
 356          *
 357          * @since               2.1
 358          *
 359          * @return              A string list of detail information text
 360          */
 361         Tizen::Base::Collection::IList* GetMessageTextListN(void) const;
 362
 363         /**
 364          * Sets a string list of message text for a notification message.
 365          *
 366          * @since               2.1
 367          *
 368          * @return              An error code
 369          * @param[in]   pTextList               A list of detail information text
 370          * @exception   E_SUCCESS               The method is successful.
 371          * @exception   E_INVALID_ARG   The specified @c textList is empty or the length of individual text is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
 372          * @remarks             This information is only meaningful when the notification style is Shell::NOTIFICATION_STYLE_NORMAL. @n
 373          *                              Use the tab(\\t) character to separate the columns.
 374          *
 375          */
 376         result SetMessageTextList(const Tizen::Base::Collection::IList* pTextList);
 377
 378         /**
 379          * Gets a list of the message thumbnail image absolute file path for a notification message.
 380          *
 381          * @since               2.1
 382          *
 383          * @return              A string list of thumbnail image file path
 384          */
 385         Tizen::Base::Collection::IList* GetMessageThumbnailFilePathListN(void) const;
 386
 387         /**
 388          * Sets a string list of the message thumbnail image absolute file path for a notification message.
 389          *
 390          * @since               2.1
 391          *
 392          * @return              An error code
 393          * @param[in]   pThumbnailPathList      A list of the thumbnail image file path
 394          * @exception   E_SUCCESS                       The method is successful.
 395          * @exception   E_INVALID_ARG           The specified path is invalid.
 396          * @remarks             This information is only meaningful when then notification style is Shell::NOTIFICATION_STYLE_THUMBNAIL.
 397          */
 398         result SetMessageThumbnailFilePathList(const Tizen::Base::Collection::IList* pThumbnailPathList);
 399
 400         /**
 401          * Gets the notification count text of a notification message.
 402          *
 403          * @since               2.1
 404          *
 405          * @return              The notification count text
 406          */
 407         Tizen::Base::String GetNotificationCountText(void) const;
 408
 409         /**
 410          * Sets the notification count text of a notification message.
 411          *
 412          * @since               2.1
 413          *
 414          * @return              An error code
 415          * @param[in]   notificationCountText   The event count text
 416          * @exception   E_SUCCESS                               The method is successful.
 417          * @exception   E_INVALID_ARG                   The specified @c eventCountText is empty or the length of @c eventCountText is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
 418          */
 419         result SetNotificationCountText(const Tizen::Base::String& notificationCountText);
 420
 421         /**
 422          * Gets the absolute file path of the background image for a notification message.
 423          *
 424          * @since               2.1
 425          *
 426          * @return              The file path of a background image file
 427          */
 428         Tizen::Base::String GetBackgroundImageFilePath(void) const;
 429
 430         /**
 431          * Sets the absolute file path of the background image for a notification message.
 432          *
 433          * @since               2.1
 434          *
 435          * @return              An error code
 436          * @param[in]   imagePath               The file path of the background image
 437          * @exception   E_SUCCESS               The method is successful.
 438          * @exception   E_INVALID_ARG   The specified path is invalid.
 439          */
 440         result SetBackgroundImageFilePath(const Tizen::Base::String& imagePath);
 441
 442
 443 private:
 444         class _NotificationRequestImpl* __pNotificationRequestImpl;
 445
 446         friend class _NotificationRequestImpl;
 447 }; // NotificationRequest
 448
 449 } } // Tizen::App
 450
 451 #endif // _FSHELL_NOTIFICATION_REQUEST_H_