anna
/
ocarina
1
0
Fork 0
Code Issues 7 Pull Requests Releases Wiki Activity

Queue: Update doxygen documentation 

I also remove the related section of the DESIGN document.

Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>
This commit is contained in:
Anna Schumaker 2014-12-09 08:39:04 -05:00
parent 6f58813b3c
commit 39eb22f05c
4 changed files with 80 additions and 214 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
DESIGN
View File

@ -66,162 +66,6 @@ Callbacks:
Queue:
Queues are lists of songs that the user has requested to play. They
are the main interface for all music played by Ocarina.
- Flags:
enum queue_flag {
Q_ENABLED (1 << 0),
Q_RANDOM (1 << 1),
Q_REPEAT (1 << 2),
Q_NO_SORT (1 << 3),
};
- Sorting:
enum sort_t {
SORT_ARTIST,
SORT_ALBUM,
SORT_COUNT,
SORT_GENRE,
SORT_LENGTH,
SORT_PLAYED,
SORT_TITLE,
SORT_TRACK,
SORT_YEAR,
};
- Sort info:
struct sort_info {
sort_t field;
bool ascending;
};
- Sorting:
Sorting is done using std::stable_sort() to make sure that orders won't
change unexpectedly.
- Queue:
class Queue {
protected:
vector<Track *> _tracks;
list<sort_t> _sort_order;
unsigned int _cur;
unsigned int _flags;
unsigned int _length;
public:
Queue();
Queue(unsigned int);
void read(File &);
void write(File &);
void set_flag(queue_flag);
void unset_flag(queue_flag);
bool has_flag(queue_flag);
unsigned int add(Track *);
void del(Track *);
void del(unsigned int);
void updated(Track *);
Track *next();
unsigned int size();
const std::string size_str();
const std::string length_str();
void sort(sort_t, bool);
Track *operator[](unsigned int);
void track_selected(unsigned int);
};
File Format:
File << flags << tracks.size() << tracks[0] << tracks[1] << ... << tracks[N];
- API
Queue :: Queue();
Initialize _flags = 0, _cur = -1, _length = 0, and empty sort
order.
Queue :: Queue(unsigned int flags);
Initialize _flags = flags, _cur = -1, _length = 0, and empty
sort order.
void Queue :: read(File &f);
Read queue from file.
void Queue :: write(File &f);
Write queue to file.
void Queue :: set_flag(queue_flag f);
Set the appropriate flag.
void Queue :: unset_flag(queue_flag f);
Unset the appropriate flag.
bool Queue :: has_flag(queue_flag f);
Return true if the queue has the flag enabled and false
otherwise.
unsigned int Queue :: add(Track *track);
Add a new track to the tracks vector and return the index.
Increase length by the length of the track.
void Queue :: del(Track *track);
Remove all instances of the requested track from the queue.
void Queue :: del(unsigned int queue_id);
Remove the track at the given index from the queue.
void Queue :: updated(Track *track);
Find all indexes of the updated track and notify the UI that
it has changed.
Track *Queue :: next();
Return the next track to play.
if (tracks.size() == 0)
return NULL;
if (flags & PL_RANDOM):
_cur += rand() % tracks.size();
else:
_cur += 1;
if (_cur >= tracks.size())
_cur -= tracks.size();
track = tracks[_cur];
if (!(flags & PL_REPEAT)):
del(_cur);
return track;
unsigned int Queue :: size();
Return the number of tracks currently on the queue.
const std::string Queue :: size_str();
Return the number of tracks currently on the queue, in string
form.
const std::string Queue :: length_str();
Return the remaining length of the queue in a human-readable
format.
void Queue :: sort(sort_t field, bool reset);
If the field is already in the sort order, toggle its
ascending value. Otherwise, add a new sort field to the end
of the sort order with ascending set to true. If reset is set
to true, clear the sorting list before appending.
Track *Queue :: operator[](unsigned int i);
Return the track and index i.
void Queue :: track_selected(unsigned int queue_id);
Set _cur to queue_id. If PQ_REPEAT is not set, remove the
track from the queue.
Library:
The library is in charge of scanning and updating library paths added
to the tag database. In addition, the library layer is also in charge

54
core/queue.cpp
View File

