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