Design: Various updates

Add more to the Library, Playlist and Audio design to match how I expect
the GUI to use the backend.

Signed-off-by: Anna Schumaker <schumaker.anna@gmail.com>

design/audio.txt

@@ -5,7 +5,7 @@
 		audio.cpp
 
 == Depends ==
-playlist
+playlist library
 
 Audio: (lib/audio.cpp)
 	This file will introduce an "audio" namespace containing all of the
@@ -15,7 +15,9 @@ Audio: (lib/audio.cpp)
 
 	The audio layer will also control the "pause after N tracks" feature
 	so songs can be loaded without neeting to pass in a "begin playback"
-	flag every time.
+	flag every time.  The remaining tracks counter will only be decremented
+	when a song finishes through the end-of-stream message passed by the
+	gst pipeline.
 
 - Internal:
 	Set up a message bus to look for end-of-stream and error messages so
@@ -24,32 +26,47 @@ Audio: (lib/audio.cpp)
 	count.
 
 - API:
-	audio :: init(argc, argv)
+	void audio :: init(argc, argv)
 		Initialize the gstreamer layer and reload the track that was
 		last loaded before shutdown.  Please only pass --gst-* options
 		for argv.
 
-	audio :: load_file(filepath)
-		Loads a file path but does not begin playback.
+	void audio :: play()
+		Begin or resume playback.
 
-	audio :: play()
-		Begin playback
+	void audio :: pause()
+		Pause playback.
 
-	audio :: pause()
-		Pause playback
-
-	audio :: seek_to(X)
+	void audio :: seek_to(int)
 		Seek to a position X seconds into the track
 
-	audio :: stop()
+	void audio :: stop()
 		pause()
 		seek_to(0)
 
-	audio :: pause_after(N)
+	void audio :: next()
+		Call the playlist :: next() function to get the next trackid,
+		and load that file into the gstreamer pipeline.  Do not change
+		the state of the pipeline (if nothing is playing yet, don't
+		call play()).
+
+	void audio :: previous()
+		Call the playlist :: previous() function to iterate backwards
+		through the recently played playlist. Load the returned trackid
+		without changing the pipeline state.
+
+	trackid audio :: current_trackid()
+		Return the trackid of the currently playing song.
+
+	unsigned int audio :: position()
+		Return the number of seconds that the song has played.
+
+	unsigned int audio :: duration()
+		Return the duration of the current song in seconds.
+
+	void audio :: pause_after(unsigned int)
 		Pause after N tracks, pass a negative number to disable.
 
-	audio :: position()
-		Return the number of seconds that the song has played
-
-	audio :: duration()
-		Return the duration of the current song in seconds
+	unsigned int audio :: pause_count()
+		Return the number of tracks that will be played before
+		playback pauses.

design/footer.txt

@@ -77,3 +77,7 @@ Future work:
 	- Extra testing ideas: (6.1)
 		- Run tests through valgrind to help find memory leaks
 		- Combine earlier tests into a single file
+
+	- Exceptions: (6.1)
+		- Don't return error codes, throw exceptions like C++ is
+		  designed to do.

design/library.txt

@@ -92,8 +92,8 @@ Library: (lib/library.cpp)
 	File << title << endl;
 	File << filepath << endl;
 
-- Track: /* This struct lies outside the library namespace */
-	struct Track {
+- Song:
+	struct Song {
 		library :: Album   *album;
 		library :: Artist  *artist;
 		library :: Genre   *genre;
@@ -153,8 +153,8 @@ Library: (lib/library.cpp)
 	void library :: update_path(lib_id);
 		Update the given library_db row, if valid.
 
-	struct Track library :: lookup(track_id)
-		Fill out a Track structure for the provided track_id
+	struct Song library :: lookup(track_id)
+		Fill out a Song structure for the provided track_id
 
 #ifdef CONFIG_DEBUG
 	void library :: print_db(DB_Type);

design/playlist.txt

@@ -84,3 +84,85 @@ Playlist: (lib/playlist.cpp)
 	allow for simpler removals, since I won't need to search for a track id.
 	I can easily create a function for mapping a list of playlist_ids to
 	track_ids...
+
+
+
+
+
+
+- API
+	void playlist :: init();
+		Read in the playlist file
+
+*	Playlist *playlist :: add();
+		Add a new playlist to the deck, return the created playlist
+		to the caller.
+
+*	void playlist :: remove(Playlist *);
+		Remove the provided playlist from the deck.  The pointer will
+		be unusable after calling this function.
+
+	void playlist :: move(Playlist *, unsigned int);
+		Move the playlist to the provided location in the deck.
+
+*	trackid_t playlist :: next()
+		Return the next trackid from the top playlist on the playlist
+		deck (id = deck[0].next()).  If the top playlist is now empty,
+		remove it.
+
+	void playlist :: prev()
+		Keep a playlist :: Playlist recent(PL_ENABLED)
+		Whenever next() is called, add the returned track to the front
+		of this playlist, reset recent.cur to 0.
+		When prev() is called, return recent.next();
+
+	trackid_t playlist :: Playlist :: next()
+		If PL_RANDOM is set:
+			Randomly pick a value between 1 and size().  Increment
+			the cur pointer by this value, taking into account any
+			roll over.
+		Else:
+			cur += 1, if cur == size(): cur = 0;
+
+		if PL_DRAIN is set:
+			Remove the trackid pointed to by cur from the list and
+			return its value.
+
+		return list[cur]
+
+	void playlist :: Playlist :: set_flag(flag);
+		Set the user-requested flag
+
+	void playlist :: Playlist :: clear_flag(flag);
+		Clear the user-requested flag
+
+	const unsigned int playlist :: Playlist :: get_flags();
+		return flags
+
+	bool playlist :: Playlist :: play_row(unsigned int id);
+		Call this fuction to play a song from the playlist.  id matches
+		up to the index in the playlist to play.  Return true if the
+		selected row should be removed from the playlist, false
+		otherwise.
+
+	string playlist :: Playlist :: get_length()
+		Calculate the length of the playlist and return a string
+		in mm:ss format with the results.
+
+	unsigned int playlist :: Playlist :: size()
+		Return the number of tracks in your playlist
+
+	unsigned int playlist :: Playlist :: current_index()
+		Return the current index into the playlist
+
+	unsigned int playlist :: Playlist :: filter(string text)
+		Set the current filter text
+
+	unsigned int playlist :: Playlist :: is_visible(id)
+		Check if the playlist id is visible based on playlis text
+
+*	unsigned int playlist :: Playlist :: add_track(trackid_t)
+		Add a new track to the playlist
+
+*	unsigned int playlist :: Playlist :: rm_track(playlistid_t)
+		Remove a row from the playlist