@ -13,52 +13,50 @@
#define O_HOURS (60 * O_MINUTES)
#define O_DAYS (24 * O_HOURS)
Queue :: Queue()
: _cur(-1), _flags(0), _length(0)
{
}
Queue :: Queue(unsigned int f)
: _cur(-1), _flags(f), _length(0)
{
}
Queue :: Queue(unsigned int flags)
: _cur(-1), _flags(flags), _length(0)
{}
Queue :: Queue()
: _cur(-1), _flags(0), _length(0)
{}
Queue :: ~Queue()
{
}
{}
void Queue :: write(File &f)
void Queue :: write(File &file)
{
f << _flags << " " << _tracks.size();
file << _flags << " " << _tracks.size();
for (unsigned int i = 0; i < _tracks.size(); i++)
f << " " << _tracks[i]->index();
file << " " << _tracks[i]->index();
}
void Queue :: read(File &f)
void Queue :: read(File &file)
{
unsigned int n, id;
f >> _flags >> n;
file >> _flags >> n;
_tracks.resize(n);
for (unsigned int i = 0; i < n; i++) {
f >> id;
file >> id;
_tracks[i] = tags :: get_track(id);
_length += _tracks[i]->length();
}
}
void Queue :: set_flag(queue_flags f)
void Queue :: set_flag(queue_flags flag)
{
_flags |= f;
_flags |= flag;
}
void Queue :: unset_flag(queue_flags f)
void Queue :: unset_flag(queue_flags flag)
{
_flags &= ~f;
_flags &= ~flag;
}
bool Queue :: has_flag(queue_flags f)
bool Queue :: has_flag(queue_flags flag)
{
return (_flags & f) == (unsigned int)f;
return (_flags & flag) == (unsigned int)flag;
}
/*
@ -167,9 +165,9 @@ void Queue :: del(Track *track)
}
}
void Queue :: del(unsigned int id)
void Queue :: del(unsigned int index)
{
_del_at(_tracks[id], id);
_del_at(_tracks[index], index);
}
void Queue :: updated(Track *track)
@ -274,14 +272,14 @@ void Queue :: sort(sort_t field, bool reset)
get_callbacks()->on_queue_track_changed(this, i);
}
Track *Queue :: operator[](unsigned int i)
Track *Queue :: operator[](unsigned int index)
{
return _tracks[i];
return _tracks[index];
}
void Queue :: track_selected(unsigned int id)
void Queue :: track_selected(unsigned int index)
{
_cur = id;
_cur = index;
if (has_flag(Q_REPEAT) == false) {
del(_cur);
_cur--;

81
include/core/queue.h
View File

@ -49,15 +49,21 @@ struct sort_info {
/**
* Class defining playback queues.
* 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;
std :: vector <struct sort_info> _sort_order;
unsigned int _cur;
unsigned int _flags;
unsigned int _length;
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. */
unsigned int find_sorted_id(Track *);
unsigned int _add_at(Track *, unsigned int);
@ -65,56 +71,57 @@ protected:
public:
/**
* Default queue constructor.
*/
Queue();
/**
* Alternat queue constructor.
* @param f Create a queue with flags set to f.
* Alternate queue constructor.
*
* @param flags Create a queue with _flags set to flags.
*/
Queue(unsigned int);
/**
* Queue destructor.
*/
~Queue();
Queue(); /**< Default queue constructor. */
~Queue(); /**< Queue destructor. */
/**
* Write a queue to disk.
* @param f File queue data will be written to.
*
* @param file File that Queue data will be written to.
*/
void write(File &);
/**
* Read a queue from disk.
* @param f File to read queue data from.
*
* @param file File to read Queue data from.
*/
void read(File &);
/**
* Set a queue flag.
* @param f queue_flag to set.
*
* @param flag queue_flag to set.
*/
virtual void set_flag(queue_flags);
/**
* Clear a queue flag.
* @param f queue_flag to clear.
*
* @param flag queue_flag to clear.
*/
virtual void unset_flag(queue_flags);
/**
* Check if a queue has a specific flag set.
* @param f queue_flag to check.
* @return true if queue_flag is 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.
* 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.
*/
@ -122,50 +129,65 @@ public:
/**
* Remove all instances of a track from the queue.
*
* @param track Track to remove from the queue.
*/
virtual void del(Track *);
/**
* Remove a track based on its queue index.
*
* @param index Track index to remove from the queue.
*/
virtual void del(unsigned int);
/**
* 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.
* @return The next Track on the queue.
* 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 size of the queue, as a string.
*
* @return The number of tracks on the queue, in string form.
*/
const std::string size_str();
/**
* Find the runtime of the queue.
*
* @return The runtime of the queue, as a string.
*/
const std::string length_str();
/**
* Add a new parameter for sorting the queue.
* 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.
*/
@ -173,6 +195,7 @@ public:
/**
* Access a track by index.
*
* @param index The index to look up.
* @return The track found at the requested index.
*/
@ -180,7 +203,9 @@ public:
/**
* Tell the queue that a track has been selected for playback without
* calling Queue :: next().
* 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);

3
tests/core/queue.cpp
View File

@ -15,8 +15,7 @@ unsigned int last_update = 0;
Track *TRACK_NULL = NULL;
class TestQueue : public Queue
{
class TestQueue : public Queue {
public:
TestQueue() : Queue() {}
TestQueue(unsigned int f) : Queue(f) {}