Functions ¶

Creates the shared thumbnail path for the file that corresponds to the given uri and size. No checks are made regarding the existence of the thumbnail.

It is the duty of the caller to free the returned string.

New in version 4.17.1.

Libxfce4util.expand_desktop_entry_field_codes(command, uri_list, icon, name, uri, requires_terminal)¶

Parameters:

command (str) – Input string (command to expand) or None.
uri_list ([str]) – Input string list (filename/URL field) or None.
icon (str) – Input string (icon field) or None.
name (str) – Input string (name field) or None.
uri (str) – Input string (URI field) or None.
requires_terminal (bool) – Input boolean.

Returns:

None on error, else the string, which should be freed using GLib.free() when no longer needed.

Return type:

Expands field codes in command according to Freedesktop.org Desktop Entry Specification.

Libxfce4util.expand_variables(command, envp)¶

Parameters:

command (str) – Input string or None.
envp (str) – Addition environment variables to take into account. These variables have higher priority than the ones in the process’s environment.

Returns:

None on error, else the string, which should be freed using GLib.free() when no longer needed.

Return type:

Expands shell like environment variables and tilde (~/ and ~user/ are both supported) in command.

New in version 4.2.

Libxfce4util.g_file_create_checksum(file, cancellable)¶

Parameters:

file (Gio.File) – a Gio.File.
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

Returns:

Checksum of the file. If file read fails, returns None. Free with GLib.free().

Return type:

str or None

Generates an SHA-256 hash of the file. Utilizes GLib.compute_checksum_for_data() which is present since Glib 2.16.

New in version 4.17.

Libxfce4util.g_file_is_trusted(file, cancellable)¶

Parameters:

file (Gio.File) – a Gio.File.
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

Returns:

True if safety flag is verified or not supported. False otherwise.

Return type:

Compares the checksum stored in safety flag with the actual file. If it matches, it is considered safe.

Read the documentation of Libxfce4util.g_file_set_trusted() for details.

New in version 4.17.

Libxfce4util.g_file_metadata_is_supported(file)¶

Parameters:: file (Gio.File) – a Gio.File.
Returns:: True is GVFS-metadata is supported, False otherwise.
Return type:: bool

Checks if GVFS-metadata is available for the file provided.

New in version 4.17.

Libxfce4util.g_file_set_trusted(file, is_trusted, cancellable)¶

Parameters:

file (Gio.File) – a Gio.File.
is_trusted (bool) – True if trusted, False if not
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

Returns:

True on success, False on error.

Return type:

Sets the “safety flag” on if is_trusted.

Safety flag is a new concept introduced in XFCE 4.17. It is basically an additional execution flag stored in GVFS-metadata. Unlike the execution flag (+x), it is safe to assume that this flag did not come from foreign location (for example, by downloading an tar archive) and is set by user.

The checksum of the file is stored, and would be considered “on” only if checksum matches with the file on execution.

New in version 4.17.

Libxfce4util.g_string_append_quoted(string, unquoted)¶

Parameters:

string (GLib.String) – A GLib.String.
unquoted (str) – A literal string.

Quotes a string unquoted and appends to an existing GLib.String string. The shell will interpret the quoted string to mean unquoted. The quoting style used is undefined (check GLib.shell_quote ()).

New in version 4.17.

Libxfce4util.get_dir_localized(directory)¶

Parameters:: directory (str) – directory name to check for a localized variant.
Returns:: path of the localized directory name or copy of directory if no such directory exists. Returned string should be freed using GLib.free().
Return type:: str

Similar to Libxfce4util.get_file_localized(), but works on directory instead of a file.

Libxfce4util.get_dir_localized_r(buffer, length, directory)¶

Parameters:

buffer (str) – destination buffer to store the localized filename to.
length (int) – size of buffer in bytes.
directory (str) – name of directory to check for localized variant of.

Returns:

pointer to buffer or None on error.

Return type:

Similar to Libxfce4util.get_file_localized_r, but works on directory instead of regular file.

Libxfce4util.get_file_localized(filename)¶

Parameters:: filename (str) – name of a file to look for a localized version.
Returns:: path of the localized file or copy of filename if no such file exists. Returned string should be freed using GLib.free().
Return type:: str

Checks if theres a version of filename which is localized to the current locale. This is done by appending the full locale name to filename, separated by a ‘.’. If theres no file of that name, it retries using the full locale name without the encoding (if any), then without the qualifier (if any) and at last the base locale is tried. If all of those fails, a copy of filename is returned.

