Config cleanup (#207)

* Simplified config file, remove "cache.toml" * Added configuration instructions to README Mostly copied from Emulsion website. * Improved configuration documentation * Update README.md Co-authored-by: Jeron Aldaron Lau <[email protected]> --------- Co-authored-by: Jeron Aldaron Lau <[email protected]>
ardaku · Nov 1, 2023 · 36293d7 · 36293d7
1 parent e736d7a
commit 36293d7
Show file tree

Hide file tree

Showing 8 changed files with 494 additions and 428 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,9 @@
 ## Alloy
+
 Image viewer based on (now-discontinued) [Emulsion].
 
 Alloy targets Windows, Mac, and Linux (with more targets to come!).
 
-A note for Linux users: Wayland support is limited (for now), so for example
-expect high CPU usage and the title text not being shown. However X is fully
-supported.
-
 Releases will be made as needed, with no set schedule.  Merging of bugfix PRs
 will warrant an immediate new release.  Related features may be grouped together
 in a release.
@@ -36,6 +33,303 @@ Alloy is not currently distributed officially on crates.io or through GitHub
 releases (for Mac and Windows) and Flathub (for Linux), but will be in the
 future.
 
+## Configuration
+
+The `config.toml` file allows for some modifications in the behaviour of
+alloy.
+
+Depending on the platform, this file can be created at one of the following
+locations.
+
+- Windows: `%appdata%\Alloy\config\config.toml`
+- MacOS: `$HOME/Library/Application Support/Alloy/config.toml`
+- Linux: `$XDG_CONFIG_HOME/alloy/config.toml` or `$HOME/.config/alloy/config.toml`
+
+The contents of the `config.toml` file may for example be the following:
+
+```toml
+[window]
+title_folders = 1
+mode = "Fullscreen"
+
+[bindings]
+img_next = ["j"]
+img_prev = ["k"]
+```
+
+All sections in this file are optional, meaning that if for example only
+`[window]` is specified then every other section will be using their default
+values.
+
+## Section `[window]`
+
+Field name    | Default    | Description
+--------------|------------|-------------------------------------------------
+title_folders | `0`        | Number of folders from the path to display in title
+mode          | `"Normal"` | Window mode to start: `"Fullscreen"` / `"Maximized"`
+
+## Section `[image]`
+
+Field name   | Default   | Description
+-------------|-----------|------------
+scaling      | `"Fixed"` | Scaling mode: `"FitStretch"` / `"FitMin"`
+antialiasing | `"Auto"`  | Antialias mode: `"Always"` / `"Never"`
+
+## Section `[bindings]`
+
+Input bindings can be overridden in this section.  These are the default
+values:
+
+```toml
+img_next = ["d", "right", "pagedown"]
+img_prev = ["a", "left", "pageup"]
+img_orig = ["q", "1"]
+img_fit_best = ["e"]
+img_fit = ["f"]
+img_del = ["delete"]
+img_copy = ["cmdctrl+C"]
+
+pan = ["space"]
+play_anim = ["alt+a", "alt+v"]
+play_present = ["p"]
+play_present_rnd = ["alt+p"]
+toggle_fullscreen = ["F11", "return"]
+toggle_antialias = ["s"]
+automatic_antialias = ["alt+s"]
+escape = ["Escape"]
+
+# Zoom and pan the camera using keyboard input
+# (Not bound by default)
+zoom_in = []
+zoom_out = []
+pan_left = []
+pan_right = []
+pan_up = []
+pan_down = []
+```
+
+Note that all items in this section are optional so it’s fully valid to only
+specify one of the actions.  In this case all the rest will use the default
+bindings.  For example
+
+```toml
+[bindings]
+img_next = ["space", "right"]
+pan = []
+```
+
+The names of the actions are case sensitive but the input strings are not.
+
+It is valid to specify an empty array like `img_del = []` in which case the
+action will never be triggered.
+
+A config file with bindings will look like the following.
+
+```toml
+[bindings]
+img_next = ["d", "right"]
+img_prev = ["a", "left"]
+img_orig = ["q"]
+img_fit = ["f"]
+img_del = ["delete"]
+pan = ["space"]
+play_anim = ["alt+a", "alt+v"]
+play_present = ["p"]
+play_present_rnd = ["alt+p"]
+```
+
+Modifiers may be specified separated by `+` characters.  For example `"ctrl+x"`
+or `"ctrl+alt+u"`.  Spaces are trimmed from each element and so `" ctrl+ x"` or
+`"ctrl + alt+u "` are equally valid.
+
+The following modifiers are valid:
+
+- `alt`: The Alt key
+- `ctrl`: The Control key
+- `logo`: The Command key on macOS; the Windows key on Windows
+- `cmdctrl`: The Command key on macOS; the Control key elsewhere
+
+There are a few special cases for typeable characters:
+
+- `' '` must be specified as `space`
+- `'+'` must be specified as `add`
+- `'-'` must be specified as `subtract`
+
+The following list contains all supported non-typeable key names.
+
+```txt
+# The Escape key
+Escape,
+
+F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,
+F13, F14, F15, F16, F17, F18, F19, F20, F21, F22, F23, F24,
+
+# Print Screen/SysRq
+Snapshot,
+# Scroll Lock
+Scroll,
+# Pause/Break key
+Pause,
+
+# `Insert`, next to Backspace
+Insert,
+Home,
+Delete,
+End,
+PageDown,
+PageUp,
+
+Left,
+Up,
+Right,
+Down,
+
+Back,
+# The Enter key
+Return,
+
+# The "Compose" key on Linux
+Compose,
+
+Numlock,
+
+Numpad0, Numpad1, Numpad2, Numpad3, Numpad4,
+Numpad5, Numpad6, Numpad7, Numpad8, Numpad9,
+
+Apps,
+Ax,
+Calculator,
+Capital,
+Convert,
+Decimal,
+Kana,
+Kanji,
+LAlt,
+LControl,
+LShift,
+LWin,
+Mail,
+MediaSelect,
+MediaStop,
+Mute,
+MyComputer,
+NavigateForward,  # also called "Prior"
+NavigateBackward, # also called "Next"
+NextTrack,
+NoConvert,
+OEM102,
+PlayPause,
+Power,
+PrevTrack,
+RAlt,
+RControl,
+RShift,
+RWin,
+Sleep,
+Stop,
+Sysrq,
+Unlabeled,
+VolumeDown,
+VolumeUp,
+Wake,
+WebBack,
+WebFavorites,
+WebForward,
+WebHome,
+WebRefresh,
+WebSearch,
+WebStop,
+Yen,
+Copy,
+Paste,
+Cut,
+```
+
+## Commands
+
+Any number of `[[commands]]` sections may exist.
+
+To add a shortcut for opening the current image with Gimp on Windows, add the
+following:
+
+```toml
+# Note the double brackets!
+[[commands]]
+input = ["alt+t", "u"]
+program = "cmd"
+# Note that the Gimp exe path is between single quotation marks (')
+args = ["/C", "start", "", 'C:\Program Files\GIMP 2\bin\gimp-2.10.exe', "${img}"]
+```
+
+A very simple command might look like the one below.
+
+```toml
+# Note the double brackets!
+[[commands]]
+input = ["alt+k"]
+program = "git"
+```
+
+With the above added to the `config.toml` file, whenever the `alt+k` key
+combination is pressed, alloy executes git which prints the default git cli
+help message to the standard output.  As you can see input is an array, meaning
+that a single command can be bound to any number of different inputs.  See the
+bindings section for more on specifying inputs.
+
+Any command is only executed when there’s an image open.
+
+It’s important that alloy doesn’t execute these commands in a particular shell.
+This means that many programs which are available from your preferred command
+line interface, are not available to alloy.  With that said it is possible to
+execute shell commands if we specify the shell as the program itself.  For
+example the following will print “Hello World” to the “hello.txt” file when
+executed from Windows.
+
+```toml
+[[commands]]
+input = ["alt+k"]
+program = "cmd"
+args = ["/C", "echo Hello World > hello.txt"]
+```
+
+As it was previously stated, any number of `[[commands]]` can be specified.
+
+```toml
+[[commands]]
+input = ["alt+k"]
+program = "git"
+
+# Every command definition must start with [[commands]], even
+# if the previous section was also a [[commands]] section.
+[[commands]]
+input = ["alt+l"]
+program = "git"
+args = ["status"]
+```
+
+There are two more parameters for each command.
+
+- `args`: an array of arguments passed on to the program
+- `envs`: an array of environment variable definitions
+
+Within the args, one may use `${img}` and `${folder}` for the currently open
+image file path and its parent folder path respectively.  Note that these are
+substituted with a simple find and replace so there’s no need to escape dollar
+signs ($) and they have to be typed in the exact format specified here.
+
+The following example specifies a single environment variable and invokes cmd
+with three command line arguments.
+
+```toml
+[[commands]]
+input = ["alt+t", "u"]
+program = "cmd"
+args = ["/C", "echo", "%TEST_VAR% ${img}"]
+envs = [{name = "TEST_VAR", value = "Wohoo :D"}]
+```
+
+This might for example print: `Wohoo :D \\?\D:\MyImages\mountain.jpg`
+
 ## Reporting Bugs
 
 If Alloy closes unexpectedly please locate the `"panic.txt"` file. This file has