SDL_Android/SmartDeviceLinkProxyAndroid/src/com/smartdevicelink/proxy/rpc/Alert.java

   1 package com.smartdevicelink.proxy.rpc;\r
   2 \r
   3 import java.util.Hashtable;\r
   4 import java.util.Vector;\r
   5 \r
   6 import com.smartdevicelink.proxy.RPCRequest;\r
   7 import com.smartdevicelink.proxy.constants.Names;\r
   8 \r
   9 /**\r
  10  * Provides information to the user using either TTS, the Display or both and\r
  11  * can include a system-generated alert tone\r
  12  * <p>\r
  13  * <ul>\r
  14  * <li>The displayed portion of the Alert, if any, will persist until the\r
  15  * specified timeout has elapsed, or the Alert is preempted</li>\r
  16  * <li>An Alert will preempt (abort) any SmartDeviceLink Operation that is in-progress,\r
  17  * except an already-in-progress Alert</li>\r
  18  * <li>An Alert cannot be preempted by any SmartDeviceLink Operation</li>\r
  19  * <li>An Alert can be preempted by a user action (button push)</li>\r
  20  * <li>An Alert will fail if it is issued while another Alert is in progress</li>\r
  21  * <li>Although each Alert parameter is optional, in fact each Alert request\r
  22  * must supply at least one of the following parameters:<br/>\r
  23  * <ul>\r
  24  * <li>alertText1</li>\r
  25  * <li>alertText2</li>\r
  26  * <li>alertText3</li>\r
  27  * <li>ttsChunks</li>\r
  28  * </ul>\r
  29  * </li>\r
  30  * </ul>\r
  31  * <br/>\r
  32  * <b>HMILevel needs to be FULL or LIMITED.</b><br/>\r
  33  * <b>If the app has been granted function group Notification the HMILevel can\r
  34  * also be BACKGROUND</b><br/>\r
  35  * \r
  36  * @since SmartDeviceLink 1.0\r
  37  * @see Show\r
  38  * @see Speak\r
  39  */\r
  40 public class Alert extends RPCRequest {\r
  41 \r
  42         /**\r
  43          * Constructs a new Alert object\r
  44          */    \r
  45         public Alert() {\r
  46         super("Alert");\r
  47     }\r
  48         /**\r
  49          * Constructs a new Alert object indicated by the Hashtable parameter\r
  50          * <p>\r
  51          * \r
  52          * @param hash\r
  53          *            The Hashtable to use\r
  54          */     \r
  55     public Alert(Hashtable hash) {\r
  56         super(hash);\r
  57     }\r
  58         /**\r
  59          * Gets the text which is displayed in the first field of the display during\r
  60          * the Alert\r
  61          * \r
  62          * @return String - a String value representing the text which is displayed\r
  63          *         in the first field during the Alert\r
  64          */    \r
  65     public String getAlertText1() {\r
  66         return (String) parameters.get(Names.alertText1);\r
  67     }\r
  68         /**\r
  69          * Sets the String to be displayed in the first field of the display during\r
  70          * the Alert\r
  71          * \r
  72          * @param alertText1\r
  73          *            String Value\r
  74          *            <p>\r
  75          *            <b>Notes: </b><br/>\r
  76          *            <ul>\r
  77          *            <li>Length is limited to what is indicated in <i>\r
  78          *            {@linkplain RegisterAppInterface}</i> response</li>\r
  79          *            <li>If omitted, top display line will be cleared</li>\r
  80          *            <li>Text is always centered</li>\r
  81          *            </ul>\r
  82          */    \r
  83     public void setAlertText1(String alertText1) {\r
  84         if (alertText1 != null) {\r
  85             parameters.put(Names.alertText1, alertText1);\r
  86         } else {\r
  87                 parameters.remove(Names.alertText1);\r
  88         }\r
  89     }\r
  90         /**\r
  91          * Gets the text which is displayed in the second field of the display\r
  92          * during the Alert\r
  93          * \r
  94          * @return String -a String value representing the text which is displayed\r
  95          *         in the second field during the Alert\r
  96          */    \r
  97     public String getAlertText2() {\r
  98         return (String) parameters.get(Names.alertText2);\r
  99     }\r
 100         /**\r
 101          * Sets the String to be displayed in the second field of the display during\r
 102          * the Alert\r
 103          * \r
 104          * @param alertText2\r
 105          *            String Value\r
 106          *            <p>\r
 107          *            <b>Notes: </b><br/>\r
 108          *            <ul>\r
 109          *            <li>Only permitted if HMI supports a second display line</li>\r
 110          *            <li>Length is limited to what is indicated in <i>\r
 111          *            {@linkplain RegisterAppInterface}</i> response</li>\r
 112          *            <li>If omitted, second display line will be cleared</li>\r
 113          *            <li>Text is always centered</li>\r
 114          *            </ul>\r
 115          */    \r
 116     public void setAlertText2(String alertText2) {\r
 117         if (alertText2 != null) {\r
 118             parameters.put(Names.alertText2, alertText2);\r
 119         } else {\r
 120                 parameters.remove(Names.alertText2);\r
 121         }\r
 122     }\r
 123 \r
 124         /**\r
 125          * Gets the text which is displayed in the third field of the display during\r
 126          * the Alert\r
 127          * \r
 128          * @return String -a String value representing the text which is displayed\r
 129          *         in the third field during the Alert\r
 130          * \r
 131          * @since SmartDeviceLink 2.0\r
 132          */\r
 133     public String getAlertText3() {\r
 134         return (String) parameters.get(Names.alertText3);\r
 135     }\r
 136 \r
 137         /**\r
 138          * Sets the String to be displayed in the third field of the display during\r
 139          * the Alert\r
 140          * \r
 141          * @param alertText3\r
 142          *            String Value\r
 143          *            <p>\r
 144          *            <b>Notes: </b><br/>\r
 145          *            <ul>\r
 146          *            <li>Only permitted if HMI supports a third display line</li>\r
 147          *            <li>Length is limited to what is indicated in <i>\r
 148          *            {@linkplain RegisterAppInterface}</i> response</li>\r
 149          *            <li>If omitted, third display line will be cleared</li>\r
 150          *            <li>Text is always centered</li>\r
 151          *            </ul>\r
 152          * \r
 153          * @since SmartDeviceLink 2.0\r
 154          */\r
 155     public void setAlertText3(String alertText3) {\r
 156         if (alertText3 != null) {\r
 157             parameters.put(Names.alertText3, alertText3);\r
 158         } else {\r
 159                 parameters.remove(Names.alertText3);\r
 160         }\r
 161     }\r
 162         /**\r
 163          * Gets TTSChunk[], the Array of type TTSChunk which, taken together,\r
 164          * specify what is to be spoken to the user\r
 165          * \r
 166          * @return Vector -a Vector<TTSChunk> value specify what is to be spoken to\r
 167          *         the user\r
 168          */    \r
 169     public Vector<TTSChunk> getTtsChunks() {\r
 170         if (parameters.get(Names.ttsChunks) instanceof Vector<?>) {\r
 171                 Vector<?> list = (Vector<?>)parameters.get(Names.ttsChunks);\r
 172                 if (list != null && list.size() > 0) {\r
 173                     Object obj = list.get(0);\r
 174                     if (obj instanceof TTSChunk) {\r
 175                         return (Vector<TTSChunk>) list;\r
 176                     } else if (obj instanceof Hashtable) {\r
 177                         Vector<TTSChunk> newList = new Vector<TTSChunk>();\r
 178                         for (Object hashObj : list) {\r
 179                             newList.add(new TTSChunk((Hashtable)hashObj));\r
 180                         }\r
 181                         return newList;\r
 182                     }\r
 183                 }\r
 184         }\r
 185         return null;\r
 186     }\r
 187         /**\r
 188          * Sets array of type TTSChunk which, taken together, specify what is to be\r
 189          * spoken to the user\r
 190          * \r
 191          * @param ttsChunks\r
 192          *            <p>\r
 193          *            <b>Notes: </b>Array must have a least one element\r
 194          */    \r
 195     public void setTtsChunks(Vector<TTSChunk> ttsChunks) {\r
 196         if (ttsChunks != null) {\r
 197             parameters.put(Names.ttsChunks, ttsChunks);\r
 198         } else {\r
 199                 parameters.remove(Names.ttsChunks);\r
 200         }\r
 201     }\r
 202         /**\r
 203          * Gets the duration of the displayed portion of the alert, in milliseconds\r
 204          * \r
 205          * @return Integer -an Integer value representing the duration of the\r
 206          *         displayed portion of the alert, in milliseconds\r
 207          */    \r
 208     public Integer getDuration() {\r
 209         return (Integer) parameters.get(Names.duration);\r
 210     }\r
 211         /**\r
 212          * Sets the duration of the displayed portion of the alert, in milliseconds.\r
 213          * After this amount of time has passed, the display fields alertText1 and\r
 214          * alertText2 will revert to what was displayed in those fields before the\r
 215          * alert began\r
 216          * <p>\r
 217          * \r
 218          * @param duration\r
 219          *            the Integer values representing the duration time, in\r
 220          *            milliseconds\r
 221          *            <p>\r
 222          *            <b>Notes: </b><br/>\r
 223          *            <ul>\r
 224          *            <li>Min Value: 3000; Max Value: 10000</li>\r
 225          *            <li>If omitted, the default is 5000 milliseconds</li>\r
 226          *            </ul>\r
 227          */    \r
 228     public void setDuration(Integer duration) {\r
 229         if (duration != null) {\r
 230             parameters.put(Names.duration, duration);\r
 231         } else {\r
 232                 parameters.remove(Names.duration);\r
 233         }\r
 234     }\r
 235         /**\r
 236          * Gets a Boolean value representing the alert tone\r
 237          * \r
 238          * @return Boolean -If TRUE, means an alert tone will be played before the\r
 239          *         TTS (if any) is spoken\r
 240          */    \r
 241     public Boolean getPlayTone() {\r
 242         return (Boolean) parameters.get(Names.playTone);\r
 243     }\r
 244         /**\r
 245          * Sets whether the alert tone should be played before the TTS (if any) is\r
 246          * spoken\r
 247          * \r
 248          * @param playTone\r
 249          *            a Boolean value which specifies whether the alert tone should\r
 250          *            be played before the TTS (if any) is spoken\r
 251          *            <p>\r
 252          *            <b>Notes: </b>If omitted, default is true\r
 253          */    \r
 254     public void setPlayTone(Boolean playTone) {\r
 255         if (playTone != null) {\r
 256             parameters.put(Names.playTone, playTone);\r
 257         } else {\r
 258                 parameters.remove(Names.playTone);\r
 259         }\r
 260     }\r
 261 \r
 262         /**\r
 263          * Gets the SoftButton Vector object\r
 264          * \r
 265          * @return Vector<SoftButton> -a Vector<SoftButton> representing the Vector\r
 266          *         object\r
 267          * @since SmartDeviceLink 2.0\r
 268          */\r
 269     public Vector<SoftButton> getSoftButtons() {\r
 270         if (parameters.get(Names.softButtons) instanceof Vector<?>) {\r
 271                 Vector<?> list = (Vector<?>)parameters.get(Names.softButtons);\r
 272                 if (list != null && list.size() > 0) {\r
 273                     Object obj = list.get(0);\r
 274                     if (obj instanceof SoftButton) {\r
 275                         return (Vector<SoftButton>) list;\r
 276                     } else if (obj instanceof Hashtable) {\r
 277                         Vector<SoftButton> newList = new Vector<SoftButton>();\r
 278                         for (Object hashObj : list) {\r
 279                             newList.add(new SoftButton((Hashtable)hashObj));\r
 280                         }\r
 281                         return newList;\r
 282                     }\r
 283                 }\r
 284         }\r
 285         return null;\r
 286     }\r
 287 \r
 288         /**\r
 289          * Sets the SoftButtons\r
 290          * \r
 291          * @param softButtons\r
 292          *            a Vector<SoftButton> value\r
 293          *            <p>\r
 294          *            <b>Notes: </b><br/>\r
 295          *            <ul>\r
 296          *            <li>If omitted on supported displays, the alert will not have\r
 297          *            any SoftButton</li>\r
 298          *            <li>ArrayMin: 0</li>\r
 299          *            <li>ArrayMax: 4</li>\r
 300          *            </ul>\r
 301          * @since SmartDeviceLink 2.0\r
 302          */\r
 303     public void setSoftButtons(Vector<SoftButton> softButtons) {\r
 304         if (softButtons != null) {\r
 305             parameters.put(Names.softButtons, softButtons);\r
 306         } else {\r
 307                 parameters.remove(Names.softButtons);\r
 308         }\r
 309     }\r
 310 }\r