Libxfce4util.get_file_localized_r(buffer, length, filename)¶

Parameters:

buffer (str) – destination buffer to store the localized filename to.
length (int) – size of buffer in bytes.
filename (str) – name of a file to look for a localized version.

Returns:

pointer to buffer or None on error.

Return type:

Similar in functionality to Libxfce4util.get_file_localized(), but stores the result in buffer instead of allocating a new buffer.

Libxfce4util.get_homedir()¶

Returns:: the path to the current user’s home directory.
Return type:: str

Similar to GLib.get_home_dir() in functionality but will never return None. While GLib.get_home_dir() may return None under certain circumstances, this function is garantied to never ever return None, but always return a valid character pointer with the absolute path to the user’s home directory.

The returned string is owned by libxfce4util and must not be freed by the caller.

Libxfce4util.get_license_text(license_type)¶

Parameters:: license_type (Libxfce4util.LicenseTextType) – an Libxfce4util.LicenseTextType.
Returns:: the license text for license_type.
Return type:: str

Returns the text of the software license specified in the license_type translated to the current language. If no translation is available, the english license text will be returned.

Libxfce4util.get_path_localized(dst, size, paths, filename, test)¶

Parameters:

dst (str) – destination buffer.
size (int) – size of dst in bytes.
paths (str) – the path
filename (str) – the filename
test (GLib.FileTest) – test

Return type:

paths is a ‘:’-separated list of pathnames, with:

%F: the filename
%L: the language string, as returned by setlocale(LC_MESSAGES, NULL)
%l: the language component of the language string
%N: application name

Example paths: /usr/local/lib/%L/%F:/usr/local/share/%N/%l/%F

Libxfce4util.get_userdir()¶

Returns:: the path to the current user’s “.xfce4” directory.
Return type:: str

Safe way to retrieve the path to the user’s “.xfce4” directory. The path to the current user’s “.xfce4” directory is either taken from the environment variable XFCE4HOME if defined, or if unset, is gained by concatenating the path to the user’s home directory and the “.xfce4”. That says, it will, by default, return the path “$HOME/.xfce4”, where $HOME is replaced with the absolute path to the user’s home directory.

The returned string is managed by libxfce4util and must not be freed by the caller.

Libxfce4util.gethostname()¶

Returns:: the current node’s hostname. The string has to be freed by the caller using GLib.free().
Return type:: str

Portable way to query the hostname of the node running the process. This function does not ever return None, but always returns a string containing the current node’s hostname.

Libxfce4util.locale_match(locale1, locale2)¶

Parameters:

locale1 (str) – the current locale value as returned by setlocale(LC_MESSAGES,:obj:None).
locale2 (str) – the locale value to match against.

Returns:

an integer value indicating the level of matching, where the constant Libxfce4util.LOCALE_FULL_MATCH indicates a full match and Libxfce4util.LOCALE_NO_MATCH means no match. Every other value indicates a partial match, the higher the value, the better the match. You should not rely on any specific value besides the constants Libxfce4util.LOCALE_FULL_MATCH and Libxfce4util.LOCALE_NO_MATCH, since the range of returned values may change in the future.

Return type:

int

The locale is of the general form LANG_COUNTRY.ENCODING @ MODIFIER, where each of COUNTRY, ENCODING and MODIFIER can be absent.

The match is done by actually removing the rightmost element one by one. This is not entirely according to the freedesktop.org specification, but much easier. Will probably be fixed in the future.

New in version 4.2.

Libxfce4util.mkdirhier(whole_path, mode)¶

Parameters:

whole_path (str) – path to the directory to create.
mode (int) – file permissions to use for the newly created directories.

Raises:

Returns:

True on success, else False.

Return type:

Creates the specified directory whole_path, but unlike the mkdir() function from the standard C library, if any of the parent directories of the whole_path do not exists, they are created as well.

If the directory specified by whole_path already exists, this function performs no operation and simply returns True.

New in version 4.2.

Libxfce4util.posix_signal_handler_init()¶

Raises:: GLib.Error
Returns:: True on success, False on failure, in which case error will be set.
Return type:: bool

Initializes the POSIX signal handler system. Must be called before setting any POSIX signal handlers.

Libxfce4util.posix_signal_handler_restore_handler(signal)¶

Parameters:: signal (int) – A POSIX signal id number.

Restores the default handler for signal.

Libxfce4util.posix_signal_handler_set_handler(signal, handler, *user_data)¶

Parameters:

