Functions¶

	`append_quoted` (string, unquoted)
	`expand_variables` (command, envp)
	`get_dir_localized` (directory)
	`get_dir_localized_r` (buffer, length, directory)
	`get_file_localized` (filename)
	`get_file_localized_r` (buffer, length, filename)
	`get_homedir` ()
	`get_license_text` (license_type)
	`get_path_localized` (dst, size, paths, filename, test)
	`get_userdir` ()
	`gethostname` ()
	`locale_match` (locale1, locale2)
	`mkdirhier` (whole_path, mode)
	`posix_signal_handler_init` ()
	`posix_signal_handler_restore_handler` (signal)
	`posix_signal_handler_set_handler` (signal, handler, *user_data)
	`posix_signal_handler_shutdown` ()
	`rc_config_open` (type, resource, readonly)
	`rc_simple_open` (filename, readonly)
	`resource_dirs` (type)
	`resource_lookup` (type, filename)
	`resource_lookup_all` (type, filename)
	`resource_match` (type, pattern, unique)
	`resource_match_custom` (type, unique, func, *user_data)
	`resource_pop_path` (type)
	`resource_push_path` (type, path)
	`resource_save_location` (type, relpath, create)
	`textdomain` (package, localedir, encoding)
	`utf8_remove_controls` (str, max_len, end)
	`utf8_strndup` (src, max_len)
	`version_string` ()

Details¶

Libxfce4util.append_quoted(string, unquoted)¶

Parameters:	string (`GLib.String`) – unquoted (`str`) –

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:	`str`

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

New in version 4.2.

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:	`str`

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:	`str`

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 g_get_homedir() in functionality but will never return None. While g_get_homedir() 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:	`str`

paths is a ‘:’-separated list of pathnames.

%F - The filename %L - The language string, as returned by setlocale(LC_MESSAGES, None) %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:	`GLib.Error`
Returns:	`True` on success, else `False`.
Return type:	`bool`

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:	`GLib.Error`
Returns:	`True` on success, `False` otherwise, in which case error will be set.
Return type:	`bool`

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(), xfce_resource_lookup_dirs() 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:	`str`

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:	`str`

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

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:	`str`

Duplicates the src string up to max_len characters (note that characters does not mean bytes with UTF-8).

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

New in version 4.3.

Libxfce4util.version_string()¶

Returns:	the overall version information of the installed Xfce desktop.
Return type:	`str`

Queries the version string of the installed Xfce desktop environment.

New in version 4.2.