ocarina/include/core/queue.h

/**
 * Copyright 2013 (c) Anna Schumaker.
 */
#ifndef OCARINA_CORE_QUEUE_H
#define OCARINA_CORE_QUEUE_H

#include <core/file.h>
#include <core/tags/track.h>

#include <vector>
#include <list>


/**
 * Enum defining flags that effect a Queue's behavior.
 */
enum queue_flags {
	Q_ENABLED = (1 << 0),	/**< Queue is enabled.                        */
	Q_RANDOM  = (1 << 1),	/**< Queue will pick songs randomly.          */
	Q_REPEAT  = (1 << 2),	/**< Queue will not remove songs when picked. */
	Q_NO_SORT = (1 << 3),	/**< Queue will not be sorted.                */
};


/**
 * Track fields that can be compared.
 */
enum sort_t {
	SORT_ARTIST,	/**< Sort tracks by Artist name.      */
	SORT_ALBUM,	/**< Sort tracks by Album name.       */
	SORT_COUNT,	/**< Sort tracks by Play count.       */
	SORT_GENRE,	/**< Sort tracks by Genre.            */
	SORT_LENGTH,	/**< Sort tracks by Track length.     */
	SORT_PLAYED,	/**< Sort tracks by last played date. */
	SORT_TITLE,	/**< Sort tracks by Track title.      */
	SORT_TRACK,	/**< Sort tracks by Track number.     */
	SORT_YEAR,	/**< Sort tracks by Track year.       */
};



/**
 * Class to assist in notifying the GUI of queue changes.
 */
class QNotifier {
public:
	QNotifier() {}; /**< Notifier constructor. */

	/**
	 * Called when a track is added to a queue.
	 *
	 * @param  pos  Position in the queue that the track was added.
	 */
	virtual void on_track_added(unsigned int) = 0;

	/**
	 * Called when a track is removed from a queue.
	 *
	 * @param  pos  Position in the queue that the track was removed from.
	 */
	virtual void on_track_removed(unsigned int) = 0;

	/**
	 * Called when a track has been updated.
	 *
	 * @param  pos  Position in the queue of the updated track.
	 */
	virtual void on_track_updated(unsigned int) = 0;
};


/**
 * Struct for passing sort parameters.
 */
struct sort_info {
	sort_t field;
	bool   ascending;
};


/**
 * Queues are lists of songs that the user has requested to play next,
 * although not necessarily in a specific order.
 *
 * When writing a Queue to disk: write out the _flags and size values
 * first, followed by the list of track indexes.
 *
 * 	... << _flags << _tracks.size() << tracks[N]->index() << ...;
 */
class Queue {
protected:
	std :: vector <Track *> _tracks; /**< List of tracks in this queue. */
	std :: vector <struct sort_info> _sort_order; /**< Current sort settings. */
	unsigned int _cur;	/**< The index of the last track played. */
	unsigned int _flags;	/**< Mask of queue_flags. */
	unsigned int _length;	/**< Total runtime of the queue. */
	QNotifier   *_notify;	/**< Notification object associated with this queue. */

	unsigned int find_sorted_id(Track *);
	unsigned int _add_at(Track *, unsigned int);

public:
	/**
	 * Alternate queue constructor.
	 *
	 * @param  flags  Create a queue with _flags set to flags.
	 */
	Queue(unsigned int);

	Queue();          /**< Default queue constructor. */
	virtual ~Queue(); /**< Queue destructor.          */

	/**
	 * Write a queue to disk.
	 *
	 * @param  file  File that Queue data will be written to.
	 */
	void write(File &);

	/**
	 * Read a queue from disk.
	 *
	 * @param  file  File to read Queue data from.
	 */
	void read(File &);


	/**
	 * Set a queue flag.
	 *
	 * @param  flag  queue_flag to set.
	 */
	virtual void set_flag(queue_flags);

	/**
	 * Clear a queue flag.
	 *
	 * @param  flag  queue_flag to clear.
	 */
	virtual void unset_flag(queue_flags);

	/**
	 * Check if a queue has a specific flag set.
	 *
	 * @param  flag  queue_flag to check.
	 * @return true if queue_flag is set and false otherwise.
	 */
	bool has_flag(queue_flags);


	/**
	 * Set a notifier for this queue.
	 *
	 * @param  notify  notifier instance to associate with this queue.
	 */
	void set_notifier(QNotifier *);


	/**
	 * Add a track to the queue, possibly matching the
	 * current sort order.
	 *
	 * @param  track  Track to add to the queue.
	 * @return The index of the track in the queue.
	 */
	virtual unsigned int add(Track *);

	/**
	 * Remove a track based on its queue index.
	 *
	 * @param  index  Track index to remove from the queue.
	 */
	virtual void del(unsigned int);

	/**
	 * Remove all instances of a track from the queue.
	 *
	 * @param  track Track to remove from the queue.
	 */
	virtual void del(Track *);

	/**
	 * Signal to the queue that a track has been updated.
	 *
	 * @param  track  The track that has been modified.
	 */
	void updated(Track *);

	/**
	 * Pick the next track from the queue.  If Q_RANDOM is set then a
	 * random Track will be returned, otherwise _cur will be incremented
	 * and used to pick the next Track.  If Q_REPEAT is not set then
	 * the chosen track will be removed from the queue.
	 *
	 * @return The next Track on the queue, or NULL if the Queue is empty.
	 */
	Track *next();


	/**
	 * Find the size of the queue.
	 *
	 * @return The number of tracks on the queue.
	 */
	unsigned int size();

	/**
	 * Find the runtime of the queue.
	 *
	 * @return The runtime of the queue.
	 */
	unsigned int length();


	/**
	 * Add a new sort field to the queue.  If the field is already in the
	 * _sort_order then it's ascending  or descending value will be toggled.
	 *
	 * If reset is set to True then the _sort_order will be cleared before
	 * adding the new value.
	 *
	 * @param  field  Field to sort by.
	 * @param  reset  Set to true if current sort data should be discarded.
	 */
	virtual void sort(sort_t, bool);

	/**
	 * Access a track by index.
	 *
	 * @param  index  The index to look up.
	 * @return  The track found at the requested index.
	 */
	Track *operator[](unsigned int);

	/**
	 * Tell the queue that a track has been selected for playback without
	 * calling Queue :: next().  If Q_REPEAT is not set then the Track
	 * will be removed from the queue.
	 *
	 * @param  index  The index that is now playing.
	 */
	void track_selected(unsigned int);
};

#endif /* OCARINA_CORE_QUEUE_H */