RBEntryView: Rhythmbox Development Reference Manual

## RBEntryView RBEntryView — a GtkTreeView for displaying track listings |

## Functions

RBEntryView * | rb_entry_view_new ()
GtkTreeViewColumn * | rb_entry_view_get_column ()
void | rb_entry_view_append_column ()
void | rb_entry_view_append_column_custom ()
void | rb_entry_view_insert_column_custom ()
void | rb_entry_view_set_columns_clickable ()
void | rb_entry_view_set_model ()
void | rb_entry_view_set_state ()
gboolean | rb_entry_view_have_selection ()
gboolean | rb_entry_view_have_complete_selection ()
GList * | rb_entry_view_get_selected_entries ()
void | rb_entry_view_select_all ()
void | rb_entry_view_select_none ()
void | rb_entry_view_select_entry ()
gboolean | rb_entry_view_get_entry_contained ()
gboolean | rb_entry_view_get_entry_visible ()
void | rb_entry_view_scroll_to_entry ()
void | rb_entry_view_enable_drag_source ()
void | rb_entry_view_get_sorting_order ()
void | rb_entry_view_set_sorting_order ()
char * | rb_entry_view_get_sorting_type ()
void | rb_entry_view_set_sorting_type ()
void | rb_entry_view_set_fixed_column_width ()
void | rb_entry_view_set_column_editable ()
const char * | rb_entry_view_get_time_date_column_sample ()
void | rb_entry_view_resort_model ()

## Properties

RhythmDB * | db | Read / Write / Construct Only
gboolean | is-drag-dest | Read / Write / Construct Only
gboolean | is-drag-source | Read / Write / Construct Only
RhythmDBQueryModel * | model | Read / Write
gint | playing-state | Read / Write
RBShellPlayer * | shell-player | Read / Write / Construct Only
gchar * | sort-order | Read / Write
GStrv | visible-columns | Read / Write

## Signals

void | entries-replaced | Run Last
void | entry-activated | Run Last
void | entry-added | Run Last
void | entry-deleted | Run Last
void | have-selection-changed | Run Last
void | selection-changed | Run Last
void | show-popup | Run Last

## Types and Values

enum | RBEntryViewColumn
enum | RBEntryViewState
struct | RBEntryView
struct | RBEntryViewClass

## Object Hierarchy

        GEnum
        ├── RBEntryViewColumn
        ╰── RBEntryViewState
        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBox
                        ╰── RBEntryView

## Implemented Interfaces

RBEntryView implements AtkImplementorIface, GtkBuildable and GtkOrientable.

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

## Functions

