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.                */
	Q_SAVE_FLAGS = (1 << 4), /* Queue will be saved when flags change.   */
	Q_SAVE_SORT  = (1 << 5), /* Queue will be saved when 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 queue_ops {
	/* Called to have a higher layer save the queue. */
	void (*qop_save)(struct queue *, enum queue_flags);
};


/**
 * 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.  */

	const struct queue_ops *q_ops; /* The queue's operations vector. */

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


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


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


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


/* Called to initialize a queue. */
void queue_init(struct queue *, unsigned int, const struct queue_ops *);


/* Called to check if the queue has a specific flag set. */
static inline bool queue_has_flag(struct queue *queue, enum queue_flags flag)
{
	return (queue->q_flags & flag) == (unsigned int)flag;
}

/* Called to find the size of the queue. */
static inline unsigned int queue_size(struct queue *queue)
{
	return queue->q_tracks.size();
}

/* Called to access the queued track at a given index. */
static inline struct track *queue_at(struct queue *queue, unsigned int index)
{
	return queue->q_tracks[index];
}


/* Called to tell the queue that a track has been updated. */
void queue_updated(struct queue *, struct track *);


/* Called to tell the queue that a specific index has been selected. */
void queue_selected(struct queue *, unsigned int);

/* Called to pick the next track from the queue. */
struct track *queue_next(struct queue *);

#endif /* OCARINA_CORE_QUEUE_H */