shell/rb-history.h

   1 /*
   2  *  arch-tag: Header for Song History List
   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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  19  *
  20  */
  21
  22 /**
  23  * RBHistory is a GSequence that maintains a "current" pointer and can delete
  24  * an arbitrary element in amortized O(log(N)) time. It can call a deletion
  25  * callback when it removes one of its entries. RBHistory is a pure data
  26  * structure and can probably lose its GObject-ness.
  27  *
  28  * I may also add another "enqueued" pointer to help manage a queue of next
  29  * songs under shuffle.
  30  *
  31  * All operations take amortized O(log(N)) (worst-case O(N)) time unless noted
  32  * otherwise.
  33  */
  34
  35 #include <glib/glist.h>
  36 #include "rhythmdb.h"
  37 #include "rb-shell-player.h"
  38
  39 #ifndef __RB_HISTORY_H
  40 #define __RB_HISTORY_H
  41
  42 G_BEGIN_DECLS
  43
  44 #define RB_TYPE_HISTORY         (rb_history_get_type ())
  45 #define RB_HISTORY(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), RB_TYPE_HISTORY, RBHistory))
  46 #define RB_HISTORY_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST((k), RB_TYPE_HISTORY, RBHistoryClass))
  47 #define RB_IS_HISTORY(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), RB_TYPE_HISTORY))
  48 #define RB_IS_HISTORY_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_HISTORY))
  49 #define RB_HISTORY_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_HISTORY, RBHistoryClass))
  50
  51 typedef struct RBHistoryPrivate RBHistoryPrivate;
  52
  53 typedef struct
  54 {
  55         GObject parent;
  56
  57         RBHistoryPrivate *priv;
  58 } RBHistory;
  59
  60 typedef struct
  61 {
  62         GObjectClass parent_class;
  63
  64 } RBHistoryClass;
  65
  66 GType                   rb_history_get_type     (void);
  67
  68 RBHistory *             rb_history_new          (gboolean truncate_on_play,
  69                                                  GFunc destroyer,
  70                                                  gpointer destroy_userdata);
  71
  72 RBHistory *             rb_history_clone        (RBHistory *orig,
  73                                                  GFunc callback,
  74                                                  gpointer userdata);
  75
  76 void                    rb_history_set_destroy_notify   (RBHistory *hist,
  77                                                          GFunc destroyer,
  78                                                          gpointer destroy_userdata);
  79 void                    rb_history_set_truncate_on_play (RBHistory *hist, gboolean truncate_on_play);
  80 void                    rb_history_set_maximum_size     (RBHistory *hist, guint maximum_size);
  81
  82 guint                   rb_history_length       (RBHistory *hist);
  83
  84 RhythmDBEntry *         rb_history_first        (RBHistory *hist);
  85 RhythmDBEntry *         rb_history_previous     (RBHistory *hist);
  86 RhythmDBEntry *         rb_history_current      (RBHistory *hist);
  87 RhythmDBEntry *         rb_history_next         (RBHistory *hist);
  88 RhythmDBEntry *         rb_history_last         (RBHistory *hist);
  89
  90 /** These move around within the history but never go beyond the head or tail */
  91 void                    rb_history_go_first     (RBHistory *hist);
  92 void                    rb_history_go_previous  (RBHistory *hist);
  93 void                    rb_history_go_next      (RBHistory *hist);
  94 void                    rb_history_go_last      (RBHistory *hist);
  95
  96 /**
  97  * Sets the song after "current" to @entry and, depending on the value of the
  98  * "truncate-on-play" property, may remove the entries after this.
  99  */
 100 void                    rb_history_set_playing  (RBHistory *hist, RhythmDBEntry *entry);
 101
 102 /**
 103  * Adds entry onto the end of the history list
 104  */
 105 void                    rb_history_append       (RBHistory *hist, RhythmDBEntry *entry);
 106
 107 /**
 108  * Gets the index of the current entry. This is guaranteed to be < the
 109  * history's size, so if the history is empty, it returns -1.
 110  */
 111 gint                    rb_history_get_current_index    (RBHistory *hist);
 112
 113 /**
 114  * Inserts @entry at @index within the history list. 0<=@index<=size
 115  */
 116 void                    rb_history_insert_at_index      (RBHistory *hist, RhythmDBEntry *entry, guint index);
 117
 118 /**
 119  * If the entry is in the history, removes all instances of it. Unrefs the
 120  * entry and decrements the list size.
 121  */
 122 void                    rb_history_remove_entry (RBHistory *hist, RhythmDBEntry *entry);
 123
 124 /** Empties the history list */
 125 void                    rb_history_clear        (RBHistory *hist);
 126
 127 /** Returns a copy of the whole history in order. Caller must free the result.
 128  * Takes O(Nlog(N)) time. */
 129 GPtrArray *             rb_history_dump         (RBHistory *hist);
 130
 131 gboolean                rb_history_contains_entry       (RBHistory *hist, RhythmDBEntry *entry);
 132
 133 G_END_DECLS
 134
 135 #endif /* __RB_HISTORY_H */