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

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
} 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" and "sql".

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