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