shell/rb-play-order.h

   1 /*
   2  *  arch-tag: Header for base class for play order classes
   3  *
   4  *  Copyright (C) 2003 Jeffrey Yasskin <jyasskin@mail.utexas.edu>
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this program; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA.
  19  *
  20  */
  21
  22 /**
  23  * RBPlayOrder defines the interface for classes which can control the order
  24  * songs play.
  25  *
  26  * See rb-play-order-*.{h,c} for examples.
  27  *
  28  * Only rb-play-order.c should include the subclasses' headers (and it should
  29  * only use them to instantiate the right subclass). Anyone else who wants to
  30  * use the heirarchy should include rb-play-order.h and call the functions
  31  * defined here.
  32  *
  33  * When you add a new play order, remember to update the long description of
  34  * the state/play_order key in data/rhythmbox.schemas and to add the
  35  * appropriate code to rb_play_order_new().
  36  */
  37
  38 #ifndef __RB_PLAY_ORDER_H
  39 #define __RB_PLAY_ORDER_H
  40
  41 #include <rhythmdb/rhythmdb.h>
  42 #include <rhythmdb/rhythmdb-query-model.h>
  43
  44 #include <rb-shell-player.h>
  45
  46 G_BEGIN_DECLS
  47
  48 #define RB_TYPE_PLAY_ORDER         (rb_play_order_get_type ())
  49 #define RB_PLAY_ORDER(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), RB_TYPE_PLAY_ORDER, RBPlayOrder))
  50 #define RB_PLAY_ORDER_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST ((k), RB_TYPE_PLAY_ORDER, RBPlayOrderClass))
  51 #define RB_IS_PLAY_ORDER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), RB_TYPE_PLAY_ORDER))
  52 #define RB_IS_PLAY_ORDER_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_PLAY_ORDER))
  53 #define RB_PLAY_ORDER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_PLAY_ORDER, RBPlayOrderClass))
  54
  55 typedef struct RBPlayOrderPrivate RBPlayOrderPrivate;
  56
  57 typedef struct
  58 {
  59         GObject parent;
  60
  61         RBPlayOrderPrivate *priv;
  62 } RBPlayOrder;
  63
  64 typedef gboolean (*RBPlayOrderQueryFunc) (RBPlayOrder *porder);
  65
  66 typedef struct
  67 {
  68         GObjectClass parent_class;
  69
  70         /* EVENTS */
  71         void (*playing_source_changed) (RBPlayOrder *porder);
  72         void (*db_changed) (RBPlayOrder *porder, RhythmDB *new_db);
  73         void (*playing_entry_changed) (RBPlayOrder *porder, RhythmDBEntry *old_entry, RhythmDBEntry *new_entry);
  74         void (*entry_added) (RBPlayOrder *porder, RhythmDBEntry *entry);
  75         void (*entry_removed) (RBPlayOrder *porder, RhythmDBEntry *entry);
  76         void (*query_model_changed) (RBPlayOrder *porder);
  77         void (*db_entry_deleted) (RBPlayOrder *porder, RhythmDBEntry *entry);
  78         void (*playing_entry_removed) (RBPlayOrder *porder, RhythmDBEntry *entry);
  79
  80         /* QUERIES */
  81         /**
  82          * Returns whether there is a next song. This controls the next
  83          * button's sensitivity. If not implemented, defaults to
  84          * get_next()!=NULL.
  85          *
  86          * Must not change any visible state.
  87          */
  88         gboolean (*has_next) (RBPlayOrder* porder);
  89         /**
  90          * get_next() must return the next song to play. It's called when a
  91          * song finishes, when the user clicks the next button, and when the
  92          * user clicks play after playback is stopped.
  93          *
  94          * get_next() is also used to find the first song. You can figure out
  95          * whether the player is currently playing by calling
  96          * rb_play_order_player_is_playing(porder).
  97          *
  98          * Must not change any visible state.
  99          */
 100         RhythmDBEntry* (*get_next) (RBPlayOrder* porder);
 101         /**
 102          * Tells the play order that the user has moved to the next song.
 103          * Should be called before the EntryView::playing-entry property is
 104          * changed.
 105          */
 106         void (*go_next) (RBPlayOrder* porder);
 107         /**
 108          * Returns whether there is a previous song. This controls the previous
 109          * button's sensitivity. If not implemented, defaults to
 110          * get_previous()!=NULL.
 111          *
 112          * Must not change any visible state.
 113          */
 114         gboolean (*has_previous) (RBPlayOrder* porder);
 115         /**
 116          * get_previous() must return the previous song to play. It's called
 117          * when the user clicks the previous button within 2 seconds of the
 118          * beginning of a song.
 119          *
 120          * Must not change any visible state.
 121          */
 122         RhythmDBEntry* (*get_previous) (RBPlayOrder* porder);
 123         /**
 124          * Tells the play order that the user has moved to the previous song.
 125          * Should be called before the EntryView::playing-entry property is
 126          * changed.
 127          */
 128         void (*go_previous) (RBPlayOrder* porder);
 129
 130         /* SIGNALS */
 131         void (*have_next_previous_changed) (RBPlayOrder *porder, gboolean have_next, gboolean have_previous);
 132 } RBPlayOrderClass;
 133
 134 GType                   rb_play_order_get_type          (void);
 135
 136 RBPlayOrder *           rb_play_order_new               (const char* play_order_name, RBShellPlayer *player);
 137
 138 typedef struct {
 139         /** Value of the state/play-order gconf key */
 140         char *name;
 141         /** Contents of the play order dropdown; should be gettext()ed before use. */
 142         char *description;
 143         /** the play order's _new function */
 144         RBPlayOrder *(*constructor)(RBShellPlayer *player);
 145         /** TRUE if the play order should appear in the dropdown */
 146         gboolean is_in_dropdown;
 147         /** If the value of the state/play-order gconf key isn't found, the one
 148          * with is_default==TRUE will be used. */
 149         gboolean is_default;
 150 } RBPlayOrderDescription;
 151 const RBPlayOrderDescription *  rb_play_order_get_orders        (void);
 152
 153 void                    rb_play_order_playing_source_changed    (RBPlayOrder *porder,
 154                                                                  RBSource *source);
 155 void                    rb_play_order_query_model_changed       (RBPlayOrder *porder);
 156
 157 gboolean                rb_play_order_has_next          (RBPlayOrder* porder);
 158 RhythmDBEntry *         rb_play_order_get_next          (RBPlayOrder *porder);
 159 void                    rb_play_order_go_next           (RBPlayOrder *porder);
 160 gboolean                rb_play_order_has_previous      (RBPlayOrder* porder);
 161 RhythmDBEntry *         rb_play_order_get_previous      (RBPlayOrder *porder);
 162 void                    rb_play_order_go_previous       (RBPlayOrder *porder);
 163
 164 void                    rb_play_order_set_playing_entry (RBPlayOrder *porder,
 165                                                          RhythmDBEntry *entry);
 166 RhythmDBEntry *         rb_play_order_get_playing_entry (RBPlayOrder *porder);
 167
 168 /* Private utility functions used by play order implementations */
 169
 170 RBShellPlayer *         rb_play_order_get_player        (RBPlayOrder *porder);
 171 RBSource *              rb_play_order_get_source        (RBPlayOrder *porder);
 172 RhythmDB *              rb_play_order_get_db            (RBPlayOrder *porder);
 173 RhythmDBQueryModel *    rb_play_order_get_query_model   (RBPlayOrder *porder);
 174 gboolean                rb_play_order_model_not_empty   (RBPlayOrder *porder);
 175
 176 void                    rb_play_order_have_next_changed (RBPlayOrder *porder, gboolean have_next);
 177 void                    rb_play_order_have_previous_changed (RBPlayOrder *porder, gboolean have_previous);
 178
 179 gboolean                rb_play_order_player_is_playing (RBPlayOrder *porder);
 180
 181 void                    rb_play_order_check_if_empty (RBPlayOrder *porder, RhythmDBEntry *entry);
 182
 183 G_END_DECLS
 184
 185 #endif /* __RB_PLAY_ORDER_H */