gimputils: GIMP Base Library Reference Manual

## gimputils gimputils — Utilities of general interest |

## Functions

gchar * | gimp_any_to_utf8 ()
const gchar * | gimp_filename_to_utf8 ()
const gchar * | gimp_file_get_utf8_name ()
gboolean | gimp_file_has_extension ()
gboolean | gimp_file_show_in_file_manager ()
gchar * | gimp_utf8_strtrim ()
gchar * | gimp_escape_uline ()
gchar * | gimp_strip_uline ()
gchar * | gimp_canonicalize_identifier ()
GimpEnumDesc * | gimp_enum_get_desc ()
gboolean | gimp_enum_get_value ()
const gchar * | gimp_enum_value_get_desc ()
const gchar * | gimp_enum_value_get_help ()
const gchar * | gimp_enum_value_get_abbrev ()
GimpFlagsDesc * | gimp_flags_get_first_desc ()
gboolean | gimp_flags_get_first_value ()
const gchar * | gimp_flags_value_get_desc ()
const gchar * | gimp_flags_value_get_help ()
const gchar * | gimp_flags_value_get_abbrev ()
gboolean | gimp_stack_trace_available ()
gboolean | gimp_stack_trace_print ()
void | gimp_stack_trace_query ()

## Description

Utilities of general interest

## Functions

### gimp_any_to_utf8 ()

    gchar *
    gimp_any_to_utf8 (const gchar *str,
                      gssize len,
                      const gchar *warning_format,
                      ...);

This function takes any string (UTF-8 or not) and always returns a valid UTF-8 string.

If `str` is valid UTF-8, a copy of the string is returned.

If UTF-8 validation fails, `g_locale_to_utf8()` is tried and if it succeeds the resulting string is returned.

Otherwise, the portion of `str` that is UTF-8, concatenated with "(invalid UTF-8 string)" is returned. If not even the start of `str` is valid UTF-8, only "(invalid UTF-8 string)" is returned.

#### Parameters

str | The string to be converted to UTF-8. |
len | The length of the string, or -1 if the string is nul-terminated. |
warning_format | The message format for the warning message if conversion to UTF-8 fails. See the ``printf()`` documentation. |
... | The parameters to insert into the format string. |

#### Returns

The UTF-8 string as described above.

### gimp_filename_to_utf8 ()

    const gchar *
    gimp_filename_to_utf8 (const gchar *filename);

Convert a filename in the filesystem's encoding to UTF-8 temporarily. The return value is a pointer to a string that is guaranteed to be valid only during the current iteration of the main loop or until the next call to `gimp_filename_to_utf8()`.

The only purpose of this function is to provide an easy way to pass a filename in the filesystem encoding to a function that expects an UTF-8 encoded filename.

#### Parameters

filename | The filename to be converted to UTF-8. |

#### Returns

A temporarily valid UTF-8 representation of `filename` . This string must not be changed or freed.

### gimp_file_get_utf8_name ()

    const gchar *
    gimp_file_get_utf8_name (GFile *file);

This function works like `gimp_filename_to_utf8()` and returns a UTF-8 encoded string that does not need to be freed.

It converts a GFile's path or uri to UTF-8 temporarily. The return value is a pointer to a string that is guaranteed to be valid only during the current iteration of the main loop or until the next call to `gimp_file_get_utf8_name()`.

The only purpose of this function is to provide an easy way to pass a GFile's name to a function that expects an UTF-8 encoded string.

See `g_file_get_parse_name()`.

#### Parameters

file | a GFile |

#### Returns

A temporarily valid UTF-8 representation of `file` 's name. This string must not be changed or freed.

Since: 2.10

### gimp_file_has_extension ()

    gboolean
    gimp_file_has_extension (GFile *file,
                             const gchar *extension);

This function checks if `file` 's URI ends with `extension` . It behaves like `g_str_has_suffix()` on `g_file_get_uri()`, except that the string comparison is done case-insensitively using `g_ascii_strcasecmp()`.

#### Parameters

file | a GFile |
extension | an ASCII extension |

#### Returns

`TRUE` if `file` 's URI ends with `extension` , `FALSE` otherwise.

Since: 2.10

### gimp_file_show_in_file_manager ()

    gboolean
    gimp_file_show_in_file_manager (GFile *file,
                                    GError **error);

Shows `file` in the system file manager.

#### Parameters

file | a GFile |
error | return location for a GError |

#### Returns

`TRUE` on success, `FALSE` otherwise. On `FALSE`, `error` is set.

Since: 2.10

