TeplUtils: Tepl 6 Reference Manual

## TeplUtils

TeplUtils — Utility functions

## Functions

gchar * | tepl_utils_str_middle_truncate ()
gchar * | tepl_utils_str_end_truncate ()
gchar * | tepl_utils_str_replace ()
gchar * | tepl_utils_markup_escape_text ()
gchar * | tepl_utils_get_file_extension ()
gchar * | tepl_utils_get_file_shortname ()
gchar * | tepl_utils_replace_home_dir_with_tilde ()
gboolean | tepl_utils_decode_uri ()
gboolean | tepl_utils_create_parent_directories ()
void | tepl_utils_file_query_exists_async ()
gboolean | tepl_utils_file_query_exists_finish ()
GtkWidget * | tepl_utils_create_close_button ()
void | tepl_utils_show_warning_dialog ()
void | tepl_utils_list_box_clear ()
void | tepl_utils_list_box_setup_scrolling ()
void | tepl_utils_list_box_scroll_to_row ()
void | tepl_utils_list_box_scroll_to_selected_row ()
GtkListBoxRow * | tepl_utils_list_box_get_row_at_index_with_filter ()
GtkListBoxRow ** | tepl_utils_list_box_get_filtered_children ()
void | tepl_utils_override_font_description ()
void | tepl_utils_override_font_string ()
GtkWidget * | tepl_utils_get_titled_component ()
gboolean | tepl_utils_binding_transform_func_smart_bool ()
gboolean | tepl_utils_can_use_gsettings_schema ()
gboolean | tepl_utils_can_use_gsettings_key ()

## Types and Values

#define | TEPL_UTILS_STYLE_PROVIDER_PRIORITY_LIBRARY

## Includes

    #include <tepl/tepl.h>

## Description

Utility functions.

## Functions

### tepl_utils_str_middle_truncate ()

    gchar *
    tepl_utils_str_middle_truncate (const gchar *str,
                                    guint truncate_length);

If `str` is longer than `truncate_length` , then this function returns `str` truncated in the middle with a “…” character. Otherwise it just returns a copy of `str` .

#### Parameters

str | a UTF-8 string. |
truncate_length | truncate the string at that length, in UTF-8 characters (not bytes). |

#### Returns

the truncated string. Free with `g_free()`.

Since: 4.4

### tepl_utils_str_end_truncate ()

    gchar *
    tepl_utils_str_end_truncate (const gchar *str,
                                 guint truncate_length);

Like `tepl_utils_str_middle_truncate()` but the “…” character is at the end.

#### Parameters

str | a UTF-8 string. |
truncate_length | truncate the string at that length, in UTF-8 characters (not bytes). |

#### Returns

the truncated string. Free with `g_free()`.

Since: 4.4

### tepl_utils_str_replace ()

    gchar *
    tepl_utils_str_replace (const gchar *string,
                            const gchar *search,
                            const gchar *replacement);

Replaces all occurences of `search` by `replacement` .

The function does only one pass, for example:

    1
    tepl_utils_str_replace ("aaaa", "aa", "a");

returns "aa", not "a".

#### Parameters

string | a string |
search | the search string |
replacement | the replacement string |

#### Returns

A newly allocated string with the replacements. Free with `g_free()`.

Since: 4.4

### tepl_utils_markup_escape_text ()

    gchar *
    tepl_utils_markup_escape_text (const gchar *src);

The same as `g_markup_escape_text()`, but with an implementation that fully supports round-trip integrity. I.e. when GMarkupParser or any other XML parser will decode/unescape the string, the exact same string as `src` will be brought back. As long as `src` is a valid UTF-8 string.

The other difference with `g_markup_escape_text()` is that the `length` parameter is not present for `tepl_utils_markup_escape_text()`.

### g_markup_escape_text() doesn't fully support round-trip integrity

In fact, `g_markup_escape_text()` doesn't escape the tabstop, newline and carriage return characters. And the GMarkupParser correctly processes whitespace and line endings according to the XML rules for normalization of line endings and attribute values.

For example `"\t"` (a tab) after a round-trip through `g_markup_escape_text()` and GMarkupParser becomes a simple space.