signal (int) – A POSIX signal id number.
handler (Libxfce4util.PosixSignalHandler) – A callback function.
user_data (object or None) – Arbitrary data that will be passed to handler.

Raises:

Returns:

True on success, False otherwise, in which case error will be set.

Return type:

Sets handler to be called whenever signal is caught by the application. The user_data parameter will be passed as an argument to handler.

Libxfce4util.posix_signal_handler_shutdown()¶: Frees all memory associated with the POSIX signal handling system and restores all default signal handlers.

Libxfce4util.rc_config_open(type, resource, readonly)¶

Parameters:

type (Libxfce4util.ResourceType) – The resource type being opened
resource (str) – The resource name to open
readonly (bool) – whether to open resource readonly.

Returns:

the newly created Libxfce4util.Rc object, or None on error.

Return type:

Libxfce4util.Rc

If readonly is True parsing is generally faster, because only untranslated entries and entries that match the current locale will be loaded. Also if you pass True for readonly, #xfce_rc_config will fail if resource does not reference a regular file.

It is no error if readonly is False and the file referenced by resource does not exists. In this case you’ll start with a fresh config, which contains only the default group and no entries.

New in version 4.2.

Libxfce4util.rc_simple_open(filename, readonly)¶

Parameters:

filename (str) – name of the filename to open.
readonly (bool) – whether to open filename readonly.

Returns:

the newly created Libxfce4util.Rc object, or None on error.

Return type:

Libxfce4util.Rc

Parses the resource config file specified by filename.

If readonly is True parsing is generally faster, because only untranslated entries and entries that match the current locale will be loaded. Also if you pass True for readonly, Libxfce4util.Rc.simple_open will fail if filename does not reference a regular file.

It is no error if readonly is False and the file referenced by filename does not exists. In this case you’ll start with a fresh config, which contains only the default group and no entries.

New in version 4.2.

Libxfce4util.resource_dirs(type)¶

Parameters:: type (Libxfce4util.ResourceType) – type of the resource.
Returns:: list of possible directories for type.
Return type:: [str]

Queries the list of possible directories for the specified type. The first element of the list is always the save location for type. None of the directories returned in the list are garantied to exist.

This function should be rarely used. You should consider using Libxfce4util.resource_lookup() or Libxfce4util.resource_match() instead.

The returned list must be freed using GLib.strfreev().

New in version 4.2.

Libxfce4util.resource_lookup(type, filename)¶

Parameters:

type (Libxfce4util.ResourceType) – type of resource to lookup.
filename (str) – relative filename of the resource, e.g. “xfwm4/xfwmrc”.

Returns:

the absolute path to the first file or directory in the search path, that matches filename or None if no such file or directory could be found.

Return type:

Looks for a resource of the specified type whose relative path matches filename. filename can either reference a regular file, in which case it must not end with a slash character (‘/’), or a directory, when filename contains a trailing slash character (‘/’).

The caller is responsible to free the returned string using GLib.free() when no longer needed.

New in version 4.2.

Libxfce4util.resource_lookup_all(type, filename)¶

Parameters:

type (Libxfce4util.ResourceType) – type of the resource to lookup.
filename (str) – relative file path. If filename contains a trailing slash character it is taken to reference a directory, else it is taken to reference a file.

Returns:

list of possible resources for type.

Return type:

[str]

Similar to Libxfce4util.resource_lookup(), but returns all resource of the specified type, that whose name is filename.

The caller is responsible to free the returned string array using GLib.strfreev() when no longer needed.

New in version 4.2.

Libxfce4util.resource_match(type, pattern, unique)¶

Parameters:

type (Libxfce4util.ResourceType) – type of the resource to locate directories for.
pattern (str) – only accept filenames that fit to the pattern. The pattern needs to be a valid GPattern.
unique (bool) – if True, only return items which have unique suffixes.

Returns:

string array of all the relative paths whose names matches the given pattern. The return value has to be freed using GLib.strfreev() when no longer needed.

Return type:

[str]

Tries to find all resources with the specified type. The function will look into all specified directories and return all filenames in these directories. The returned filenames are given relative the base directories specified by type.

If pattern contains a trailing slash, Libxfce4util.resource_match looks only for directories that match pattern, else it’ll only look for regular files. In case you are looking for directories, the returned entries will contain a trailing slash as well, so you can easily use them with other resource functions like Libxfce4util.resource_lookup or Libxfce4util.resource_save_location.

