/////
vim:set ts=4 sw=4 tw=82 noet:
/////
:quotes.~:

imv (5)
=======

Name
----
imv - imv configuration file

Description
-----------

imv can be customised with this configuration file, changing its default
behaviour, key bindings, and appearance.

The imv configuration file is an ini-style file, with multiple 'key = value'
settings, separated into several '[section]'s.

Options
-------

The *[options]* section accepts the following settings:

*background* = <hex-code|'checks'>::
	Set the background in imv. Can either be a 6-digit hexadecimal colour code,
	or 'checks' for a chequered background. Defaults to '000000'

*fullscreen* = <true|false>::
	Start imv fullscreen. Defaults to 'false'.

*width* = <width>::
	Initial width of the imv window. Defaults to 1280.

*height* = <height>::
	Initial height of the imv window. Defaults to 720.

*initial_pan* = <pan_factor_x> <pan_factor_y>::
	Initial pan/focus position factor of the opened images. A value of 50
	represents the middle point of the image (50%).
	Defaults to '50 50'

*list_files_at_exit* = <true|false>::
	Print open files to stdout at exit, each on a separate line.
	Defaults to 'false'.

*loop_input* = <true|false>::
	Return to first image after viewing the last one. Defaults to 'true'.

*overlay* = <true|false>::
	Start with the overlay visible. Defaults to 'false'.

*overlay_font* = <typeface:size>::
	Use the specified font in the overlay. Defaults to 'Monospace:24'.

*overlay_text* = <text>::
	Use the given text as the overlay's text. The provided text is shell expanded,
	so the output of commands can be used (for example, '$(ls)'). Environment
	variables can also be used, including the ones accessible to imv's 'exec'
	command.

*overlay_text_color* = <hex-code>::
	Set the color for the text in the overlay. Is a 6-digit hexadecimal color
	code. Defaults to 'ffffff'.

*overlay_text_alpha* = <hex-code>::
	Set the alpha for the text in the overlay. Is a 2-digit hexadecimal color
	code. Defaults to 'ff'.

*overlay_background_color* = <hex-code>::
	Set the color for the background of the overlay. Is a 6-digit hexadecimal color
	code. Defaults to '000000'.

*overlay_background_alpha* = <hex-code>::
	Set the alpha for the background of the overlay. Is a 2-digit hexadecimal color
	code. Defaults to 'c3'.

*overlay_position_bottom* = <true|false>::
	Display the overlay at the bottom of the imv window, instead of the top.

*recursively* = <true|false>::
	Load input paths recursively. Defaults to 'false'.

*scaling_mode* = <none|shrink|full|crop>::
	Set scaling mode to use. 'none' will show each image at its actual size.
	'shrink' will scale down the image to fit inside the window. 'full' will
	both scale up and scale down the image to fit perfectly inside the window.
	'crop' will scale and crop the image to fill the window.
	Defaults to 'full'.

*slideshow_duration* = <duration>::
	Start imv in slideshow mode, and set the amount of time to show each image
	for in seconds. Defaults to '0', i.e. no slideshow.

*suppress_default_binds* = <true|false>::
	Disable imv's built-in binds so they don't conflict with custom ones.
	Defaults to 'false'.

*title_text* = <text>::
	Use the given text as the window's title. The provided text is shell
	expanded, so the output of commands can be used: '$(ls)' as can environment
	variables, including the ones accessible to imv's 'exec' command.

*upscaling_method* = <linear|nearest_neighbour>::
	Use the specified method to upscale images. Defaults to 'linear'.

Aliases
-------

The *[aliases]* section allows aliases to be added for imv's build in commands.
For example, 'x = close' would add a 'x' command that simply executes the
'close' command.  Any arguments provided to an alias are appended to the
command configured by the alias.

Binds
-----

The *[binds]* section allows custom key bindings to be added to imv.

Binds are in the format 'key combination = command'. A key combination can
consist of multiple keys in succession. Multiple commands for a single key
combination can be defined by separating each command with a ';'. Single and
double quotes are honoured, as is escaping with a backslash, to allow the
proper quoting of shell commands.

Single keys such as 'q' are just that: 'q = quit' will bind the 'q' key to the
'quit' command.

Modifier keys can be specified by prefixing them: 'Ctrl+q', 'Meta+f',
'Shift+G'. If multiple modifier keys are desired, they are specified in the
order 'Ctrl+Meta+Shift'. When a key's name is more than a single character,
or a modifier is used it must be wrapped in '<' and '>', for example:
'<Ctrl+q>'.

Multiple keys in succession can be specified by listing them in order:
'gg = goto 1' will bind two presses of the 'g' key to jump to the first
image, and '<Ctrl+a>p = exec echo hi' will bind the key sequence of 'Ctrl+a'
followed by 'p' to executing the shell command 'echo hi'.

Many keys, such as '<', and '>' have special names. On X11, these can be easily
found with the xev(1) command. For example, '!' is called 'exclam', '<' is
called 'less', '>' is called 'greater'.

A complete list of keysyms can also be found on most systems with the
'dumpkeys -l' command.

**imv**(1)
