## gva-main

gva-main — Main Window

## Synopsis

    void                gva_main_init                       (void);
    gboolean            gva_main_build_database             (GError **error);
    gboolean            gva_main_analyze_roms               (GError **error);
    gboolean            gva_main_init_search_completion     (GError **error);
    void                gva_main_connect_proxy_cb           (GtkUIManager *manager,
                                                             GtkAction *action,
                                                             GtkWidget *proxy);
    void                gva_main_cursor_busy                (void);
    void                gva_main_cursor_normal              (void);
    void                gva_main_progress_bar_show          (void);
    void                gva_main_progress_bar_hide          (void);
    void                gva_main_progress_bar_set_fraction  (gdouble fraction);
    guint               gva_main_statusbar_get_context_id   (const gchar *context_description);
    guint               gva_main_statusbar_push             (guint context_id,
                                                             const gchar *format,
                                                             ...);
    void                gva_main_statusbar_pop              (guint context_id);
    void                gva_main_statusbar_remove           (guint context_id,
                                                             guint message_id);
    void                gva_main_execute_search             (void);
    gchar *             gva_main_get_last_search_text       (void);
    void                gva_main_set_last_search_text       (const gchar *text);
    gboolean            gva_main_get_last_selected_match    (gchar **column_name,
                                                             gchar **search_text);
    void                gva_main_set_last_selected_match    (const gchar *column_name,
                                                             const gchar *search_text);
    void                gva_main_search_entry_activate_cb   (GtkEntry *entry);
    void                gva_main_search_entry_notify_cb     (GtkEntry *entry,
                                                             GParamSpec *pspec);
    gboolean            gva_main_search_query_tooltip_cb    (GtkWidget *widget,
                                                             gint x,
                                                             gint y,
                                                             gboolean keyboard_mode,
                                                             GtkTooltip *tooltip);
    void                gva_main_window_destroy_cb          (GtkWindow *window);

## Description

These functions manipulate the main window, excluding the tree view. The tree view functions are documented separately in the gva-tree-view section.

## Details

### gva_main_init ()

    void                gva_main_init                       (void);

Initializes the main window.

This function should be called once when the application starts.

### gva_main_build_database ()

    gboolean            gva_main_build_database             (GError **error);

Executes the lengthy process of constructing the games database. The function updates the main window's progress bar to help track the database construction. The function is synchronous; it blocks until database construction is complete or aborted.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the database construction was successful, `FALSE` if construction failed or was aborted

### gva_main_analyze_roms ()

    gboolean            gva_main_analyze_roms               (GError **error);

Executes the lengthy process of analyzing all available ROM and sample sets for correctness and then updating the games database with the new status information. The function updates the main window's progress bar to help track the analysis. The function is synchronous; it blocks until the analysis is complete or aborted.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the analysis completed successfully, `FALSE` if the analysis failed or was aborted

### gva_main_init_search_completion ()

    gboolean            gva_main_init_search_completion     (GError **error);

Initializes autocompletion in the search entry. This must be done after the game database is built and ROMs are analyzed. If an error occurs, the function returns `FALSE` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if autocompletion was initialized successfully, `FALSE` if an error occurred

### gva_main_connect_proxy_cb ()

    void                gva_main_connect_proxy_cb           (GtkUIManager *manager,
                                                             GtkAction *action,
                                                             GtkWidget *proxy);

Callback for `manager`'s "`connect`-proxy" signal. The function configures main menu items to display the appropriate tooltip in the status bar when the mouse hovers over them. `action` supplies the tooltip.

`manager` : | a GtkUIManager
`action` : | a GtkAction
`proxy` : | a GtkWidget

### gva_main_cursor_busy ()

    void                gva_main_cursor_busy                (void);

Sets the mouse cursor to busy. Generally useful before starting a long-running foreground task.

### gva_main_cursor_normal ()

    void                gva_main_cursor_normal              (void);

Sets the mouse cursor back to normal. Generally useful after completing a long-running foreground task.

### gva_main_progress_bar_show ()

    void                gva_main_progress_bar_show          (void);

Shows the progress bar in the main window's status bar and sets the mouse cursor to busy. Generally useful before starting a long-running foreground task.

### gva_main_progress_bar_hide ()

    void                gva_main_progress_bar_hide          (void);

Hides the progress bar in the main window's status bar and sets the mouse cursor back to normal. Generally useful after completing a long-running foreground task.

### gva_main_progress_bar_set_fraction ()

    void                gva_main_progress_bar_set_fraction  (gdouble fraction);

Thin wrapper for `gtk_progress_bar_set_fraction()` that uses the main window's progress bar.

Causes the progress bar to "fill in" the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive.

`fraction` : | fraction of the task that's been completed

### gva_main_statusbar_get_context_id ()

    guint               gva_main_statusbar_get_context_id   (const gchar *context_description);

Thin wrapper for `gtk_statusbar_get_context_id()` that uses the main window's status bar.