### gimp_utf8_strtrim ()

    gchar *
    gimp_utf8_strtrim (const gchar *str,
                       gint max_chars);

Creates a (possibly trimmed) copy of `str` . The string is cut if it exceeds `max_chars` characters or on the first newline. The fact that the string was trimmed is indicated by appending an ellipsis.

#### Parameters

str | an UTF-8 encoded string (or `NULL`) |
max_chars | the maximum number of characters before the string get trimmed |

#### Returns

A (possibly trimmed) copy of `str` which should be freed using `g_free()` when it is not needed any longer.

### gimp_escape_uline ()

    gchar *
    gimp_escape_uline (const gchar *str);

This function returns a copy of `str` with all underline converted to two adjacent underlines. This comes in handy when needing to display strings with underlines (like filenames) in a place that would convert them to mnemonics.

#### Parameters

str | Underline infested string (or `NULL`) |

#### Returns

A (possibly escaped) copy of `str` which should be freed using `g_free()` when it is not needed any longer.

Since: 2.2

### gimp_strip_uline ()

    gchar *
    gimp_strip_uline (const gchar *str);

This function returns a copy of `str` stripped of underline characters. This comes in handy when needing to strip mnemonics from menu paths etc.

In some languages, mnemonics are handled by adding the mnemonic character in brackets (like "File (_F)"). This function recognizes this construct and removes the whole bracket construction to get rid of the mnemonic (see bug 157561).

#### Parameters

str | underline infested string (or `NULL`) |

#### Returns

A (possibly stripped) copy of `str` which should be freed using `g_free()` when it is not needed any longer.

### gimp_canonicalize_identifier ()

    gchar *
    gimp_canonicalize_identifier (const gchar *identifier);

Turns any input string into a canonicalized string.

Canonical identifiers are e.g. expected by the PDB for procedure and parameter names. Every character of the input string that is not either '-', 'a-z', 'A-Z' or '0-9' will be replaced by a '-'.

#### Parameters

identifier | The identifier string to canonicalize. |

#### Returns

The canonicalized identifier. This is a newly allocated string that should be freed with `g_free()` when no longer needed.

Since: 2.4

### gimp_enum_get_desc ()

    GimpEnumDesc *
    gimp_enum_get_desc (GEnumClass *enum_class,
                        gint value);

Retrieves GimpEnumDesc associated with the given value, or `NULL`.

#### Parameters

enum_class | a GEnumClass |
value | a value from `enum_class` |

#### Returns

the value's GimpEnumDesc.

Since: 2.2

### gimp_enum_get_value ()

    gboolean
    gimp_enum_get_value (GType enum_type,
                         gint value,
                         const gchar **value_name,
                         const gchar **value_nick,
                         const gchar **value_desc,
                         const gchar **value_help);

Checks if `value` is valid for the enum registered as `enum_type` . If the value exists in that enum, its name, nick and its translated description and help are returned (if `value_name` , `value_nick` , `value_desc` and `value_help` are not `NULL`).

#### Parameters

enum_type | the GType of a registered enum |
value | an integer value |
value_name | return location for the value's name (or `NULL`) |
value_nick | return location for the value's nick (or `NULL`) |
value_desc | return location for the value's translated description (or `NULL`) |
value_help | return location for the value's translated help (or `NULL`) |

#### Returns

`TRUE` if `value` is valid for the `enum_type` , `FALSE` otherwise

Since: 2.2

### gimp_enum_value_get_desc ()

    const gchar *
    gimp_enum_value_get_desc (GEnumClass *enum_class,
                              GEnumValue *enum_value);

Retrieves the translated description for a given `enum_value` .

#### Parameters

enum_class | a GEnumClass |
enum_value | a GEnumValue from `enum_class` |

#### Returns

the translated description of the enum value

Since: 2.2

### gimp_enum_value_get_help ()

    const gchar *
    gimp_enum_value_get_help (GEnumClass *enum_class,
                              GEnumValue *enum_value);

Retrieves the translated help for a given `enum_value` .

#### Parameters

enum_class | a GEnumClass |
enum_value | a GEnumValue from `enum_class` |

#### Returns

the translated help of the enum value

Since: 2.2

### gimp_enum_value_get_abbrev ()

    const gchar *
    gimp_enum_value_get_abbrev (GEnumClass *enum_class,
                                GEnumValue *enum_value);

Retrieves the translated abbreviation for a given `enum_value` .

#### Parameters

enum_class | a GEnumClass |
enum_value | a GEnumValue from `enum_class` |

#### Returns

the translated abbreviation of the enum value

Since: 2.10