Example: Libxfce4util.resource_match (Libxfce4util.ResourceType.CONFIG, “foo/bar*”) will probably return (“foo/bar”, “foo/barbaz”, …).

New in version 4.2.

Libxfce4util.resource_match_custom(type, unique, func, *user_data)¶

Parameters:

type (Libxfce4util.ResourceType) – type of the resource to locate directories for.
unique (bool) – if True, only return items which have unique suffixes.
func (Libxfce4util.MatchFunc) – callback to determine if there was a match
user_data (object or None) – caller defined data

Returns:

The caller is responsible to free the returned string array using GLib.strfreev() when no longer needed.

Return type:

[str]

Yet to be implemented!

New in version 4.2.

Libxfce4util.resource_pop_path(type)¶

Parameters:: type (Libxfce4util.ResourceType) – type of the resource which search list should be shrinked.

Undoes the effect of the latest call to Libxfce4util.resource_push_path(). You should take special care to call Libxfce4util.resource_pop_path() exactly same times as Libxfce4util.resource_push_path(), everything else might result in unwanted and maybe even undefined behaviour. You have been warned!

New in version 4.2.

Libxfce4util.resource_push_path(type, path)¶

Parameters:

type (Libxfce4util.ResourceType) – type of the resource which search list should be expanded.
path (str) – search path to add.

Appends path to the search path list for type. This function was written primary for use within modules in larger applications, for example MCS plugins.

For example, if you need to add a specific path to the search path list in your MCS, you should call Libxfce4util.resource_push_path() prior to calling one of the resource search functions and call Libxfce4util.resource_pop_path() right afterwards.

New in version 4.2.

Libxfce4util.resource_save_location(type, relpath, create)¶

Parameters:

type (Libxfce4util.ResourceType) – type of location to return.
relpath (str) – relative path of the resource.
create (bool) – whether to create missing directory.

Returns:

the path where resources of the specified type should be saved or None on error. The returned string should be freed when no longer needed.

Return type:

If relpath contains a trailing slash (‘/’) character, Libxfce4util.resource_save_location() finds the directory to save files into for the given type in the user’s home directory. All directories needed (including those given by relpath) will be created on demand if create if True.

If relpath does not end with a slash (‘/’) character, it is taken to be the name of a file to return the save location for. All the directories needed will be created on demand if create is True.

Specifying None or the empty string for relpath allows you to discover the base path for saving files of the specified type, though normally you should not need this.

New in version 4.2.

Libxfce4util.str_replace(str, pattern, replacement)¶

Parameters:

str (str) – the input string.
pattern (str) – a search pattern in str.
replacement (str) – replacement string for pattern.

Returns:

a newly allocated copy of str where all occurrences of pattern are replaced with replacement. Or None if str is None.

Return type:

str or None

Searches str for occurances of pattern and replaces each such occurance with replacement. Returns a newly allocated copy of str on which the given replacement were performed. The caller is responsible to free the returned string using GLib.free() when no longer needed.

Note that pattern and replacement don’t need to be of the same size. If replacement is None, the pattern will be removed from the string.

Note for future Xfce developers: Deprecate this function when GLib.String.replace() is available. (Added since Glib >= 2.68)

New in version 4.17.

Libxfce4util.textdomain(package, localedir, encoding)¶

Parameters:

package (str) – the package name.
localedir (str) – the package<!—->s locale directory.
encoding (str) – the encoding to use the package<!—->s translations or None to use “UTF-8”.

Sets up the translations for package.

Libxfce4util.unescape_desktop_entry_value(value)¶

Parameters:: value (str) – Value string to replace escape sequences.
Returns:: None on error, else the string, which should be freed using GLib.free() when no longer needed.
Return type:: str

Unescapes sequences in value according to Freedesktop.org Desktop Entry Specification.

New in version 4.18.

Libxfce4util.utf8_remove_controls(str, max_len, end)¶

Parameters:

str (str) – target string.
max_len (int) – max characters to check or -1 for no character limit.
end (str) – pointer to the endpoint in str or None for no endpoint.

Returns:

pointer to str or None on error.

Return type:

Removes all control characters from str up to end or up to max_len characters (note that characters does not mean bytes with UTF-8), where both str and max_len may not be given.

Control characters are replaced in str by whitespaces, no new string will be allocated. The operation is done in-place.

New in version 4.2.

Libxfce4util.utf8_strndup(src, max_len)¶

Parameters:

src (str) – target string.
max_len (int) – max characters to duplicate or -1 for no character limit.

Returns:

pointer to the newly allocated string.

Return type: