Rhythmbox Development Reference Manual: RBPlayOrder

## RBPlayOrder RBPlayOrder — base class for play order implementations |

## Functions

void | rb_play_order_playing_source_changed ()
void | rb_play_order_query_model_changed ()
gboolean | rb_play_order_has_next ()
RhythmDBEntry * | rb_play_order_get_next ()
void | rb_play_order_go_next ()
gboolean | rb_play_order_has_previous ()
RhythmDBEntry * | rb_play_order_get_previous ()
void | rb_play_order_go_previous ()
void | rb_play_order_set_playing_entry ()
RhythmDBEntry * | rb_play_order_get_playing_entry ()
RBShellPlayer * | rb_play_order_get_player ()
RBSource * | rb_play_order_get_source ()
RhythmDB * | rb_play_order_get_db ()
RhythmDBQueryModel * | rb_play_order_get_query_model ()
gboolean | rb_play_order_model_not_empty ()
gboolean | rb_play_order_player_is_playing ()

## Properties

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

## Signals

void | have-next-previous-changed | Run Last

## Types and Values

struct | RBPlayOrder
struct | RBPlayOrderClass

## Object Hierarchy

        GObject
        ╰── RBPlayOrder
            ╰── RBRandomPlayOrder

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

porder | RBPlayOrder instance |

#### Returns

next entry to play.

[transfer full]

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

#### Parameters

porder | RBPlayOrder instance |

### rb_play_order_has_previous ()

    gboolean
    rb_play_order_has_previous (RBPlayOrder *porder);

Returns `TRUE` if there is an entry before the current entry in the play order. If not currently playing, returns `FALSE`.

#### Parameters

porder | RBPlayOrder instance |

#### Returns

`TRUE` if previous entry exists

### rb_play_order_get_previous ()

    RhythmDBEntry *
    rb_play_order_get_previous (RBPlayOrder *porder);

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

#### Parameters

porder | RBPlayOrder instance |

#### Returns

previous entry.

[transfer full]

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

#### Parameters

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.

#### Parameters

porder | RBPlayOrder instance |
entry | The new playing entry (or NULL for none). | [transfer none][allow-none]

### rb_play_order_get_playing_entry ()

    RhythmDBEntry *
    rb_play_order_get_playing_entry (RBPlayOrder *porder);

Returns the current playing entry in the play order.

#### Parameters

porder | RBPlayOrder instance |

#### Returns

playing entry.

[transfer full]

### rb_play_order_get_player ()

    RBShellPlayer *
    rb_play_order_get_player (RBPlayOrder *porder);

Only for use by RBPlayOrder subclasses.

#### Parameters

porder | RBPlayOrder instance |

#### Returns

RBShellPlayer instance.

[transfer none]

### rb_play_order_get_source ()

    RBSource *
    rb_play_order_get_source (RBPlayOrder *porder);

Only for use by RBPlayOrder subclasses.

#### Parameters

porder | RBPlayOrder instance |

#### Returns

the playing RBSource instance.

[transfer none]

### rb_play_order_get_db ()

    RhythmDB *
    rb_play_order_get_db (RBPlayOrder *porder);

Only for use by RBPlayOrder subclasses.

#### Parameters

porder | RBPlayOrder instance |

#### Returns

the RhythmDB instance.

[transfer none]

### rb_play_order_get_query_model ()

    RhythmDBQueryModel *
    rb_play_order_get_query_model (RBPlayOrder *porder);

Only for use by RBPlayOrder subclasses.

#### Parameters

porder | RBPlayOrder instance |

#### Returns

the active RhythmDBQueryModel for the playing source.

[transfer none]

### rb_play_order_model_not_empty ()

    gboolean
    rb_play_order_model_not_empty (RBPlayOrder *porder);

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.

#### Parameters

porder | RBPlayOrder instance |

#### Returns

`TRUE` if not empty

### rb_play_order_player_is_playing ()

    gboolean
    rb_play_order_player_is_playing (RBPlayOrder *porder);

Returns `TRUE` if there is a current playing entry in the play order.

#### Parameters

porder | RBPlayOrder instance |

#### Returns

`TRUE` if playing

## Types and Values

### struct RBPlayOrder

    struct RBPlayOrder;

### struct RBPlayOrderClass

    struct RBPlayOrderClass {
    	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);
    };

## Property Details

### The `“player”` property

      “player”                   RBShellPlayer *

The RBShellPlayer instance

Flags: Read / Write / Construct Only

### The `“playing-entry”` property

      “playing-entry”            RhythmDBEntry *

The current playing RhythmDBEntry

Flags: Read / Write

## Signal Details

### The `“have-next-previous-changed”` signal

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

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

#### Parameters

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

Flags: Run Last