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);
const gchar* gimp_enum_value_get_name       (GEnumClass *enum_class,
                                             GEnumValue *enum_value);
gboolean    gimp_enum_get_value             (GType enum_type,
                                             gint value,
                                             const gchar **value_nick,
                                             const gchar **value_name);

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.

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.

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

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

Retrieves the translated name for a given enum_value.

enum_class : a GEnumClass
enum_value : a GEnumValue from enum_class
Returns : the translated name of the enum value

Since GIMP 2.2


gimp_enum_get_value ()

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

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

enum_type : the GType of a registered enum
value : an integer value
value_nick : return location for the value's nick (or NULL)
value_name : return location for the value's translated name (or NULL)
Returns : TRUE if value is valid for the enum_type, FALSE otherwise

Since GIMP 2.2