smw/deskflow
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: document the gui config

Browse source
This commit is contained in:
sithlord48 2025-08-20 01:31:10 -04:00 committed by Chris Rizzitello
parent 3a66969dec
commit 7e12c5b76d
1 changed files with 243 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

252
doc/user/configuration.md
View file

@ -34,6 +34,240 @@ Windows will save to the install dir if settings are loaded from there. If not,
When using settings from the install dir, the service mode will not be available.
## Valid GUI Keys
The GUI config file contains several sections.
Each section is formatted the same.
Option-value pairs are only written if the value is not the default value.
```
[section]
option=value
```
### Client
This section contains options used when in client mode.
It will begin with `[client]`
| Option | Valid Values | Description |
|:----------------------|:------------------:|:-----------|
| binary | Filename | The filename of the binary to call for client mode. This binary exists in the same path as the GUI |
| invertScrollDirection | `true` or `false` | Invert scroll on this client [default: false] |
| languageSync | `true` or `false` | Sync to server language [default: true] |
| remoteHost | `IP` or `hostname` | The remote host last connected to |
| xdpRestoreToken | UUID | Restore token provided by XDG portals |
### Core
This section contains general options it will begin with `[core]`
|Option | Valid Values|Description|
|:--------------|:-----------:|:-----------|
| coreMode | `0` or `1` or `2` | The mode to start in 0: None, 1: Client, 2: Server [default: 0]|
| interface | IP Address | Preferred IP to use for network communication. By default the server board casts on any available address |
| lastVersion | M.m.p.t | The version last run used for checking for updates |
| port | port # | Port to use when connecting [default: 24800 |
| preventSleep | `true` or `false` | Prevent sleep when Deskflow is active [default: false] |
| processMode | `1` or `0` | The mode we use to start the process Service or Desktop |
| screenName | string | Name used to identify the screen [default: machine's hostname] |
| startedBefore | `true` or `false `| Have we started client or server before. Used in logic when deciding to show some dialogs.
| updateUrl | URL | The URL to use when checking for a new version number, it should return a version [default: https://api.deskflow.org/version]|
### Daemon
This section contains options used by the daemon on windows it will begin with `[daemon]`
|Option | Valid Values|Description|
|:----------|:-----------:|:-----------|
| command | Filename | The filename of the binary the daemon. This binary exists in the same path as the deskflow GUI |
| elevate | `true` or `false` | Elevate the daemon app [default: true unless portable mode ] |
| logFile | Filepath | Filepath of the daemon log |
| logLevel | valid log Level, | Log Level |
### GUI
This section contains options used by the GUI it will begin with `[gui]`
|Option | Valid Values |Description|
|:------------------|:-----------------:|:-----------|
| autoHide | `true` or `false` | When true the app will hide itself on start up [default: false] |
| enableUpdateCheck | `true` or `false` | When true check the update URL to see if a new version was released on start up [default: false] |
| closeReminder | `true` or `false` | Used to track if we have shown the reminder that when you close the app it remain running in the background [default: true]|
| logExpanded | `true` or `false` | Should the log section of the GUI be opened [default: false] |
| symbolicTrayIcon | `true` or `false` | When true use the monocolor (symbolic) icon false uses a colorful icon for the tray |
| windowGeometry | QRect | Geometry of the window used to restore the window geometry after exiting the app |
### Log
This section contains options used by the application logging it will begin with `[log]`
|Option | Valid Values |Description|
|:------|:-----------------:|:-----------|
| file | Filepath | The file to write the log into |
| level | Valid log level | Log level to use |
| toFile | `true` or `false` | When true the log will be written to the value of the `file` option |
### Security
This section contains options used by the application security it will begin with `[security]`
|Option | Valid Values |Description|
|:----------------------|:-----------------:|:-----------|
| checkPeerFingerprints | `true` or `false` | When true peers will have their fingerprints confirmed by the user and stored [default: true] |
| certificate | Filepath | Path to the certificate to use to encrypt messages.|
| keySize | `2048` OR `4096` | Size of the TLS key to use [default: 2048]|
| tlsEnabled | `true` or `false` | Are we using TLS encryption when communicating [default: true].|
### Server
This section contains options used when in server mode it will begin with `[server]`
|Option | Valid Values |Description|
|:-------------------|:-----------------:|:-----------|
| binary | Filename | The name of the binary to call for client mode. This binary exists in same path as the Deskflow GUI |
| configVisible | `true` or `false` | Used internally to track when the severs has a configuration dialog showing.|
| externalConfig | `true` or `false` | When true use the external config path |
| externalConfigFile | Filepath | Path the server config file if it does not exist the GUI will it generated based on the `internalConfig` section.|
### InternalConfig
This section contains options used when in server mode it will begin with `[internalConfig]`
block of a server config file as seen below. This section is used by the GUI to generate a server configuration
```
[internalConfig]
clipboardSharing=true
clipboardSharingSize=@Variant(\0\0\0\x84\0\0\0\0\0\0<\0)
disableLockToScreen=false
hasHeartbeat=false
hasSwitchDelay=false
hasSwitchDoubleTap=false
heartbeat=5000
hotkeys\1\actions\1\activeOnRelease=false
hotkeys\1\actions\1\hasScreens=true
hotkeys\1\actions\1\keys\1\key=83
hotkeys\1\actions\1\keys\size=1
hotkeys\1\actions\1\lockCursorToScreen=0
hotkeys\1\actions\1\restartServer=false
hotkeys\1\actions\1\switchInDirection=0
hotkeys\1\actions\1\switchScreenName=void
hotkeys\1\actions\1\type=0
hotkeys\1\actions\1\typeScreenNames\size=0
hotkeys\1\actions\size=1
hotkeys\1\keys\1\key=83
hotkeys\1\keys\size=1
hotkeys\size=1
numColumns=5
numRows=3
protocol=1
relativeMouseMoves=false
screens\1\name=
screens\10\aliasArray\size=0
screens\10\fixArray\1\fix=false
screens\10\fixArray\2\fix=false
screens\10\fixArray\3\fix=false
screens\10\fixArray\4\fix=false
screens\10\fixArray\size=4
screens\10\modifierArray\1\modifier=0
screens\10\modifierArray\2\modifier=1
screens\10\modifierArray\3\modifier=2
screens\10\modifierArray\4\modifier=3
screens\10\modifierArray\5\modifier=4
screens\10\modifierArray\6\modifier=5
screens\10\modifierArray\size=6
screens\10\name=null
screens\10\switchCornerArray\1\switchCorner=false
screens\10\switchCornerArray\2\switchCorner=false
screens\10\switchCornerArray\3\switchCorner=false
screens\10\switchCornerArray\4\switchCorner=false
screens\10\switchCornerArray\size=4
screens\10\switchCornerSize=0
screens\11\name=
screens\12\name=
screens\13\name=
screens\14\name=
screens\15\name=
screens\2\name=
screens\3\name=
screens\4\name=
screens\5\name=
screens\6\name=
screens\7\aliasArray\size=0
screens\7\fixArray\1\fix=false
screens\7\fixArray\2\fix=false
screens\7\fixArray\3\fix=false
screens\7\fixArray\4\fix=false
screens\7\fixArray\size=4
screens\7\modifierArray\1\modifier=0
screens\7\modifierArray\2\modifier=1
screens\7\modifierArray\3\modifier=2
screens\7\modifierArray\4\modifier=3
screens\7\modifierArray\5\modifier=4
screens\7\modifierArray\6\modifier=5
screens\7\modifierArray\size=6
screens\7\name=void
screens\7\switchCornerArray\1\switchCorner=false
screens\7\switchCornerArray\2\switchCorner=false
screens\7\switchCornerArray\3\switchCorner=false
screens\7\switchCornerArray\4\switchCorner=false
screens\7\switchCornerArray\size=4
screens\7\switchCornerSize=0
screens\8\aliasArray\size=0
screens\8\fixArray\1\fix=false
screens\8\fixArray\2\fix=false
screens\8\fixArray\3\fix=false
screens\8\fixArray\4\fix=false
screens\8\fixArray\size=4
screens\8\modifierArray\1\modifier=0
screens\8\modifierArray\2\modifier=1
screens\8\modifierArray\3\modifier=2
screens\8\modifierArray\4\modifier=3
screens\8\modifierArray\5\modifier=4
screens\8\modifierArray\6\modifier=5
screens\8\modifierArray\size=6
screens\8\name=chris-Precision-5570
screens\8\switchCornerArray\1\switchCorner=false
screens\8\switchCornerArray\2\switchCorner=false
screens\8\switchCornerArray\3\switchCorner=false
screens\8\switchCornerArray\4\switchCorner=false
screens\8\switchCornerArray\size=4
screens\8\switchCornerSize=0
screens\9\aliasArray\size=0
screens\9\fixArray\1\fix=false
screens\9\fixArray\2\fix=false
screens\9\fixArray\3\fix=false
screens\9\fixArray\4\fix=false
screens\9\fixArray\size=4
screens\9\modifierArray\1\modifier=0
screens\9\modifierArray\2\modifier=1
screens\9\modifierArray\3\modifier=2
screens\9\modifierArray\4\modifier=3
screens\9\modifierArray\5\modifier=4
screens\9\modifierArray\6\modifier=5
screens\9\modifierArray\size=6
screens\9\name=abyss.lan
screens\9\switchCornerArray\1\switchCorner=false
screens\9\switchCornerArray\2\switchCorner=false
screens\9\switchCornerArray\3\switchCorner=false
screens\9\switchCornerArray\4\switchCorner=false
screens\9\switchCornerArray\size=4
screens\9\switchCornerSize=0
screens\size=15
switchCornerArray\1\switchCorner=false
switchCornerArray\2\switchCorner=false
switchCornerArray\3\switchCorner=false
switchCornerArray\4\switchCorner=false
switchCornerArray\size=4
switchCornerSize=0
switchDelay=250
switchDoubleTap=250
win32KeepForeground=false
```
# Server Config
The `deskflow-server` command accepts the `-c` or `--config` option, which takes one argument,
@ -76,11 +310,11 @@ This declares three screens named ''moe'', ''larry'', and ''curly''. Screen ''la
A screen can have the following options:
|Option | Valid Values| Description|
|:----------|:-----------:|:-----------|
|halfDuplexCapsLock| true or false | This computer has a ''Caps Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Caps Lock'' acts strangely on all screens then you may need to set this option to true on the server screen. If it acts strangely on one screen then that screen may need the option set to true.|
|halfDuplexNumLock | true or false | This computer has a ''Num Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Num Lock'' acts strangely on all screens then you may need to set this option to true on the server screen. If it acts strangely on one screen then that screen may need the option set to true.|
|halfDuplexScrollLock| true or false| This computer has a ''Scroll Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Scroll Lock'' acts strangely on all screens then you may need to set this option to true on the server screen. If it acts strangely on one screen then that screen may need the option set to true.|
|xtestIsXineramaUnaware| true or false| This option works around a bug in the XTest extension when used in combination with Xinerama. It affects X11 clients only. Not all versions of the XTest extension are aware of the Xinerama extension. As a result, they do not move the mouse correctly when using multiple Xinerama screens. This option is currently ''true'' by default. If you know your XTest extension is Xinerama aware then set this option to ''false''.|
|preserveFocus| true or false | When true don't drop focus when switching screens
|halfDuplexCapsLock| `true` or `false` | This computer has a ''Caps Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Caps Lock'' acts strangely on all screens then you may need to set this option to true on the server screen. If it acts strangely on one screen then that screen may need the option set to true.|
|halfDuplexNumLock | `true` or `false` | This computer has a ''Num Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Num Lock'' acts strangely on all screens then you may need to set this option to true on the server screen. If it acts strangely on one screen then that screen may need the option set to true.|
|halfDuplexScrollLock| `true` or `false`| This computer has a ''Scroll Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Scroll Lock'' acts strangely on all screens then you may need to set this option to true on the server screen. If it acts strangely on one screen then that screen may need the option set to true.|
|xtestIsXineramaUnaware| `true` or `false`| This option works around a bug in the XTest extension when used in combination with Xinerama. It affects X11 clients only. Not all versions of the XTest extension are aware of the Xinerama extension. As a result, they do not move the mouse correctly when using multiple Xinerama screens. This option is currently ''true'' by default. If you know your XTest extension is Xinerama aware then set this option to ''false''.|
|preserveFocus| `true` or `false` | When true don't drop focus when switching screens
|switchCorners| corners |See <a href="#switch-corners">switchCorners</a> below.|
|switchCornerSize | integer | see switchCornerSize below.|
|shift | shift ctrl alt meta super none | Map the server's shift modifer to different key on a client screen|
@ -157,11 +391,11 @@ end
|switchCornerSize | integer (N) | Sets the size of all corners in pixels. The cursor must be within `N` pixels of the corner to be considered to be in the corner.|
|switchDelay | integer| Deskflow won't switch screens when the mouse reaches the edge of a screen unless it stays on the edge for `N` milliseconds. This helps prevent unintentional switching when working near the edge of a screen.|
|switchDoubleTap| integer(N) | Deskflow won't switch screens when the mouse reaches the edge of a screen unless it's moved away from the edge and then back to the edge within `N` milliseconds. With the option you have to quickly tap the edge twice to switch. This helps prevent unintentional switching when working near the edge of a screen.|
|screenSaverSync| true or false| ''Note: Removed in v1.14.1'' If set to ''false'' then Deskflow won't synchronize screen savers. Client screen savers will start according to their individual configurations. The server screen saver won't start if there is input, even if that input is directed toward a client screen.|
|relativeMouseMoves| true or false| If set to ''true'' then secondary screens move the mouse using relative rather than absolute mouse moves when and only when the cursor is locked to the screen (by ''Scroll Lock'' or a configured hot key). This is intended to make Deskflow work better with certain games. If set to ''false'' or not set then all mouse moves are absolute.|
|clipboardSharing| true or false|If set to ''true'' then clipboard sharing will be enabled and the ''clipboardSharingSize'' setting will be used. If set to false, then clipboard sharing will be disabled and the the ''clipboardSharingSize'' setting will be ignored.|
|screenSaverSync| `true` or `false`| ''Note: Removed in v1.14.1'' If set to ''false'' then Deskflow won't synchronize screen savers. Client screen savers will start according to their individual configurations. The server screen saver won't start if there is input, even if that input is directed toward a client screen.|
|relativeMouseMoves| `true` or `false`| If set to ''true'' then secondary screens move the mouse using relative rather than absolute mouse moves when and only when the cursor is locked to the screen (by ''Scroll Lock'' or a configured hot key). This is intended to make Deskflow work better with certain games. If set to ''false'' or not set then all mouse moves are absolute.|
|clipboardSharing| `true` or `false`|If set to ''true'' then clipboard sharing will be enabled and the ''clipboardSharingSize'' setting will be used. If set to false, then clipboard sharing will be disabled and the the ''clipboardSharingSize'' setting will be ignored.|
|clipboardSharingSize| integer (N)| Deskflow will send a maximum of `N` kilobytes of clipboard data to another computer when the mouse transitions to that computer.|
|win32KeepForeground | true or false| If set to ''true'' (the default), Deskflow will grab the foreground focus on a Windows server (thereby putting all other windows in the background) upon switching to a client. If set to ''false'', it will leave the currently foreground window in the foreground. Deskflow grabs the focus to avoid issues with other apps interfering with Deskflow's ability to read the hardware inputs. |
|win32KeepForeground | `true` or `false`| If set to ''true'' (the default), Deskflow will grab the foreground focus on a Windows server (thereby putting all other windows in the background) upon switching to a client. If set to ''false'', it will leave the currently foreground window in the foreground. Deskflow grabs the focus to avoid issues with other apps interfering with Deskflow's ability to read the hardware inputs. |
|keystroke(key) | actions | Binds the ''key'' combination key to the given ''actions''. ''key'' is an optional list of modifiers (''shift'', ''control'', ''alt'', ''meta'' or ''super'') optionally followed by a character or a key name, all separated by + (plus signs). You must have either modifiers or a character/key name or both. See below for `valid key names` and `actions`. Keyboard hot keys are handled while the cursor is on the primary screen and secondary screens. Separate actions can be assigned to press and release.|
|mousebutton(button) | actions| Binds the modifier and mouse button combination ''button'' to the given ''actions''. ''button'' is an optional list of modifiers (''shift'', ''control'', ''alt'', ''meta'' or ''super'') followed by a button number. The primary button (the left button for right handed users) is button 1, the middle button is 2, etc. Actions can be found below. Mouse button actions are not handled while the cursor is on the primary screen. You cannot use these to perform an action while on the primary screen. Separate actions can be assigned to press and release.|