### gimp_flags_get_first_desc ()

    GimpFlagsDesc *
    gimp_flags_get_first_desc (GFlagsClass *flags_class,
                               guint value);

Retrieves the first GimpFlagsDesc that matches the given value, or `NULL`.

#### Parameters

flags_class | a GFlagsClass |
value | a value from `flags_class` |

#### Returns

the value's GimpFlagsDesc.

Since: 2.2

### gimp_flags_get_first_value ()

    gboolean
    gimp_flags_get_first_value (GType flags_type,
                                guint value,
                                const gchar **value_name,
                                const gchar **value_nick,
                                const gchar **value_desc,
                                const gchar **value_help);

Checks if `value` is valid for the flags registered as `flags_type` . If the value exists in that flags, its name, nick and its translated description and help are returned (if `value_name` , `value_nick` , `value_desc` and `value_help` are not `NULL`).

#### Parameters

flags_type | the GType of registered flags |
value | an integer value |
value_name | return location for the value's name (or `NULL`) |
value_nick | return location for the value's nick (or `NULL`) |
value_desc | return location for the value's translated description (or `NULL`) |
value_help | return location for the value's translated help (or `NULL`) |

#### Returns

`TRUE` if `value` is valid for the `flags_type` , `FALSE` otherwise

Since: 2.2

### gimp_flags_value_get_desc ()

    const gchar *
    gimp_flags_value_get_desc (GFlagsClass *flags_class,
                               GFlagsValue *flags_value);

Retrieves the translated description for a given `flags_value` .

#### Parameters

flags_class | a GFlagsClass |
flags_value | a GFlagsValue from `flags_class` |

#### Returns

the translated description of the flags value

Since: 2.2

### gimp_flags_value_get_help ()

    const gchar *
    gimp_flags_value_get_help (GFlagsClass *flags_class,
                               GFlagsValue *flags_value);

Retrieves the translated help for a given `flags_value` .

#### Parameters

flags_class | a GFlagsClass |
flags_value | a GFlagsValue from `flags_class` |

#### Returns

the translated help of the flags value

Since: 2.2

### gimp_flags_value_get_abbrev ()

    const gchar *
    gimp_flags_value_get_abbrev (GFlagsClass *flags_class,
                                 GFlagsValue *flags_value);

Retrieves the translated abbreviation for a given `flags_value` .

#### Parameters

flags_class | a GFlagsClass |
flags_value | a GFlagsValue from `flags_class` |

#### Returns

the translated abbreviation of the flags value

Since: 2.10

### gimp_stack_trace_available ()

    gboolean
    gimp_stack_trace_available (gboolean optimal);

Returns TRUE if we have dependencies to generate backtraces. If `optimal` is TRUE, the function will return TRUE only when we are able to generate optimal traces (i.e. with GDB or LLDB); otherwise we return TRUE even if only `backtrace()` API is available.

On Win32, we return TRUE if Dr. Mingw is built-in, FALSE otherwise.

Note: this function is not crash-safe, i.e. you should not try to use it in a callback when the program is already crashing. In such a case, call `gimp_stack_trace_print()` or `gimp_stack_trace_query()` directly.

#### Parameters

optimal | whether we get optimal traces. |

Since: 2.10

### gimp_stack_trace_print ()

    gboolean
    gimp_stack_trace_print (const gchar *prog_name,
                            gpointer stream,
                            gchar **trace);

Attempts to generate a stack trace at current code position in `prog_name` . `prog_name` is mostly a helper and can be set to NULL. Nevertheless if set, it has to be the current program name (argv[0]). This function is not meant to generate stack trace for third-party programs, and will attach the current process id only. Internally, this function uses `gdb` or `lldb` if they are available, or the `stacktrace()` API on platforms where it is available. It always fails on Win32.

The stack trace, once generated, will either be printed to `stream` or returned as a newly allocated string in `trace` , if not NULL.

In some error cases (e.g. segmentation fault), trying to allocate more memory will trigger more segmentation faults and therefore loop our error handling (which is just wrong). Therefore printing to a file description is an implementation without any memory allocation.

#### Parameters

prog_name | the program to attach to. |
stream | a FILE * stream. |
trace | location to store a newly allocated string of the trace. |

#### Returns

TRUE if a stack trace could be generated, FALSE otherwise.

Since: 2.10

### gimp_stack_trace_query ()

    void
    gimp_stack_trace_query (const gchar *prog_name);

This is mostly the same as `g_on_error_query()` except that we use our own backtrace function, much more complete. `prog_name` must be the current program name (argv[0]). It does nothing on Win32.

#### Parameters

prog_name | the program to attach to. |

Since: 2.10