src/amarok.h

   1 //See COPYING file for licensing information
   2
   3 #ifndef AMAROK_H
   4 #define AMAROK_H
   5
   6 #include <K3ProcIO> //Amarok::ProcIO
   7 #include <KActionCollection>
   8 #include <KConfig>
   9 #include <KIO/NetAccess>
  10 #include <KUrl> // recursiveUrlExpand
  11
  12 #include "amarok_export.h"
  13
  14 class QColor;
  15 class QDateTime;
  16 class QEvent;
  17 class QMutex;
  18 class QPixmap;
  19 class QWidget;
  20 class DynamicMode;
  21 class Q3ListView;
  22 class Q3ListViewItem;
  23 namespace KIO { class Job; }
  24
  25 namespace Amarok
  26 {
  27     const int VOLUME_MAX = 100;
  28     const int SCOPE_SIZE = 9; //= 2**9 = 512
  29     const int blue       = 0x202050;
  30     const int VOLUME_SENSITIVITY = 30; //for mouse wheels
  31     const int GUI_THREAD_ID = 0;
  32
  33     extern QMutex globalDirsMutex; // defined in app.cpp
  34
  35     namespace ColorScheme
  36     {
  37         ///eg. base of the Amarok Player-window
  38         extern QColor Base; //Amarok::blue
  39         ///eg. text in the Amarok Player-window
  40         extern QColor Text; //Qt::white
  41         ///eg. background colour for Amarok::PrettySliders
  42         extern QColor Background; //brighter blue
  43         ///eg. outline of slider widgets in Player-window
  44         extern QColor Foreground; //lighter blue
  45         ///eg. K3ListView alternative row color
  46         extern QColor AltBase; //grey toned base
  47     }
  48
  49     /** The version of the playlist XML format. Increase whenever it changes backwards-incompatibly. */
  50     inline QString xmlVersion() { return "2.4"; }
  51
  52     /**
  53      * Convenience function to return the KApplication instance KConfig object
  54      * pre-set to a specific group.
  55      * @param group Will pre-set the KConfig object to this group.
  56      */
  57     /* FIXME: This function can lead to very bizarre and hard to figure bugs.
  58               While we don`t fix it properly, use it like this: amarok::config( Group )->readEntry( ... ) */
  59     AMAROK_EXPORT KConfigGroup config( const QString &group = "General" ); //defined in app.cpp
  60
  61     /**
  62      * @return the KActionCollection used by Amarok
  63      * The KActionCollection is owned by the PlaylistWindow, so you must ensure
  64      * you don't try to use this before then, but we've taken steps to prevent
  65      * this eventuality - you should be safe.
  66      */
  67     KActionCollection *actionCollection(); //defined in app.cpp
  68
  69     /**
  70      * An event handler that handles events in a generic Amarok fashion. Mainly
  71      * useful for drops, ie offers the Amarok popup for adding tracks to the
  72      * playlist. You shouldn't pass every event here, ie closeEvents will not be
  73      * handled as expected! Check the source in app.cpp if you want to see what
  74      * it can do.
  75      * @param recipient The object that received the event.
  76      * @param e The event you want handled in a generic fashion.
  77      * @return true if the event was handled.
  78      */
  79     bool genericEventHandler( QWidget *recipient, QEvent *e ); //defined in app.cpp
  80
  81     /**
  82      * Invoke the external web browser set in Amarok's configuration.
  83      * @param url The URL to be opened in the browser.
  84      * @return True if the browser could be started.
  85      */
  86     bool invokeBrowser( const QString& url ); //defined in app.cpp
  87
  88     /**
  89      * Obtain an Amarok PNG image as a QPixmap
  90      */
  91     QPixmap getPNG( const QString& /*fileName*/ ); //defined in app.cpp
  92
  93     /**
  94      * Obtain an Amarok JPG image as a QPixmap
  95      */
  96     QPixmap getJPG( const QString& /*fileName*/ ); //defined in app.cpp
  97
  98     /**
  99      * The mainWindow is the playlistWindow
 100      */
 101     QWidget *mainWindow(); //defined in app.cpp
 102
 103     /**
 104      * Allocate one on the stack, and it'll set the busy cursor for you until it
 105      * is destroyed
 106      */
 107     class OverrideCursor { //defined in app.cpp
 108     public:
 109         OverrideCursor( Qt::CursorShape cursor = Qt::WaitCursor );
 110        ~OverrideCursor();
 111     };
 112
 113     /**
 114      * For saving files to ~/.kde/share/apps/amarok/directory
 115      * @param directory will be created if not existing, you MUST end the string
 116      *                  with '/'
 117      */
 118     AMAROK_EXPORT QString saveLocation( const QString &directory = QString() ); //defined in collectionreader.cpp
 119
 120     KIO::Job *trashFiles( const KUrl::List &files ); //defined in app.cpp
 121
 122     /**
 123      * For recursively expanding the contents of a directory into a KUrl::List
 124      * (playlists are ignored)
 125      */
 126     //PORT 2.0
 127 //     AMAROK_EXPORT KUrl::List recursiveUrlExpand( const KUrl &url, int maxURLs = -1 ); //defined in playlistloader.cpp
 128 //     AMAROK_EXPORT KUrl::List recursiveUrlExpand( const KUrl::List &urls, int maxURLs = -1 ); //defined in playlistloader.cpp
 129
 130     QString verboseTimeSince( const QDateTime &datetime ); //defined in contextbrowser.cpp
 131
 132     QString verboseTimeSince( uint time_t ); //defined in contextbrowser.cpp
 133
 134     /**
 135      * Function that must be used when separating contextBrowser escaped urls
 136      */
 137     // defined in contextbrowser.cpp
 138     void albumArtistTrackFromUrl( QString url, QString &artist, QString &album, QString &detail );
 139
 140     /**
 141      * @return the LOWERCASE file extension without the preceding '.', or "" if there is none
 142      */
 143     inline QString extension( const QString &fileName )
 144     {
 145         return fileName.contains( '.' ) ? fileName.mid( fileName.lastIndexOf( '.' ) + 1 ).toLower() : "";
 146     }
 147
 148     /** Transform url into a file url if possible */
 149     inline KUrl mostLocalURL( const KUrl &url )
 150     {
 151         return KIO::NetAccess::mostLocalUrl( url, mainWindow() );
 152     }
 153
 154     /**
 155      * @return the last directory in @param fileName
 156      */
 157     inline QString directory( const QString &fileName )
 158     {
 159         return fileName.section( '/', 0, -2 );
 160     }
 161   /** Due to xine-lib, we have to make K3Process close all fds, otherwise we get "device is busy" messages
 162   * Used by Amarok::ProcIO and Amarok::Process, exploiting commSetupDoneC(), a virtual method that
 163   * happens to be called in the forked process
 164   * See bug #103750 for more information.
 165   */
 166   //TODO ugly hack, fix K3Process for KDE 4.0
 167     void closeOpenFiles(int out, int in, int err); //defined in scriptmanager.cpp
 168
 169     /**
 170     * Returns internal code for database type, DbConnection::sqlite, DbConnection::mysql, or DbConnection::postgresql
 171     * @param type either "SQLite", "MySQL", or "Postgresql".
 172     */
 173     int databaseTypeCode( const QString type ); //defined in configdialog.cpp
 174
 175     void setUseScores( bool use ); //defined in app.cpp
 176     void setUseRatings( bool use );
 177     void setMoodbarPrefs( bool show, bool moodier, int alter, bool withMusic );
 178
 179     bool repeatNone(); //defined in actionclasses.cpp
 180     bool repeatTrack();
 181     bool repeatAlbum();
 182     bool repeatPlaylist();
 183     bool randomOff();
 184     bool randomTracks();
 185     bool randomAlbums();
 186     bool favorNone();
 187     bool favorScores();
 188     bool favorRatings();
 189     bool favorLastPlay();
 190     bool entireAlbums(); //repeatAlbum() || randomAlbums()
 191
 192     const DynamicMode *dynamicMode(); //defined in playlist.cpp
 193
 194     Q3ListViewItem* findItemByPath( Q3ListView *view, QString path ); //defined in playlistbrowser.cpp
 195     QStringList splitPath( QString path ); //defined in playlistbrowser.cpp
 196
 197     /**
 198      * Maps the icon name to a system icon or custom Amarok icon, depending on the settings.
 199      */
 200     AMAROK_EXPORT QString icon( const QString& name ); //defined in iconloader.cpp
 201
 202     /**
 203      * Removes accents from the string
 204      * @param path The original path.
 205      * @return The cleaned up path.
 206      */
 207     AMAROK_EXPORT QString cleanPath( const QString &path ); //defined in app.cpp
 208
 209     /**
 210      * Replaces all non-ASCII characters with '_'.
 211      * @param path The original path.
 212      * @return The ASCIIfied path.
 213      */
 214     AMAROK_EXPORT QString asciiPath( const QString &path ); //defined in app.cpp
 215
 216     /**
 217      * Transform path into one valid on VFAT file systems
 218      * @param path The original path.
 219      * @return The cleaned up path.
 220      */
 221     AMAROK_EXPORT QString vfatPath( const QString &path ); //defined in app.cpp
 222
 223     /**
 224      * Compare both strings from left to right and remove the common part from input
 225      * @param input the string that get's cleaned.
 226      * @param ref a reference to compare input with.
 227      * @return The cleaned up string.
 228      */
 229     AMAROK_EXPORT QString decapitateString( const QString &input, const QString &ref );
 230
 231     /*
 232      * Transform to be usable within HTML/HTML attributes
 233      */
 234     AMAROK_EXPORT QString escapeHTMLAttr( const QString &s );
 235     AMAROK_EXPORT QString unescapeHTMLAttr( const QString &s ); //defined in statistics.cpp
 236
 237     /* defined in scriptmanager.cpp */
 238     /**
 239      * Returns the proxy that should be used for a given URL.
 240      * @param url the url.
 241      * @return The url of the proxy, or a empty string if no proxy should be used.
 242      */
 243     QString proxyForUrl(const QString& url);
 244
 245     /**
 246      * Returns the proxy that should be used for a given protocol.
 247      * @param protocol the protocol.
 248      * @return The url of the proxy, or a empty string if no proxy should be used.
 249      */
 250     QString proxyForProtocol(const QString& protocol);
 251
 252     /*defined in collectionbrowser/collectiontreeitemmodel.cpp */
 253     /**
 254      * Small function aimed to convert Eagles, The -> The Eagles (and back again).
 255      * @param str the string to manipulate
 256      * @param reverse if true, The Eagles -> Eagles, The. If false, Eagles, The -> The Eagles
 257      */
 258     void manipulateThe( QString &str, bool reverse );
 259
 260     ////////////////////////////////////////////////////////////////////////////////
 261     // class Amarok::ProcIO
 262     ////////////////////////////////////////////////////////////////////////////////
 263     /**
 264     * Due to xine-lib, we have to make K3Process close all fds, otherwise we get "device is busy" messages
 265     * Used by Amarok::ProcIO and AmarokProcess, exploiting commSetupDoneC(), a virtual method that
 266     * happens to be called in the forked process
 267     * See bug #103750 for more information.
 268     */
 269     class AMAROK_EXPORT ProcIO : public K3ProcIO {
 270         public:
 271         ProcIO(); // ctor sets the textcodec to UTF-8, in scriptmanager.cpp
 272         virtual int commSetupDoneC() {
 273             const int i = K3ProcIO::commSetupDoneC();
 274             Amarok::closeOpenFiles( K3ProcIO::out[0],K3ProcIO::in[0],K3ProcIO::err[0] );
 275             return i;
 276         }
 277     };
 278
 279     ////////////////////////////////////////////////////////////////////////////////
 280     // class Amarok::Process
 281     ////////////////////////////////////////////////////////////////////////////////
 282     /** Due to xine-lib, we have to make K3Process close all fds, otherwise we get "device is busy" messages
 283      * Used by Amarok::ProcIO and Amarok::Process, exploiting commSetupDoneC(), a virtual method that
 284      * happens to be called in the forked process
 285      * See bug #103750 for more information.
 286      */
 287     class AMAROK_EXPORT Process : public K3Process {
 288         public:
 289         Process( QObject *parent = 0 ) : K3Process( parent ) {}
 290         virtual int commSetupDoneC() {
 291             const int i = K3Process::commSetupDoneC();
 292             Amarok::closeOpenFiles(K3Process::out[0],K3Process::in[0], K3Process::err[0]);
 293             return i;
 294         }
 295     };
 296
 297
 298 }
 299
 300
 301 /**
 302  * Use this to const-iterate over QStringLists, if you like.
 303  * Watch out for the definition of last in the scope of your for.
 304  *
 305  *     QStringList strings;
 306  *     oldForeach( strings )
 307  *         debug() << *it << endl;
 308  */
 309 #define oldForeach( x ) \
 310     for( QStringList::ConstIterator it = x.begin(), end = x.end(); it != end; ++it )
 311
 312 /**
 313  * You can use this for lists that aren't QStringLists.
 314  * Watch out for the definition of last in the scope of your for.
 315  *
 316  *     BundleList bundles;
 317  *     oldForeachType( BundleList, bundles )
 318  *         debug() << *it.url() << endl;
 319  */
 320 #define oldForeachType( Type, x ) \
 321     for( Type::ConstIterator it = x.begin(), end = x.end(); it != end; ++it )
 322
 323 /**
 324  * Creates iterators of type @p Type.
 325  * Watch out for the definitions of last and end in your scope.
 326  *
 327  *     BundleList bundles;
 328  *     for( for_iterators( BundleList, bundles ); it != end; ++it )
 329  *         debug() << *it.url() << endl;
 330  */
 331 #define for_iterators( Type, x ) \
 332     Type::ConstIterator it = x.begin(), end = x.end(), last = x.fromLast()
 333
 334
 335 /// Update this when necessary
 336 #define APP_VERSION "2.0-SVN"
 337
 338 #endif