#### Parameters

src | a nul-terminated UTF-8 string. |

#### Returns

a newly allocated string with the escaped text, or `NULL` if `src` is not a valid UTF-8 string. Free with `g_free()` when no longer needed.

[transfer full][nullable]

Since: 5.0

### tepl_utils_get_file_extension ()

    gchar *
    tepl_utils_get_file_extension (const gchar *filename);

Examples:

- "file.pdf" returns ".pdf".

- "file.PDF" returns ".pdf".

- "file.tar.gz" returns ".gz".

- "path/to/file.pdf" returns ".pdf".

- "file" (without an extension) returns "" (the empty string).

#### Parameters

filename | a filename. |

#### Returns

the `filename` 's extension with the dot, in lowercase. Free with `g_free()`.

Since: 4.4

### tepl_utils_get_file_shortname ()

    gchar *
    tepl_utils_get_file_shortname (const gchar *filename);

Returns `filename` without its extension. With the “extension” having the same definition as in `tepl_utils_get_file_extension()`; in other words it returns the other part of `filename` .

#### Parameters

filename | a filename. |

#### Returns

the `filename` without its extension. Free with `g_free()`.

Since: 4.4

### tepl_utils_replace_home_dir_with_tilde ()

    gchar *
    tepl_utils_replace_home_dir_with_tilde
                                   (const gchar *filename);

Replaces the home directory with a tilde, if the home directory is present in the `filename` .

#### Parameters

filename | the filename. |

#### Returns

the new filename. Free with `g_free()`.

Since: 4.4

### tepl_utils_decode_uri ()

    gboolean
    tepl_utils_decode_uri (const gchar *uri,
                           gchar **scheme,
                           gchar **user,
                           gchar **host,
                           gchar **port,
                           gchar **path);

Parse and break an uri apart in its individual components like the uri scheme, user info, host, port and path. The return value pointer can be `NULL` to ignore certain parts of the uri. If the function returns `TRUE`, then all return value pointers should be freed using `g_free()`.

#### Parameters

uri | the uri to decode |
scheme | return value pointer for the uri's scheme (e.g. http, sftp, ...), or `NULL`. | [out][optional]
user | return value pointer for the uri user info, or `NULL`. | [out][optional]
host | return value pointer for the uri host, or `NULL`. | [out][optional]
port | return value pointer for the uri port, or `NULL`. | [out][optional]
path | return value pointer for the uri path, or `NULL`. | [out][optional]

#### Returns

`TRUE` if the uri could be properly decoded, `FALSE` otherwise.

Since: 5.0

### tepl_utils_create_parent_directories ()

    gboolean
    tepl_utils_create_parent_directories (GFile *file,
                                          GCancellable *cancellable,
                                          GError **error);

Synchronously creates parent directories of `file` , so that `file` can be saved.

#### Parameters

file | a file |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | a location to a `NULL` GError, or `NULL`. | [out][optional]

#### Returns

whether the directories are correctly created. `FALSE` is returned on error.

Since: 5.0

