code.vuplus.com Git - vuplus_xbmc/blob - xbmc/interfaces/legacy/ListItem.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 <map>
  24 #include <vector>
  25
  26 #include "cores/playercorefactory/PlayerCoreFactory.h"
  27
  28 #include "AddonClass.h"
  29 #include "Dictionary.h"
  30 #include "CallbackHandler.h"
  31 #include "ListItem.h"
  32 #include "music/tags/MusicInfoTag.h"
  33 #include "FileItem.h"
  34 #include "AddonString.h"
  35 #include "Tuple.h"
  36 #include "commons/Exception.h"
  37
  38
  39 namespace XBMCAddon
  40 {
  41   namespace xbmcgui
  42   {
  43     XBMCCOMMONS_STANDARD_EXCEPTION(ListItemException);
  44
  45     class ListItem : public AddonClass
  46     {
  47     public:
  48 #ifndef SWIG
  49       CFileItemPtr item;
  50 #endif
  51
  52       ListItem(const String& label = emptyString,
  53                const String& label2 = emptyString,
  54                const String& iconImage = emptyString,
  55                const String& thumbnailImage = emptyString,
  56                const String& path = emptyString);
  57
  58 #ifndef SWIG
  59       inline ListItem(CFileItemPtr pitem) : item(pitem) {}
  60
  61       static inline AddonClass::Ref<ListItem> fromString(const String& str)
  62       {
  63         AddonClass::Ref<ListItem> ret = AddonClass::Ref<ListItem>(new ListItem());
  64         ret->item.reset(new CFileItem(str));
  65         return ret;
  66       }
  67 #endif
  68
  69       virtual ~ListItem();
  70
  71       /**
  72        * getLabel() -- Returns the listitem label.\n
  73        * \n
  74        * example:
  75        *   - label = self.list.getSelectedItem().getLabel()
  76        */
  77       String getLabel();
  78
  79       /**
  80        * getLabel2() -- Returns the listitem label.\n
  81        * \n
  82        * example:
  83        *   - label = self.list.getSelectedItem().getLabel2()
  84        */
  85       String getLabel2();
  86
  87       /**
  88        * setLabel(label) -- Sets the listitem's label.\n
  89        * \n
  90        * label          : string or unicode - text string.\n
  91        * \n
  92        * example:
  93        *   - self.list.getSelectedItem().setLabel('Casino Royale')
  94        */
  95       void setLabel(const String& label);
  96
  97       /**
  98        * setLabel2(label) -- Sets the listitem's label2.\n
  99        * \n
 100        * label          : string or unicode - text string.\n
 101        * \n
 102        * example:
 103        *   - self.list.getSelectedItem().setLabel2('Casino Royale')
 104        */
 105       void setLabel2(const String& label);
 106
 107       /**
 108        * setIconImage(icon) -- Sets the listitem's icon image.\n
 109        * \n
 110        * icon            : string - image filename.\n
 111        * \n
 112        * example:
 113        *   - self.list.getSelectedItem().setIconImage('emailread.png')
 114        */
 115       void setIconImage(const String& iconImage);
 116
 117       /**
 118        * setThumbnailImage(thumbFilename) -- Sets the listitem's thumbnail image.\n
 119        * \n
 120        * thumb           : string - image filename.\n
 121        * \n
 122        * example:
 123        *   - self.list.getSelectedItem().setThumbnailImage('emailread.png')
 124        */
 125       void setThumbnailImage(const String& thumbFilename);
 126
 127       /**
 128        * select(selected) -- Sets the listitem's selected status.\n
 129        * \n
 130        * selected        : bool - True=selected/False=not selected\n
 131        * \n
 132        * example:
 133        *   - self.list.getSelectedItem().select(True)
 134        */
 135       void select(bool selected);
 136
 137       /**
 138        * isSelected() -- Returns the listitem's selected status.\n
 139        * \n
 140        * example:
 141        *   - is = self.list.getSelectedItem().isSelected()
 142        */
 143       bool isSelected();
 144
 145       /**
 146        * setInfo(type, infoLabels) -- Sets the listitem's infoLabels.\n
 147        * \n
 148        * type              : string - type of media(video/music/pictures).\n
 149        * infoLabels        : dictionary - pairs of { label: value }.\n
 150        * \n
 151        * *Note, To set pictures exif info, prepend 'exif:' to the label. Exif values must be passed\n
 152        *        as strings, separate value pairs with a comma. (eg. {'exif:resolution': '720,480'}\n
 153        *        See CPictureInfoTag::TranslateString in PictureInfoTag.cpp for valid strings.\n
 154        * \n
 155        *        You can use the above as keywords for arguments and skip certain optional arguments.\n
 156        *        Once you use a keyword, all following arguments require the keyword.\n
 157        * \n
 158        * - General Values that apply to all types:
 159        *     - count         : integer (12) - can be used to store an id for later, or for sorting purposes
 160        *     - size          : long (1024) - size in bytes
 161        *     - date          : string (%d.%m.%Y / 01.01.2009) - file date
 162        * - Video Values:
 163        *     - genre         : string (Comedy)
 164        *     - year          : integer (2009)
 165        *     - episode       : integer (4)
 166        *     - season        : integer (1)
 167        *     - top250        : integer (192)
 168        *     - tracknumber   : integer (3)
 169        *     - rating        : float (6.4) - range is 0..10
 170        *     - watched       : depreciated - use playcount instead
 171        *     - playcount     : integer (2) - number of times this item has been played
 172        *     - overlay       : integer (2) - range is 0..8.  See GUIListItem.h for values
 173        *     - cast          : list (Michal C. Hall)
 174        *     - castandrole   : list (Michael C. Hall|Dexter)
 175        *     - director      : string (Dagur Kari)
 176        *     - mpaa          : string (PG-13)
 177        *     - plot          : string (Long Description)
 178        *     - plotoutline   : string (Short Description)
 179        *     - title         : string (Big Fan)
 180        *     - originaltitle : string (Big Fan)
 181        *     - sorttitle     : string (Big Fan)
 182        *     - duration      : string (3:18)
 183        *     - studio        : string (Warner Bros.)
 184        *     - tagline       : string (An awesome movie) - short description of movie
 185        *     - writer        : string (Robert D. Siegel)
 186        *     - tvshowtitle   : string (Heroes)
 187        *     - premiered     : string (2005-03-04)
 188        *     - status        : string (Continuing) - status of a TVshow
 189        *     - code          : string (tt0110293) - IMDb code
 190        *     - aired         : string (2008-12-07)
 191        *     - credits       : string (Andy Kaufman) - writing credits
 192        *     - lastplayed    : string (%Y-%m-%d %h:%m:%s = 2009-04-05 23:16:04)
 193        *     - album         : string (The Joshua Tree)
 194        *     - artist        : list (['U2'])
 195        *     - votes         : string (12345 votes)
 196        *     - trailer       : string (/home/user/trailer.avi)
 197        *     - dateadded     : string (%Y-%m-%d %h:%m:%s = 2009-04-05 23:16:04)
 198        * - Music Values:
 199        *     - tracknumber   : integer (8)
 200        *     - duration      : integer (245) - duration in seconds
 201        *     - year          : integer (1998)
 202        *     - genre         : string (Rock)
 203        *     - album         : string (Pulse)
 204        *     - artist        : string (Muse)
 205        *     - title         : string (American Pie)
 206        *     - rating        : string (3) - single character between 0 and 5
 207        *     - lyrics        : string (On a dark desert highway...)
 208        *     - playcount     : integer (2) - number of times this item has been played
 209        *     - lastplayed    : string (%Y-%m-%d %h:%m:%s = 2009-04-05 23:16:04)
 210        * - Picture Values:
 211        *     - title         : string (In the last summer-1)
 212        *     - picturepath   : string (/home/username/pictures/img001.jpg)
 213        *     - exif*         : string (See CPictureInfoTag::TranslateString in PictureInfoTag.cpp for valid strings)
 214        *
 215        * example:\n
 216        *   - self.list.getSelectedItem().setInfo('video', { 'Genre': 'Comedy' })n\n
 217        */
 218       void setInfo(const char* type, const Dictionary& infoLabels);
 219
 220       /**
 221        * addStreamInfo(type, values) -- Add a stream with details.\n
 222        * \n
 223        * type              : string - type of stream(video/audio/subtitle).\n
 224        * values            : dictionary - pairs of { label: value }.\n
 225        *
 226        * - Video Values:
 227        *     - codec         : string (h264)
 228        *     - aspect        : float (1.78)
 229        *     - width         : integer (1280)
 230        *     - height        : integer (720)
 231        *     - duration      : integer (seconds)
 232        * - Audio Values:
 233        *     - codec         : string (dts)
 234        *     - language      : string (en)
 235        *     - channels      : integer (2)
 236        * - Subtitle Values:
 237        *     - language      : string (en)
 238        *
 239        * example:
 240        *   - self.list.getSelectedItem().addStreamInfo('video', { 'Codec': 'h264', 'Width' : 1280 })
 241        */
 242       void addStreamInfo(const char* cType, const Dictionary& dictionary);
 243
 244       /**
 245        * addContextMenuItems([(label, action,)*], replaceItems) -- Adds item(s) to the context menu for media lists.\n
 246        * \n
 247        * items               : list - [(label, action,)*] A list of tuples consisting of label and action pairs.
 248        *   - label           : string or unicode - item's label.
 249        *   - action          : string or unicode - any built-in function to perform.
 250        * replaceItems        : [opt] bool - True=only your items will show/False=your items will be added to context menu(Default).
 251        * \n
 252        * List of functions - http://wiki.xbmc.org/?title=List_of_Built_In_Functions \n
 253        * \n
 254        * *Note, You can use the above as keywords for arguments and skip certain optional arguments.\n
 255        *        Once you use a keyword, all following arguments require the keyword.\n
 256        * \n
 257        * example:
 258        *   - listitem.addContextMenuItems([('Theater Showtimes', 'XBMC.RunScript(special://home/scripts/showtimes/default.py,Iron Man)',)])n
 259        */
 260       void addContextMenuItems(const std::vector<Tuple<String,String> >& items, bool replaceItems = false) throw (ListItemException);
 261
 262       /**
 263        * setProperty(key, value) -- Sets a listitem property, similar to an infolabel.\n
 264        * \n
 265        * key            : string - property name.\n
 266        * value          : string or unicode - value of property.\n
 267        * \n
 268        * *Note, Key is NOT case sensitive.\n
 269        *        You can use the above as keywords for arguments and skip certain optional arguments.\n
 270        *        Once you use a keyword, all following arguments require the keyword.\n
 271        * \n
 272        *  Some of these are treated internally by XBMC, such as the 'StartOffset' property, which is\n
 273        *  the offset in seconds at which to start playback of an item.  Others may be used in the skin\n
 274        *  to add extra information, such as 'WatchedCount' for tvshow items\n
 275        *
 276        * example:
 277        *   - self.list.getSelectedItem().setProperty('AspectRatio', '1.85 : 1')
 278        *   - self.list.getSelectedItem().setProperty('StartOffset', '256.4')
 279        */
 280       void setProperty(const char * key, const String& value);
 281
 282       /**
 283        * getProperty(key) -- Returns a listitem property as a string, similar to an infolabel.\n
 284        * \n
 285        * key            : string - property name.\n
 286        * \n
 287        * *Note, Key is NOT case sensitive.\n
 288        *        You can use the above as keywords for arguments and skip certain optional arguments.\n
 289        *        Once you use a keyword, all following arguments require the keyword.\n
 290        *
 291        * example:
 292        *   - AspectRatio = self.list.getSelectedItem().getProperty('AspectRatio')
 293        */
 294       String getProperty(const char* key);
 295
 296       /**
 297        * addContextMenuItems([(label, action,)*], replaceItems) -- Adds item(s) to the context menu for media lists.\n
 298        * \n
 299        * items               : list - [(label, action,)*] A list of tuples consisting of label and action pairs.
 300        *   - label           : string or unicode - item's label.
 301        *   - action          : string or unicode - any built-in function to perform.
 302        * replaceItems        : [opt] bool - True=only your items will show/False=your items will be added to context menu(Default).
 303        * \n
 304        * List of functions - http://wiki.xbmc.org/?title=List_of_Built_In_Functions \n
 305        * \n
 306        * *Note, You can use the above as keywords for arguments and skip certain optional arguments.\n
 307        *        Once you use a keyword, all following arguments require the keyword.\n
 308        * \n
 309        * example:
 310        *   - listitem.addContextMenuItems([('Theater Showtimes', 'XBMC.RunScript(special://home/scripts/showtimes/default.py,Iron Man)',)])
 311        */
 312       //    void addContextMenuItems();
 313
 314       /**
 315        * setPath(path) -- Sets the listitem's path.\n
 316        * \n
 317        * path           : string or unicode - path, activated when item is clicked.\n
 318        * \n
 319        * *Note, You can use the above as keywords for arguments.\n
 320        *
 321        * example:
 322        *   - self.list.getSelectedItem().setPath(path='ActivateWindow(Weather)')
 323        */
 324       void setPath(const String& path);
 325
 326       /**
 327        * setMimeType(mimetype) -- Sets the listitem's mimetype if known.\n
 328        * \n
 329        * mimetype           : string or unicode - mimetype.\n
 330        * \n
 331        * *If known prehand, this can avoid xbmc doing HEAD requests to http servers to figure out file type.\n
 332        */
 333       void setMimeType(const String& mimetype);
 334
 335       /**
 336        * getdescription() -- Returns the description of this PlayListItem.\n
 337        */
 338       String getdescription();
 339
 340       /**
 341        * getduration() -- Returns the duration of this PlayListItem\n
 342        */
 343       String getduration();
 344
 345       /**
 346        * getfilename() -- Returns the filename of this PlayListItem.\n
 347        */
 348       String getfilename();
 349     };
 350
 351     typedef std::vector<ListItem*> ListItemList;
 352
 353   }
 354 }
 355
 356