ocarina/include/core/queue.h

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

extern "C" {
#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.                */
};


/**
 * 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 {
	compare_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() << ...;
 */
struct queue {
	unsigned int q_cur;    /* The queue's last-played index.          */
	unsigned int q_flags;  /* The queue's set of flags.               */
	unsigned int q_length; /* The queue's total runtime (in seconds). */
	QNotifier   *q_notify; /* The queue's notification functions.     */

	std :: vector <struct track *> q_tracks; /* The queue's list of tracks. */
	std :: vector <struct sort_info> q_sort; /* The queue's sort settings.  */

	unsigned int find_sorted_id(struct track *);
	unsigned int _add_at(struct track *, unsigned int);


	/**
	 * 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);


	/**
	 * 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(struct 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(struct track *);

	/**
	 * Signal to the queue that a track has been updated.
	 *
	 * @param  track  The track that has been modified.
	 */
	void updated(struct 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.
	 */
	struct track *next();


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


	/**
	 * 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(compare_t, bool);

	/**
	 * Access a track by index.
	 *
	 * @param  index  The index to look up.
	 * @return  The track found at the requested index.
	 */
	struct 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 */