## 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.