## gva-tree-view

gva-tree-view — Main Tree View

## Synopsis

    void                gva_tree_view_init                  (void);
    GtkTreePath *       gva_tree_view_lookup                (const gchar *game);
    gboolean            gva_tree_view_update                (GError **error);
    gboolean            gva_tree_view_run_query             (const gchar *expression,
                                                             GError **error);
    GtkTreeModel *      gva_tree_view_get_model             (void);
    void                gva_tree_view_update_status_bar     (void);
    const gchar *       gva_tree_view_get_selected_game     (void);
    void                gva_tree_view_set_selected_game     (const gchar *game);
    gint                gva_tree_view_get_selected_view     (void);
    void                gva_tree_view_set_selected_view     (gint view);
    const gchar *       gva_tree_view_get_last_selected_game
                                                            (void);
    void                gva_tree_view_set_last_selected_game
                                                            (const gchar *game);
    void                gva_tree_view_get_last_sort_column_id
                                                            (GvaGameStoreColumn *column_id,
                                                             GtkSortType *order);
    void                gva_tree_view_set_last_sort_column_id
                                                            (GvaGameStoreColumn column_id,
                                                             GtkSortType order);
    gboolean            gva_tree_view_button_press_event_cb (GtkTreeView *view,
                                                             GdkEventButton *event);
    gboolean            gva_tree_view_popup_menu_cb         (GtkTreeView *view);
    gboolean            gva_tree_view_query_tooltip_cb      (GtkTreeView *view,
                                                             gint x,
                                                             gint y,
                                                             gboolean keyboard_mode,
                                                             GtkTooltip *tooltip);
    void                gva_tree_view_row_activated_cb      (GtkTreeView *view,
                                                             GtkTreePath *path,
                                                             GtkTreeViewColumn *column);

## Description

These functions manipulate the tree view widget in the main window.

## Details

### gva_tree_view_init ()

    void                gva_tree_view_init                  (void);

Initializes the main tree view.

This function should be called once when the application starts.

### gva_tree_view_lookup ()

    GtkTreePath *       gva_tree_view_lookup                (const gchar *game);

Looks up `game` in the tree view's store and returns a GtkTreePath to the corresponding row, or `NULL` if `game` was not found.

`game` : | the name of a game
Returns : | a GtkTreePath to the row corresponding to `game`, or `NULL`

### gva_tree_view_update ()

    gboolean            gva_tree_view_update                (GError **error);

Refreshes the contents of the tree view by querying the game database using criteria appropriate for the currently selected game list view. If an error occurs, it returns `FALSE` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_tree_view_run_query ()

    gboolean            gva_tree_view_run_query             (const gchar *expression,
                                                             GError **error);

Similar to `gva_tree_view_update()` but applies custom criteria to the game database query. If an error occurs, it returns `FALSE` and sets `error`.

`expression` : | an SQL "where" expression
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_tree_view_get_model ()

    GtkTreeModel *      gva_tree_view_get_model             (void);

Thin wrapper for `gtk_tree_view_get_model()` that uses the main tree view.

Returns the model the main tree view is based on. Returns `NULL` if the model is unset.

Returns : | a GtkTreeModel, or `NULL` if the model is unset

### gva_tree_view_update_status_bar ()

    void                gva_tree_view_update_status_bar     (void);

Puts a message in the main status bar containing the MAME version and the number of games displayed in the current view. This message gets shown when the status bar has nothing more important to show.

### gva_tree_view_get_selected_game ()

    const gchar *       gva_tree_view_get_selected_game     (void);

Returns the name of the game corresponding to the currently selected row, or `NULL` if no row is selected.

Returns : | the name of the selected game, or `NULL` if no game is selected

### gva_tree_view_set_selected_game ()

    void                gva_tree_view_set_selected_game     (const gchar *game);

Selects the row corresponding to `game`. If the row is invisible in the current view, unselect all tree view rows. The function also calls `gva_tree_view_set_last_selected_game()` so that the selected game will be persistent across sessions.