Returns a new context identifier, given a description of the actual context. Note that the description is not shown in the UI.

`context_description` : | textual description of what context the new message is being used in
Returns : | a context identifier

### gva_main_statusbar_push ()

    guint               gva_main_statusbar_push             (guint context_id,
                                                             const gchar *format,
                                                             ...);

Thin wrapper for `gtk_statusbar_push()` that uses the main window's status bar.

Pushes a new message onto the status bar's stack. As a convenience, the function takes a ``printf()``-style format string and variable length argument list.

`context_id` : | a context identifier
`format` : | a standard ``printf()`` format string
`...` : | the arguments to insert into the format string
Returns : | a message identifier that can be used with `gva_main_statusbar_remove()`

### gva_main_statusbar_pop ()

    void                gva_main_statusbar_pop              (guint context_id);

Thin wrapper for `gtk_statusbar_pop()` that uses the main window's status bar.

Removes the first message in the status bar's stack with the given context id.

Note that this may not change the displayed message, if the message at the top of the stack has a different context id.

`context_id` : | a context identifier

### gva_main_statusbar_remove ()

    void                gva_main_statusbar_remove           (guint context_id,
                                                             guint message_id);

Thin wrapper for `gtk_statusbar_remove()` that uses the main window's status bar.

Forces the removal of a message from a status bar's stack. The exact `context_id` and `message_id` must be specified.

`context_id` : | a context identifier
`message_id` : | a message identifier

### gva_main_execute_search ()

    void                gva_main_execute_search             (void);

Executes a game database search and configures the main window to display the results. More precisely, the function saves the search entry contents to GConf, switches to the Search Results view, forces an update, ensures a row in the resulting game list is selected, and gives focus to the main tree view.

The SQL expression used in the database search is retrieved from `gva_main_get_search_expression()`. It is applied while updating the Search Results view.

### gva_main_get_last_search_text ()

    gchar *             gva_main_get_last_search_text       (void);

Returns the most recent search entry text from either the current or previous session of GNOME Video Arcade.

Returns : | the most recent search text

### gva_main_set_last_search_text ()

    void                gva_main_set_last_search_text       (const gchar *text);

Writes `text` to GConf key `/apps/gnome-video-arcade/search`.

This is used to remember the search entry text from the previous session of GNOME Video Arcade so that the same text can be preset in the search entry at startup.

`text` : | the search entry text

### gva_main_get_last_selected_match ()

    gboolean            gva_main_get_last_selected_match    (gchar **column_name,
                                                             gchar **search_text);

Returns the most recently selected match in a search completion list from either the current or previous session of GNOME Video Arcade. If the completion feature was not used in the most recent search, `column_name` and `search_text` are set to `NULL` and the function returns `FALSE`.

`column_name` : | return location for the column name
`search_text` : | return location for the search text
Returns : | `TRUE` if match values were successfully retrieved from GConf, `FALSE` otherwise

### gva_main_set_last_selected_match ()

    void                gva_main_set_last_selected_match    (const gchar *column_name,
                                                             const gchar *search_text);

Writes `column_name` and `search_text` to GConf key `/apps/gnome-video-arcade/sql-expression` as a string pair.

This is used to remember whether the search results from the previous session of GNOME Video Arcade were the result of selecting a match from the search completion list. If so, the values are also used to restore the contents of the Search Results view.

`column_name` : | the column name of the completion match
`search_text` : | the search text of the completion match

### gva_main_search_entry_activate_cb ()

    void                gva_main_search_entry_activate_cb   (GtkEntry *entry);

Handler for "activate" signals to the search entry.

Saves the contents of the search entry and switches the main window to the "Search Results" view.

`entry` : | the search entry

### gva_main_search_entry_notify_cb ()

    void                gva_main_search_entry_notify_cb     (GtkEntry *entry,
                                                             GParamSpec *pspec);

Handler for "notify" signals to the search entry.

Hides the search interface when the search entry loses input focus.

`entry` : | the search entry
`pspec` : | a GParamSpec

### gva_main_search_query_tooltip_cb ()

    gboolean            gva_main_search_query_tooltip_cb    (GtkWidget *widget,
                                                             gint x,
                                                             gint y,
                                                             gboolean keyboard_mode,
                                                             GtkTooltip *tooltip);

Handler for "query-tooltip" signals to the search interface.

Displays some tips for searching.

`widget` : | the object which received the signal
`x` : | the x coordinate of the cursor position where the request has been emitted, relative to `widget->window`
`y` : | the y coordinate of the cursor position where the request has been emitted, relative to `widget->window`
`keyboard_mode` : | `TRUE` if the tooltip was triggerd using the keyboard
`tooltip` : | a GtkTooltip
Returns : | always `TRUE` (show the tooltip)

### gva_main_window_destroy_cb ()

    void                gva_main_window_destroy_cb          (GtkWindow *window);

Handler for "destroy" signals to the main window.

Activates the GVA_ACTION_QUIT action.

`window` : | the main window