gimputils

## gimputils gimputils — Utilities of general interest |

## Synopsis

    gchar *             gimp_any_to_utf8                    (const gchar *str,
                                                             gssize len,
                                                             const gchar *warning_format,
                                                             ...);
    const gchar *       gimp_filename_to_utf8               (const gchar *filename);
    gchar *             gimp_utf8_strtrim                   (const gchar *str,
                                                             gint max_chars);
    gchar *             gimp_escape_uline                   (const gchar *str);
    gchar *             gimp_strip_uline                    (const gchar *str);
    gchar *             gimp_canonicalize_identifier        (const gchar *identifier);
    GimpEnumDesc *      gimp_enum_get_desc                  (GEnumClass *enum_class,
                                                             gint 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);
    const gchar *       gimp_enum_value_get_desc            (GEnumClass *enum_class,
                                                             GEnumValue *enum_value);
    const gchar *       gimp_enum_value_get_help            (GEnumClass *enum_class,
                                                             GEnumValue *enum_value);
    GimpFlagsDesc *     gimp_flags_get_first_desc           (GFlagsClass *flags_class,
                                                             guint 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);
    const gchar *       gimp_flags_value_get_desc           (GFlagsClass *flags_class,
                                                             GFlagsValue *flags_value);
    const gchar *       gimp_flags_value_get_help           (GFlagsClass *flags_class,
                                                             GFlagsValue *flags_value);

## Description

## Details

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

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

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

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

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

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

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

`enum_class` : | a GEnumClass
`value` : | a value from `enum_class`
Returns : | the value's GimpEnumDesc.

Since GIMP 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 desc and help are returned (if `value_name`, `value_nick`, `value_desc` and `value_help` are not `NULL`).

`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 desc (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 GIMP 2.2

### gimp_enum_value_get_desc ()

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

Retrieves the translated desc for a given `enum_value`.

`enum_class` : | a GEnumClass
`enum_value` : | a GEnumValue from `enum_class`
Returns : | the translated desc of the enum value

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

`enum_class` : | a GEnumClass
`enum_value` : | a GEnumValue from `enum_class`
Returns : | the translated help of the enum value

Since GIMP 2.2

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

`flags_class` : | a GFlagsClass
`value` : | a value from `flags_class`
Returns : | the value's GimpFlagsDesc.

Since GIMP 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 desc and help are returned (if `value_name`, `value_nick`, `value_desc` and `value_help` are not `NULL`).

`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 desc (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 GIMP 2.2

### gimp_flags_value_get_desc ()

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

Retrieves the translated desc for a given `flags_value`.

`flags_class` : | a GFlagsClass
`flags_value` : | a GFlagsValue from `flags_class`
Returns : | the translated desc of the flags value

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

`flags_class` : | a GFlagsClass
`flags_value` : | a GFlagsValue from `flags_class`
Returns : | the translated help of the flags value

Since GIMP 2.2