rb-play-order

rb-play-order — base class for play order implementations

Synopsis

                    RBPlayOrder;
                    RBPlayOrderClass;
void                rb_play_order_playing_source_changed
                                                        (RBPlayOrder *porder,
                                                         RBSource *source);
void                rb_play_order_query_model_changed   (RBPlayOrder *porder);
gboolean            rb_play_order_has_next              (RBPlayOrder *porder);
RhythmDBEntry*      rb_play_order_get_next              (RBPlayOrder *porder);
void                rb_play_order_go_next               (RBPlayOrder *porder);
gboolean            rb_play_order_has_previous          (RBPlayOrder *porder);
RhythmDBEntry*      rb_play_order_get_previous          (RBPlayOrder *porder);
void                rb_play_order_go_previous           (RBPlayOrder *porder);
void                rb_play_order_set_playing_entry     (RBPlayOrder *porder,
                                                         RhythmDBEntry *entry);
RhythmDBEntry*      rb_play_order_get_playing_entry     (RBPlayOrder *porder);
RBShellPlayer*      rb_play_order_get_player            (RBPlayOrder *porder);
RBSource*           rb_play_order_get_source            (RBPlayOrder *porder);
RhythmDB*           rb_play_order_get_db                (RBPlayOrder *porder);
RhythmDBQueryModel* rb_play_order_get_query_model       (RBPlayOrder *porder);
gboolean            rb_play_order_model_not_empty       (RBPlayOrder *porder);

Object Hierarchy

  GObject
   +----RBPlayOrder
         +----RBRandomPlayOrder

Properties

  "player"                   RBShellPlayer*        : Read / Write / Construct Only
  "playing-entry"            RhythmDBEntry*        : Read / Write

Signals

  "have-next-previous-changed"                     : Run Last

Description

A play order defines an ordering of the entries from a RhythmDBQueryModel that the RBShellPlayer uses to get the next or previous entry to play.

Play order methods are invoked when changes are made to the query model, when the query model is replaced, the playing source is changed, or a new playing entry is selected.

The play order must implement methods to check for, retrieve, and move to the next and previous entries in the play order. Only the go_next and go_previous methods actually change anything.

The play order should also emit the have-next-previous-changed signal to hint that the availability of either a next or previous entry in the order may have changed. This information is used to update the sensitivity of the next and previous buttons.

Details

RBPlayOrder

typedef struct _RBPlayOrder RBPlayOrder;


RBPlayOrderClass

typedef struct {
	GObjectClass parent_class;

	/* EVENTS */
	void (*playing_source_changed) (RBPlayOrder *porder);
	void (*db_changed) (RBPlayOrder *porder, RhythmDB *new_db);
	void (*playing_entry_changed) (RBPlayOrder *porder, RhythmDBEntry *old_entry, RhythmDBEntry *new_entry);
	void (*entry_added) (RBPlayOrder *porder, RhythmDBEntry *entry);
	void (*entry_removed) (RBPlayOrder *porder, RhythmDBEntry *entry);
	void (*query_model_changed) (RBPlayOrder *porder);
	void (*db_entry_deleted) (RBPlayOrder *porder, RhythmDBEntry *entry);
	void (*playing_entry_removed) (RBPlayOrder *porder, RhythmDBEntry *entry);

	/* QUERIES */
	/*
	 * Returns whether there is a next song. This controls the next
	 * button's sensitivity. If not implemented, defaults to
	 * get_next()!=NULL.
	 *
	 * Must not change any visible state.
	 */
	gboolean (*has_next) (RBPlayOrder* porder);
	/*
	 * get_next() must return the next song to play. It's called when a
	 * song finishes, when the user clicks the next button, and when the
	 * user clicks play after playback is stopped.
	 *
	 * get_next() is also used to find the first song. You can figure out
	 * whether the player is currently playing by calling
	 * rb_play_order_player_is_playing(porder).
	 *
	 * Must not change any visible state.
	 */
	RhythmDBEntry* (*get_next) (RBPlayOrder* porder);
	/*
	 * Tells the play order that the user has moved to the next song.
	 * Should be called before the EntryView::playing-entry property is
	 * changed.
	 */
	void (*go_next) (RBPlayOrder* porder);
	/*
	 * Returns whether there is a previous song. This controls the previous
	 * button's sensitivity. If not implemented, defaults to
	 * get_previous()!=NULL.
	 *
	 * Must not change any visible state.
	 */
	gboolean (*has_previous) (RBPlayOrder* porder);
	/*
	 * get_previous() must return the previous song to play. It's called
	 * when the user clicks the previous button within 2 seconds of the
	 * beginning of a song.
	 *
	 * Must not change any visible state.
	 */
	RhythmDBEntry* (*get_previous) (RBPlayOrder* porder);
	/*
	 * Tells the play order that the user has moved to the previous song.
	 * Should be called before the EntryView::playing-entry property is
	 * changed.
	 */
	void (*go_previous) (RBPlayOrder* porder);

	/* SIGNALS */
	void (*have_next_previous_changed) (RBPlayOrder *porder, gboolean have_next, gboolean have_previous);
} RBPlayOrderClass;


