KMediaPlayer

player.h
1 // Copyright (C) 2002 Neil Stevens <[email protected]>
2 //
3 // Permission is hereby granted, free of charge, to any person obtaining a copy
4 // of this software and associated documentation files (the "Software"), to deal
5 // in the Software without restriction, including without limitation the rights
6 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7 // copies of the Software, and to permit persons to whom the Software is
8 // furnished to do so, subject to the following conditions:
9 //
10 // The above copyright notice and this permission notice shall be included in
11 // all copies or substantial portions of the Software.
12 //
13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 // THE AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
17 // AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
18 // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
19 //
20 // Except as contained in this notice, the name(s) of the author(s) shall not be
21 // used in advertising or otherwise to promote the sale, use or other dealings
22 // in this Software without prior written authorization from the author(s).
23 
24 #ifndef KMEDIAPLAYERPLAYER_H
25 #define KMEDIAPLAYERPLAYER_H
26 
27 #include <kparts/readonlypart.h>
28 #include "view.h"
29 
30 #include "kmediaplayer_export.h"
31 
32 #include <memory>
33 
34 /**
35  * An interface for media playback parts.
36  */
37 namespace KMediaPlayer
38 {
39 
40 /**
41  * KPart interface to allow controlling and querying playback of a media track.
42  *
43  * This class provides methods to control playback of a single media track, as
44  * well as providing information on the current playback state. It can
45  * optionally provide access to a user interface that can be displayed to the
46  * user.
47  *
48  * There are two servicetypes for this KParts interface: KMediaPlayer/Player
49  * and KMediaPlayer/Engine. KMediaPlayer/Player provides a user interface (see
50  * view()), while KMediaPlayer/Engine just provides direct control via this
51  * class.
52  */
53 class KMEDIAPLAYER_EXPORT Player : public KParts::ReadOnlyPart
54 {
55  Q_OBJECT
56  Q_ENUMS(State)
57  /**
58  * Whether the length property is valid.
59  *
60  * Not all media tracks have a length (for example, some streams are
61  * continuous).
62  */
63  Q_PROPERTY(bool hasLength READ hasLength)
64  /**
65  * The length of the media track in milliseconds.
66  *
67  * The value is undefined if hasLength is @c false.
68  */
69  Q_PROPERTY(qlonglong length READ length)
70  /**
71  * Whether playback should loop.
72  *
73  * As this interface has no concept of a playlist, this indicates
74  * whether the current media track will play repeatedly.
75  */
76  Q_PROPERTY(bool looping READ isLooping WRITE setLooping)
77  /**
78  * The position in the media track in milliseconds.
79  */
80  Q_PROPERTY(qlonglong position READ position)
81  /**
82  * Whether seek() can be expected to work on the current media track.
83  *
84  * Some streams cannot be seeked.
85  */
86  Q_PROPERTY(bool seekable READ isSeekable)
87  /**
88  * The current state of the player.
89  */
90  Q_PROPERTY(State state READ state WRITE setState NOTIFY stateChanged)
91 
92 public:
93  /**
94  * Constructs a Player instance with no associated GUI.
95  *
96  * This should be used when a KMediaPlayer/Engine is requested.
97  */
98  explicit Player(QObject *parent);
99 
100  /**
101  * Constructs a Player instance with a GUI.
102  *
103  * This should be used when a KMediaPlayer/Player is requested.
104  */
105  Player(QWidget *parentWidget, const char *widgetName, QObject *parent);
106 
107  /**
108  * Cleans up any associated resources.
109  *
110  * This should not explicitly delete any widget returned by view(): if it
111  * has been reparented, it is up to the caller to dispose of it properly.
112  */
113  virtual ~Player();
114 
115  /**
116  * Returns the widget associated with this player.
117  *
118  * If the part's service type is KMediaPlayer/Player, this should not return
119  * 0. However, if the part's service is just KMediaPlayer/Engine, this may
120  * return 0.
121  *
122  * @returns A widget to view and control this Player instance, or 0 if
123  * there is no GUI.
124  */
125  virtual View *view() = 0;
126 
127 public Q_SLOTS:
128  /**
129  * Pauses playback of the media track.
130  *
131  * If the media track is not already paused, this should have no effect.
132  */
133  virtual void pause() = 0;
134 
135  /**
136  * Starts playing the media track.
137  *
138  * If the media track is already playing, this should have no effect.
139  */
140  virtual void play() = 0;
141 
142  /**
143  * Stops playback of the media track and returns it to the beginning.
144  */
145  virtual void stop() = 0;
146 
147  /**
148  * Moves the current playback position.
149  *
150  * This will have no effect if isSeekable() is @c false.
151  *
152  * @param msec The new playback position in milliseconds.
153  */
154  virtual void seek(qlonglong msec) = 0;
155 public:
156  /**
157  * Returns whether seek() can be expected to work on the current media
158  * track.
159  */
160  virtual bool isSeekable() const = 0;
161 
162  /**
163  * Returns the current playback position in milliseconds.
164  */
165  virtual qlonglong position() const = 0;
166 
167  /**
168  * Returns whether the current media track has a length.
169  */
170  virtual bool hasLength() const = 0;
171 
172  /**
173  * Returns the length of the current media track.
174  *
175  * The returned value is undefined if hasLength() returns @c false.
176  */
177  virtual qlonglong length() const = 0;
178 
179 public Q_SLOTS:
180  /**
181  * Sets whether playback should loop.
182  *
183  * @param on If @c true, playback will resume from the start of the
184  * track when the end is reached; if @c false it will not.
185  */
186  void setLooping(bool on);
187 public:
188  /**
189  * Returns whether playback will loop.
190  */
191  bool isLooping() const;
192 Q_SIGNALS:
193  /**
194  * Indicates that the value of isLooping() has changed.
195  *
196  * @param isLooping The new value.
197  */
198  void loopingChanged(bool isLooping);
199 
200 public:
201  /**
202  * The possible states of the player.
203  */
204  enum State {
205  /**
206  * No track is loaded.
207  *
208  * Most functions will not work in this state.
209  */
211  /**
212  * A track is loaded, but playback is stopped.
213  *
214  * The position should always be 0 in this state. Playback will start
215  * from the beginning when play() is called.
216  */
218  /**
219  * Playback is temporarily suspended.
220  *
221  * Playback will resume from the current position when play() is called.
222  */
224  /**
225  * The media is currently being output.
226  */
227  Play
228  };
229  /**
230  * Returns the current state of the player.
231  */
232  State state() const;
233 Q_SIGNALS:
234  /**
235  * Indicates that the value returned by state() has changed.
236  *
237  * @param newState The new value.
238  */
239  void stateChanged(KMediaPlayer::Player::State newState);
240 
241 protected Q_SLOTS:
242  /**
243  * Sets the current state.
244  *
245  * This allows implementors to alter the playback state. This will emit the
246  * stateChanged() signal as appropriate.
247  */
248  void setState(State state);
249 
250 protected:
251  /* Enable the stateChanged(QString&, ...) method that was hidden by
252  the stateChanged(State) signal */
254 
255 private:
256  std::unique_ptr<class PlayerPrivate> const d;
257 };
258 
259 }
260 
261 Q_DECLARE_METATYPE(KMediaPlayer::Player::State)
262 
263 #endif
A user interface to control a Player object.
Definition: view.h:40
A track is loaded, but playback is stopped.
Definition: player.h:217
virtual void stateChanged(const QString &newstate, ReverseStateChange reverse=StateNoReverse)
No track is loaded.
Definition: player.h:210
An interface for media playback parts.
Definition: player.h:37
Playback is temporarily suspended.
Definition: player.h:223
KPart interface to allow controlling and querying playback of a media track.
Definition: player.h:53
State
The possible states of the player.
Definition: player.h:204
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue May 11 2021 22:42:46 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.