## gva-util

gva-util — Miscellaneous Utilities

## Synopsis

    gchar *             gva_choose_inpname                  (const gchar *game);
    gchar *             gva_find_data_file                  (const gchar *basename);
    GvaDebugFlags       gva_get_debug_flags                 (void);
    enum                GvaDebugFlags;
    const gchar *       gva_get_last_version                (void);
    gchar *             gva_get_monospace_font_name         (void);
    void                gva_get_time_elapsed                (GTimeVal *start_time,
                                                             GTimeVal *time_elapsed);
    const gchar *       gva_get_user_data_dir               (void);
    void                gva_help_display                    (GtkWindow *parent,
                                                             const gchar *link_id);
    gchar *             gva_search_collate_key              (const gchar *string);
    gboolean            gva_spawn_with_pipes                (const gchar *command_line,
                                                             GPid *child_pid,
                                                             gint *standard_input,
                                                             gint *standard_output,
                                                             gint *standard_error,
                                                             GError **error);

## Description

These are miscellaneous utility functions that are used throughout the application.

## Details

### gva_choose_inpname ()

    gchar *             gva_choose_inpname                  (const gchar *game);

Returns the name of a MAME input file for `game` that does not already exist. For example, given the game "pacman" the function will return the first filename that does not already exist: "pacman.inp", "pacman-1.inp", "pacman-2.inp", etc.

`game` : | the name of a game
Returns : | a newly-allocated input filename for `game`

### gva_find_data_file ()

    gchar *             gva_find_data_file                  (const gchar *basename);

Searches for a file named `basename` in a number of standard system-wide directories and returns a newly-allocated string containing the path to the first match. The string should be freed with `g_free()`. If no match is found the function returns `NULL`.

`basename` : | the base name of the file to search for
Returns : | the pathname of the first match, or `NULL` if no match was found

### gva_get_debug_flags ()

    GvaDebugFlags       gva_get_debug_flags                 (void);

Returns a set of bit flags indicating what kinds of debugging messages are enabled through the GVA_DEBUG environment variable.

Returns : | bitwise combination of GvaDebugFlags values

### enum GvaDebugFlags

    typedef enum
    {
            GVA_DEBUG_NONE = 0,
            GVA_DEBUG_MAME = 1 << 0,
            GVA_DEBUG_SQL  = 1 << 1,
            GVA_DEBUG_IO   = 1 << 2,
            GVA_DEBUG_INP  = 1 << 3
    } GvaDebugFlags;

These flags indicate which types of debugging messages will be triggered at runtime. Debugging messages can be triggered by setting the GVA_DEBUG environment variable to a colon-separated list of "mame", "sql" and "io".

`GVA_DEBUG_NONE` | Print no messages.
`GVA_DEBUG_MAME` | Print shell commands invoking MAME.
`GVA_DEBUG_SQL` | Print SQL commands to the game database.
`GVA_DEBUG_IO` | Print all communication between GVA and MAME.
`GVA_DEBUG_INP` | Print information about input files.

### gva_get_last_version ()

    const gchar *       gva_get_last_version                (void);

Returns the most recently run version of GNOME Video Arcade prior to the current run. This is used to detect GNOME Video Arcade upgrades.

Returns : | the most recently run version of GNOME Video Arcade

### gva_get_monospace_font_name ()

    gchar *             gva_get_monospace_font_name         (void);

Returns the user's preferred fixed-width font name. The return value is a newly-allocated string and should be freed with `g_free()`.

Returns : | the name of a fixed-width font

### gva_get_time_elapsed ()

    void                gva_get_time_elapsed                (GTimeVal *start_time,
                                                             GTimeVal *time_elapsed);

Writes the time elapsed since `start_time` to `time_elapsed`. Set the start time by calling `g_get_current_time()`.

`start_time` : | a start time
`time_elapsed` : | location to put the time elasped

### gva_get_user_data_dir ()

    const gchar *       gva_get_user_data_dir               (void);

Returns the directory where user-specific application data is stored. The function also creates the directory the first time it is called.

Returns : | user-specific application data directory

### gva_help_display ()

    void                gva_help_display                    (GtkWindow *parent,
                                                             const gchar *link_id);

Opens the user documentation to the section given by `link_id`, or to the table of contents if `link_id` is `NULL`. If the user documentation cannot be opened, it presents a dialog describing the error. The dialog is set as transient to `parent` if `parent` is `NULL`.

`parent` : | a parent GtkWindow or `NULL`
`link_id` : | help section to present or `NULL`

### gva_search_collate_key ()

    gchar *             gva_search_collate_key              (const gchar *string);

Converts a string into a collation key that can be compared with other collation keys produced by the same function using `strcmp()`.

Specifically, the function filters out spaces and punctuation from `string` for easier comparison with what a human is likely to type in an interactive search. e.g. Typing "mspacman" will match "Ms. Pac-Man".

`string` : | a string
Returns : | a newly-allocated collation key

### gva_spawn_with_pipes ()

    gboolean            gva_spawn_with_pipes                (const gchar *command_line,
                                                             GPid *child_pid,
                                                             gint *standard_input,
                                                             gint *standard_output,
                                                             gint *standard_error,
                                                             GError **error);

Convenience function that passes `command_line` to `g_shell_parse_argv()`, and passes the resulting argument list to `gdk_spawn_on_screen_with_pipes()`. If an error occurs, it results `FALSE` and sets `error`.

`command_line` : | a command line
`child_pid` : | return location for child process ID, or `NULL`
`standard_input` : | return location for file descriptor to write to child's stdin, or `NULL`
`standard_output` : | return location for file descriptor to write to child's stdout, or `NULL`
`standard_error` : | return location for file descriptor to write to child's stderr, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if successful, `FALSE` if an error occurred