~~NOTOC~~ 
====== Settings of xfdashboard ======
\\
<note warning>This document is work-in-progress and refers to the current development version of **xfdashboard**. Settings names and types may change although it is tried to keep it stable. It may also not be up-to-date.</note>
\\
===== Table of contents =====

  * [[#Get and modify settings|Get and modify settings]]

  * [[#Table of settings|Table of settings]]
    * [[#General|General]]
    * [[#Applications view|Applications view]]
    * [[#Windows view|Windows view]]

  * [[#Key bindings and actions|Key bindings and actions]]

  * [[#List of actions|List of actions]]
    * [[#XfdashboardFocusable|XfdashboardFocusable]]
    * [[#XfdashboardFocusManager|XfdashboardFocusManager]]
    * [[#XfdashboardQuicklaunch|XfdashboardQuicklaunch]]
    * [[#XfdashboardWindowsView|XfdashboardWindowsView]]

----

\\ ===== Get and modify settings =====

The settings of **xfdashboard** are stored via Xfconf in channel **xfdashboard**.

To get value of a setting execute the following command:

<code>
xfconf-query -c xfdashboard -p PROPERTY-NAME
</code>

To modify a value either use the graphical editor **xfce4-settings-editor** or run the following command:

<code>
xfconf-query -c xfdashboard -p PROPERTY-NAME -n -t TYPE -s VALUE
</code>

<note important>The **PROPERTY-NAME** is a combination of a path and a name. Please notice the path which has to be prefixed to the real property name, e.g. you have to prefix **/** to the property **theme** - which is **/theme** at the end - to change the **theme** property.

The path is mentioned in the introduction of each group.</note>

\\ ===== Table of settings =====

==== General ====

The following table lists all possible settings affecting the core of **xfdashboard**. All property names must be prefixed with the path **/**.

^ Name ^ Type ^ Default ^ Description ^
| enable-unmapped-window-workaround | boolean | false | If set to true a workaround for minimized windows is activated which tries to get still images of these windows by restoring them shortly and minimizing them again. Be aware that this is a workaround and your minimized windows could stay unminimized. | 
| favourites | array of strings | //(empty)// | Contains a list of strings. Each string specifies a **.desktop** file to an application shown in quicklaunch. The order in this array is the order how the icons in quicklaunch appear. Each **.desktop** file must be given without path - just the plain filename. | 
| min-notification-timeout | unsigned integer | 3000 | Specifies the minimum time in milliseconds a notification is displayed on screen. | 
| reset-search-on-resume | boolean | true | If set to true then the search view will be resetted when xfdashboard resumes. That means the active view is switched back to last view active before search was started and search box will be emptied. \ This setting only takes effect if **xfdashboard** is running in daemon mode. | 
| switch-view-on-resume | string | //(empty)// | If set to a valid and known internal name of a view this view will always be activated when xfdashboard resumes and specified view is not a search view. This setting is case-sensitive. \ Valid names for built-in views are: **windows** and **applications**. \ This setting only takes effect if **xfdashboard** is running in daemon mode. | 
| theme | string | xfdashboard | Name of theme to use for styling. More information about file-location and how this setting is used see section [[projects:applications:xfdashboard:theming#File location and structure|File location and structure]] in documentation about [[projects:applications:xfdashboard:theming|theming]]. | 

==== Applications view ====

The following table lists all possible settings affecting the built-in applications view of **xfdashboard**. All property names must be prefixed with the path **/components/applications-view/**.

^ Name ^ Type ^ Default ^ Description ^
| show-all-apps | boolean | false | If set to true a menu entry &quot;All installed applications&quot; is shown containing all installed applications without any sub-directory. |

==== Windows view ====

The following table lists all possible settings affecting the built-in windows view of **xfdashboard**. All property names must be prefixed with the path **/components/windows-view/**.

^ Name ^ Type ^ Default ^ Description ^
| scroll-event-changes-workspace | boolean | false | If set to true any scroll event, like mouse-whell up or down, will change the active workspace. This behaviour is the same as in workspace selector. | 

\\ ===== Key bindings and actions =====

A key binding describes which action to trigger when a specified key combination is pressed at an actor - optionally this action can be triggered at a different target actor.

Key bindings are configured in a XML document.

**xfdashboard** will look up for the key binding configuration file **bindings.xml** at the paths in the following order:

  * ${XDG_CONFIG_HOME}/xfdashboard/bindings.xml
  * ${SYSTEM-WIDE-DATA}/xfdashboard/bindings.xml

The XML document must begin with the top-level element **<bindings>** which is a grouping element for all key bindings defined. The top-level element does not expect any attributes set.

Key bindings are **<key>** elements under the top-level elements and takes two required attributes and three optional attributes.

The first required attribute is **code** which describes the key combination. Each key and modifier must be listed here and seperated by either **+**, **-** or spaces. Modifiers must be enclosed by **<** and **>**. Valid modifiers are: **<Ctrl>**, **<Control>**, **<Shift>**, **<Alt>**, **<Mod1>**, **<Mod2>**, **<Mod3>**, **<Mod4>**, **<Mod5>**, **<Super>**, **<Hyper>** and **<Meta>**.

The second required attribute is **source** which describes which actor must have be focus when the key combination configured in **code** is pressed to get the action triggered. It take the object's class name. Using **XfdashboardFocusable** as source matches every currently focused actor and can be used as a global key bindings which works at any time.

The third attribute **when** is optional and describes when the action should be triggered - either when the key combination configured in **code** is pressed or released. Valid value are **pressed** when the action should be triggered when the key combination is pressed or **released** when it should be triggered on release of the pressed key combination. If this attribute is missing the default is **pressed**.

The fourth attribute **target** is optional and describes at which other actor the action should be triggered at. The target actor must be a focusable actor that means it must be derived from class **XfdashboardFocusable**. The value of this attribute is the object's class name of the targer. If this attribute is missing the default is to trigger the action on currently focused actor which is usually the same as in **source**.

The fifth attribute **allow-unfocusable-targets** is optional and describes if an action should also be triggered, even if an unfocusable actor was defined at **target**. This attribute expect a boolean value - either **true** or **false**. But also their numeric counterparts 0 and 1 are valid. Usually you should never set this attribute and is mostly used for views at the moment as the view in **target** may not be active and visible at the time the action should be triggered. If this attribute is missing the default is **false**.

The content of the **key** element is the action to trigger and must be set.

The format for the XML file can be described with the following simple but not fully accurate DTD: 

<code>
<!ELEMENT bindings (key*)>

<!ELEMENT key      (#CDATA)>
<!ATTLIST key      code                         CDATA    #REQUIRED
                   source                       CDATA    #REQUIRED
                   when                         CDATA    #IMPLIED
                   target                       CDATA    #IMPLIED
                   allow-unfocusable-targets    CDATA    #IMPLIED>
</code>

\\ ===== List of actions =====

==== XfdashboardFocusable =====

^ Action ^ Description ^
| selection-move-left | Move selection left |
| selection-move-right | Move selection right |
| selection-move-up | Move selection up |
| selection-move-down | Move selection to left |
| selection-move-page-left | Move selection left by page |
| selection-move-page-right | Move selection right by page |
| selection-move-page-up | Move selection up by page |
| selection-move-page-down | Move selection down by page |
| selection-move-first | Move selection to first item |
| selection-move-last | Move selection to last item |
| selection-activate | Activate current selection |


==== XfdashboardFocusManager =====

^ Action ^ Description ^
| focus-move-next | Move focus to next focusable actor |
| focus-move-previous | Move focus to previous focusable actor |


==== XfdashboardQuicklaunch =====

^ Action ^ Description ^
| favourite-reorder-left | Move selected favourite to left and reorder all favourites |
| favourite-reorder-right | Move selected favourite to right and reorder all favourites |
| favourite-reorder-up | Move selected favourite upwards and reorder all favourites |
| favourite-reorder-down | Move selected favourite downwards and reorder all favourites |
| selection-add-favourite | Add current selection at any focusable actor to favourites if possible |
| selection-remove-favourite | Remove current selection from favourites (like dragging it to trash) |


==== XfdashboardWindowsView =====

^ Action ^ Description ^
| window-close | Close window of current selection in view |
| windows-activate-window-one | Activate first window in view |
| windows-activate-window-two | Activate second window in view |
| windows-activate-window-three | Activate third window in view |
| windows-activate-window-four | Activate 4th window in view |
| windows-activate-window-five | Activate 5th window in view |
| windows-activate-window-six | Activate 6th window in view |
| windows-activate-window-seven | Activate 7th window in view |
| windows-activate-window-eight | Activate 8th window in view |
| windows-activate-window-nine | Activate 9th window in view |
| windows-activate-window-ten | Activate 10th window in view |
| windows-show-numbers | Show digit for key-binding shortcut instead of close button |
| windows-hide-numbers | Hide digit for key-binding shortcut and show close button again |