### tepl_utils_file_query_exists_async ()

    void
    tepl_utils_file_query_exists_async (GFile *file,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

The asynchronous version of `g_file_query_exists()`. When the operation is finished, `callback` will be called. You can then call `tepl_utils_file_query_exists_finish()` to get the result of the operation.

#### Parameters

file | a GFile. |
cancellable | a GCancellable. |
callback | the callback to call when the operation is finished. |
user_data | the data to pass to the callback function. |

Since: 5.0

### tepl_utils_file_query_exists_finish ()

    gboolean
    tepl_utils_file_query_exists_finish (GFile *file,
                                         GAsyncResult *result);

Finishes the operation started with `tepl_utils_file_query_exists_async()`. There is no output GError parameter, so you should check if the operation has been cancelled (in which case `FALSE` will be returned).

#### Parameters

file | a GFile. |
result | a GAsyncResult. |

#### Returns

`TRUE` if the file exists and the operation hasn't been cancelled, `FALSE` otherwise.

Since: 5.0

### tepl_utils_create_close_button ()

    GtkWidget *
    tepl_utils_create_close_button (void);

#### Returns

a new close button (a GtkButton).

[transfer floating]

Since: 5.0

### tepl_utils_show_warning_dialog ()

    void
    tepl_utils_show_warning_dialog (GtkWindow *parent,
                                    const gchar *format,
                                    ...);

Shows a GtkDialog with the provided warning message.

#### Parameters

parent | the GtkWindow issuing the warning. | [nullable]
format | format string, as with `printf()`. |
... | parameters to insert into the format string. |

Since: 5.0

### tepl_utils_list_box_clear ()

    void
    tepl_utils_list_box_clear (GtkListBox *list_box);

Removes all rows of `list_box` , to obtain an empty GtkListBox.

#### Parameters

list_box | a GtkListBox. |

Since: 6.0

### tepl_utils_list_box_setup_scrolling ()

    void
    tepl_utils_list_box_setup_scrolling (GtkListBox *list_box,
                                         GtkScrolledWindow *scrolled_window);

Setup vertical scrolling between `list_box` and `scrolled_window` , to be able to use `tepl_utils_list_box_scroll_to_row()` afterwards.

This function is intended to be called only once per GtkListBox, when initializing the `list_box` and `scrolled_window` widgets.

#### Parameters

list_box | a GtkListBox. |
scrolled_window | a GtkScrolledWindow. |

Since: 6.0

### tepl_utils_list_box_scroll_to_row ()

    void
    tepl_utils_list_box_scroll_to_row (GtkListBox *list_box,
                                       GtkListBoxRow *row);

Scrolls to a specific GtkListBoxRow.

Before using this function, `tepl_utils_list_box_setup_scrolling()` must have been called.

#### Parameters

list_box | a GtkListBox. |
row | a GtkListBoxRow. |

Since: 6.0

### tepl_utils_list_box_scroll_to_selected_row ()

    void
    tepl_utils_list_box_scroll_to_selected_row
                                   (GtkListBox *list_box);

Calls `tepl_utils_list_box_scroll_to_row()` on the row returned by `gtk_list_box_get_selected_row()`. This function assumes that there is either zero or one selected row.

Before using this function, `tepl_utils_list_box_setup_scrolling()` must have been called.

#### Parameters

list_box | a GtkListBox. |

Since: 6.0

### tepl_utils_list_box_get_row_at_index_with_filter ()

    GtkListBoxRow *
    tepl_utils_list_box_get_row_at_index_with_filter
                                   (GtkListBox *list_box,
                                    gint index,
                                    GtkListBoxFilterFunc filter_func,
                                    gpointer user_data);

This function has the same semantics as `gtk_list_box_get_row_at_index()`, but it takes into account only the rows for which `filter_func` returns `TRUE`.

As an example, if `index` is 0, it returns the first GtkListBoxRow for which `filter_func` returns `TRUE`.

#### Parameters

list_box | a GtkListBox. |
index | the index of the row, starting at 0. The index is among the filtered rows only. |
filter_func | non-`NULL` callback function. | [scope call]
user_data | user data passed to `filter_func` . |

#### Returns

the child GtkListBoxRow or `NULL`.

[transfer none][nullable]

Since: 6.0

### tepl_utils_list_box_get_filtered_children ()

    GtkListBoxRow **
    tepl_utils_list_box_get_filtered_children
                                   (GtkListBox *list_box,
                                    GtkListBoxFilterFunc filter_func,
                                    gpointer user_data,
                                    gint *n_filtered_children);

Gets an array of all the GtkListBoxRow childen of `list_box` for which `filter_func` returns `TRUE`. The elements in the array are sorted by increasing index order (as returned by `gtk_list_box_row_get_index()`).

#### Parameters

list_box | a GtkListBox. |
filter_func | non-`NULL` callback function. | [scope call]
user_data | user data passed to `filter_func` . |
n_filtered_children | location to store the number of GtkListBoxRow's present in the returned array, without counting the terminating `NULL`. | [out][optional]

#### Returns

a `NULL`-terminated array of GtkListBoxRow objects, or `NULL`. Free with `g_free()` when no longer needed.

[array zero-terminated=1][element-type GtkListBoxRow][transfer container][nullable]

Since: 6.0

### tepl_utils_override_font_description ()

    void
    tepl_utils_override_font_description (GtkWidget *widget,
                                          const PangoFontDescription *font_desc);

A replacement for `gtk_widget_override_font()`. Because `gtk_widget_override_font()` is deprecated but was useful.

See also `tepl_pango_font_description_to_css()`.

#### Parameters

widget | a GtkWidget. |
font_desc | the PangoFontDescription to use, or `NULL` to undo the effect of previous calls to this function on `widget` . | [nullable]

Since: 6.2

### tepl_utils_override_font_string ()

    void
    tepl_utils_override_font_string (GtkWidget *widget,
                                     const gchar *font_str);

A convenience function that calls `tepl_utils_override_font_description()`.

See `pango_font_description_from_string()` for a description of the format of the string representation for `font_str` .

#### Parameters

widget | a GtkWidget. |
font_str | a string representation of a PangoFontDescription, or `NULL` to undo the effect of previous calls to this function on `widget` . | [nullable]

Since: 6.2

### tepl_utils_get_titled_component ()

    GtkWidget *
    tepl_utils_get_titled_component (const gchar *title,
                                     GtkWidget *component);

To add a title to a GUI component.

Useful for example in a GtkDialog window, when there are several components, or logical groups.

The title will be in bold, left-aligned, and the `component` will have a left margin.

#### Parameters

title | the title. |
component | a GtkWidget. |

#### Returns

a new widget containing the `title` above the `component` .

[transfer floating]

Since: 6.2

### tepl_utils_binding_transform_func_smart_bool ()

    gboolean
    tepl_utils_binding_transform_func_smart_bool
                                   (GBinding *binding,
                                    const GValue *from_value,
                                    GValue *to_value,
                                    gpointer user_data);

A GBindingTransformFunc to transform between these two GValue types:

- A GValue of type gboolean.

- A GValue of type GVariant, with the GVariant of type boolean.

For convenience, this function works in both directions (hence the “smart”), it introspects the types of `from_value` and `to_value` .

Note that if `from_value` and `to_value` are of the same GValue type, this function won't work and you shouldn't use a custom GBindingTransformFunc in the first place.

#### Parameters

binding | a GBinding. |
from_value | the GValue containing the value to transform. |
to_value | the GValue in which to store the transformed value. |
user_data | data passed to the transform function. |

#### Returns

`TRUE` if the transformation was successful, and `FALSE` otherwise.

Since: 5.0

### tepl_utils_can_use_gsettings_schema ()

    gboolean
    tepl_utils_can_use_gsettings_schema (const gchar *schema_id);

Checks that a GSettings schema exists.

Especially useful for external GSettings (provided by another application for instance).

#### Parameters

schema_id | a GSettings schema ID. |

#### Returns

`TRUE` if a GSettings instance can be created with `schema_id` . `FALSE` otherwise (in that case the program would crash).

Since: 6.2

### tepl_utils_can_use_gsettings_key ()

    gboolean
    tepl_utils_can_use_gsettings_key (GSettings *settings,
                                      const gchar *key);

Especially useful for external GSettings (provided by another application for instance).

See also: `tepl_utils_can_use_gsettings_schema()` which is typically used before this function.

#### Parameters

settings | a GSettings object. |
key | the key to introspect. |

#### Returns

whether the GSettings key exists.

Since: 6.2

## Types and Values

### TEPL_UTILS_STYLE_PROVIDER_PRIORITY_LIBRARY

    #define TEPL_UTILS_STYLE_PROVIDER_PRIORITY_LIBRARY (GTK_STYLE_PROVIDER_PRIORITY_APPLICATION - 1)

A priority that can be used when adding a GtkStyleProvider for library-specific style information.

Has a higher priority than `GTK_STYLE_PROVIDER_PRIORITY_SETTINGS` and a lower priority than `GTK_STYLE_PROVIDER_PRIORITY_APPLICATION`.

The Tepl library uses this priority for its GtkStyleProvider's.

Since: 6.0