2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
<refentry id="rhythmbox-rb-util">
6
<refentrytitle role="top_of_page" id="rhythmbox-rb-util.top_of_page">rb-util</refentrytitle>
7
<manvolnum>3</manvolnum>
8
<refmiscinfo>RHYTHMBOX Library</refmiscinfo>
12
<refname>rb-util</refname>
13
<refpurpose>assorted utility functions</refpurpose>
16
<refsynopsisdiv id="rhythmbox-rb-util.synopsis" role="synopsis">
17
<title role="synopsis.title">Synopsis</title>
20
<link linkend="gboolean">gboolean</link> <link linkend="rb-true-function">rb_true_function</link> (<link linkend="gpointer">gpointer</link> dummy);
21
<link linkend="gboolean">gboolean</link> <link linkend="rb-false-function">rb_false_function</link> (<link linkend="gpointer">gpointer</link> dummy);
22
<link linkend="gpointer">gpointer</link> <link linkend="rb-null-function">rb_null_function</link> (<link linkend="gpointer">gpointer</link> dummy);
23
<link linkend="gpointer">gpointer</link> <link linkend="rb-copy-function">rb_copy_function</link> (<link linkend="gpointer">gpointer</link> data);
24
<link linkend="int">int</link> <link linkend="rb-gvalue-compare">rb_gvalue_compare</link> (<link linkend="GValue">GValue</link> *a,
25
<link linkend="GValue">GValue</link> *b);
26
<link linkend="int">int</link> <link linkend="rb-compare-gtimeval">rb_compare_gtimeval</link> (<link linkend="GTimeVal">GTimeVal</link> *a,
27
<link linkend="GTimeVal">GTimeVal</link> *b);
28
<link linkend="GtkWidget">GtkWidget</link> * <link linkend="rb-image-new-from-stock">rb_image_new_from_stock</link> (const <link linkend="gchar">gchar</link> *stock_id,
29
<link linkend="GtkIconSize">GtkIconSize</link> size);
30
<link linkend="void">void</link> <link linkend="rb-gtk-action-popup-menu">rb_gtk_action_popup_menu</link> (<link linkend="GtkUIManager">GtkUIManager</link> *uimanager,
31
const <link linkend="char">char</link> *path);
32
<link linkend="gboolean">gboolean</link> <link linkend="rb-is-main-thread">rb_is_main_thread</link> (void);
33
<link linkend="void">void</link> <link linkend="rb-assert-locked">rb_assert_locked</link> (<link linkend="GMutex">GMutex</link> *mutex);
34
<link linkend="void">void</link> <link linkend="rb-threads-init">rb_threads_init</link> (void);
35
<link linkend="gchar">gchar</link>** <link linkend="rb-string-split-words">rb_string_split_words</link> (const <link linkend="gchar">gchar</link> *string);
36
<link linkend="gchar">gchar</link>* <link linkend="rb-search-fold">rb_search_fold</link> (const <link linkend="char">char</link> *original);
37
<link linkend="char">char</link> * <link linkend="rb-make-duration-string">rb_make_duration_string</link> (<link linkend="guint">guint</link> duration);
38
<link linkend="char">char</link> * <link linkend="rb-make-elapsed-time-string">rb_make_elapsed_time_string</link> (<link linkend="guint">guint</link> elapsed,
39
<link linkend="guint">guint</link> duration,
40
<link linkend="gboolean">gboolean</link> show_remaining);
41
<link linkend="gboolean">gboolean</link> <link linkend="rb-string-list-equal">rb_string_list_equal</link> (<link linkend="GList">GList</link> *a,
42
<link linkend="GList">GList</link> *b);
43
<link linkend="GList">GList</link>* <link linkend="rb-string-list-copy">rb_string_list_copy</link> (<link linkend="GList">GList</link> *list);
44
<link linkend="gboolean">gboolean</link> <link linkend="rb-string-list-contains">rb_string_list_contains</link> (<link linkend="GList">GList</link> *list,
45
const <link linkend="char">char</link> *s);
46
<link linkend="void">void</link> <link linkend="rb-list-destroy-free">rb_list_destroy_free</link> (<link linkend="GList">GList</link> *list,
47
<link linkend="GDestroyNotify">GDestroyNotify</link> destroyer);
48
<link linkend="void">void</link> <link linkend="rb-list-deep-free">rb_list_deep_free</link> (<link linkend="GList">GList</link> *list);
49
<link linkend="void">void</link> <link linkend="rb-slist-deep-free">rb_slist_deep_free</link> (<link linkend="GSList">GSList</link> *list);
50
<link linkend="GList">GList</link>* <link linkend="rb-collate-hash-table-keys">rb_collate_hash_table_keys</link> (<link linkend="GHashTable">GHashTable</link> *table);
51
<link linkend="GList">GList</link>* <link linkend="rb-collate-hash-table-values">rb_collate_hash_table_values</link> (<link linkend="GHashTable">GHashTable</link> *table);
52
<link linkend="GList">GList</link>* <link linkend="rb-uri-list-parse">rb_uri_list_parse</link> (const <link linkend="char">char</link> *uri_list);
53
<link linkend="char">char</link>* <link linkend="rb-mime-get-friendly-name">rb_mime_get_friendly_name</link> (const <link linkend="char">char</link> *mime_type);
54
<link linkend="gboolean">gboolean</link> <link linkend="rb-signal-accumulator-object-handled">rb_signal_accumulator_object_handled</link>
55
(<link linkend="GSignalInvocationHint">GSignalInvocationHint</link> *hint,
56
<link linkend="GValue">GValue</link> *return_accu,
57
const <link linkend="GValue">GValue</link> *handler_return,
58
<link linkend="gpointer">gpointer</link> dummy);
59
<link linkend="gboolean">gboolean</link> <link linkend="rb-signal-accumulator-value-array">rb_signal_accumulator_value_array</link> (<link linkend="GSignalInvocationHint">GSignalInvocationHint</link> *hint,
60
<link linkend="GValue">GValue</link> *return_accu,
61
const <link linkend="GValue">GValue</link> *handler_return,
62
<link linkend="gpointer">gpointer</link> dummy);
63
<link linkend="void">void</link> <link linkend="rb-value-array-append-data">rb_value_array_append_data</link> (<link linkend="GValueArray">GValueArray</link> *array,
64
<link linkend="GType">GType</link> type,
66
<link linkend="void">void</link> <link linkend="rb-value-free">rb_value_free</link> (<link linkend="GValue">GValue</link> *val);
67
<link linkend="gboolean">gboolean</link> <link linkend="rb-str-in-strv">rb_str_in_strv</link> (const <link linkend="char">char</link> *needle,
68
<link linkend="char">char</link> **haystack);
69
<link linkend="void">void</link> <link linkend="rb-set-tree-view-column-fixed-width">rb_set_tree_view_column_fixed_width</link> (<link linkend="GtkWidget">GtkWidget</link> *treeview,
70
<link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> *column,
71
<link linkend="GtkCellRenderer">GtkCellRenderer</link> *renderer,
72
const <link linkend="char">char</link> **strings,
73
<link linkend="int">int</link> padding);
74
<link linkend="GdkPixbuf">GdkPixbuf</link> * <link linkend="rb-scale-pixbuf-to-size">rb_scale_pixbuf_to_size</link> (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
75
<link linkend="GtkIconSize">GtkIconSize</link> size);
87
<refsect1 id="rhythmbox-rb-util.description" role="desc">
88
<title role="desc.title">Description</title>
90
This is a dumping ground for utility functions that may or may not
91
be generally useful in Rhythmbox or elsewhere. Things end up here
92
if they're clever or if they're used all over the place.</para>
97
<refsect1 id="rhythmbox-rb-util.details" role="details">
98
<title role="details.title">Details</title>
99
<refsect2 id="rb-true-function" role="function">
100
<title>rb_true_function ()</title>
101
<indexterm zone="rb-true-function"><primary sortas="rb_true_function">rb_true_function</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_true_function (<link linkend="gpointer">gpointer</link> dummy);</programlisting>
103
Just returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, useful as a callback function.</para>
105
</para><variablelist role="params">
106
<varlistentry><term><parameter>dummy</parameter> :</term>
107
<listitem><simpara> unused
108
</simpara></listitem></varlistentry>
109
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>
110
</simpara></listitem></varlistentry>
111
</variablelist></refsect2>
112
<refsect2 id="rb-false-function" role="function">
113
<title>rb_false_function ()</title>
114
<indexterm zone="rb-false-function"><primary sortas="rb_false_function">rb_false_function</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_false_function (<link linkend="gpointer">gpointer</link> dummy);</programlisting>
116
Just returns <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, useful as a callback function.</para>
118
</para><variablelist role="params">
119
<varlistentry><term><parameter>dummy</parameter> :</term>
120
<listitem><simpara> unused
121
</simpara></listitem></varlistentry>
122
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>
123
</simpara></listitem></varlistentry>
124
</variablelist></refsect2>
125
<refsect2 id="rb-null-function" role="function">
126
<title>rb_null_function ()</title>
127
<indexterm zone="rb-null-function"><primary sortas="rb_null_function">rb_null_function</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> rb_null_function (<link linkend="gpointer">gpointer</link> dummy);</programlisting>
129
Just returns NULL. Useful as a callback function.</para>
131
</para><variablelist role="params">
132
<varlistentry><term><parameter>dummy</parameter> :</term>
133
<listitem><simpara> unused
134
</simpara></listitem></varlistentry>
135
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> NULL
136
</simpara></listitem></varlistentry>
137
</variablelist></refsect2>
138
<refsect2 id="rb-copy-function" role="function">
139
<title>rb_copy_function ()</title>
140
<indexterm zone="rb-copy-function"><primary sortas="rb_copy_function">rb_copy_function</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> rb_copy_function (<link linkend="gpointer">gpointer</link> data);</programlisting>
142
Just returns its first argument. Useful as a callback function.</para>
144
</para><variablelist role="params">
145
<varlistentry><term><parameter>data</parameter> :</term>
146
<listitem><simpara> generic argument
147
</simpara></listitem></varlistentry>
148
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>data</parameter>
149
</simpara></listitem></varlistentry>
150
</variablelist></refsect2>
151
<refsect2 id="rb-gvalue-compare" role="function">
152
<title>rb_gvalue_compare ()</title>
153
<indexterm zone="rb-gvalue-compare"><primary sortas="rb_gvalue_compare">rb_gvalue_compare</primary></indexterm><programlisting><link linkend="int">int</link> rb_gvalue_compare (<link linkend="GValue">GValue</link> *a,
154
<link linkend="GValue">GValue</link> *b);</programlisting>
156
Compares <parameter>a</parameter> and <parameter>b</parameter> for sorting. <parameter>a</parameter> and <parameter>b</parameter> must contain the same value
157
type for the comparison to be valid. Comparisons for some value types
158
are not particularly useful.</para>
160
</para><variablelist role="params">
161
<varlistentry><term><parameter>a</parameter> :</term>
162
<listitem><simpara> left hand side
163
</simpara></listitem></varlistentry>
164
<varlistentry><term><parameter>b</parameter> :</term>
165
<listitem><simpara> right hand size
166
</simpara></listitem></varlistentry>
167
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> -1 if <parameter>a</parameter> < <parameter>b</parameter>, 0 if <parameter>a</parameter> == <parameter>b</parameter>, 1 if <parameter>a</parameter> > <parameter>b</parameter>
168
</simpara></listitem></varlistentry>
169
</variablelist></refsect2>
170
<refsect2 id="rb-compare-gtimeval" role="function">
171
<title>rb_compare_gtimeval ()</title>
172
<indexterm zone="rb-compare-gtimeval"><primary sortas="rb_compare_gtimeval">rb_compare_gtimeval</primary></indexterm><programlisting><link linkend="int">int</link> rb_compare_gtimeval (<link linkend="GTimeVal">GTimeVal</link> *a,
173
<link linkend="GTimeVal">GTimeVal</link> *b);</programlisting>
175
Compares two <link linkend="GTimeval"><type>GTimeval</type></link> structures for sorting.</para>
177
</para><variablelist role="params">
178
<varlistentry><term><parameter>a</parameter> :</term>
179
<listitem><simpara> left hand side
180
</simpara></listitem></varlistentry>
181
<varlistentry><term><parameter>b</parameter> :</term>
182
<listitem><simpara> right hand size
183
</simpara></listitem></varlistentry>
184
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> -1 if <parameter>a</parameter> < <parameter>b</parameter>, 0 if <parameter>a</parameter> == <parameter>b</parameter>, 1 if <parameter>a</parameter> > <parameter>b</parameter>
185
</simpara></listitem></varlistentry>
186
</variablelist></refsect2>
187
<refsect2 id="rb-image-new-from-stock" role="function">
188
<title>rb_image_new_from_stock ()</title>
189
<indexterm zone="rb-image-new-from-stock"><primary sortas="rb_image_new_from_stock">rb_image_new_from_stock</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> * rb_image_new_from_stock (const <link linkend="gchar">gchar</link> *stock_id,
190
<link linkend="GtkIconSize">GtkIconSize</link> size);</programlisting>
192
Same as <parameter>gtk_image_new_from_stock</parameter> except that it mirrors the icons for RTL
195
</para><variablelist role="params">
196
<varlistentry><term><parameter>stock_id</parameter> :</term>
197
<listitem><simpara> stock image id
198
</simpara></listitem></varlistentry>
199
<varlistentry><term><parameter>size</parameter> :</term>
200
<listitem><simpara> requested icon size
201
</simpara></listitem></varlistentry>
202
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GtkImage"><type>GtkImage</type></link> of the requested stock item
203
</simpara></listitem></varlistentry>
204
</variablelist></refsect2>
205
<refsect2 id="rb-gtk-action-popup-menu" role="function">
206
<title>rb_gtk_action_popup_menu ()</title>
207
<indexterm zone="rb-gtk-action-popup-menu"><primary sortas="rb_gtk_action_popup_menu">rb_gtk_action_popup_menu</primary></indexterm><programlisting><link linkend="void">void</link> rb_gtk_action_popup_menu (<link linkend="GtkUIManager">GtkUIManager</link> *uimanager,
208
const <link linkend="char">char</link> *path);</programlisting>
210
Simple shortcut for getting a popup menu from a <link linkend="GtkUIManager"><type>GtkUIManager</type></link> and
211
displaying it.</para>
213
</para><variablelist role="params">
214
<varlistentry><term><parameter>uimanager</parameter> :</term>
215
<listitem><simpara> a <link linkend="GtkUIManager"><type>GtkUIManager</type></link>
216
</simpara></listitem></varlistentry>
217
<varlistentry><term><parameter>path</parameter> :</term>
218
<listitem><simpara> UI path for the popup to display
219
</simpara></listitem></varlistentry>
220
</variablelist></refsect2>
221
<refsect2 id="rb-is-main-thread" role="function">
222
<title>rb_is_main_thread ()</title>
223
<indexterm zone="rb-is-main-thread"><primary sortas="rb_is_main_thread">rb_is_main_thread</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_is_main_thread (void);</programlisting>
225
Checks if currently executing on the main thread.</para>
227
</para><variablelist role="params">
228
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if on the main thread
229
</simpara></listitem></varlistentry>
230
</variablelist></refsect2>
231
<refsect2 id="rb-assert-locked" role="function">
232
<title>rb_assert_locked ()</title>
233
<indexterm zone="rb-assert-locked"><primary sortas="rb_assert_locked">rb_assert_locked</primary></indexterm><programlisting><link linkend="void">void</link> rb_assert_locked (<link linkend="GMutex">GMutex</link> *mutex);</programlisting>
235
Asserts that <parameter>mutex</parameter> is currently locked. Does not work with all
236
mutex implementations.</para>
238
</para><variablelist role="params">
239
<varlistentry><term><parameter>mutex</parameter> :</term>
240
<listitem><simpara> a <link linkend="GMutex"><type>GMutex</type></link>
241
</simpara></listitem></varlistentry>
242
</variablelist></refsect2>
243
<refsect2 id="rb-threads-init" role="function">
244
<title>rb_threads_init ()</title>
245
<indexterm zone="rb-threads-init"><primary sortas="rb_threads_init">rb_threads_init</primary></indexterm><programlisting><link linkend="void">void</link> rb_threads_init (void);</programlisting>
247
Initializes various thread helpers. Must be called on startup.</para>
250
<refsect2 id="rb-string-split-words" role="function">
251
<title>rb_string_split_words ()</title>
252
<indexterm zone="rb-string-split-words"><primary sortas="rb_string_split_words">rb_string_split_words</primary></indexterm><programlisting><link linkend="gchar">gchar</link>** rb_string_split_words (const <link linkend="gchar">gchar</link> *string);</programlisting>
254
Splits <parameter>string</parameter> on word boundaries using Unicode character definitions.</para>
256
</para><variablelist role="params">
257
<varlistentry><term><parameter>string</parameter> :</term>
258
<listitem><simpara> the string to split
259
</simpara></listitem></varlistentry>
260
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> NULL-terminated array of strings, must be freed by caller (see <parameter>g_strfreev</parameter>)
261
</simpara></listitem></varlistentry>
262
</variablelist></refsect2>
263
<refsect2 id="rb-search-fold" role="function">
264
<title>rb_search_fold ()</title>
265
<indexterm zone="rb-search-fold"><primary sortas="rb_search_fold">rb_search_fold</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* rb_search_fold (const <link linkend="char">char</link> *original);</programlisting>
267
Returns a case-folded and punctuation-stripped version of <parameter>original</parameter>, useful
268
for performing text searches.</para>
270
</para><variablelist role="params">
271
<varlistentry><term><parameter>original</parameter> :</term>
272
<listitem><simpara> the string to fold
273
</simpara></listitem></varlistentry>
274
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> case-folded string, must be freed by caller.
275
</simpara></listitem></varlistentry>
276
</variablelist></refsect2>
277
<refsect2 id="rb-make-duration-string" role="function">
278
<title>rb_make_duration_string ()</title>
279
<indexterm zone="rb-make-duration-string"><primary sortas="rb_make_duration_string">rb_make_duration_string</primary></indexterm><programlisting><link linkend="char">char</link> * rb_make_duration_string (<link linkend="guint">guint</link> duration);</programlisting>
281
Constructs a string describing the specified duration. The string
282
describes hours, minutes, and seconds, and its format is localised.</para>
284
</para><variablelist role="params">
285
<varlistentry><term><parameter>duration</parameter> :</term>
286
<listitem><simpara> duration in seconds
287
</simpara></listitem></varlistentry>
288
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> duration string, must be freed by caller.
289
</simpara></listitem></varlistentry>
290
</variablelist></refsect2>
291
<refsect2 id="rb-make-elapsed-time-string" role="function">
292
<title>rb_make_elapsed_time_string ()</title>
293
<indexterm zone="rb-make-elapsed-time-string"><primary sortas="rb_make_elapsed_time_string">rb_make_elapsed_time_string</primary></indexterm><programlisting><link linkend="char">char</link> * rb_make_elapsed_time_string (<link linkend="guint">guint</link> elapsed,
294
<link linkend="guint">guint</link> duration,
295
<link linkend="gboolean">gboolean</link> show_remaining);</programlisting>
297
Constructs a string describing a playback position. The string describes hours,
298
minutes, and seconds, and its format is localised. The string can describe either
299
the elapsed time or the time remaining.</para>
301
</para><variablelist role="params">
302
<varlistentry><term><parameter>elapsed</parameter> :</term>
303
<listitem><simpara> elapsed time (in seconds)
304
</simpara></listitem></varlistentry>
305
<varlistentry><term><parameter>duration</parameter> :</term>
306
<listitem><simpara> duration (in seconds)
307
</simpara></listitem></varlistentry>
308
<varlistentry><term><parameter>show_remaining</parameter> :</term>
309
<listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, show the remaining time, otherwise show elapsed time
310
</simpara></listitem></varlistentry>
311
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> elapsed/remaining time string, must be freed by caller
312
</simpara></listitem></varlistentry>
313
</variablelist></refsect2>
314
<refsect2 id="rb-string-list-equal" role="function">
315
<title>rb_string_list_equal ()</title>
316
<indexterm zone="rb-string-list-equal"><primary sortas="rb_string_list_equal">rb_string_list_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_string_list_equal (<link linkend="GList">GList</link> *a,
317
<link linkend="GList">GList</link> *b);</programlisting>
319
Checks if <parameter>a</parameter> and <parameter>b</parameter> contain exactly the same set of strings,
320
regardless of order.</para>
322
</para><variablelist role="params">
323
<varlistentry><term><parameter>a</parameter> :</term>
324
<listitem><simpara> list of strings to compare
325
</simpara></listitem></varlistentry>
326
<varlistentry><term><parameter>b</parameter> :</term>
327
<listitem><simpara> other list of strings to compare
328
</simpara></listitem></varlistentry>
329
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the lists contain all the same strings
330
</simpara></listitem></varlistentry>
331
</variablelist></refsect2>
332
<refsect2 id="rb-string-list-copy" role="function">
333
<title>rb_string_list_copy ()</title>
334
<indexterm zone="rb-string-list-copy"><primary sortas="rb_string_list_copy">rb_string_list_copy</primary></indexterm><programlisting><link linkend="GList">GList</link>* rb_string_list_copy (<link linkend="GList">GList</link> *list);</programlisting>
336
Creates a deep copy of <parameter>list</parameter>.</para>
338
</para><variablelist role="params">
339
<varlistentry><term><parameter>list</parameter> :</term>
340
<listitem><simpara> list of strings to copy
341
</simpara></listitem></varlistentry>
342
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> copied list, must be freed (and its contents freed)
344
</simpara></listitem></varlistentry>
345
</variablelist></refsect2>
346
<refsect2 id="rb-string-list-contains" role="function">
347
<title>rb_string_list_contains ()</title>
348
<indexterm zone="rb-string-list-contains"><primary sortas="rb_string_list_contains">rb_string_list_contains</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_string_list_contains (<link linkend="GList">GList</link> *list,
349
const <link linkend="char">char</link> *s);</programlisting>
351
Checks if <parameter>list</parameter> contains the string <parameter>s</parameter>.</para>
353
</para><variablelist role="params">
354
<varlistentry><term><parameter>list</parameter> :</term>
355
<listitem><simpara> list to check
356
</simpara></listitem></varlistentry>
357
<varlistentry><term><parameter>s</parameter> :</term>
358
<listitem><simpara> string to check for
359
</simpara></listitem></varlistentry>
360
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if found
361
</simpara></listitem></varlistentry>
362
</variablelist></refsect2>
363
<refsect2 id="rb-list-destroy-free" role="function">
364
<title>rb_list_destroy_free ()</title>
365
<indexterm zone="rb-list-destroy-free"><primary sortas="rb_list_destroy_free">rb_list_destroy_free</primary></indexterm><programlisting><link linkend="void">void</link> rb_list_destroy_free (<link linkend="GList">GList</link> *list,
366
<link linkend="GDestroyNotify">GDestroyNotify</link> destroyer);</programlisting>
368
Calls <parameter>destroyer</parameter> for each element in <parameter>list</parameter>, then frees <parameter>list</parameter>.</para>
370
</para><variablelist role="params">
371
<varlistentry><term><parameter>list</parameter> :</term>
372
<listitem><simpara> list to destroy
373
</simpara></listitem></varlistentry>
374
<varlistentry><term><parameter>destroyer</parameter> :</term>
375
<listitem><simpara> function to call to free elements of <parameter>list</parameter>
376
</simpara></listitem></varlistentry>
377
</variablelist></refsect2>
378
<refsect2 id="rb-list-deep-free" role="function">
379
<title>rb_list_deep_free ()</title>
380
<indexterm zone="rb-list-deep-free"><primary sortas="rb_list_deep_free">rb_list_deep_free</primary></indexterm><programlisting><link linkend="void">void</link> rb_list_deep_free (<link linkend="GList">GList</link> *list);</programlisting>
382
Frees each element of <parameter>list</parameter> and <parameter>list</parameter> itself.</para>
384
</para><variablelist role="params">
385
<varlistentry><term><parameter>list</parameter> :</term>
386
<listitem><simpara> list to free
387
</simpara></listitem></varlistentry>
388
</variablelist></refsect2>
389
<refsect2 id="rb-slist-deep-free" role="function">
390
<title>rb_slist_deep_free ()</title>
391
<indexterm zone="rb-slist-deep-free"><primary sortas="rb_slist_deep_free">rb_slist_deep_free</primary></indexterm><programlisting><link linkend="void">void</link> rb_slist_deep_free (<link linkend="GSList">GSList</link> *list);</programlisting>
393
Frees each element of <parameter>list</parameter> and <parameter>list</parameter> itself.</para>
395
</para><variablelist role="params">
396
<varlistentry><term><parameter>list</parameter> :</term>
397
<listitem><simpara> list to free
398
</simpara></listitem></varlistentry>
399
</variablelist></refsect2>
400
<refsect2 id="rb-collate-hash-table-keys" role="function">
401
<title>rb_collate_hash_table_keys ()</title>
402
<indexterm zone="rb-collate-hash-table-keys"><primary sortas="rb_collate_hash_table_keys">rb_collate_hash_table_keys</primary></indexterm><programlisting><link linkend="GList">GList</link>* rb_collate_hash_table_keys (<link linkend="GHashTable">GHashTable</link> *table);</programlisting>
404
Returns a <link linkend="GList"><type>GList</type></link> containing all keys from <parameter>table</parameter>. The keys are
407
</para><variablelist role="params">
408
<varlistentry><term><parameter>table</parameter> :</term>
409
<listitem><simpara> <link linkend="GHashTable"><type>GHashTable</type></link> to collate
410
</simpara></listitem></varlistentry>
411
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GList"><type>GList</type></link> of keys, must be freed by caller
412
</simpara></listitem></varlistentry>
413
</variablelist></refsect2>
414
<refsect2 id="rb-collate-hash-table-values" role="function">
415
<title>rb_collate_hash_table_values ()</title>
416
<indexterm zone="rb-collate-hash-table-values"><primary sortas="rb_collate_hash_table_values">rb_collate_hash_table_values</primary></indexterm><programlisting><link linkend="GList">GList</link>* rb_collate_hash_table_values (<link linkend="GHashTable">GHashTable</link> *table);</programlisting>
418
Returns a <link linkend="GList"><type>GList</type></link> containing all values from <parameter>table</parameter>. The values are
421
</para><variablelist role="params">
422
<varlistentry><term><parameter>table</parameter> :</term>
423
<listitem><simpara> <link linkend="GHashTable"><type>GHashTable</type></link> to collate
424
</simpara></listitem></varlistentry>
425
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GList"><type>GList</type></link> of values, must be freed by caller
426
</simpara></listitem></varlistentry>
427
</variablelist></refsect2>
428
<refsect2 id="rb-uri-list-parse" role="function">
429
<title>rb_uri_list_parse ()</title>
430
<indexterm zone="rb-uri-list-parse"><primary sortas="rb_uri_list_parse">rb_uri_list_parse</primary></indexterm><programlisting><link linkend="GList">GList</link>* rb_uri_list_parse (const <link linkend="char">char</link> *uri_list);</programlisting>
432
Converts a single string containing a list of URIs into
433
a <link linkend="GList"><type>GList</type></link> of URI strings.</para>
435
</para><variablelist role="params">
436
<varlistentry><term><parameter>uri_list</parameter> :</term>
437
<listitem><simpara> string containing URIs to parse
438
</simpara></listitem></varlistentry>
439
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GList"><type>GList</type></link> of URI strings, must be deep-freed by caller
440
</simpara></listitem></varlistentry>
441
</variablelist></refsect2>
442
<refsect2 id="rb-mime-get-friendly-name" role="function">
443
<title>rb_mime_get_friendly_name ()</title>
444
<indexterm zone="rb-mime-get-friendly-name"><primary sortas="rb_mime_get_friendly_name">rb_mime_get_friendly_name</primary></indexterm><programlisting><link linkend="char">char</link>* rb_mime_get_friendly_name (const <link linkend="char">char</link> *mime_type);</programlisting>
446
Returns a human-friendly description of the MIME type <parameter>mime_type</parameter>.</para>
448
</para><variablelist role="params">
449
<varlistentry><term><parameter>mime_type</parameter> :</term>
450
<listitem><simpara> a MIME type
451
</simpara></listitem></varlistentry>
452
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> type description, must be freed by caller
453
</simpara></listitem></varlistentry>
454
</variablelist></refsect2>
455
<refsect2 id="rb-signal-accumulator-object-handled" role="function">
456
<title>rb_signal_accumulator_object_handled ()</title>
457
<indexterm zone="rb-signal-accumulator-object-handled"><primary sortas="rb_signal_accumulator_object_handled">rb_signal_accumulator_object_handled</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_signal_accumulator_object_handled
458
(<link linkend="GSignalInvocationHint">GSignalInvocationHint</link> *hint,
459
<link linkend="GValue">GValue</link> *return_accu,
460
const <link linkend="GValue">GValue</link> *handler_return,
461
<link linkend="gpointer">gpointer</link> dummy);</programlisting>
463
A <link linkend="GSignalAccumulator"><type>GSignalAccumulator</type></link> that aborts the signal emission after the
464
first handler to return a value, and returns the value returned by
465
that handler. This is the opposite behaviour from what you get when
466
no accumulator is specified, where the last signal handler wins.</para>
468
</para><variablelist role="params">
469
<varlistentry><term><parameter>hint</parameter> :</term>
470
<listitem><simpara> a <link linkend="GSignalInvocationHint"><type>GSignalInvocationHint</type></link>
471
</simpara></listitem></varlistentry>
472
<varlistentry><term><parameter>return_accu</parameter> :</term>
473
<listitem><simpara> holds the accumulated return value
474
</simpara></listitem></varlistentry>
475
<varlistentry><term><parameter>handler_return</parameter> :</term>
476
<listitem><simpara> holds the return value to be accumulated
477
</simpara></listitem></varlistentry>
478
<varlistentry><term><parameter>dummy</parameter> :</term>
479
<listitem><simpara> user data (unused)
480
</simpara></listitem></varlistentry>
481
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to abort signal emission, <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to continue
482
</simpara></listitem></varlistentry>
483
</variablelist></refsect2>
484
<refsect2 id="rb-signal-accumulator-value-array" role="function">
485
<title>rb_signal_accumulator_value_array ()</title>
486
<indexterm zone="rb-signal-accumulator-value-array"><primary sortas="rb_signal_accumulator_value_array">rb_signal_accumulator_value_array</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_signal_accumulator_value_array (<link linkend="GSignalInvocationHint">GSignalInvocationHint</link> *hint,
487
<link linkend="GValue">GValue</link> *return_accu,
488
const <link linkend="GValue">GValue</link> *handler_return,
489
<link linkend="gpointer">gpointer</link> dummy);</programlisting>
491
A <link linkend="GSignalAccumulator"><type>GSignalAccumulator</type></link> used to combine all returned values into
492
a <link linkend="GValueArray"><type>GValueArray</type></link>.</para>
494
</para><variablelist role="params">
495
<varlistentry><term><parameter>hint</parameter> :</term>
496
<listitem><simpara> a <link linkend="GSignalInvocationHint"><type>GSignalInvocationHint</type></link>
497
</simpara></listitem></varlistentry>
498
<varlistentry><term><parameter>return_accu</parameter> :</term>
499
<listitem><simpara> holds the accumulated return value
500
</simpara></listitem></varlistentry>
501
<varlistentry><term><parameter>handler_return</parameter> :</term>
502
<listitem><simpara> holds the return value to be accumulated
503
</simpara></listitem></varlistentry>
504
<varlistentry><term><parameter>dummy</parameter> :</term>
505
<listitem><simpara> user data (unused)
506
</simpara></listitem></varlistentry>
507
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to abort signal emission, <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to continue
508
</simpara></listitem></varlistentry>
509
</variablelist></refsect2>
510
<refsect2 id="rb-value-array-append-data" role="function">
511
<title>rb_value_array_append_data ()</title>
512
<indexterm zone="rb-value-array-append-data"><primary sortas="rb_value_array_append_data">rb_value_array_append_data</primary></indexterm><programlisting><link linkend="void">void</link> rb_value_array_append_data (<link linkend="GValueArray">GValueArray</link> *array,
513
<link linkend="GType">GType</link> type,
514
...);</programlisting>
516
Appends a single value to <parameter>array</parameter>, collecting it from <parameter>Varargs</parameter>.</para>
518
</para><variablelist role="params">
519
<varlistentry><term><parameter>array</parameter> :</term>
520
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to append to
521
</simpara></listitem></varlistentry>
522
<varlistentry><term><parameter>type</parameter> :</term>
523
<listitem><simpara> <link linkend="GType"><type>GType</type></link> of the value being appended
524
</simpara></listitem></varlistentry>
525
<varlistentry><term><parameter>...</parameter> :</term>
526
<listitem><simpara> value to append
527
</simpara></listitem></varlistentry>
528
</variablelist></refsect2>
529
<refsect2 id="rb-value-free" role="function">
530
<title>rb_value_free ()</title>
531
<indexterm zone="rb-value-free"><primary sortas="rb_value_free">rb_value_free</primary></indexterm><programlisting><link linkend="void">void</link> rb_value_free (<link linkend="GValue">GValue</link> *val);</programlisting>
533
Unsets and frees <parameter>val</parameter>. <parameter>val</parameter> must have been allocated using
534
<parameter>g_slice_new</parameter> or <parameter>g_slice_new0</parameter>.</para>
536
</para><variablelist role="params">
537
<varlistentry><term><parameter>val</parameter> :</term>
538
<listitem><simpara> a <link linkend="GValue"><type>GValue</type></link>
539
</simpara></listitem></varlistentry>
540
</variablelist></refsect2>
541
<refsect2 id="rb-str-in-strv" role="function">
542
<title>rb_str_in_strv ()</title>
543
<indexterm zone="rb-str-in-strv"><primary sortas="rb_str_in_strv">rb_str_in_strv</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_str_in_strv (const <link linkend="char">char</link> *needle,
544
<link linkend="char">char</link> **haystack);</programlisting>
546
Checks if <parameter>needle</parameter> is present in the NULL-terminated string
547
array <parameter>haystack</parameter>.</para>
549
</para><variablelist role="params">
550
<varlistentry><term><parameter>needle</parameter> :</term>
551
<listitem><simpara> string to search for
552
</simpara></listitem></varlistentry>
553
<varlistentry><term><parameter>haystack</parameter> :</term>
554
<listitem><simpara> array of strings to search
555
</simpara></listitem></varlistentry>
556
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if found
557
</simpara></listitem></varlistentry>
558
</variablelist></refsect2>
559
<refsect2 id="rb-set-tree-view-column-fixed-width" role="function">
560
<title>rb_set_tree_view_column_fixed_width ()</title>
561
<indexterm zone="rb-set-tree-view-column-fixed-width"><primary sortas="rb_set_tree_view_column_fixed_width">rb_set_tree_view_column_fixed_width</primary></indexterm><programlisting><link linkend="void">void</link> rb_set_tree_view_column_fixed_width (<link linkend="GtkWidget">GtkWidget</link> *treeview,
562
<link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> *column,
563
<link linkend="GtkCellRenderer">GtkCellRenderer</link> *renderer,
564
const <link linkend="char">char</link> **strings,
565
<link linkend="int">int</link> padding);</programlisting>
567
Sets a fixed size for a tree view column based on
568
a set of strings to be displayed in the column.</para>
570
</para><variablelist role="params">
571
<varlistentry><term><parameter>treeview</parameter> :</term>
572
<listitem><simpara> the <link linkend="GtkTreeView"><type>GtkTreeView</type></link> containing the column
573
</simpara></listitem></varlistentry>
574
<varlistentry><term><parameter>column</parameter> :</term>
575
<listitem><simpara> the <link linkend="GtkTreeViewColumn"><type>GtkTreeViewColumn</type></link> to size
576
</simpara></listitem></varlistentry>
577
<varlistentry><term><parameter>renderer</parameter> :</term>
578
<listitem><simpara> the <link linkend="GtkCellRenderer"><type>GtkCellRenderer</type></link> used in the column
579
</simpara></listitem></varlistentry>
580
<varlistentry><term><parameter>strings</parameter> :</term>
581
<listitem><simpara> a NULL-terminated set of strings to base the size on
582
</simpara></listitem></varlistentry>
583
<varlistentry><term><parameter>padding</parameter> :</term>
584
<listitem><simpara> a small amount of extra padding for the column
585
</simpara></listitem></varlistentry>
586
</variablelist></refsect2>
587
<refsect2 id="rb-scale-pixbuf-to-size" role="function">
588
<title>rb_scale_pixbuf_to_size ()</title>
589
<indexterm zone="rb-scale-pixbuf-to-size"><primary sortas="rb_scale_pixbuf_to_size">rb_scale_pixbuf_to_size</primary></indexterm><programlisting><link linkend="GdkPixbuf">GdkPixbuf</link> * rb_scale_pixbuf_to_size (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
590
<link linkend="GtkIconSize">GtkIconSize</link> size);</programlisting>
592
Creates a new <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link> from the original one, for a target of
593
size, respecting the aspect ratio of the image.</para>
595
</para><variablelist role="params">
596
<varlistentry><term><parameter>pixbuf</parameter> :</term>
597
<listitem><simpara> the <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link> containing the original image
598
</simpara></listitem></varlistentry>
599
<varlistentry><term><parameter>size</parameter> :</term>
600
<listitem><simpara> a stock icon size
601
</simpara></listitem></varlistentry>
602
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> scaled <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link>
603
</simpara></listitem></varlistentry>
604
</variablelist></refsect2>
added
removed
doc/reference/xml/rb-util.xml
