KCompactDisc

kcompactdisc.h
1 /*
2  * KCompactDisc - A CD drive interface for the KDE Project.
3  *
4  * Copyright (C) 2005 Shaheedur R. Haque <[email protected]>
5  * Copyright (C) 2007 Alexander Kern <[email protected]>
6  *
7  * This program is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 2, or (at your option)
10  * any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20  */
21 
22 #ifndef KCOMPACTDISC_H
23 #define KCOMPACTDISC_H
24 
25 #include <QObject>
26 #include <QStringList>
27 #include <QUrl>
28 #include <QTimer>
29 
30 #include "kcompactdisc_export.h"
31 
32 class KCompactDiscPrivate;
33 
34 /**
35  * KCompactDisc - A CD drive interface for the KDE Project.
36  *
37  * The disc interface is modelled by these slots:
38  *
39  * @see playTrack(unsigned int track): Play specified track.
40  * @see playPosition(unsigned int position): seek to specified position.
41  * @see next(): Play next track in the playlist.
42  * @see prev(): Play previous track in the playlist.
43  * @see pause(): Toggle between pause/resume.
44  * @see stop(): Stop playout:
45  * @see eject(): Stop playout and eject disc or Close
46  * tray and try to read TOC from disc.
47  *
48  * The progress of playout is modelled by these signals:
49  *
50  * @see playoutPositionChanged(unsigned int position): A position in a track.
51  * @see playoutTrackChanged(unsigned int track): A playout of this track is started.
52  *
53  *
54  * The shape of playlist is controlled by these accessors.
55  *
56  * @see setRandomPlaylist(bool): Shuffle the playlist.
57  * @see setLoopPlaylist(bool): Couple begin and end of playlist.
58  *
59  *
60  * The disc lifecycle is modelled by these signals:
61  *
62  * @see #discChanged(...): A new disc was inserted.
63  * @see discStatusString(KCompactDisc::Playing): A disc started playout.
64  * @see discStatusString(KCompactDisc::Paused): A disc was paused.
65  * @see discStatusString(KCompactDisc::Stopped): The disc stopped.
66  * @see discStatusString(KCompactDisc::NoDisc): The disc is removed. No disc in tray or data disc.
67  * @see discStatusString(KCompactDisc::NotReady): The disc is present. But playout is not possible.
68  * @see discInformation(KCompactDisc::DiscInfo info): A content for disc information is arrived.
69  *
70  *
71  * The volume control is modelled by these slots:
72  *
73  * @see setVolume(unsigned int volume): A new volume value.
74  * @see setBalance(unsigned int balance): A new balance value.
75  *
76  *
77  * And these signals:
78  *
79  * @see volumeChanged(unsigned int volume): A current volume value.
80  * @see balanceChanged(unsigned int balance): A current balance value.
81  *
82  *
83  * All times in this interface are in seconds. Valid track numbers are
84  * positive numbers; zero is not a valid track number.
85  */
86 class KCOMPACTDISC_EXPORT KCompactDisc : public QObject
87 {
88  Q_OBJECT
89 /*
90  Q_CLASSINFO("D-Bus Interface", "org.kde.KSCD")
91 
92 public Q_SLOTS:
93  Q_SCRIPTABLE bool playing();
94  Q_SCRIPTABLE void play() { play(); }
95  Q_SCRIPTABLE void stop() { stop(); }
96  Q_SCRIPTABLE void previous() { prev(); }
97  Q_SCRIPTABLE void next() { next(); }
98  Q_SCRIPTABLE void jumpTo(int seconds) { jumpToTime(seconds); }
99  Q_SCRIPTABLE void eject() { eject(); }
100  Q_SCRIPTABLE void toggleLoop() { loop(); }
101  Q_SCRIPTABLE void toggleShuffle() { random(); }
102  Q_SCRIPTABLE void toggleTimeDisplay() { cycleplaytimemode(); }
103  Q_SCRIPTABLE void cddbDialog() { CDDialogSelected(); }
104  Q_SCRIPTABLE void optionDialog() { showConfig(); }
105  Q_SCRIPTABLE void setTrack(int t) { trackSelected(t > 0 ? t - 1 : 0); }
106  Q_SCRIPTABLE void volumeDown() { decVolume(); }
107  Q_SCRIPTABLE void volumeUp() { incVolume(); }
108  Q_SCRIPTABLE void setVolume(int v);
109  Q_SCRIPTABLE void setDevice(const QString& dev);
110  Q_SCRIPTABLE int getVolume() { return Prefs::volume(); }
111  Q_SCRIPTABLE int currentTrack();
112  Q_SCRIPTABLE int currentTrackLength();
113  Q_SCRIPTABLE int currentPosition();
114  Q_SCRIPTABLE int getStatus();
115  Q_SCRIPTABLE QString currentTrackTitle();
116  Q_SCRIPTABLE QString currentAlbum();
117  Q_SCRIPTABLE QString currentArtist();
118  Q_SCRIPTABLE QStringList trackList();
119 */
120 public:
121  enum InformationMode
122  {
123  Synchronous, // Return and emit signal when cdrom and cddb information arrives.
124  Asynchronous // Block until cdrom and cddb information has been obtained
125  };
126 
127  enum DiscCommand
128  {
129  Play,
130  Pause,
131  Next,
132  Prev,
133  Stop,
134  Eject,
135  Loop,
136  Random
137  };
138 
139  enum DiscStatus
140  {
141  Playing,
142  Paused,
143  Stopped,
144  Ejected,
145  NoDisc,
146  NotReady,
147  Error
148  };
149 
150  enum DiscInfo
151  {
152  Cdtext,
153  Cddb,
154  PhononMetadata
155  };
156 
157  explicit KCompactDisc(InformationMode = KCompactDisc::Synchronous);
158  ~KCompactDisc() override;
159 
160  /**
161  * @param device Name of CD device, e.g. /dev/cdrom.
162  * @param volume Playback volume.
163  * @param digitalPlayback Select digital or analog playback.
164  * @param audioSystem For digital playback, system to use, e.g. "phonon".
165  * @param audioDevice For digital playback, device to use.
166  * @return true if the device seemed usable.
167  */
168  bool setDevice(
169  const QString &device,
170  unsigned volume = 50,
171  bool digitalPlayback = true,
172  const QString &audioSystem = QString(),
173  const QString &audioDevice = QString());
174 
175  /**
176  * If the url is a media:/ or system:/ URL returns
177  * the device it represents, otherwise returns device
178  */
179  static QString urlToDevice(const QUrl& url);
180 
181  /**
182  * All installed audio backends.
183  */
184  static const QStringList audioSystems();
185 
186  /**
187  * All present CDROM devices.
188  */
189  static const QStringList cdromDeviceNames();
190 
191  /**
192  * The default CDROM device for this system.
193  */
194  static const QString defaultCdromDeviceName();
195 
196  /**
197  * The Url of default CDROM device for this system.
198  */
199  static const QUrl defaultCdromDeviceUrl();
200 
201  /**
202  * The Url of named CDROM device for this system.
203  */
204  static const QUrl cdromDeviceUrl(const QString &);
205 
206  /**
207  * The Udi of default CDROM device for this system.
208  */
209  static const QString defaultCdromDeviceUdi();
210 
211  /**
212  * The Udi of named CDROM device for this system.
213  */
214  static const QString cdromDeviceUdi(const QString &);
215 
216  /**
217  * SCSI parameter VENDOR of current CDROM device.
218  *
219  * @return Null string if no usable device set.
220  */
221  const QString &deviceVendor();
222 
223  /**
224  * SCSI parameter MODEL of current CDROM device.
225  *
226  * @return Null string if no usable device set.
227  */
228  const QString &deviceModel();
229 
230  /**
231  * SCSI parameter REVISION of current CDROM device.
232  *
233  * @return Null string if no usable device set.
234  */
235  const QString &deviceRevision();
236 
237  /**
238  * Current CDROM device.
239  *
240  * @return Null string if no usable device set.
241  */
242  const QString &deviceName();
243 
244  /**
245  * Current device as QUrl.
246  */
247  const QUrl deviceUrl();
248 
249  /**
250  * Current disc, 0 if no disc or impossible to calculate id.
251  */
252  unsigned discId();
253 
254  /**
255  * CDDB signature of disc, empty if no disc or not possible to deliver.
256  */
257  const QList<unsigned> &discSignature();
258 
259  /**
260  * Artist for whole disc.
261  *
262  * @return Disc artist or null string.
263  */
264  const QString &discArtist();
265 
266  /**
267  * Title of disc.
268  *
269  * @return Disc title or null string.
270  */
271  const QString &discTitle();
272 
273  /**
274  * Known length of disc.
275  *
276  * @return Disc length in seconds.
277  */
278  unsigned discLength();
279 
280  /**
281  * Current position on the disc.
282  *
283  * @return Position in seconds.
284  */
285  unsigned discPosition();
286 
287  /**
288  * Current status.
289  *
290  * @return Current status.
291  */
292  KCompactDisc::DiscStatus discStatus();
293 
294  /**
295  * Status as string.
296  *
297  * @return Status as QString.
298  */
299  QString discStatusString(KCompactDisc::DiscStatus status);
300 
301  /**
302  * Artist of current track.
303  *
304  * @return Track artist or null string.
305  */
306  QString trackArtist();
307 
308  /**
309  * Artist of given track.
310  *
311  * @return Track artist or null string.
312  */
313  QString trackArtist(unsigned track);
314 
315  /**
316  * Title of current track.
317  *
318  * @return Track title or null string.
319  */
320  QString trackTitle();
321 
322  /**
323  * Title of given track.
324  *
325  * @return Track title or null string.
326  */
327  QString trackTitle(unsigned track);
328 
329  /**
330  * Length of current track.
331  *
332  * @return Track length in seconds.
333  */
334  unsigned trackLength();
335 
336  /**
337  * Length of given track.
338  *
339  * @param track Track number.
340  * @return Track length in seconds.
341  */
342  unsigned trackLength(unsigned track);
343 
344  /**
345  * Current track.
346  *
347  * @return Track number.
348  */
349  unsigned track();
350 
351  /**
352  * Current track position.
353  *
354  * @return Track position in seconds.
355  */
356  unsigned trackPosition();
357 
358  /**
359  * Number of tracks.
360  */
361  unsigned tracks();
362 
363  /**
364  * Is status playing.
365  */
366  bool isPlaying();
367 
368  /**
369  * Is status pausing.
370  */
371  bool isPaused();
372 
373  /**
374  * Is status no disc.
375  */
376  bool isNoDisc();
377 
378  /**
379  * @return if the track is actually an audio track.
380  */
381  bool isAudio(unsigned track);
382 
383 
384 public Q_SLOTS:
385 
386  /**
387  * Start playout of track.
388  */
389  void playTrack(unsigned int track);
390 
391  /**
392  * Start playout or seek to given position of track.
393  */
394  void playPosition(unsigned int position);
395 
396  /* GUI bindings */
397  /**
398  * Start playout.
399  */
400  void play();
401 
402  /**
403  * Start playout of next track.
404  */
405  void next();
406 
407  /**
408  * Start playout of previous track.
409  */
410  void prev();
411 
412  /**
413  * Pause/resume playout.
414  */
415  void pause();
416 
417  /**
418  * Stop playout.
419  */
420  void stop();
421 
422  /**
423  * Open/close tray.
424  */
425  void eject();
426 
427  /**
428  * Switch endless playout on/off.
429  */
430  void loop();
431 
432  /**
433  * Switch random playout on/off.
434  */
435  void random();
436 
437  /**
438  * Pipe GUI command.
439  */
440  void doCommand(KCompactDisc::DiscCommand);
441 
442 
443  void metadataLookup();
444 
445 
446 Q_SIGNALS:
447  /**
448  * A new position in a track. This signal is delivered at
449  * approximately 1 second intervals while a track is playing. At first sight,
450  * this might seem overzealous, but it is likely that any CD player UI will use
451  * this to track the second-by-second position, so we may as well do it for
452  * them.
453  *
454  * @param position Position within track in seconds.
455  */
456  void playoutPositionChanged(unsigned int position);
457 
458  /**
459  * A new track is started.
460  *
461  * @param track Track number.
462  */
463  void playoutTrackChanged(unsigned int track);
464 
465 
466 public Q_SLOTS:
467 
468  void setRandomPlaylist(bool);
469  void setLoopPlaylist(bool);
470  void setAutoMetadataLookup(bool);
471 
472 
473 Q_SIGNALS:
474 
475  void randomPlaylistChanged(bool);
476  void loopPlaylistChanged(bool);
477 
478 
479 Q_SIGNALS:
480 
481  /**
482  * A new Disc is inserted
483  *
484  */
485  void discChanged(unsigned int tracks);
486 
487  /**
488  * A new Disc information is arrived
489  *
490  */
491  void discInformation(KCompactDisc::DiscInfo info);
492 
493  /**
494  * A Disc status changed
495  *
496  */
497  void discStatusChanged(KCompactDisc::DiscStatus status);
498 
499 
500 public Q_SLOTS:
501 
502  /**
503  * Set volume
504  */
505  void setVolume(unsigned int volume);
506 
507  /**
508  * Set balance
509  */
510  void setBalance(unsigned int balance);
511 
512 Q_SIGNALS:
513 
514  /**
515  * New volume
516  */
517  void volumeChanged(unsigned int volume);
518 
519  /**
520  * New balance
521  */
522  void balanceChanged(unsigned int balance);
523 
524 
525 protected:
526  KCompactDiscPrivate * d_ptr;
527  KCompactDisc(KCompactDiscPrivate &dd, QObject *parent);
528 
529 private:
530  Q_DECLARE_PRIVATE(KCompactDisc)
531 #ifdef USE_WMLIB
532  friend class KWMLibCompactDiscPrivate;
533 #endif
534  friend class KPhononCompactDiscPrivate;
535 };
536 
537 #endif
KCompactDisc - A CD drive interface for the KDE Project.
Definition: kcompactdisc.h:86
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Oct 18 2021 23:23:11 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.