### rb_entry_view_new ()

    RBEntryView *
    rb_entry_view_new (RhythmDB *db,
                       GObject *shell_player,
                       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.

#### Parameters

db | the RhythmDB instance |
shell_player | the RBShellPlayer instance |
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_get_column ()

    GtkTreeViewColumn *
    rb_entry_view_get_column (RBEntryView *view,
                              RBEntryViewColumn coltype);

Retrieves a predefined column from the entry view. This can be used to insert additional cell renderers into the column.

#### Parameters

view | a RBEntryView |
coltype | type of column to retrieve |

#### Returns

a GtkTreeViewColumn instance, or NULL.

[transfer none]

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

#### Parameters

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.

#### Parameters

view | a RBEntryView |
column | a GtkTreeViewColumn to append. | [transfer full]
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. | [closure][scope notified]
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.

#### Parameters

view | a RBEntryView |
column | a GtkTreeViewColumn to append. | [transfer full]
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. | [closure][scope notified]
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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

view | a RBEntryView |
state | the new playing entry state |

### rb_entry_view_have_selection ()

    gboolean
    rb_entry_view_have_selection (RBEntryView *view);

Determines whether there is an active selection in the view.

#### Parameters

view | a RBEntryView |

#### Returns

TRUE if one or more rows are selected

### rb_entry_view_have_complete_selection ()

    gboolean
    rb_entry_view_have_complete_selection (RBEntryView *view);

Determines whether all entries in the view are selected.

#### Parameters

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

Gathers the selected entries from the view.

#### Parameters

view | a RBEntryView |

#### Returns

a GList of selected entries in the view.

[element-type RhythmDBEntry][transfer full]

### rb_entry_view_select_all ()

    void
    rb_entry_view_select_all (RBEntryView *view);

Selects all rows in the view

#### Parameters

view | a RBEntryView |

### rb_entry_view_select_none ()

    void
    rb_entry_view_select_none (RBEntryView *view);

Deselects all rows in the view.

#### Parameters

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.

#### Parameters

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

Determines whether a specified entry is present in the view.

#### Parameters

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

Determines whether a specified entry is present in the view and is currently visible.

#### Parameters

view | a RBEntryView |
entry | a RhythmDBEntry to check |

#### Returns

TRUE if the entry is 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

view | a RBEntryView |
column_name | returns the sort column name. | [out callee-allocates][allow-none][transfer full]
sort_order | returns the sort ordering as a GtkSortType value. | [out][allow-none]

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

#### Parameters

view | a RBEntryView |
column_name | name of the column to sort on |
sort_order | order to sort in, as a GtkSortType |

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

#### Parameters

view | an RBEntryView |

#### Returns

sort order description.

[transfer full]

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

#### Parameters

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.

#### Parameters

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. | [array zero-terminated=1]

### rb_entry_view_set_column_editable ()

    void
    rb_entry_view_set_column_editable (RBEntryView *view,
                                       RBEntryViewColumn column,
                                       gboolean editable);

Enables in-place editing of the values in a column. The underlying `RhythmDBEntry` is updated when editing is complete.

#### Parameters

view | a RBEntryView |
column | a RBEntryViewColumn to update |
editable | `TRUE` to make the column editable, `FALSE` otherwise |

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

#### Parameters

view | a RBEntryView to resort |

## Types and Values

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

#### Members

RB_ENTRY_VIEW_COL_TRACK_NUMBER | the track number column |
RB_ENTRY_VIEW_COL_TITLE | the title column |
RB_ENTRY_VIEW_COL_ARTIST | the artist column |
RB_ENTRY_VIEW_COL_ALBUM | the album column |
RB_ENTRY_VIEW_COL_GENRE | the genre column |
RB_ENTRY_VIEW_COL_COMMENT | the comment column |
RB_ENTRY_VIEW_COL_DURATION | the duration column |
RB_ENTRY_VIEW_COL_QUALITY | the quality (bitrate) column |
RB_ENTRY_VIEW_COL_RATING | the rating column |
RB_ENTRY_VIEW_COL_PLAY_COUNT | the play count column |
RB_ENTRY_VIEW_COL_YEAR | the year (release date) column |
RB_ENTRY_VIEW_COL_LAST_PLAYED | the last played time column |
RB_ENTRY_VIEW_COL_FIRST_SEEN | the first seen (imported) column |
RB_ENTRY_VIEW_COL_LAST_SEEN | the last seen column |
RB_ENTRY_VIEW_COL_LOCATION | the location column |
RB_ENTRY_VIEW_COL_BPM | the BPM column |
RB_ENTRY_VIEW_COL_ERROR | the error column |
RB_ENTRY_VIEW_COL_COMPOSER | the composer column |

### enum RBEntryViewState

#### Members

RB_ENTRY_VIEW_NOT_PLAYING |  |
RB_ENTRY_VIEW_PLAYING |  |
RB_ENTRY_VIEW_PAUSED |  |

### struct RBEntryView

    struct RBEntryView;

### struct RBEntryViewClass

    struct RBEntryViewClass {
    	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 (*show_popup)             (RBEntryView *view, gboolean over_entry);
    };

## Property Details

### The `“db”` property

      “db”                       RhythmDB *

RhythmDB instance

Flags: Read / Write / Construct Only

### The `“is-drag-dest”` property

      “is-drag-dest”             gboolean

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

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“is-drag-source”` property

      “is-drag-source”           gboolean

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

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“model”` property

      “model”                    RhythmDBQueryModel *

The RhythmDBQueryModel backing the view

Flags: Read / Write

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

      “playing-state”            gint

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

Flags: Read / Write

Allowed values: [0,2]

Default value: 0

### The `“shell-player”` property

      “shell-player”             RBShellPlayer *

RBShellPlayer instance

Flags: Read / Write / Construct Only

### The `“sort-order”` property

      “sort-order”               gchar *

The sort order for the track listing.

Flags: Read / Write

Default value: NULL

### The `“visible-columns”` property

      “visible-columns”          GStrv

An array containing the names of the visible columns.

Flags: Read / Write

## Signal Details

### The `“entries-replaced”` signal

    void
    user_function (RBEntryView *view,
                   gpointer     user_data)

Emitted when the model backing the entry view is replaced.

#### Parameters

view | the RBEntryView |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“entry-activated”` signal

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

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

#### Parameters

view | the RBEntryView |
entry | the RhythmDBEntry that was activated |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“entry-added”` signal

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

Emitted when an entry is added to the view

#### Parameters

view | the RBEntryView |
entry | the RhythmDBEntry that was added |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“entry-deleted”` signal

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

Emitted when an entry has been removed from the view

#### Parameters

view | the RBEntryView |
entry | the RhythmDBEntry that was removed |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“have-selection-changed”` signal

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

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

#### Parameters

view | the RBEntryView |
have_selection | TRUE if one or more rows are selected |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“selection-changed”` signal

    void
    user_function (RBEntryView *view,
                   gpointer     user_data)

Emitted when the set of selected entries changes

#### Parameters

view | the RBEntryView |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“show-popup”` signal

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

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.

#### Parameters

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

Flags: Run Last