community.general.xfconf module – Edit XFCE4 Configurations

Note

This module is part of the community.general collection (version 10.0.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.xfconf.

Synopsis

  • This module allows for the manipulation of Xfce 4 Configuration with the help of xfconf-query.

Parameters

Parameter

Comments

channel

string / required

A Xfconf preference channel is a top-level tree key, inside of the Xfconf repository that corresponds to the location for which all application properties/keys are stored. See man xfconf-query(1).

force_array

aliases: array

boolean

added in community.general 1.0.0

Force array even if only one element.

Choices:

  • false ← (default)

  • true

property

string / required

A Xfce preference key is an element in the Xfconf repository that corresponds to an application preference. See man xfconf-query(1).

state

string

The action to take upon the property/value.

The state get has been removed in community.general 5.0.0. Please use the module community.general.xfconf_info instead.

Choices:

  • "present" ← (default)

  • "absent"

value

list / elements=any

Preference properties typically have simple values such as strings, integers, or lists of strings and integers. See man xfconf-query(1).

value_type

list / elements=string

The type of value being set.

When providing more than one value_type, the length of the list must be equal to the length of value.

If only one value_type is provided, but value contains more than on element, that value_type will be applied to all elements of value.

If the property being set is an array and it can possibly have only one element in the array, then force_array=true must be used to ensure that xfconf-query will interpret the value as an array rather than a scalar.

Support for uchar, char, uint64, and int64 has been added in community.general 4.8.0.

Choices:

  • "string"

  • "int"

  • "double"

  • "bool"

  • "uint"

  • "uchar"

  • "char"

  • "uint64"

  • "int64"

  • "float"

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

See Also

See also

xfconf-query(1) man page

Manual page of the xfconf-query tool at the XFCE documentation site.

xfconf - Configuration Storage System

XFCE documentation for the Xfconf configuration system.

Examples

---
- name: Change the DPI to "192"
  xfconf:
    channel: "xsettings"
    property: "/Xft/DPI"
    value_type: "int"
    value: "192"

- name: Set workspace names (4)
  xfconf:
    channel: xfwm4
    property: /general/workspace_names
    value_type: string
    value: ['Main', 'Work1', 'Work2', 'Tmp']

- name: Set workspace names (1)
  xfconf:
    channel: xfwm4
    property: /general/workspace_names
    value_type: string
    value: ['Main']
    force_array: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

channel

string

The channel specified in the module parameters

Returned: success

Sample: "xsettings"

cmd

list / elements=string

added in community.general 5.4.0

A list with the resulting xfconf-query command executed by the module.

Returned: success

Sample: ["/usr/bin/xfconf-query", "--channel", "xfce4-panel", "--property", "/plugins/plugin-19/timezone", "--create", "--type", "string", "--set", "Pacific/Auckland"]

previous_value

any

The value of the preference key before executing the module. Either a single string value or a list of strings for array types.

This is a string or a list of strings.

Returned: success

Sample: "\"96\" or [\"red\", \"blue\", \"green\"]"

property

string

The property specified in the module parameters

Returned: success

Sample: "/Xft/DPI"

value

any

The value of the preference key after executing the module. Either a single string value or a list of strings for array types.

This is a string or a list of strings.

Returned: success

Sample: "\"192\" or [\"orange\", \"yellow\", \"violet\"]"

value_type

any

The type of the value that was changed (none for state=reset). Either a single string value or a list of strings for array types.

This is a string or a list of strings.

Returned: success

Sample: "\"int\" or [\"str\", \"str\", \"str\"]"

Authors

  • Joseph Benden (@jbenden)

  • Alexei Znamensky (@russoz)