rb-util: Rhythmbox Development Reference Manual

## rb-util rb-util — assorted utility functions |

## Functions

#define | RB_CHAIN_GOBJECT_METHOD()
gboolean | rb_true_function ()
gboolean | rb_false_function ()
gpointer | rb_null_function ()
gpointer | rb_copy_function ()
int | rb_gvalue_compare ()
int | rb_compare_gtimeval ()
int | rb_safe_strcmp ()
char * | rb_make_time_string ()
char * | rb_make_duration_string ()
char * | rb_make_elapsed_time_string ()
void | rb_threads_init ()
gboolean | rb_is_main_thread ()
gchar * | rb_search_fold ()
gchar ** | rb_string_split_words ()
gboolean | rb_string_list_equal ()
gboolean | rb_string_list_contains ()
GList * | rb_string_list_copy ()
void | rb_list_deep_free ()
void | rb_list_destroy_free ()
void | rb_slist_deep_free ()
gboolean | rb_str_in_strv ()
GList * | rb_collate_hash_table_keys ()
GList * | rb_collate_hash_table_values ()
GList * | rb_uri_list_parse ()
gboolean | rb_signal_accumulator_object_handled ()
gboolean | rb_signal_accumulator_value_handled ()
gboolean | rb_signal_accumulator_boolean_or ()
gboolean | rb_signal_accumulator_value_array ()
void | rb_value_array_append_data ()
void | rb_value_free ()
void | rb_assert_locked ()
void | rb_set_tree_view_column_fixed_width ()
GdkPixbuf * | rb_scale_pixbuf_to_size ()
void | (*RBDelayedSyncFunc) ()
void | rb_settings_delayed_sync ()
void | rb_menu_update_link ()

## Types and Values

#define | FFWD_OFFSET
#define | RWD_OFFSET

## 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.

## Functions

### 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.

[skip]

#### Parameters

dummy | unused |

#### Returns

`TRUE`

### rb_false_function ()

    gboolean
    rb_false_function (gpointer dummy);

Just returns `FALSE`, useful as a callback function.

[skip]

#### Parameters

dummy | unused |

#### Returns

`FALSE`

### rb_null_function ()

    gpointer
    rb_null_function (gpointer dummy);

Just returns NULL. Useful as a callback function.

[skip]

#### Parameters

dummy | unused |

#### Returns

NULL

### rb_copy_function ()

    gpointer
    rb_copy_function (gpointer data);

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

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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_threads_init ()

    void
    rb_threads_init (void);

Initializes various thread helpers. Must be called on startup.

[skip]

### 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.

#### Parameters

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.

#### Parameters

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.

[skip]

#### Parameters

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` .

[skip]

#### Parameters

list | list to check. | [element-type utf8]
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` .

[skip]

#### Parameters

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.

[skip]

#### Parameters

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` .

[skip]

#### Parameters

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.

[skip]

#### Parameters

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` .

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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` .

[skip]

#### Parameters

array | GArray to append to |
type | GType of the value being appended |
... | value to append |

### 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` .

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

menu | menu to update |
link_attr | attribute indicating the menu link to update |
target | new menu link target |

## Types and Values

### FFWD_OFFSET

    #define FFWD_OFFSET 20

### RWD_OFFSET

    #define RWD_OFFSET 10