rb-util

rb-util — assorted utility functions

Synopsis

#define             FFWD_OFFSET
#define             RWD_OFFSET
#define             RB_CHAIN_GOBJECT_METHOD             (klass,
                                                         method,
                                                         instance)
gboolean            rb_true_function                    (gpointer dummy);
gboolean            rb_false_function                   (gpointer dummy);
gpointer            rb_null_function                    (gpointer dummy);
gpointer            rb_copy_function                    (gpointer data);
int                 rb_gvalue_compare                   (GValue *a,
                                                         GValue *b);
int                 rb_compare_gtimeval                 (GTimeVal *a,
                                                         GTimeVal *b);
int                 rb_safe_strcmp                      (const char *a,
                                                         const char *b);
char *              rb_make_time_string                 (guint seconds);
char *              rb_make_duration_string             (guint duration);
char *              rb_make_elapsed_time_string         (guint elapsed,
                                                         guint duration,
                                                         gboolean show_remaining);
GtkWidget *         rb_image_new_from_stock             (const gchar *stock_id,
                                                         GtkIconSize size);
void                rb_threads_init                     (void);
gboolean            rb_is_main_thread                   (void);
gchar *             rb_search_fold                      (const char *original);
gchar **            rb_string_split_words               (const gchar *string);
gboolean            rb_string_list_equal                (GList *a,
                                                         GList *b);
gboolean            rb_string_list_contains             (GList *list,
                                                         const char *s);
GList *             rb_string_list_copy                 (GList *list);
void                rb_list_deep_free                   (GList *list);
void                rb_list_destroy_free                (GList *list,
                                                         GDestroyNotify destroyer);
void                rb_slist_deep_free                  (GSList *list);
gboolean            rb_str_in_strv                      (const char *needle,
                                                         const char **haystack);
GList *             rb_collate_hash_table_keys          (GHashTable *table);
GList *             rb_collate_hash_table_values        (GHashTable *table);
GList *             rb_uri_list_parse                   (const char *uri_list);
gboolean            rb_signal_accumulator_object_handled
                                                        (GSignalInvocationHint *hint,
                                                         GValue *return_accu,
                                                         const GValue *handler_return,
                                                         gpointer dummy);
gboolean            rb_signal_accumulator_value_handled (GSignalInvocationHint *hint,
                                                         GValue *return_accu,
                                                         const GValue *handler_return,
                                                         gpointer dummy);
gboolean            rb_signal_accumulator_boolean_or    (GSignalInvocationHint *hint,
                                                         GValue *return_accu,
                                                         const GValue *handler_return,
                                                         gpointer dummy);
gboolean            rb_signal_accumulator_value_array   (GSignalInvocationHint *hint,
                                                         GValue *return_accu,
                                                         const GValue *handler_return,
                                                         gpointer dummy);
void                rb_value_array_append_data          (GArray *array,
                                                         GType type,
                                                         ...);
void                rb_value_free                       (GValue *val);
void                rb_assert_locked                    (GMutex *mutex);
void                rb_set_tree_view_column_fixed_width (GtkWidget *treeview,
                                                         GtkTreeViewColumn *column,
                                                         GtkCellRenderer *renderer,
                                                         const char **strings,
                                                         int padding);
GdkPixbuf *         rb_scale_pixbuf_to_size             (GdkPixbuf *pixbuf,
                                                         GtkIconSize size);
void                (*RBDelayedSyncFunc)                (GSettings *settings,
                                                         gpointer data);
void                rb_settings_delayed_sync            (GSettings *settings,
                                                         RBDelayedSyncFunc sync_func,
                                                         gpointer data,
                                                         GDestroyNotify destroy);
void                rb_menu_update_link                 (GMenu *menu,
                                                         const char *link_attr,
                                                         GMenuModel *target);

Description

This is a dumping ground for utility functions that may or may not be generally useful in Rhythmbox or elsewhere. Things end up here if they're clever or if they're used all over the place.

Details

FFWD_OFFSET

#define FFWD_OFFSET 20


RWD_OFFSET

#define RWD_OFFSET 10


RB_CHAIN_GOBJECT_METHOD()

#define             RB_CHAIN_GOBJECT_METHOD(klass, method, instance)


rb_true_function ()

gboolean            rb_true_function                    (gpointer dummy);

Just returns TRUE, useful as a callback function.

dummy :

unused

Returns :

TRUE

rb_false_function ()

gboolean            rb_false_function                   (gpointer dummy);

Just returns FALSE, useful as a callback function.

dummy :

unused

Returns :

FALSE

rb_null_function ()

gpointer            rb_null_function                    (gpointer dummy);

Just returns NULL. Useful as a callback function.

dummy :

unused

Returns :

NULL

rb_copy_function ()

gpointer            rb_copy_function                    (gpointer data);

Just returns its first argument. Useful as a callback function.

data :

generic argument

Returns :

data

rb_gvalue_compare ()

int                 rb_gvalue_compare                   (GValue *a,
                                                         GValue *b);

