rb-play-order

## rb-play-order rb-play-order — |

## Synopsis

    typedef     RBPlayOrderPrivate;
    RBPlayOrder* rb_play_order_new              (const char *play_order_name,
                                                 RBShellPlayer *player);
                RBPlayOrderDescription;
    const RBPlayOrderDescription* rb_play_order_get_orders
                                                (void);
    void        rb_play_order_playing_source_changed
                                                (RBPlayOrder *porder,
                                                 RBSource *source);
    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);
    RBShellPlayer* rb_play_order_get_player     (RBPlayOrder *porder);
    RBSource*   rb_play_order_get_source        (RBPlayOrder *porder);
    RhythmDB*   rb_play_order_get_db            (RBPlayOrder *porder);
    RhythmDBEntry* rb_play_order_get_playing_entry
                                                (RBPlayOrder *porder);
    gboolean    rb_play_order_player_is_playing (RBPlayOrder *porder);
    void        rb_play_order_ref_entry_swapped (RhythmDBEntry *entry,
                                                 RhythmDB *db);
    void        rb_play_order_unref_entry_swapped
                                                (RhythmDBEntry *entry,
                                                 RhythmDB *db);

## Description

## Details

### RBPlayOrderPrivate

    typedef struct RBPlayOrderPrivate RBPlayOrderPrivate;

### rb_play_order_new ()

    RBPlayOrder* rb_play_order_new              (const char *play_order_name,
                                                 RBShellPlayer *player);

Creates a new RBPlayOrder of the specified type.

`play_order_name` : |
`player` : | RBShellPlayer instance to attach to
Returns : | RBPlayOrder instance

### RBPlayOrderDescription

    typedef struct {
    	/** Value of the state/play-order gconf key */
    	char *name;
    	/** Contents of the play order dropdown; should be gettext()ed before use. */
    	char *description;
    	/** the play order's _new function */
    	RBPlayOrder *(*constructor)(RBShellPlayer *player);
    	/** TRUE if the play order should appear in the dropdown */
    	gboolean is_in_dropdown;
    	/** If the value of the state/play-order gconf key isn't found, the one
    	 * with is_default==TRUE will be used. */
    	gboolean is_default;
    } RBPlayOrderDescription;

### rb_play_order_get_orders ()

    const RBPlayOrderDescription* rb_play_order_get_orders
                                                (void);

Defines the set of available play orders, their translatable descriptions, their constructor functions, whether they should appear in a drop-down list of play orders, and which one is the default.

This should be the only function with full knowledge of what play orders are available.

Returns : |

### 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_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_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_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_player_is_playing ()

    gboolean    rb_play_order_player_is_playing (RBPlayOrder *porder);

`porder` : | RBPlayOrder instance
Returns : | true if there is a current playing entry in the play order.

### rb_play_order_ref_entry_swapped ()

    void        rb_play_order_ref_entry_swapped (RhythmDBEntry *entry,
                                                 RhythmDB *db);

Utility function that can be used with RBHistory to implement play orders that maintain an internal list of entries.

`entry` : | RhythmDBEntry to reference
`db` : | RhythmDB instance

### rb_play_order_unref_entry_swapped ()

    void        rb_play_order_unref_entry_swapped
                                                (RhythmDBEntry *entry,
                                                 RhythmDB *db);

Utility function that can be used with RBHistory to implement play orders that maintain an internal list of entries.

`entry` : | RhythmDBEntry to unreference
`db` : | RhythmDB instance