src/Tizen.Applications.Notification/Tizen.Applications.Notifications/NotificationActiveStyle.cs

   1 /*
   2  * Copyright (c) 2017 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 namespace Tizen.Applications.Notifications
  18 {
  19     using System.Collections.Generic;
  20
  21     /// <summary>
  22     /// This class contains common properties and methods of notifications.
  23     /// </summary>
  24     /// <remarks>
  25     /// A notification is a message that is displayed on the notification area.
  26     /// It is created to notify information to the user through the application.
  27     /// This class helps you to provide method and property for creating notification object.
  28     /// </remarks>
  29     public sealed partial class Notification
  30     {
  31         /// <summary>
  32         ///  Class for generating active style notification.
  33         /// </summary>
  34         public sealed class ActiveStyle : StyleBase
  35         {
  36             private IDictionary<ButtonIndex, ButtonAction> buttonDictionary;
  37             private int hideTimeout = 0;
  38             private int deleteTimeout = 0;
  39
  40             /// <summary>
  41             /// Initializes a new instance of the <see cref="ActiveStyle"/> class.
  42             /// </summary>
  43             public ActiveStyle()
  44             {
  45                 buttonDictionary = new Dictionary<ButtonIndex, ButtonAction>();
  46             }
  47
  48             /// <summary>
  49             /// Gets or sets an absolute path for an image file to display on the background of active notification.
  50             /// </summary>
  51             public string BackgroundImage { get; set; }
  52
  53             /// <summary>
  54             /// Gets or sets a value indicating whether the active notification is removed automatically. Default value is true.
  55             /// </summary>
  56             /// <remarks>
  57             /// IsAutoRemove option lets the active notification to be removed several seconds after it shows.
  58             /// When 'IsAutoRemove' is set as false, the active notification will not be removed as long as the user removes
  59             /// it or the application, which posted the active notification.
  60             /// </remarks>>
  61             public bool IsAutoRemove { get; set; } = true;
  62
  63             /// <summary>
  64             /// Gets or sets the default button to display highlight on the active notification.
  65             /// </summary>
  66             /// <remarks>
  67             /// The default button for display highlight is only reflected on the Tizen TV.
  68             /// If you use this property on other profile, this value has no effect.
  69             /// </remarks>
  70             public ButtonIndex DefaultButton { get; set; } = ButtonIndex.None;
  71
  72             /// <summary>
  73             /// Gets or sets a ReplyAction to this active notification style.
  74             /// </summary>
  75             /// <remarks>
  76             /// When you add a ReplyAction to the ActiveStyle, the notification UI will show a ReplyAction with button.
  77             /// If you set null parameter, ReplyAction is not displayed.
  78             /// </remarks>
  79             /// <example>
  80             /// <code>
  81             ///
  82             /// ButtonAction button = new ButtonAction
  83             /// {
  84             ///     Index = ButtonIndex.First,
  85             ///     Text = "Yes"
  86             ///     Action = new AppControl{ ApplicationId = "org.tizen.app" };
  87             /// };
  88             ///
  89             /// ReplyAction reply = new ReplyAction
  90             /// {
  91             ///     ParentIndex = ButtonIndex.First;
  92             ///     PlaceHolderText = "Please write your reply."
  93             ///     ReplyMax = 160,
  94             ///     Button = new ButtonAction
  95             ///     {
  96             ///         Text = "Yes",
  97             ///         ImagePath = "image path"
  98             ///         Action = new AppControl{ ApplicationId = "org.tizen.app" };
  99             ///     };
 100             /// };
 101             ///
 102             /// ActiveStyle active = new ActiveStyle
 103             /// {
 104             ///     AutoRemove = true,
 105             ///     BackgroundImage = "image path",
 106             ///     ReplyAction = reply
 107             /// };
 108             ///
 109             /// active.AddButtonAction(button);
 110             /// </code>
 111             /// </example>
 112             public ReplyAction ReplyAction { get; set; }
 113
 114             /// <summary>
 115             /// Gets or sets Action which is invoked when notification is hidden by user.
 116             /// </summary>
 117             /// <remarks>
 118             /// If you set it to null, the already set AppControl will be removed and nothing will happen when notification is hidden by user.
 119             /// The property is only reflected on Tizen TV.
 120             /// If you use this API on other profile, this action have no effect
 121             /// </remarks>
 122             /// <seealso cref="Tizen.Applications.AppControl"></seealso>
 123             public AppControl HiddenByUserAction { get; set; }
 124
 125             /// <summary>
 126             /// Gets or sets Action which is invoked when there is no any response by user until hide timeout.
 127             /// </summary>
 128             /// <remarks>
 129             /// This action occurs when there is no response to the notification until the delete timeout set by SetRemoveTime().
 130             /// If you set it to null, the already set AppControl will be removed and nothing will happen when notification is hidden by timeout.
 131             /// The property is only reflected on Tizen TV.
 132             /// If you use this API on other profile, this action settings have no effect
 133             /// </remarks>
 134             /// <seealso cref="Tizen.Applications.AppControl"></seealso>
 135             public AppControl HiddenByTimeoutAction { get; set; }
 136
 137             /// <summary>
 138             /// Gets or sets Action which is invoked when the notification is hidden by external factor.
 139             /// </summary>
 140             /// <remarks>
 141             /// If you set it to null, the already set AppControl will be removed and nothing will happen when notification is hidden by external factor.
 142             /// The property is only reflected on Tizen TV.
 143             /// If you use this API on other profile, this action settings have no effect
 144             /// </remarks>
 145             /// <seealso cref="Tizen.Applications.AppControl"></seealso>
 146             public AppControl HiddenByExternalAction { get; set; }
 147
 148             /// <summary>
 149             /// Gets the key of ActiveStyle.
 150             /// </summary>
 151             internal override string Key
 152             {
 153                 get
 154                 {
 155                     return "Active";
 156                 }
 157             }
 158
 159             /// <summary>
 160             /// Method to set time to hide or delete notification.
 161             /// </summary>
 162             /// <remarks>
 163             /// The time settings for hiding and deleting are only reflected on the Tizen TV.
 164             /// If you use this API on other profile, this time settings have no effect.
 165             /// </remarks>
 166             /// <param name="hideTime">The value in seconds when the notification can be hidden from the notification viewer after the notification is posted.</param>
 167             /// <param name="deleteTime">The value in seconds when the notification can be deleted from the notification list in setting application after notification is posted.</param>
 168             /// <exception cref="ArgumentException">Thrown when argument is invalid.</exception>
 169             public void SetRemoveTime(int hideTime, int deleteTime)
 170             {
 171                 if (hideTime < 0 || deleteTime < 0)
 172                 {
 173                     throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid argument");
 174                 }
 175
 176                 hideTimeout = hideTime;
 177                 deleteTimeout = deleteTime;
 178             }
 179
 180             /// <summary>
 181             /// Method to get time set to hide or delete notification.
 182             /// </summary>
 183             /// <param name="hideTime">The value in seconds when the notification can be hidden from the notification viewer after notification is posted.</param>
 184             /// <param name="deleteTime">The value in seconds when the notification can be deleted from the notification list in setting application after notification is posted.</param>
 185             public void GetRemoveTime(out int hideTime, out int deleteTime)
 186             {
 187                 hideTime = hideTimeout;
 188                 deleteTime = deleteTimeout;
 189             }
 190
 191             /// <summary>
 192             /// Method to add a button to the active notification style.
 193             /// Buttons are displayed on the notification.
 194             /// </summary>
 195             /// <remarks>
 196             /// If you add button that has same index, the button is replaced to latest adding button.
 197             /// If you don't set an index on ButtonAction, the index is set sequentially from zero.
 198             /// </remarks>
 199             /// <param name="button">A ButtonAction for appear to the notification.</param>
 200             /// <exception cref="ArgumentException">Thrown when an argument is invalid.</exception>
 201             /// <example>
 202             /// <code>
 203             ///
 204             /// ButtonAction button = new ButtonAction
 205             /// {
 206             ///     Index = 0,
 207             ///     Text = "Yes"
 208             ///     Action = new AppControl{ ApplicationId = "org.tizen.app" };
 209             /// };
 210             ///
 211             /// ActiveStyle active = new ActiveStyle
 212             /// {
 213             ///     IsAutoRemove = true,
 214             ///     BackgroundImage = "image path",
 215             /// };
 216             ///
 217             /// active.AddButtonAction(button);
 218             ///
 219             /// </code>
 220             /// </example>
 221             public void AddButtonAction(ButtonAction button)
 222             {
 223                 if (button == null)
 224                 {
 225                     throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid ButtonAction object");
 226                 }
 227
 228                 if (button.Index == ButtonIndex.None)
 229                 {
 230                     button.Index = (ButtonIndex)buttonDictionary.Count;
 231                     buttonDictionary.Add(button.Index, button);
 232                 }
 233                 else if (button.Index >= ButtonIndex.First)
 234                 {
 235                     if (buttonDictionary.ContainsKey(button.Index))
 236                     {
 237                         buttonDictionary.Remove(button.Index);
 238                     }
 239
 240                     buttonDictionary.Add(button.Index, button);
 241                 }
 242             }
 243
 244             /// <summary>
 245             /// Removes the ButtonAction you already added.
 246             /// </summary>
 247             /// <param name="index">The index to remove a button.</param>
 248             /// <returns>true if the element is successfully found and removed; otherwise, false.</returns>
 249             public bool RemoveButtonAction(ButtonIndex index)
 250             {
 251                 bool ret = buttonDictionary.Remove(index);
 252
 253                 if (ret == false)
 254                 {
 255                     Log.Debug(Notification.LogTag, "Invalid key, there is no button matched input index");
 256                 }
 257                 else
 258                 {
 259                     Log.Debug(Notification.LogTag, "The button was removed.");
 260                 }
 261
 262                 return ret;
 263             }
 264
 265             /// <summary>
 266             /// Gets the ButtonAction of the active notification.
 267             /// </summary>
 268             /// <param name="index">The index to get a button you already added.</param>
 269             /// <returns>The ButtonAction object, which you already added.</returns>
 270             /// <exception cref="ArgumentException">Thrown when an argument is invalid.</exception>
 271             public ButtonAction GetButtonAction(ButtonIndex index)
 272             {
 273                 ButtonAction button = null;
 274
 275                 if (buttonDictionary.ContainsKey(index) == true)
 276                 {
 277                     buttonDictionary.TryGetValue(index, out button);
 278                 }
 279                 else
 280                 {
 281                     throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "The value is not existed.");
 282                 }
 283
 284                 return button;
 285             }
 286
 287             internal ICollection<ButtonAction> GetButtonAction()
 288             {
 289                 return buttonDictionary.Values;
 290             }
 291
 292             internal override void Make(Notification notification)
 293             {
 294                 ActiveBinder.BindObject(notification);
 295             }
 296         }
 297     }
 298 }