community.general.xfconf module – Edit XFCE4 Configurations

Note

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

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. Please see the xfconf-query(1) man page for more details.

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)