Compares a and b for sorting. a and b must contain the same value type for the comparison to be valid. Comparisons for some value types are not particularly useful.

a :

left hand side

b :

right hand size

Returns :

-1 if a < b, 0 if a == b, 1 if a > b

rb_compare_gtimeval ()

int                 rb_compare_gtimeval                 (GTimeVal *a,
                                                         GTimeVal *b);

Compares two GTimeVal structures for sorting.

a :

left hand side

b :

right hand size

Returns :

-1 if a < b, 0 if a == b, 1 if a > b

rb_safe_strcmp ()

int                 rb_safe_strcmp                      (const char *a,
                                                         const char *b);


rb_make_time_string ()

char *              rb_make_time_string                 (guint seconds);

Constructs a string describing the specified time.

seconds :

time in seconds

Returns :

time string. [transfer full]

rb_make_duration_string ()

char *              rb_make_duration_string             (guint duration);

Constructs a string describing the specified duration. The string describes hours, minutes, and seconds, and its format is localised.

duration :

duration in seconds

Returns :

duration string. [transfer full]

rb_make_elapsed_time_string ()

char *              rb_make_elapsed_time_string         (guint elapsed,
                                                         guint duration,
                                                         gboolean show_remaining);

Constructs a string describing a playback position. The string describes hours, minutes, and seconds, and its format is localised. The string can describe either the elapsed time or the time remaining.

elapsed :

elapsed time (in seconds)

duration :

duration (in seconds)

show_remaining :

if TRUE, show the remaining time, otherwise show elapsed time

Returns :

elapsed/remaining time string. [transfer full]

rb_image_new_from_stock ()

GtkWidget *         rb_image_new_from_stock             (const gchar *stock_id,
                                                         GtkIconSize size);

Same as gtk_image_new_from_stock except that it mirrors the icons for RTL languages.

stock_id :

stock image id

size :

requested icon size

Returns :

a GtkImage of the requested stock item. [transfer full]

rb_threads_init ()

void                rb_threads_init                     (void);

Initializes various thread helpers. Must be called on startup.


rb_is_main_thread ()

gboolean            rb_is_main_thread                   (void);

Checks if currently executing on the main thread.

Returns :

TRUE if on the main thread

rb_search_fold ()

gchar *             rb_search_fold                      (const char *original);

Returns a case-folded and punctuation-stripped version of original, useful for performing text searches.

original :

the string to fold

Returns :

case-folded string. [transfer full]

rb_string_split_words ()

gchar **            rb_string_split_words               (const gchar *string);

Splits string on word boundaries using Unicode character definitions.

string :

the string to split

Returns :

NULL-terminated array of strings. [array zero-terminated=1][transfer full]

rb_string_list_equal ()

gboolean            rb_string_list_equal                (GList *a,
                                                         GList *b);

Checks if a and b contain exactly the same set of strings, regardless of order.

a :

list of strings to compare. [element-type utf8]

b :

other list of strings to compare. [element-type utf8]

Returns :

TRUE if the lists contain all the same strings

rb_string_list_contains ()

gboolean            rb_string_list_contains             (GList *list,
                                                         const char *s);

Checks if list contains the string s.

list :

(element-type utf8) list to check

s :

string to check for

Returns :

TRUE if found

rb_string_list_copy ()

GList *             rb_string_list_copy                 (GList *list);

Creates a deep copy of list.

list :

list of strings to copy. [element-type utf8]

Returns :

copied list. [element-type utf8][transfer full]

rb_list_deep_free ()

void                rb_list_deep_free                   (GList *list);

Frees each element of list and list itself.

list :

list to free. [element-type any][transfer full]

rb_list_destroy_free ()

void                rb_list_destroy_free                (GList *list,
                                                         GDestroyNotify destroyer);

Calls destroyer for each element in list, then frees list.

list :

list to destroy

destroyer :

function to call to free elements of list

rb_slist_deep_free ()

void                rb_slist_deep_free                  (GSList *list);

Frees each element of list and list itself.

list :

list to free. [element-type any][transfer full]

rb_str_in_strv ()

gboolean            rb_str_in_strv                      (const char *needle,
                                                         const char **haystack);

Checks if needle is present in the NULL-terminated string array haystack.

needle :

string to search for

haystack :

array of strings to search

Returns :

TRUE if found

rb_collate_hash_table_keys ()

GList *             rb_collate_hash_table_keys          (GHashTable *table);

Returns a GList containing all keys from table. The keys are not copied.

table :

GHashTable to collate

Returns :

GList of keys. [element-type any][transfer container]

rb_collate_hash_table_values ()

GList *             rb_collate_hash_table_values        (GHashTable *table);

Returns a GList containing all values from table. The values are not copied.

table :

GHashTable to collate

Returns :

GList of values. [element-type any][transfer container]

rb_uri_list_parse ()

GList *             rb_uri_list_parse                   (const char *uri_list);

Converts a single string containing a list of URIs into a GList of URI strings.

uri_list :

string containing URIs to parse

Returns :

