~kubuntu-members/juk/4.11 : contents of tracksequenceiterator.h at revision 2401

~kubuntu-members/juk/4.11 : (revision 2401)

/***************************************************************************
    begin                : Thu Aug 19 2004
    copyright            : (C) 2002 - 2004 by Michael Pyne
    email                : michael.pyne@kde.org
***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef TRACKSEQUENCEITERATOR_H
#define TRACKSEQUENCEITERATOR_H

#include "playlistitem.h"
#include "playlistsearch.h"

class Playlist;

/**
 * This abstract class defines an interface to be used by TrackSequenceManager,
 * to iterate over the items in a playlist.  Implement this class in a subclass
 * in order to define your own ordering for playlist sequences.  For an example,
 * see the UpcomingPlaylist class.
 *
 * @author Michael Pyne <michael.pyne@kdemail.net>
 * @see UpcomingPlaylist
 * @see TrackSequenceManager
 */
class TrackSequenceIterator
{
public:
    /**
     * Default constructor.
     */
    TrackSequenceIterator();

    /**
     * Default copy constructor.
     *
     * @param other the TrackSequenceIterator we are copying
     */
    TrackSequenceIterator(const TrackSequenceIterator & other);

    /**
     * Default destructor.
     */
    virtual ~TrackSequenceIterator();

    /**
     * This function moves the current item to the next track.  You must
     * reimplement this function in your subclasses.
     */
    virtual void advance() = 0;

    /**
     * This function moves the current item to the previous track.  This may
     * not always make sense, and the history functionality of the Playlist
     * class currently overrides this.  You must reimplement this function in
     * your subclass.
     */
    virtual void backup() = 0;

    /**
     * This function returns the current PlaylistItem, or 0 if the iterator is
     * not pointing at any PlaylistItem.
     *
     * @return current track
     */
    virtual PlaylistItem *current() const { return m_current; }

    /**
     * This function creates a perfect copy of the object it is called on, to
     * avoid the C++ slicing problem.  When you reimplement this function, you
     * should change the return type to the name of the subclass.
     *
     * @return pointer to a copy of the object
     */
    virtual TrackSequenceIterator *clone() const = 0;

    /**
     * This function is called by the TrackSequenceManager when current() returns
     * 0, if the TrackSequenceManager has a playlist defined.  This function
     * should choose an appropriate starting track and set it as the current
     * item.  This function must be reimplemented in subclasses.
     *
     * @param playlist the playlist to iterate over
     */
    virtual void prepareToPlay(Playlist *playlist) = 0;

    /**
     * This function is called whenever the current playlist changes, such as
     * having a new search applied, items added/removed, etc.  If you need to
     * update internal state, you should do so without affecting the current
     * playing item. Default implementation does nothing.
     */
    virtual void playlistChanged();

    /**
     * This function is called by the manager when \p item is about to be
     * removed.  Subclasses should ensure that they're not still holding a
     * pointer to the item.  The default implementation does nothing.
     *
     * @param item the item about to be removed.
     */
    virtual void itemAboutToDie(const PlaylistItem *item);

    /**
     * This function is called by the TrackSequenceManager is some situations,
     * such as when playback is being stopped.  If you subclass needs to reset
     * any internal data members, do so in this function.  This function must
     * be reimplemented in subclasses.
     */
    virtual void reset() = 0;

    /**
     * This function is a public mutator to set the current item.
     *
     * @param current the new current item
     */
    virtual void setCurrent(PlaylistItem *current);

private:
    PlaylistItem::Pointer m_current; ///< the current item
};

/**
 * This is the default iterator for JuK, supporting normal, random, and album
 * random playback with or without looping.
 *
 * @author Michael Pyne <michael.pyne@kdemail.net>
 */
class DefaultSequenceIterator : public TrackSequenceIterator
{
public:
    /**
     * Default constructor.
     */
    DefaultSequenceIterator();

    /**
     * Default copy constructor.
     *
     * @param other the DefaultSequenceIterator to copy.
     */
    DefaultSequenceIterator(const DefaultSequenceIterator &other);

    /**
     * Default destructor.
     */
    virtual ~DefaultSequenceIterator();

    /**
     * This function advances to the next item in the current sequence.  The
     * algorithm used depends on what playback mode is selected.
     */
    virtual void advance();

    /**
     * This function moves to the previous item in the playlist.  This occurs
     * no matter what playback mode is selected.
     */
    virtual void backup();

    /**
     * This function prepares the class for iterator.  If no random play mode
     * is selected, the first item in the given playlist is the starting item.
     * Otherwise, an item is randomly picked to be the starting item.
     *
     * @param playlist The playlist to initialize for.
     */
    virtual void prepareToPlay(Playlist *playlist);

    /**
     * This function clears all internal state, including any random play lists,
     * and what the current album is.
     */
    virtual void reset();

    /**
     * This function recalculates the random lists, and is should be called
     * whenever its current playlist changes (at least for searches).
     */
    virtual void playlistChanged();

    /**
     * Called when \p item is about to be removed.  This function ensures that
     * it isn't remaining in the random play list.
     */
    virtual void itemAboutToDie(const PlaylistItem *item);

    /**
     * This function sets the current item, and initializes any internal lists
     * that may be needed for playback.
     *
     * @param current The new current item.
     */
    virtual void setCurrent(PlaylistItem *current);

    /**
     * This function returns a perfect copy of the object it is called on, to
     * get around the C++ slicing problem.
     *
     * @return A copy of the object the method is called on.
     */
    virtual DefaultSequenceIterator *clone() const;

private:

    /**
     * Reinitializes the internal random play list based on the playlist given
     * by \p p.  The currently playing item, if any, is automatically removed
     * from the list.
     *
     * @param p The Playlist to read items from.  If p is 0, the playlist of
     *        the currently playing item is used instead.
     */
    void refillRandomList(Playlist *p = 0);
    void initAlbumSearch(PlaylistItem *searchItem);

private:
    PlaylistItemList m_randomItems;
    PlaylistSearch m_albumSearch;
};

#endif /* TRACKSEQUENCEITERATOR_H */

// vim: set et sw=4 tw=0 sta:

1171 by Michael Pyne Like an idiot I forgot to include the license headers for the new files.	1	/***************************************************************************
1561 by Scott Wheeler Since the annotate is going to be screwed anyway by the time this is ported,	2	begin : Thu Aug 19 2004
1171 by Michael Pyne Like an idiot I forgot to include the license headers for the new files.	3	copyright : (C) 2002 - 2004 by Michael Pyne
	4	email : michael.pyne@kde.org
	5	***************************************************************************/
	6
	7	/***************************************************************************
	8	* *
	9	* This program is free software; you can redistribute it and/or modify *
	10	* it under the terms of the GNU General Public License as published by *
	11	* the Free Software Foundation; either version 2 of the License, or *
	12	* (at your option) any later version. *
	13	* *
	14	***************************************************************************/
	15
1564 by Michael Pyne Also standardize all of the JuK include header guards, to the most common style to save me	16	#ifndef TRACKSEQUENCEITERATOR_H
	17	#define TRACKSEQUENCEITERATOR_H
1170 by Michael Pyne OK, here it is. This commit introduces a new feature to JuK, the upcoming	18
	19	#include "playlistitem.h"
	20	#include "playlistsearch.h"
	21
	22	class Playlist;
	23
	24	/**
	25	* This abstract class defines an interface to be used by TrackSequenceManager,
	26	* to iterate over the items in a playlist. Implement this class in a subclass
	27	* in order to define your own ordering for playlist sequences. For an example,
	28	* see the UpcomingPlaylist class.
	29	*
	30	* @author Michael Pyne <michael.pyne@kdemail.net>
	31	* @see UpcomingPlaylist
	32	* @see TrackSequenceManager
	33	*/
	34	class TrackSequenceIterator
	35	{
	36	public:
	37	/**
	38	* Default constructor.
	39	*/
	40	TrackSequenceIterator();
	41
	42	/**
	43	* Default copy constructor.
	44	*
	45	* @param other the TrackSequenceIterator we are copying
	46	*/
	47	TrackSequenceIterator(const TrackSequenceIterator & other);
1561 by Scott Wheeler Since the annotate is going to be screwed anyway by the time this is ported,	48
1170 by Michael Pyne OK, here it is. This commit introduces a new feature to JuK, the upcoming	49	/**
	50	* Default destructor.
	51	*/
	52	virtual ~TrackSequenceIterator();
	53
	54	/**
	55	* This function moves the current item to the next track. You must
	56	* reimplement this function in your subclasses.
	57	*/
	58	virtual void advance() = 0;
	59
	60	/**
	61	* This function moves the current item to the previous track. This may
	62	* not always make sense, and the history functionality of the Playlist
	63	* class currently overrides this. You must reimplement this function in
	64	* your subclass.
	65	*/
	66	virtual void backup() = 0;
	67
	68	/**
	69	* This function returns the current PlaylistItem, or 0 if the iterator is
	70	* not pointing at any PlaylistItem.
	71	*
	72	* @return current track
	73	*/
1453 by Scott Wheeler Add a Pointer type to the PlaylistItem class with guarded pointer semantics.	74	virtual PlaylistItem *current() const { return m_current; }
1170 by Michael Pyne OK, here it is. This commit introduces a new feature to JuK, the upcoming	75
	76	/**
	77	* This function creates a perfect copy of the object it is called on, to
	78	* avoid the C++ slicing problem. When you reimplement this function, you
	79	* should change the return type to the name of the subclass.
	80	*
	81	* @return pointer to a copy of the object
	82	*/
	83	virtual TrackSequenceIterator *clone() const = 0;
	84
	85	/**
	86	* This function is called by the TrackSequenceManager when current() returns
	87	* 0, if the TrackSequenceManager has a playlist defined. This function
	88	* should choose an appropriate starting track and set it as the current
	89	* item. This function must be reimplemented in subclasses.
	90	*
	91	* @param playlist the playlist to iterate over
	92	*/
	93	virtual void prepareToPlay(Playlist *playlist) = 0;
	94
	95	/**
1510 by Michael Pyne Big huge update.	96	* This function is called whenever the current playlist changes, such as
	97	* having a new search applied, items added/removed, etc. If you need to
	98	* update internal state, you should do so without affecting the current
	99	* playing item. Default implementation does nothing.
	100	*/
	101	virtual void playlistChanged();
	102
	103	/**
	104	* This function is called by the manager when \p item is about to be
	105	* removed. Subclasses should ensure that they're not still holding a
	106	* pointer to the item. The default implementation does nothing.
	107	*
	108	* @param item the item about to be removed.
	109	*/
	110	virtual void itemAboutToDie(const PlaylistItem *item);
	111
	112	/**
1170 by Michael Pyne OK, here it is. This commit introduces a new feature to JuK, the upcoming	113	* This function is called by the TrackSequenceManager is some situations,
	114	* such as when playback is being stopped. If you subclass needs to reset
	115	* any internal data members, do so in this function. This function must
	116	* be reimplemented in subclasses.
	117	*/
	118	virtual void reset() = 0;
	119
	120	/**
	121	* This function is a public mutator to set the current item.
	122	*
	123	* @param current the new current item
	124	*/
	125	virtual void setCurrent(PlaylistItem *current);
	126
	127	private:
1453 by Scott Wheeler Add a Pointer type to the PlaylistItem class with guarded pointer semantics.	128	PlaylistItem::Pointer m_current; ///< the current item
1170 by Michael Pyne OK, here it is. This commit introduces a new feature to JuK, the upcoming	129	};
	130
	131	/**
	132	* This is the default iterator for JuK, supporting normal, random, and album
	133	* random playback with or without looping.
	134	*
	135	* @author Michael Pyne <michael.pyne@kdemail.net>
	136	*/
	137	class DefaultSequenceIterator : public TrackSequenceIterator
	138	{
	139	public:
	140	/**
	141	* Default constructor.
	142	*/
	143	DefaultSequenceIterator();
	144
	145	/**
	146	* Default copy constructor.
	147	*
	148	* @param other the DefaultSequenceIterator to copy.
	149	*/
	150	DefaultSequenceIterator(const DefaultSequenceIterator &other);
	151
	152	/**
	153	* Default destructor.
	154	*/
	155	virtual ~DefaultSequenceIterator();
	156
	157	/**
	158	* This function advances to the next item in the current sequence. The
	159	* algorithm used depends on what playback mode is selected.
	160	*/
	161	virtual void advance();
	162
	163	/**
	164	* This function moves to the previous item in the playlist. This occurs
	165	* no matter what playback mode is selected.
	166	*/
	167	virtual void backup();
	168
	169	/**
	170	* This function prepares the class for iterator. If no random play mode
	171	* is selected, the first item in the given playlist is the starting item.
	172	* Otherwise, an item is randomly picked to be the starting item.
	173	*
	174	* @param playlist The playlist to initialize for.
	175	*/
	176	virtual void prepareToPlay(Playlist *playlist);
	177
	178	/**
	179	* This function clears all internal state, including any random play lists,
	180	* and what the current album is.
	181	*/
	182	virtual void reset();
	183
	184	/**
1510 by Michael Pyne Big huge update.	185	* This function recalculates the random lists, and is should be called
	186	* whenever its current playlist changes (at least for searches).
	187	*/
	188	virtual void playlistChanged();
	189
	190	/**
	191	* Called when \p item is about to be removed. This function ensures that
	192	* it isn't remaining in the random play list.
	193	*/
	194	virtual void itemAboutToDie(const PlaylistItem *item);
	195
	196	/**
1170 by Michael Pyne OK, here it is. This commit introduces a new feature to JuK, the upcoming	197	* This function sets the current item, and initializes any internal lists
	198	* that may be needed for playback.
	199	*
	200	* @param current The new current item.
	201	*/
	202	virtual void setCurrent(PlaylistItem *current);
	203
	204	/**
	205	* This function returns a perfect copy of the object it is called on, to
	206	* get around the C++ slicing problem.
	207	*
	208	* @return A copy of the object the method is called on.
	209	*/
	210	virtual DefaultSequenceIterator *clone() const;
	211
	212	private:
1553 by Scott Wheeler Since 3.5 devel seems to have mostly slowed down, I'm synching with the branch	213
	214	/**
	215	* Reinitializes the internal random play list based on the playlist given
	216	* by \p p. The currently playing item, if any, is automatically removed
	217	* from the list.
	218	*
	219	* @param p The Playlist to read items from. If p is 0, the playlist of
	220	* the currently playing item is used instead.
	221	*/
	222	void refillRandomList(Playlist *p = 0);
1170 by Michael Pyne OK, here it is. This commit introduces a new feature to JuK, the upcoming	223	void initAlbumSearch(PlaylistItem *searchItem);
	224
	225	private:
	226	PlaylistItemList m_randomItems;
	227	PlaylistSearch m_albumSearch;
	228	};
	229
1564 by Michael Pyne Also standardize all of the JuK include header guards, to the most common style to save me	230	#endif /* TRACKSEQUENCEITERATOR_H */
1170 by Michael Pyne OK, here it is. This commit introduces a new feature to JuK, the upcoming	231
1562 by Michael Pyne Since we're standardizing the source style, figured I'd throw in the Big Huge Vim Modeline	232	// vim: set et sw=4 tw=0 sta: