rb-entry-view

rb-entry-view — a GtkTreeView for displaying track listings

Synopsis

                    RBEntryView;
                    RBEntryViewClass;
enum                RBEntryViewColumn;
RBEntryView*        rb_entry_view_new                   (RhythmDB *db,
                                                         GObject *shell_player,
                                                         const char *sort_key,
                                                         gboolean is_drag_source,
                                                         gboolean is_drag_dest);
void                rb_entry_view_append_column         (RBEntryView *view,
                                                         RBEntryViewColumn coltype,
                                                         gboolean always_visible);
void                rb_entry_view_append_column_custom  (RBEntryView *view,
                                                         GtkTreeViewColumn *column,
                                                         const char *title,
                                                         const char *key,
                                                         GCompareDataFunc sort_func,
                                                         gpointer data,
                                                         GDestroyNotify data_destroy);
void                rb_entry_view_insert_column_custom  (RBEntryView *view,
                                                         GtkTreeViewColumn *column,
                                                         const char *title,
                                                         const char *key,
                                                         GCompareDataFunc sort_func,
                                                         gpointer data,
                                                         GDestroyNotify data_destroy,
                                                         gint position);
void                rb_entry_view_set_columns_clickable (RBEntryView *view,
                                                         gboolean clickable);
void                rb_entry_view_set_model             (RBEntryView *view,
                                                         RhythmDBQueryModel *model);
void                rb_entry_view_set_state             (RBEntryView *view,
                                                         RBEntryViewState state);
gboolean            rb_entry_view_have_selection        (RBEntryView *view);
gboolean            rb_entry_view_have_complete_selection
                                                        (RBEntryView *view);
GList*              rb_entry_view_get_selected_entries  (RBEntryView *view);
void                rb_entry_view_select_all            (RBEntryView *view);
void                rb_entry_view_select_none           (RBEntryView *view);
void                rb_entry_view_select_entry          (RBEntryView *view,
                                                         RhythmDBEntry *entry);
gboolean            rb_entry_view_get_entry_contained   (RBEntryView *view,
                                                         RhythmDBEntry *entry);
gboolean            rb_entry_view_get_entry_visible     (RBEntryView *view,
                                                         RhythmDBEntry *entry);
void                rb_entry_view_scroll_to_entry       (RBEntryView *view,
                                                         RhythmDBEntry *entry);
void                rb_entry_view_enable_drag_source    (RBEntryView *view,
                                                         const GtkTargetEntry *targets,
                                                         int n_targets);
void                rb_entry_view_get_sorting_order     (RBEntryView *view,
                                                         char **column_name,
                                                         gint *sort_order);
void                rb_entry_view_set_sorting_order     (RBEntryView *view,
                                                         const char *column_name,
                                                         gint sort_order);
char*               rb_entry_view_get_sorting_type      (RBEntryView *view);
void                rb_entry_view_set_sorting_type      (RBEntryView *view,
                                                         const char *sorttype);
void                rb_entry_view_set_fixed_column_width
                                                        (RBEntryView *view,
                                                         GtkTreeViewColumn *column,
                                                         GtkCellRenderer *renderer,
                                                         const gchar **strings);
const char*         rb_entry_view_get_time_date_column_sample
                                                        (void);
void                rb_entry_view_resort_model          (RBEntryView *view);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkScrolledWindow
                                       +----RBEntryView

Implemented Interfaces

RBEntryView implements AtkImplementorIface and GtkBuildable.

Properties

  "db"                       RhythmDB*             : Read / Write / Construct Only
  "is-drag-dest"             gboolean              : Read / Write / Construct Only
  "is-drag-source"           gboolean              : Read / Write / Construct Only
  "model"                    RhythmDBQueryModel*   : Read / Write
  "playing-state"            gint                  : Read / Write
  "shell-player"             RBShellPlayer*        : Read / Write / Construct Only
  "sort-key"                 gchar*                : Read / Write

Signals

  "entries-replaced"                               : Run Last
  "entry-activated"                                : Run Last
  "entry-added"                                    : Run Last
  "entry-deleted"                                  : Run Last
  "have-selection-changed"                         : Run Last
  "selection-changed"                              : Run Last
  "show-popup"                                     : Run Last
  "sort-order-changed"                             : Run Last

Description

This class provides a predefined set of columns for displaying the common set of RhythmDBEntry properties, but also allows custom columns to be appended. The 'playing' column is always created as the first column in the tree view, displaying a playing or paused image next to the currently playing entry, and also an error image next to entries for which a playback error message has been set. Clicking on the error image opens a dialog displaying the full message.

All columns added to entry view columns should be expandable, or have a fixed minimum width set. Otherwise, the tree view must measure the contents of each row to assign sizes, which is very slow for large track lists. All the predefined column types handle this correctly.

The set of visible columns is controlled by a (single) GConf key, which contains a comma-delimited list of property names for which the associated columns are visible. The entry view object tracks this automatically.

If a GConf key for sorting is provided when constructing the entry view, it is watched and updated. The sort settings consist of a column name and an order (ascending or descending).

Details

RBEntryView

typedef struct _RBEntryView RBEntryView;


RBEntryViewClass

typedef struct {
	GtkScrolledWindowClass parent;

	void (*entry_added)		(RBEntryView *view, RhythmDBEntry *entry);
	void (*entry_deleted)		(RBEntryView *view, RhythmDBEntry *entry);
	void (*entries_replaced)	(RBEntryView *view);

	void (*entry_activated)         (RBEntryView *view, RhythmDBEntry *entry);

	void (*have_selection_changed) (RBEntryView *view, gboolean have_selection);
	void (*selection_changed)       (RBEntryView *view);
	void (*sort_order_changed)     (RBEntryView *view);

	void (*show_popup)             (RBEntryView *view, gboolean over_entry);
} RBEntryViewClass;


enum RBEntryViewColumn

typedef enum {
	RB_ENTRY_VIEW_COL_TRACK_NUMBER,
	RB_ENTRY_VIEW_COL_TITLE,
	RB_ENTRY_VIEW_COL_ARTIST,
	RB_ENTRY_VIEW_COL_ALBUM,
	RB_ENTRY_VIEW_COL_GENRE,
	RB_ENTRY_VIEW_COL_DURATION,
	RB_ENTRY_VIEW_COL_QUALITY,
	RB_ENTRY_VIEW_COL_RATING,
	RB_ENTRY_VIEW_COL_PLAY_COUNT,
	RB_ENTRY_VIEW_COL_YEAR,
	RB_ENTRY_VIEW_COL_LAST_PLAYED,
	RB_ENTRY_VIEW_COL_FIRST_SEEN,
	RB_ENTRY_VIEW_COL_LAST_SEEN,
	RB_ENTRY_VIEW_COL_LOCATION,
	RB_ENTRY_VIEW_COL_ERROR
} RBEntryViewColumn;

Predefined column types to use in RBEntryViews. Use rb_entry_view_append_column to add these to an entry view. The predefined column names map directly to the RhythmDBEntry properties the columns display.


rb_entry_view_new ()

RBEntryView*        rb_entry_view_new                   (RhythmDB *db,
                                                         GObject *shell_player,
                                                         const char *sort_key,
                                                         gboolean is_drag_source,
                                                         gboolean is_drag_dest);

Creates a new entry view. If it makes sense to allow the user to drag entries from this entry view to other sources, is_drag_source should be TRUE. If it makes sense to allow the user to drag entries from other sources to this view, is_drag_dest should be TRUE. Drag and drop in this sense is used for two purposes: to transfer tracks between the filesystem and removable devices, and to add tracks to playlists.

db :

the RhythmDB instance

shell_player :

the RBShellPlayer instance

sort_key :

the GConf key controlling the sort order for the view

is_drag_source :

if TRUE, the view should act as a drag and drop data source

is_drag_dest :

if TRUE, the view should act as a drag and drop destination

Returns :

the new entry view

rb_entry_view_append_column ()

void                rb_entry_view_append_column         (RBEntryView *view,
                                                         RBEntryViewColumn coltype,
                                                         gboolean always_visible);

Appends a predefined column type to the set of columns already present in the entry view. If always_visible is TRUE, the column will ignore the user's coulmn visibility settings and will always be visible. This should only be used when it is vital for the purpose of the source that the column be visible.

view :

a RBEntryView

coltype :

type of column to append

always_visible :

if TRUE, ignore the user's column visibility settings

rb_entry_view_append_column_custom ()

void                rb_entry_view_append_column_custom  (RBEntryView *view,
                                                         GtkTreeViewColumn *column,
                                                         const char *title,
                                                         const char *key,
                                                         GCompareDataFunc sort_func,
                                                         gpointer data,
                                                         GDestroyNotify data_destroy);

Appends a custom column to the entry view.

view :

a RBEntryView

column :

a GtkTreeViewColumn to append

title :

title for the column (translated)

key :

sort key for the column (not translated)

sort_func :

comparison function to use for sorting on the column

data :

data to pass to the sort function

data_destroy :

function to use to destroy the sort data

rb_entry_view_insert_column_custom ()

void                rb_entry_view_insert_column_custom  (RBEntryView *view,
                                                         GtkTreeViewColumn *column,
                                                         const char *title,
                                                         const char *key,
                                                         GCompareDataFunc sort_func,
                                                         gpointer data,
                                                         GDestroyNotify data_destroy,
                                                         gint position);

Inserts a custom column at the specified position.

view :

a RBEntryView

column :

a GtkTreeViewColumn to append

title :

title for the column (translated)

key :

sort key for the column (not translated)

sort_func :

comparison function to use for sorting on the column

data :

data to pass to the sort function

data_destroy :

function to use to destroy the sort data

position :

position at which to insert the column (-1 to insert at the end)

rb_entry_view_set_columns_clickable ()

void                rb_entry_view_set_columns_clickable (RBEntryView *view,
                                                         gboolean clickable);

Makes the headers for sortable columns (those for which a sort function was provided) clickable, so the user can set the sort order.

view :

a RBEntryView

clickable :

if TRUE, sortable columns will be made clickable

rb_entry_view_set_model ()

void                rb_entry_view_set_model             (RBEntryView *view,
                                                         RhythmDBQueryModel *model);

Replaces the model backing the entry view.

view :

the RBEntryView

model :

the new RhythmDBQueryModel to use for the view

rb_entry_view_set_state ()

void                rb_entry_view_set_state             (RBEntryView *view,
                                                         RBEntryViewState state);

Sets the icon to be drawn in the 'playing' column next to the current playing entry. RB_ENTRY_VIEW_PLAYING and RB_ENTRY_VIEW_PAUSED should be used when the source containing the entry view is playing, and RB_ENTRY_VIEW_NOT_PLAYING otherwise.

view :

a RBEntryView

state :

the new playing entry state

rb_entry_view_have_selection ()

gboolean            rb_entry_view_have_selection        (RBEntryView *view);

view :

a RBEntryView

Returns :

TRUE if one or more rows are selected in the view

rb_entry_view_have_complete_selection ()

gboolean            rb_entry_view_have_complete_selection
                                                        (RBEntryView *view);

view :

a RBEntryView

Returns :

TRUE if all rows in the view are selected

rb_entry_view_get_selected_entries ()

GList*              rb_entry_view_get_selected_entries  (RBEntryView *view);

view :

a RBEntryView

Returns :

a GList containing the currently selected entries in the view (must be freed)

rb_entry_view_select_all ()

void                rb_entry_view_select_all            (RBEntryView *view);

Selects all rows in the view

view :

a RBEntryView

rb_entry_view_select_none ()

void                rb_entry_view_select_none           (RBEntryView *view);

Deselects all rows in the view.

view :

a RBEntryView

rb_entry_view_select_entry ()

void                rb_entry_view_select_entry          (RBEntryView *view,
                                                         RhythmDBEntry *entry);

If the specified entry is present in the view, it is added to the selection.

view :

a RBEntryView

entry :

a RhythmDBEntry to select

rb_entry_view_get_entry_contained ()

gboolean            rb_entry_view_get_entry_contained   (RBEntryView *view,
                                                         RhythmDBEntry *entry);

view :

a RBEntryView

entry :

a RhythmDBEntry to check

Returns :

TRUE if the entry is present in the view

rb_entry_view_get_entry_visible ()

gboolean            rb_entry_view_get_entry_visible     (RBEntryView *view,
                                                         RhythmDBEntry *entry);

view :

a RBEntryView

entry :

a RhythmDBEntry to check

Returns :

TRUE if the entry is present in the view and is currently visible

rb_entry_view_scroll_to_entry ()

void                rb_entry_view_scroll_to_entry       (RBEntryView *view,
                                                         RhythmDBEntry *entry);

If the specified entry is present in the view, the view will be scrolled so that the entry is visible.

view :

a RBEntryView

entry :

a RhythmDBEntry to scroll to

rb_entry_view_enable_drag_source ()

void                rb_entry_view_enable_drag_source    (RBEntryView *view,
                                                         const GtkTargetEntry *targets,
                                                         int n_targets);

Enables the entry view to act as a data source for drag an drop operations, using a specified set of data targets.

view :

a RBEntryView

targets :

an array of GtkTargetEntry structures defining the drag data targets

n_targets :

the number of entries in the target array

rb_entry_view_get_sorting_order ()

void                rb_entry_view_get_sorting_order     (RBEntryView *view,
                                                         char **column_name,
                                                         gint *sort_order);

Retrieves the sort settings for the view.

view :

a RBEntryView

column_name :

returns the sort column name

sort_order :

returns the sort ordering as a GtkSortType value

rb_entry_view_set_sorting_order ()

void                rb_entry_view_set_sorting_order     (RBEntryView *view,
                                                         const char *column_name,
                                                         gint sort_order);

Sets the sort order for the entry view.

view :

a RBEntryView

column_name :

name of the column to sort on

sort_order :

order to sort in, as a GtkSortOrder

rb_entry_view_get_sorting_type ()

char*               rb_entry_view_get_sorting_type      (RBEntryView *view);

Constructs a string that describes the sort settings for the entry view. This consists of a column name and an order ('ascending' or 'descending') separated by a comma.

view :

an RBEntryView

Returns :

sort order description (must be freed)

rb_entry_view_set_sorting_type ()

void                rb_entry_view_set_sorting_type      (RBEntryView *view,
                                                         const char *sorttype);

Changes the sort order for the entry view. The sort order description must be a column name, followed by a comma, followed by an order description ('ascending' or 'descending').

view :

a RBEntryView

sorttype :

sort order description

rb_entry_view_set_fixed_column_width ()

void                rb_entry_view_set_fixed_column_width
                                                        (RBEntryView *view,
                                                         GtkTreeViewColumn *column,
                                                         GtkCellRenderer *renderer,
                                                         const gchar **strings);

Helper function for calling rb_set_tree_view_column_fixed_width on a column. This is important for performance reasons, as having the tree view measure the strings in each of 20000 rows is very slow.

view :

a RBEntryView

column :

the column to set the width for

renderer :

a temporary cell renderer to use

strings :

a NULL-terminated array of strings that will be displayed in the column

rb_entry_view_get_time_date_column_sample ()

const char*         rb_entry_view_get_time_date_column_sample
                                                        (void);

Returns a sample string for use in columns displaying times and dates in 'friendly' form (see rb_utf_friendly_time). For use with rb_entry_view_set_fixed_column_width.

Returns :

sample date string

rb_entry_view_resort_model ()

void                rb_entry_view_resort_model          (RBEntryView *view);

Resorts the entries in the entry view. Mostly to be used when a new model is associated with the view.

view :

a RBEntryView to resort

Property Details

The "db" property

  "db"                       RhythmDB*             : Read / Write / Construct Only

RhythmDB instance


The "is-drag-dest" property

  "is-drag-dest"             gboolean              : Read / Write / Construct Only

If TRUE, the view acts as a destination for drag and drop operations.

Default value: FALSE


The "is-drag-source" property

  "is-drag-source"           gboolean              : Read / Write / Construct Only

If TRUE, the view acts as a data source for drag and drop operations.

Default value: FALSE


The "model" property

  "model"                    RhythmDBQueryModel*   : Read / Write

The RhythmDBQueryModel backing the view


The "playing-state" property

  "playing-state"            gint                  : Read / Write

Determines the icon to show in the 'playing' column next to the current playing entry.

Allowed values: [0,2]

Default value: 0


The "shell-player" property

  "shell-player"             RBShellPlayer*        : Read / Write / Construct Only

RBShellPlayer instance


The "sort-key" property

  "sort-key"                 gchar*                : Read / Write

The GConf key that controls the sort order for the view

Default value: ""

Signal Details

The "entries-replaced" signal

void                user_function                      (RBEntryView *view,
                                                        gpointer     user_data)      : Run Last

Emitted when the model backing the entry view is replaced.

view :

the RBEntryView

user_data :

user data set when the signal handler was connected.

The "entry-activated" signal

void                user_function                      (RBEntryView   *view,
                                                        RhythmDBEntry *entry,
                                                        gpointer       user_data)      : Run Last

Emitted when an entry in the view is activated (by double clicking or by various key presses)

view :

the RBEntryView

entry :

the RhythmDBEntry that was activated

user_data :

user data set when the signal handler was connected.

The "entry-added" signal

void                user_function                      (RBEntryView   *view,
                                                        RhythmDBEntry *entry,
                                                        gpointer       user_data)      : Run Last

Emitted when an entry is added to the view

view :

the RBEntryView

entry :

the RhythmDBEntry that was added

user_data :

user data set when the signal handler was connected.

The "entry-deleted" signal

void                user_function                      (RBEntryView   *view,
                                                        RhythmDBEntry *entry,
                                                        gpointer       user_data)      : Run Last

Emitted when an entry has been removed from the view

view :

the RBEntryView

entry :

the RhythmDBEntry that was removed

user_data :

user data set when the signal handler was connected.

The "have-selection-changed" signal

void                user_function                      (RBEntryView *view,
                                                        gboolean     have_selection,
                                                        gpointer     user_data)           : Run Last

Emitted when the user first selects a row, or when no rows are selected any more.

view :

the RBEntryView

have_selection :

TRUE if one or more rows are selected

user_data :

user data set when the signal handler was connected.

The "selection-changed" signal

void                user_function                      (RBEntryView *view,
                                                        gpointer     user_data)      : Run Last

Emitted when the set of selected entries changes

view :

the RBEntryView

user_data :

user data set when the signal handler was connected.

The "show-popup" signal

void                user_function                      (RBEntryView *view,
                                                        gboolean     over_entry,
                                                        gpointer     user_data)       : Run Last

Emitted when the user performs an action that should result in a popup menu appearing. If the action was a mouse button click, over_entry is FALSE if the mouse pointer was in the blank space after the last row in the view. If the action was a key press, over_entry is FALSE if no rows in the view are selected.

view :

the RBEntryView

over_entry :

if TRUE, the popup request was made while pointing at an entry in the view

user_data :

user data set when the signal handler was connected.

The "sort-order-changed" signal

void                user_function                      (RBEntryView *view,
                                                        gpointer     user_data)      : Run Last

Emitted when the user changes the sort order for the view

view :

the RBEntryView

user_data :

user data set when the signal handler was connected.