GList of URI strings. [element-type utf8][transfer full]

rb_signal_accumulator_object_handled ()

gboolean            rb_signal_accumulator_object_handled
                                                        (GSignalInvocationHint *hint,
                                                         GValue *return_accu,
                                                         const GValue *handler_return,
                                                         gpointer dummy);

A GSignalAccumulator that aborts the signal emission after the first handler to return a value, and returns the value returned by that handler. This is the opposite behaviour from what you get when no accumulator is specified, where the last signal handler wins.

hint :

a GSignalInvocationHint

return_accu :

holds the accumulated return value

handler_return :

holds the return value to be accumulated

dummy :

user data (unused)

Returns :

FALSE to abort signal emission, TRUE to continue

rb_signal_accumulator_value_handled ()

gboolean            rb_signal_accumulator_value_handled (GSignalInvocationHint *hint,
                                                         GValue *return_accu,
                                                         const GValue *handler_return,
                                                         gpointer dummy);

A GSignalAccumulator that aborts the signal emission after the first handler to return a value, and returns the value returned by that handler. This is the opposite behaviour from what you get when no accumulator is specified, where the last signal handler wins.

hint :

a GSignalInvocationHint

return_accu :

holds the accumulated return value

handler_return :

holds the return value to be accumulated

dummy :

user data (unused)

Returns :

FALSE to abort signal emission, TRUE to continue

rb_signal_accumulator_boolean_or ()

gboolean            rb_signal_accumulator_boolean_or    (GSignalInvocationHint *hint,
                                                         GValue *return_accu,
                                                         const GValue *handler_return,
                                                         gpointer dummy);

A GSignalAccumulator used to return the boolean OR of all returned (boolean) values.

hint :

a GSignalInvocationHint

return_accu :

holds the accumulated return value

handler_return :

holds the return value to be accumulated

dummy :

user data (unused)

Returns :

FALSE to abort signal emission, TRUE to continue

rb_signal_accumulator_value_array ()

gboolean            rb_signal_accumulator_value_array   (GSignalInvocationHint *hint,
                                                         GValue *return_accu,
                                                         const GValue *handler_return,
                                                         gpointer dummy);

A GSignalAccumulator used to combine all returned values into a GArray of GValue instances.

hint :

a GSignalInvocationHint

return_accu :

holds the accumulated return value

handler_return :

holds the return value to be accumulated

dummy :

user data (unused)

Returns :

FALSE to abort signal emission, TRUE to continue

rb_value_array_append_data ()

void                rb_value_array_append_data          (GArray *array,
                                                         GType type,
                                                         ...);

Appends a single value to array, collecting it from Varargs.

array :

GArray to append to

type :

GType of the value being appended

rb_value_free ()

void                rb_value_free                       (GValue *val);

Unsets and frees val. val must have been allocated using g_slice_new or g_slice_new0.

val :

a GValue. [transfer full]

rb_assert_locked ()

void                rb_assert_locked                    (GMutex *mutex);

Asserts that mutex is currently locked. Does not work with all mutex implementations.

mutex :

a GMutex

rb_set_tree_view_column_fixed_width ()

void                rb_set_tree_view_column_fixed_width (GtkWidget *treeview,
                                                         GtkTreeViewColumn *column,
                                                         GtkCellRenderer *renderer,
                                                         const char **strings,
                                                         int padding);

Sets a fixed size for a tree view column based on a set of strings to be displayed in the column.

treeview :

the GtkTreeView containing the column

column :

the GtkTreeViewColumn to size

renderer :

the GtkCellRenderer used in the column

strings :

a NULL-terminated set of strings to base the size on. [array zero-terminated=1]

padding :

a small amount of extra padding for the column

rb_scale_pixbuf_to_size ()

GdkPixbuf *         rb_scale_pixbuf_to_size             (GdkPixbuf *pixbuf,
                                                         GtkIconSize size);

Creates a new GdkPixbuf from the original one, for a target of size, respecting the aspect ratio of the image.

pixbuf :

the GdkPixbuf containing the original image

size :

a stock icon size

Returns :

scaled GdkPixbuf. [transfer full]

RBDelayedSyncFunc ()

void                (*RBDelayedSyncFunc)                (GSettings *settings,
                                                         gpointer data);


rb_settings_delayed_sync ()

void                rb_settings_delayed_sync            (GSettings *settings,
                                                         RBDelayedSyncFunc sync_func,
                                                         gpointer data,
                                                         GDestroyNotify destroy);

Synchronizes settings in the settings instance after 500ms has elapsed with no further changes.

settings :

GSettings instance

sync_func :

function to call. [allow-none]

data :

data to pass to func. [allow-none]

destroy :

function to use to free data. [allow-none]

rb_menu_update_link ()

void                rb_menu_update_link                 (GMenu *menu,
                                                         const char *link_attr,
                                                         GMenuModel *target);

Updates a submenu link to point to the specified target menu.

menu :

menu to update

link_attr :

attribute indicating the menu link to update

target :

new menu link target