rb_play_order_playing_source_changed ()

void                rb_play_order_playing_source_changed
                                                        (RBPlayOrder *porder,
                                                         RBSource *source);

Sets the playing RBSource for the play order. Should be called by RBShellPlayer when the active source changes. Subclasses should implement playing_source_changed() to make any necessary changes.

porder :

RBPlayOrder instance

source :

New playing RBSource

rb_play_order_query_model_changed ()

void                rb_play_order_query_model_changed   (RBPlayOrder *porder);

Updates the RhythmDBQueryModel instance for the play order. Called from the RBSource notify signal handler, and also from rb_play_order_source_changed. Subclasses should implement query_model_changed() to make any necessary adjustments if they store any state based on the contents of the RhythmDBQueryModel.

porder :

RBPlayOrder instance

rb_play_order_has_next ()

gboolean            rb_play_order_has_next              (RBPlayOrder *porder);

If there is no current playing entry, returns true if the play order is non-empty.

porder :

RBPlayOrder instance.

Returns :

true if there is an entry after the current playing entry in the play order.

rb_play_order_get_next ()

RhythmDBEntry*      rb_play_order_get_next              (RBPlayOrder *porder);

porder :

RBPlayOrder instance

Returns :

the next entry in the play order, or the first if not currently playing.

rb_play_order_go_next ()

void                rb_play_order_go_next               (RBPlayOrder *porder);

Moves to the next entry in the play order. If not currently playing, sets the first entry in the play order as the playing entry.

porder :

RBPlayOrder instance

rb_play_order_has_previous ()

gboolean            rb_play_order_has_previous          (RBPlayOrder *porder);

porder :

RBPlayOrder instance

Returns :

true if there is an entry before the current entry in the play order. If not currently playing, returns false.

rb_play_order_get_previous ()

RhythmDBEntry*      rb_play_order_get_previous          (RBPlayOrder *porder);

porder :

RBPlayOrder instance

Returns :

the previous entry in the play order, or NULL if not currently playing.

rb_play_order_go_previous ()

void                rb_play_order_go_previous           (RBPlayOrder *porder);

Moves to the previous entry in the play order. If not currently playing, does nothing.

porder :

RBPlayOrder instance

rb_play_order_set_playing_entry ()

void                rb_play_order_set_playing_entry     (RBPlayOrder *porder,
                                                         RhythmDBEntry *entry);

Sets the playing entry in the play order.

porder :

RBPlayOrder instance

entry :

The new playing entry (or NULL for none)

rb_play_order_get_playing_entry ()

RhythmDBEntry*      rb_play_order_get_playing_entry     (RBPlayOrder *porder);

porder :

RBPlayOrder instance

Returns :

the current playing entry in the play order.

rb_play_order_get_player ()

RBShellPlayer*      rb_play_order_get_player            (RBPlayOrder *porder);

Only for use by RBPlayOrder subclasses.

porder :

RBPlayOrder instance

Returns :

RBShellPlayer instance

rb_play_order_get_source ()

RBSource*           rb_play_order_get_source            (RBPlayOrder *porder);

Only for use by RBPlayOrder subclasses.

porder :

RBPlayOrder instance

Returns :

the playing RBSource instance.

rb_play_order_get_db ()

RhythmDB*           rb_play_order_get_db                (RBPlayOrder *porder);

Only for use by RBPlayOrder subclasses.

porder :

RBPlayOrder instance

Returns :

the RhythmDB instance.

rb_play_order_get_query_model ()

RhythmDBQueryModel* rb_play_order_get_query_model       (RBPlayOrder *porder);

Only for use by RBPlayOrder subclasses.

porder :

RBPlayOrder instance

Returns :

the active RhythmDBQueryModel for the playing source.

rb_play_order_model_not_empty ()

gboolean            rb_play_order_model_not_empty       (RBPlayOrder *porder);

porder :

RBPlayOrder instance

Returns :

true if the RhythmDBQueryModel is not empty. Can be used to implement has_next and has_previous for play orders that have no beginning or end.

Property Details

The "player" property

  "player"                   RBShellPlayer*        : Read / Write / Construct Only

The RBShellPlayer instance


The "playing-entry" property

  "playing-entry"            RhythmDBEntry*        : Read / Write

The current playing RhythmDBEntry

Signal Details

The "have-next-previous-changed" signal

void                user_function                      (RBPlayOrder *porder,
                                                        gboolean     have_next,
                                                        gboolean     have_previous,
                                                        gpointer     user_data)          : Run Last

Emitted as a hint to suggest that the sensitivity of next/previous buttons may need to be updated.

porder :

the RBPlayOrder

have_next :

if TRUE, the play order has at least one more entry

have_previous :

if TRUE, the play order has at least one entry before the current entry

user_data :

user data set when the signal handler was connected.