`game` : | the name of a game

### gva_tree_view_get_selected_view ()

    gint                gva_tree_view_get_selected_view     (void);

Returns the index of the currently selected view.

- 0 = Available Games
- 1 = Favorite Games
- 2 = Search Results

Returns : | the index of the currently selected view

### gva_tree_view_set_selected_view ()

    void                gva_tree_view_set_selected_view     (gint view);

Sets the game list view corresponding to index `view`. See `gva_tree_view_get_selected_view()` for a list of valid indices.

Setting the game list view triggers a tree view update. See `gva_tree_view_update()` for details.

`view` : | index of the view to select

### gva_tree_view_get_last_selected_game ()

    const gchar *       gva_tree_view_get_last_selected_game
                                                            (void);

Returns the name of the most recently selected game in either the current or the previous session of GNOME Video Arcade. Note that it is still possible for this function to return `NULL`.

Returns : | the name of the most recently selected game

### gva_tree_view_set_last_selected_game ()

    void                gva_tree_view_set_last_selected_game
                                                            (const gchar *game);

Writes `game` to GConf key `/apps/gnome-video-arcade/selected-game`.

This is used to remember which game was selected in the previous session of GNOME Video Arcade so that the same game can be selected again automatically at startup.

`game` : | the name of a game

### gva_tree_view_get_last_sort_column_id ()

    void                gva_tree_view_get_last_sort_column_id
                                                            (GvaGameStoreColumn *column_id,
                                                             GtkSortType *order);

Retrieves the most recently selected sort column ID and sort order in either the current or the previous session of GNOME Video Arcade.

`column_id` : | return location for the column ID
`order` : | return location for the sort order

### gva_tree_view_set_last_sort_column_id ()

    void                gva_tree_view_set_last_sort_column_id
                                                            (GvaGameStoreColumn column_id,
                                                             GtkSortType order);

Writes `column_id` and `order` to GConf key `/apps/gnome-video-arcade/sort-column`.

This is used to remember which how the game list view was sorted in the previous session of GNOME Video Arcade so that the same sorting can be applied again automatically at startup.

`column_id` : | sort column ID
`order` : | sort order

### gva_tree_view_button_press_event_cb ()

    gboolean            gva_tree_view_button_press_event_cb (GtkTreeView *view,
                                                             GdkEventButton *event);

Handler for "button-press-event" signals to the main tree view.

On right-click, selects the row that was clicked and shows a popup menu.

`view` : | the main tree view
`event` : | a GdkEventButton
Returns : | `TRUE` if the popup menu was shown, `FALSE` otherwise

### gva_tree_view_popup_menu_cb ()

    gboolean            gva_tree_view_popup_menu_cb         (GtkTreeView *view);

Handler for "popup-menu" signals to the main tree view.

Shows a popup menu.

`view` : | the main tree view
Returns : | `TRUE`

### gva_tree_view_query_tooltip_cb ()

    gboolean            gva_tree_view_query_tooltip_cb      (GtkTreeView *view,
                                                             gint x,
                                                             gint y,
                                                             gboolean keyboard_mode,
                                                             GtkTooltip *tooltip);

Handles tooltips for the main tree view.

`view` : | the main tree view
`x` : | the x coordinate of the cursor position where the request has been emitted
`y` : | the y coordinate of the cursor position where the request has been emitted
`keyboard_mode` : | `TRUE` if the tooltip was triggered using the keyboard
`tooltip` : | a GtkTooltip
Returns : | `TRUE` if `tooltip` should be shown right now, `FALSE` otherwise

### gva_tree_view_row_activated_cb ()

    void                gva_tree_view_row_activated_cb      (GtkTreeView *view,
                                                             GtkTreePath *path,
                                                             GtkTreeViewColumn *column);

Handler for "row-activated" signals to the main tree view.

Activates the GVA_ACTION_START action.

`view` : | the main tree view
`path` : | the GtkTreePath for the activated row
`column` : | the GtkTreeViewColumn in which the activation occurred