code.vuplus.com Git - vuplus_xbmc/blob - xbmc/interfaces/legacy/Dialog.h

   1  /*
   2  *      Copyright (C) 2005-2013 Team XBMC
   3  *      http://xbmc.org
   4  *
   5  *  This Program is free software; you can redistribute it and/or modify
   6  *  it under the terms of the GNU General Public License as published by
   7  *  the Free Software Foundation; either version 2, or (at your option)
   8  *  any later version.
   9  *
  10  *  This Program is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  *  GNU General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU General Public License
  16  *  along with XBMC; see the file COPYING.  If not, see
  17  *  <http://www.gnu.org/licenses/>.
  18  *
  19  */
  20
  21 #pragma once
  22
  23 #include <vector>
  24
  25 #include "WindowException.h"
  26 #include "AddonClass.h"
  27 #include "AddonString.h"
  28 #include "ApplicationMessenger.h"
  29 #include "dialogs/GUIDialogProgress.h"
  30 #include "dialogs/GUIDialogExtendedProgressBar.h"
  31 #include "Alternative.h"
  32
  33 #define INPUT_ALPHANUM        0
  34 #define INPUT_NUMERIC         1
  35 #define INPUT_DATE            2
  36 #define INPUT_TIME            3
  37 #define INPUT_IPADDRESS       4
  38 #define INPUT_PASSWORD        5
  39
  40 #define PASSWORD_VERIFY       1
  41 #define ALPHANUM_HIDE_INPUT   2
  42
  43 namespace XBMCAddon
  44 {
  45   namespace xbmcgui
  46   {
  47     /**
  48      * Dialog class (Duh!)\n
  49      */
  50     class Dialog : public AddonClass
  51     {
  52     public:
  53
  54       inline Dialog() {}
  55       virtual ~Dialog();
  56
  57       /**
  58        * yesno(heading, line1[, line2, line3]) -- Show a dialog 'YES/NO'.\n
  59        * \n
  60        * heading        : string or unicode - dialog heading.\n
  61        * line1          : string or unicode - line #1 text.\n
  62        * line2          : [opt] string or unicode - line #2 text.\n
  63        * line3          : [opt] string or unicode - line #3 text.\n
  64        * nolabel        : [opt] label to put on the no button.\n
  65        * yeslabel       : [opt] label to put on the yes button.\n
  66        * autoclose      : [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)\n
  67        * \n
  68        * *Note, Returns True if 'Yes' was pressed, else False.\n
  69        * *Note, Optionally line1 can be sent as multi-line text. In this case line2 and line3 must be omitted.\n
  70        * \n
  71        * example:\n
  72        *   - dialog = xbmcgui.Dialog()\n
  73        *   - ret = dialog.yesno('XBMC', 'Do you want to exit this script?')n\n
  74        */
  75       bool yesno(const String& heading, const String& line1,
  76                  const String& line2 = emptyString,
  77                  const String& line3 = emptyString,
  78                  const String& nolabel = emptyString,
  79                  const String& yeslabel = emptyString,
  80                  int autoclose = 0) throw (WindowException);
  81
  82       /**
  83        * select(heading, list) -- Show a select dialog.\n
  84        * \n
  85        * heading        : string or unicode - dialog heading.\n
  86        * list           : string list - list of items.\n
  87        * autoclose      : [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)\n
  88        * \n
  89        * *Note, Returns the position of the highlighted item as an integer.\n
  90        * \n
  91        * example:\n
  92        *   - dialog = xbmcgui.Dialog()\n
  93        *   - ret = dialog.select('Choose a playlist', ['Playlist #1', 'Playlist #2, 'Playlist #3'])n\n
  94        */
  95       int select(const String& heading, const std::vector<String>& list, int autoclose=0) throw (WindowException);
  96
  97       /**
  98        * ok(heading, line1[, line2, line3]) -- Show a dialog 'OK'.\n
  99        * \n
 100        * heading        : string or unicode - dialog heading.\n
 101        * line1          : string or unicode - line #1 text.\n
 102        * line2          : [opt] string or unicode - line #2 text.\n
 103        * line3          : [opt] string or unicode - line #3 text.\n
 104        * \n
 105        * *Note, Returns True if 'Ok' was pressed, else False.\n
 106        * *Note: Optionally line1 can be sent as multi-line text. In this case line2 and line3 must be omitted.\n
 107        * \n
 108        * example:\n
 109        *   - dialog = xbmcgui.Dialog()\n
 110        *   - ok = dialog.ok('XBMC', 'There was an error.')n\n
 111        */
 112       bool ok(const String& heading, const String& line1,
 113               const String& line2 = emptyString,
 114               const String& line3 = emptyString) throw (WindowException);
 115
 116       /**
 117        * browse(type, heading, shares[, mask, useThumbs, treatAsFolder, default, enableMultiple]) -- Show a 'Browse' dialog.\n
 118        * \n
 119        * type           : integer - the type of browse dialog.\n
 120        * heading        : string or unicode - dialog heading.\n
 121        * shares         : string or unicode - from sources.xml. (i.e. 'myprograms')\n
 122        * mask           : [opt] string or unicode - '|' separated file mask. (i.e. '.jpg|.png')\n
 123        * useThumbs      : [opt] boolean - if True autoswitch to Thumb view if files exist.\n
 124        * treatAsFolder  : [opt] boolean - if True playlists and archives act as folders.\n
 125        * default        : [opt] string - default path or file.\n
 126        *
 127        * enableMultiple : [opt] boolean - if True multiple file selection is enabled.
 128        *
 129        * Types:
 130        *   - 0 : ShowAndGetDirectory
 131        *   - 1 : ShowAndGetFile
 132        *   - 2 : ShowAndGetImage
 133        *   - 3 : ShowAndGetWriteableDirectory
 134        *
 135        * *Note, If enableMultiple is False (default): returns filename and/or path as a string\n
 136        *        to the location of the highlighted item, if user pressed 'Ok' or a masked item\n
 137        *        was selected. Returns the default value if dialog was canceled.\n
 138        *        If enableMultiple is True: returns tuple of marked filenames as a strin\n
 139        *        if user pressed 'Ok' or a masked item was selected. Returns empty tuple if dialog was canceled.\n
 140        * \n
 141        *        If type is 0 or 3 the enableMultiple parameter is ignore\n
 142        * \n
 143        * example:\n
 144        *   - dialog = xbmcgui.Dialog()\n
 145        *   - fn = dialog.browse(3, 'XBMC', 'files', '', False, False, False, 'special://masterprofile/script_data/XBMC Lyrics')\n
 146        */
 147       Alternative<String, std::vector<String> > browse(int type, const String& heading, const String& s_shares,
 148                           const String& mask = emptyString, bool useThumbs = false,
 149                           bool treatAsFolder = false, const String& defaultt = emptyString,
 150                           bool enableMultiple = false) throw (WindowException);
 151
 152       /**
 153        * browse(type, heading, shares[, mask, useThumbs, treatAsFolder, default]) -- Show a 'Browse' dialog.\n
 154        * \n
 155        * type           : integer - the type of browse dialog.\n
 156        * heading        : string or unicode - dialog heading.\n
 157        * shares         : string or unicode - from sources.xml. (i.e. 'myprograms')\n
 158        * mask           : [opt] string or unicode - '|' separated file mask. (i.e. '.jpg|.png')\n
 159        * useThumbs      : [opt] boolean - if True autoswitch to Thumb view if files exist (default=false).\n
 160        * treatAsFolder  : [opt] boolean - if True playlists and archives act as folders (default=false).\n
 161        * default        : [opt] string - default path or file.\n
 162        * \n
 163        * Types:\n
 164        *   - 0 : ShowAndGetDirectory
 165        *   - 1 : ShowAndGetFile
 166        *   - 2 : ShowAndGetImage
 167        *   - 3 : ShowAndGetWriteableDirectory
 168        * \n
 169        * *Note, Returns filename and/or path as a string to the location of the highlighted item,\n
 170        *        if user pressed 'Ok' or a masked item was selected.\n
 171        *        Returns the default value if dialog was canceled.\n
 172        * \n
 173        * example:\n
 174        *   - dialog = xbmcgui.Dialog()
 175        *   - fn = dialog.browse(3, 'XBMC', 'files', '', False, False, 'special://masterprofile/script_data/XBMC Lyrics')
 176        */
 177       String browseSingle(int type, const String& heading, const String& shares,
 178                           const String& mask = emptyString, bool useThumbs = false,
 179                           bool treatAsFolder = false,
 180                           const String& defaultt = emptyString ) throw (WindowException);
 181
 182       /**
 183        * browse(type, heading, shares[, mask, useThumbs, treatAsFolder, default]) -- Show a 'Browse' dialog.\n
 184        * \n
 185        * type           : integer - the type of browse dialog.\n
 186        * heading        : string or unicode - dialog heading.\n
 187        * shares         : string or unicode - from sources.xml. (i.e. 'myprograms')\n
 188        * mask           : [opt] string or unicode - '|' separated file mask. (i.e. '.jpg|.png')\n
 189        * useThumbs      : [opt] boolean - if True autoswitch to Thumb view if files exist (default=false).\n
 190        * treatAsFolder  : [opt] boolean - if True playlists and archives act as folders (default=false).\n
 191        * default        : [opt] string - default path or file.\n
 192        * \n
 193        * Types:
 194        *   - 1 : ShowAndGetFile
 195        *   - 2 : ShowAndGetImage
 196        *
 197        * *Note, \n
 198        *       returns tuple of marked filenames as a string,"\n
 199        *       if user pressed 'Ok' or a masked item was selected. Returns empty tuple if dialog was canceled.\n
 200        * \n
 201        * example:\n
 202        *   - dialog = xbmcgui.Dialog()
 203        *   - fn = dialog.browseMultiple(2, 'XBMC', 'files', '', False, False, 'special://masterprofile/script_data/XBMC Lyrics')
 204        */
 205       std::vector<String> browseMultiple(int type, const String& heading, const String& shares,
 206                                          const String& mask = emptyString, bool useThumbs = false,
 207                                          bool treatAsFolder = false,
 208                                          const String& defaultt = emptyString ) throw (WindowException);
 209
 210
 211       /**
 212        * numeric(type, heading[, default]) -- Show a 'Numeric' dialog.\n
 213        * \n
 214        * type           : integer - the type of numeric dialog.\n
 215        * heading        : string or unicode - dialog heading.\n
 216        * default        : [opt] string - default value.\n
 217        * \n
 218        * Types:
 219        *   - 0 : ShowAndGetNumber    (default format: #)
 220        *   - 1 : ShowAndGetDate      (default format: DD/MM/YYYY)
 221        *   - 2 : ShowAndGetTime      (default format: HH:MM)
 222        *   - 3 : ShowAndGetIPAddress (default format: #.#.#.#)
 223        *
 224        * *Note, Returns the entered data as a string.\n
 225        *        Returns the default value if dialog was canceled.\n
 226        * \n
 227        * example:\n
 228        *   - dialog = xbmcgui.Dialog()
 229        *   - d = dialog.numeric(1, 'Enter date of birth')
 230        */
 231       String numeric(int type, const String& heading, const String& defaultt = emptyString);
 232
 233       /**
 234        * notification(heading, message[, icon, time, sound]) -- Show a Notification alert.\n
 235        * \n
 236        * heading        : string - dialog heading.\n
 237        * message        : string - dialog message.\n
 238        * icon           : [opt] string - icon to use. (default xbmcgui.NOTIFICATION_INFO)\n
 239        * time           : [opt] integer - time in milliseconds (default 5000)\n
 240        * sound          : [opt] bool - play notification sound (default True)\n
 241        * \n
 242        * Builtin Icons:\n
 243        *   - xbmcgui.NOTIFICATION_INFO
 244        *   - xbmcgui.NOTIFICATION_WARNING
 245        *   - xbmcgui.NOTIFICATION_ERROR
 246        * \n
 247        * example:
 248        *   - dialog = xbmcgui.Dialog()
 249        *   - dialog.notification('Movie Trailers', 'Finding Nemo download finished.', xbmcgui.NOTIFICATION_INFO, 5000)
 250        */
 251       void notification(const String& heading, const String& message, const String& icon = emptyString, int time = 0, bool sound = true);
 252
 253       /**
 254        * input(heading[, default, type, option, autoclose]) -- Show an Input dialog.\n
 255        *\n
 256        * heading        : string - dialog heading.\n
 257        * default        : [opt] string - default value. (default=empty string)\n
 258        * type           : [opt] integer - the type of keyboard dialog. (default=xbmcgui.INPUT_ALPHANUM)\n
 259        * option         : [opt] integer - option for the dialog. (see Options below)\n
 260        * autoclose      : [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)\n
 261        *\n
 262        * Types:
 263        *   - xbmcgui.INPUT_ALPHANUM         (standard keyboard)
 264        *   - xbmcgui.INPUT_NUMERIC          (format: #)
 265        *   - xbmcgui.INPUT_DATE             (format: DD/MM/YYYY)
 266        *   - xbmcgui.INPUT_TIME             (format: HH:MM)
 267        *   - xbmcgui.INPUT_IPADDRESS        (format: #.#.#.#)
 268        *   - xbmcgui.INPUT_PASSWORD         (return md5 hash of input, input is masked)
 269        *
 270        * Options Password Dialog:\n
 271        *   - xbmcgui.PASSWORD_VERIFY (verifies an existing (default) md5 hashed password)
 272        *\n
 273        * Options Alphanum Dialog:\n
 274        *   - xbmcgui.ALPHANUM_HIDE_INPUT (masks input)
 275        *\n
 276        * *Note, Returns the entered data as a string.\n
 277        *        Returns an empty string if dialog was canceled.\n
 278        *\n
 279        * example:
 280        *   - dialog = xbmcgui.Dialog()
 281        *   - d = dialog.input('Enter secret code', type=xbmcgui.INPUT_ALPHANUM, option=xbmcgui.ALPHANUM_HIDE_INPUT)n
 282        */
 283       String input(const String& heading,
 284                    const String& defaultt = emptyString,
 285                    int type = INPUT_ALPHANUM,
 286                    int option = 0,
 287                    int autoclose = 0) throw (WindowException);
 288     };
 289
 290     /**
 291      * DialogProgress class (Duh!)
 292      */
 293     class DialogProgress : public AddonClass
 294     {
 295       CGUIDialogProgress* dlg;
 296       bool                open;
 297
 298     protected:
 299       virtual void deallocating();
 300
 301     public:
 302
 303       DialogProgress() : dlg(NULL), open(false) {}
 304       virtual ~DialogProgress();
 305
 306
 307       /**
 308        * create(heading[, line1, line2, line3]) -- Create and show a progress dialog.\n
 309        * \n
 310        * heading        : string or unicode - dialog heading.\n
 311        * line1          : [opt] string or unicode - line #1 text.\n
 312        * line2          : [opt] string or unicode - line #2 text.\n
 313        * line3          : [opt] string or unicode - line #3 text.\n
 314        * \n
 315        * *Note, Optionally line1 can be sent as multi-line text. In this case line2 and line3 must be omitted.\n
 316        * *Note, Use update() to update lines and progressbar.\n
 317        * \n
 318        * example:
 319        *   - pDialog = xbmcgui.DialogProgress()
 320        *   - pDialog.create('XBMC', 'Initializing script...')
 321        */
 322       void create(const String& heading, const String& line1 = emptyString,
 323                   const String& line2 = emptyString,
 324                   const String& line3 = emptyString) throw (WindowException);
 325
 326       /**
 327        * update(percent[, line1, line2, line3]) -- Updates the progress dialog.\n
 328        * \n
 329        * percent        : integer - percent complete. (0:100)\n
 330        * line1          : [opt] string or unicode - line #1 text.\n
 331        * line2          : [opt] string or unicode - line #2 text.\n
 332        * line3          : [opt] string or unicode - line #3 text.\n
 333        * \n
 334        * *Note, Optionally line1 can be sent as multi-line text. In this case line2 and line3 must be omitted.\n
 335        * *Note, If percent == 0, the progressbar will be hidden.\n
 336        * \n
 337        * example:
 338        *   - pDialog.update(25, 'Importing modules...')
 339        */
 340       void update(int percent, const String& line1 = emptyString,
 341                   const String& line2 = emptyString,
 342                   const String& line3 = emptyString) throw (WindowException);
 343
 344       /**
 345        * close() -- Close the progress dialog.\n
 346        * \n
 347        * example:
 348        *   - pDialog.close()
 349        */
 350       void close();
 351
 352       /**
 353        * iscanceled() -- Returns True if the user pressed cancel.\n
 354        * \n
 355        * example:
 356        *   - if (pDialog.iscanceled()): return
 357        */
 358       bool iscanceled();
 359     };
 360
 361     /**
 362      * DialogProgressBG class
 363      */
 364     class DialogProgressBG : public AddonClass
 365     {
 366       CGUIDialogExtendedProgressBar* dlg;
 367       CGUIDialogProgressBarHandle* handle;
 368       bool open;
 369
 370     protected:
 371       virtual void deallocating();
 372
 373     public:
 374
 375       DialogProgressBG() : dlg(NULL), handle(NULL), open(false) {}
 376       virtual ~DialogProgressBG();
 377
 378
 379       /**
 380        * create(heading[, message]) -- Create and show a background progress dialog.\n
 381        *
 382        * heading     : string or unicode - dialog heading.\n
 383        * message     : [opt] string or unicode - message text.\n
 384        *
 385        * *Note, 'heading' is used for the dialog's id. Use a unique heading.\n
 386        *        Use  update() to update heading, message and progressbar.\n
 387        *
 388        * example:
 389        * - pDialog = xbmcgui.DialogProgressBG()
 390        * - pDialog.create('Movie Trailers', 'Downloading Monsters Inc. ...')
 391        */
 392       void create(const String& heading, const String& message = emptyString) throw (WindowException);
 393
 394       /**
 395        * update([percent, heading, message]) -- Updates the background progress dialog.
 396        *
 397        * percent     : [opt] integer - percent complete. (0:100)\n
 398        * heading     : [opt] string or unicode - dialog heading.\n
 399        * message     : [opt] string or unicode - message text.\n
 400        *
 401        * *Note, To clear heading or message, you must pass a blank character.\n
 402        *
 403        * example:
 404        * - pDialog.update(25, message='Downloading Finding Nemo ...')
 405        */
 406       void update(int percent = 0, const String& heading = emptyString, const String& message = emptyString) throw (WindowException);
 407
 408       /**
 409        * close() -- Close the background progress dialog
 410        *
 411        * example:
 412        * - pDialog.close()
 413        */
 414       void close();
 415
 416       /**
 417        * isFinished() -- Returns True if the background dialog is active.
 418        *
 419        * example:
 420        * - if (pDialog.isFinished()): return
 421        */
 422       bool isFinished();
 423     };
 424
 425   }
 426 }