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        * \n
  70        * example:\n
  71        *   - dialog = xbmcgui.Dialog()\n
  72        *   - ret = dialog.yesno('XBMC', 'Do you want to exit this script?')n\n
  73        */
  74       bool yesno(const String& heading, const String& line1,
  75                  const String& line2 = emptyString,
  76                  const String& line3 = emptyString,
  77                  const String& nolabel = emptyString,
  78                  const String& yeslabel = emptyString,
  79                  int autoclose = 0) throw (WindowException);
  80
  81       /**
  82        * select(heading, list) -- Show a select dialog.\n
  83        * \n
  84        * heading        : string or unicode - dialog heading.\n
  85        * list           : string list - list of items.\n
  86        * autoclose      : [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)\n
  87        * \n
  88        * *Note, Returns the position of the highlighted item as an integer.\n
  89        * \n
  90        * example:\n
  91        *   - dialog = xbmcgui.Dialog()\n
  92        *   - ret = dialog.select('Choose a playlist', ['Playlist #1', 'Playlist #2, 'Playlist #3'])n\n
  93        */
  94       int select(const String& heading, const std::vector<String>& list, int autoclose=0) throw (WindowException);
  95
  96       /**
  97        * ok(heading, line1[, line2, line3]) -- Show a dialog 'OK'.\n
  98        * \n
  99        * heading        : string or unicode - dialog heading.\n
 100        * line1          : string or unicode - line #1 text.\n
 101        * line2          : [opt] string or unicode - line #2 text.\n
 102        * line3          : [opt] string or unicode - line #3 text.\n
 103        * \n
 104        * *Note, Returns True if 'Ok' was pressed, else False.\n
 105        * \n
 106        * example:\n
 107        *   - dialog = xbmcgui.Dialog()\n
 108        *   - ok = dialog.ok('XBMC', 'There was an error.')n\n
 109        */
 110       bool ok(const String& heading, const String& line1,
 111               const String& line2 = emptyString,
 112               const String& line3 = emptyString) throw (WindowException);
 113
 114       /**
 115        * browse(type, heading, shares[, mask, useThumbs, treatAsFolder, default, enableMultiple]) -- Show a 'Browse' dialog.\n
 116        * \n
 117        * type           : integer - the type of browse dialog.\n
 118        * heading        : string or unicode - dialog heading.\n
 119        * shares         : string or unicode - from sources.xml. (i.e. 'myprograms')\n
 120        * mask           : [opt] string or unicode - '|' separated file mask. (i.e. '.jpg|.png')\n
 121        * useThumbs      : [opt] boolean - if True autoswitch to Thumb view if files exist.\n
 122        * treatAsFolder  : [opt] boolean - if True playlists and archives act as folders.\n
 123        * default        : [opt] string - default path or file.\n
 124        *
 125        * enableMultiple : [opt] boolean - if True multiple file selection is enabled.
 126        *
 127        * Types:
 128        *   - 0 : ShowAndGetDirectory
 129        *   - 1 : ShowAndGetFile
 130        *   - 2 : ShowAndGetImage
 131        *   - 3 : ShowAndGetWriteableDirectory
 132        *
 133        * *Note, If enableMultiple is False (default): returns filename and/or path as a string\n
 134        *        to the location of the highlighted item, if user pressed 'Ok' or a masked item\n
 135        *        was selected. Returns the default value if dialog was canceled.\n
 136        *        If enableMultiple is True: returns tuple of marked filenames as a strin\n
 137        *        if user pressed 'Ok' or a masked item was selected. Returns empty tuple if dialog was canceled.\n
 138        * \n
 139        *        If type is 0 or 3 the enableMultiple parameter is ignore\n
 140        * \n
 141        * example:\n
 142        *   - dialog = xbmcgui.Dialog()\n
 143        *   - fn = dialog.browse(3, 'XBMC', 'files', '', False, False, False, 'special://masterprofile/script_data/XBMC Lyrics')\n
 144        */
 145       Alternative<String, std::vector<String> > browse(int type, const String& heading, const String& s_shares,
 146                           const String& mask = emptyString, bool useThumbs = false,
 147                           bool treatAsFolder = false, const String& defaultt = emptyString,
 148                           bool enableMultiple = false) throw (WindowException);
 149
 150       /**
 151        * browse(type, heading, shares[, mask, useThumbs, treatAsFolder, default]) -- Show a 'Browse' dialog.\n
 152        * \n
 153        * type           : integer - the type of browse dialog.\n
 154        * heading        : string or unicode - dialog heading.\n
 155        * shares         : string or unicode - from sources.xml. (i.e. 'myprograms')\n
 156        * mask           : [opt] string or unicode - '|' separated file mask. (i.e. '.jpg|.png')\n
 157        * useThumbs      : [opt] boolean - if True autoswitch to Thumb view if files exist (default=false).\n
 158        * treatAsFolder  : [opt] boolean - if True playlists and archives act as folders (default=false).\n
 159        * default        : [opt] string - default path or file.\n
 160        * \n
 161        * Types:\n
 162        *   - 0 : ShowAndGetDirectory
 163        *   - 1 : ShowAndGetFile
 164        *   - 2 : ShowAndGetImage
 165        *   - 3 : ShowAndGetWriteableDirectory
 166        * \n
 167        * *Note, Returns filename and/or path as a string to the location of the highlighted item,\n
 168        *        if user pressed 'Ok' or a masked item was selected.\n
 169        *        Returns the default value if dialog was canceled.\n
 170        * \n
 171        * example:\n
 172        *   - dialog = xbmcgui.Dialog()
 173        *   - fn = dialog.browse(3, 'XBMC', 'files', '', False, False, 'special://masterprofile/script_data/XBMC Lyrics')
 174        */
 175       String browseSingle(int type, const String& heading, const String& shares,
 176                           const String& mask = emptyString, bool useThumbs = false,
 177                           bool treatAsFolder = false,
 178                           const String& defaultt = emptyString ) throw (WindowException);
 179
 180       /**
 181        * browse(type, heading, shares[, mask, useThumbs, treatAsFolder, default]) -- Show a 'Browse' dialog.\n
 182        * \n
 183        * type           : integer - the type of browse dialog.\n
 184        * heading        : string or unicode - dialog heading.\n
 185        * shares         : string or unicode - from sources.xml. (i.e. 'myprograms')\n
 186        * mask           : [opt] string or unicode - '|' separated file mask. (i.e. '.jpg|.png')\n
 187        * useThumbs      : [opt] boolean - if True autoswitch to Thumb view if files exist (default=false).\n
 188        * treatAsFolder  : [opt] boolean - if True playlists and archives act as folders (default=false).\n
 189        * default        : [opt] string - default path or file.\n
 190        * \n
 191        * Types:
 192        *   - 1 : ShowAndGetFile
 193        *   - 2 : ShowAndGetImage
 194        *
 195        * *Note, \n
 196        *       returns tuple of marked filenames as a string,"\n
 197        *       if user pressed 'Ok' or a masked item was selected. Returns empty tuple if dialog was canceled.\n
 198        * \n
 199        * example:\n
 200        *   - dialog = xbmcgui.Dialog()
 201        *   - fn = dialog.browseMultiple(2, 'XBMC', 'files', '', False, False, 'special://masterprofile/script_data/XBMC Lyrics')
 202        */
 203       std::vector<String> browseMultiple(int type, const String& heading, const String& shares,
 204                                          const String& mask = emptyString, bool useThumbs = false,
 205                                          bool treatAsFolder = false,
 206                                          const String& defaultt = emptyString ) throw (WindowException);
 207
 208
 209       /**
 210        * numeric(type, heading[, default]) -- Show a 'Numeric' dialog.\n
 211        * \n
 212        * type           : integer - the type of numeric dialog.\n
 213        * heading        : string or unicode - dialog heading.\n
 214        * default        : [opt] string - default value.\n
 215        * \n
 216        * Types:
 217        *   - 0 : ShowAndGetNumber    (default format: #)
 218        *   - 1 : ShowAndGetDate      (default format: DD/MM/YYYY)
 219        *   - 2 : ShowAndGetTime      (default format: HH:MM)
 220        *   - 3 : ShowAndGetIPAddress (default format: #.#.#.#)
 221        *
 222        * *Note, Returns the entered data as a string.\n
 223        *        Returns the default value if dialog was canceled.\n
 224        * \n
 225        * example:\n
 226        *   - dialog = xbmcgui.Dialog()
 227        *   - d = dialog.numeric(1, 'Enter date of birth')
 228        */
 229       String numeric(int type, const String& heading, const String& defaultt = emptyString);
 230
 231       /**
 232        * notification(heading, message[, icon, time, sound]) -- Show a Notification alert.\n
 233        * \n
 234        * heading        : string - dialog heading.\n
 235        * message        : string - dialog message.\n
 236        * icon           : [opt] string - icon to use. (default xbmcgui.NOTIFICATION_INFO)\n
 237        * time           : [opt] integer - time in milliseconds (default 5000)\n
 238        * sound          : [opt] bool - play notification sound (default True)\n
 239        * \n
 240        * Builtin Icons:\n
 241        *   - xbmcgui.NOTIFICATION_INFO
 242        *   - xbmcgui.NOTIFICATION_WARNING
 243        *   - xbmcgui.NOTIFICATION_ERROR
 244        * \n
 245        * example:
 246        *   - dialog = xbmcgui.Dialog()
 247        *   - dialog.notification('Movie Trailers', 'Finding Nemo download finished.', xbmcgui.NOTIFICATION_INFO, 5000)
 248        */
 249       void notification(const String& heading, const String& message, const String& icon = emptyString, int time = 0, bool sound = true);
 250
 251       /**
 252        * input(heading[, default, type, option, autoclose]) -- Show an Input dialog.\n
 253        *\n
 254        * heading        : string - dialog heading.\n
 255        * default        : [opt] string - default value. (default=empty string)\n
 256        * type           : [opt] integer - the type of keyboard dialog. (default=xbmcgui.INPUT_ALPHANUM)\n
 257        * option         : [opt] integer - option for the dialog. (see Options below)\n
 258        * autoclose      : [opt] integer - milliseconds to autoclose dialog. (default=do not autoclose)\n
 259        *\n
 260        * Types:
 261        *   - xbmcgui.INPUT_ALPHANUM         (standard keyboard)
 262        *   - xbmcgui.INPUT_NUMERIC          (format: #)
 263        *   - xbmcgui.INPUT_DATE             (format: DD/MM/YYYY)
 264        *   - xbmcgui.INPUT_TIME             (format: HH:MM)
 265        *   - xbmcgui.INPUT_IPADDRESS        (format: #.#.#.#)
 266        *   - xbmcgui.INPUT_PASSWORD         (return md5 hash of input, input is masked)
 267        *
 268        * Options Password Dialog:\n
 269        *   - xbmcgui.PASSWORD_VERIFY (verifies an existing (default) md5 hashed password)
 270        *\n
 271        * Options Alphanum Dialog:\n
 272        *   - xbmcgui.ALPHANUM_HIDE_INPUT (masks input)
 273        *\n
 274        * *Note, Returns the entered data as a string.\n
 275        *        Returns an empty string if dialog was canceled.\n
 276        *\n
 277        * example:
 278        *   - dialog = xbmcgui.Dialog()
 279        *   - d = dialog.input('Enter secret code', type=xbmcgui.INPUT_ALPHANUM, option=xbmcgui.ALPHANUM_HIDE_INPUT)n
 280        */
 281       String input(const String& heading,
 282                    const String& defaultt = emptyString,
 283                    int type = INPUT_ALPHANUM,
 284                    int option = 0,
 285                    int autoclose = 0) throw (WindowException);
 286     };
 287
 288     /**
 289      * DialogProgress class (Duh!)
 290      */
 291     class DialogProgress : public AddonClass
 292     {
 293       CGUIDialogProgress* dlg;
 294       bool                open;
 295
 296     protected:
 297       virtual void deallocating();
 298
 299     public:
 300
 301       DialogProgress() : dlg(NULL), open(false) {}
 302       virtual ~DialogProgress();
 303
 304
 305       /**
 306        * create(heading[, line1, line2, line3]) -- Create and show a progress dialog.\n
 307        * \n
 308        * heading        : string or unicode - dialog heading.\n
 309        * line1          : [opt] string or unicode - line #1 text.\n
 310        * line2          : [opt] string or unicode - line #2 text.\n
 311        * line3          : [opt] string or unicode - line #3 text.\n
 312        * \n
 313        * *Note, Use update() to update lines and progressbar.\n
 314        * \n
 315        * example:
 316        *   - pDialog = xbmcgui.DialogProgress()
 317        *   - pDialog.create('XBMC', 'Initializing script...')
 318        */
 319       void create(const String& heading, const String& line1 = emptyString,
 320                   const String& line2 = emptyString,
 321                   const String& line3 = emptyString) throw (WindowException);
 322
 323       /**
 324        * update(percent[, line1, line2, line3]) -- Update's the progress dialog.\n
 325        * \n
 326        * percent        : integer - percent complete. (0:100)\n
 327        * line1          : [opt] string or unicode - line #1 text.\n
 328        * line2          : [opt] string or unicode - line #2 text.\n
 329        * line3          : [opt] string or unicode - line #3 text.\n
 330        * \n
 331        * *Note, If percent == 0, the progressbar will be hidden.\n
 332        * \n
 333        * example:
 334        *   - pDialog.update(25, 'Importing modules...')
 335        */
 336       void update(int percent, const String& line1 = emptyString,
 337                   const String& line2 = emptyString,
 338                   const String& line3 = emptyString) throw (WindowException);
 339
 340       /**
 341        * close() -- Close the progress dialog.\n
 342        * \n
 343        * example:
 344        *   - pDialog.close()
 345        */
 346       void close();
 347
 348       /**
 349        * iscanceled() -- Returns True if the user pressed cancel.\n
 350        * \n
 351        * example:
 352        *   - if (pDialog.iscanceled()): return
 353        */
 354       bool iscanceled();
 355     };
 356
 357     /**
 358      * DialogProgressBG class
 359      */
 360     class DialogProgressBG : public AddonClass
 361     {
 362       CGUIDialogExtendedProgressBar* dlg;
 363       CGUIDialogProgressBarHandle* handle;
 364       bool open;
 365
 366     protected:
 367       virtual void deallocating();
 368
 369     public:
 370
 371       DialogProgressBG() : dlg(NULL), handle(NULL), open(false) {}
 372       virtual ~DialogProgressBG();
 373
 374
 375       /**
 376        * create(heading[, message]) -- Create and show a background progress dialog.n\n
 377        *
 378        * heading     : string or unicode - dialog headingn\n
 379        * message     : [opt] string or unicode - message textn\n
 380        *
 381        * *Note, 'heading' is used for the dialog's id. Use a unique heading.n\n
 382        *        Use update() to update heading, message and progressbar.n\n
 383        *
 384        * example:
 385        * - pDialog = xbmcgui.DialogProgressBG()
 386        * - pDialog.create('Movie Trailers', 'Downloading Monsters Inc. ...')
 387        */
 388       void create(const String& heading, const String& message = emptyString) throw (WindowException);
 389
 390       /**
 391        * update([percent, heading, message]) -- Updates the background progress dialog.
 392        *
 393        * percent     : [opt] integer - percent complete. (0:100)\n
 394        * heading     : [opt] string or unicode - dialog heading\n
 395        * message     : [opt] string or unicode - message text\n
 396        *
 397        * *Note, To clear heading or message, you must pass a blank character.\n
 398        *
 399        * example:
 400        * - pDialog.update(25, message='Downloading Finding Nemo ...')
 401        */
 402       void update(int percent = 0, const String& heading = emptyString, const String& message = emptyString) throw (WindowException);
 403
 404       /**
 405        * close() -- Close the background progress dialog
 406        *
 407        * example:
 408        * - pDialog.close()
 409        */
 410       void close();
 411
 412       /**
 413        * isFinished() -- Returns True if the background dialog is active.
 414        *
 415        * example:
 416        * - if (pDialog.isFinished()): return
 417        */
 418       bool isFinished();
 419     };
 420
 421   }
 422 }