File: pqiv.1

package info (click to toggle)
pqiv 2.6-1
  • links: PTS
  • area: main
  • in suites: stretch
  • size: 500 kB
  • ctags: 659
  • sloc: ansic: 6,227; sh: 318; makefile: 4
file content (526 lines) | stat: -rw-r--r-- 18,152 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
.\" vim:filetype=groff
.TH pqiv 1 "March 2016" "1.5"
.SH NAME
pqiv \- quick image viewer
.\"
.SH SYNOPSIS
\fBpqiv\fR [options] [filename(s)...]
.\"
.SH DESCRIPTION
\fBpqiv\fR is a simple command line image viewer inspired by qiv. It is highly
customizable and supports a variety of formats.
.\"
.SH OPTIONS
.\"
.TP
.BR \-c ", " \-\-transparent\-background
Draw \fBpqiv\fR's window borderless and transparent. In window mode, a mouse
click activates and deactivates window decorations.
.\"
.TP
.BR \-d ", " \-\-slideshow\-interval=\fISECONDS\fR
In slideshow mode (Activated by \fB\-\-slideshow\fR or key \fBs\fR by default),
cycle through images at this rate. Floating point values are supported, e.g.
use 0.5 to move through the images at a rate of two images per second.
.\"
.TP
.BR \-f ", " \-\-fullscreen
Start in fullscreen mode. Fullscreen can be toggled by pressing \fBf\fR at
runtime by default.
.\"
.TP
.BR \-F  ", " \-\-fade
Fade between images. See also \fB\-\-fade\-duration\fR.
.\"
.TP
.BR \-i ", " \-\-hide\-info\-box
Initially hide the info box. Whether the box is visible can be toggled by
pressing \fBi\fR at runtime by default.
.\"
.TP
.BR \-l ", " \-\-lazy\-load
\fBpqiv\fR normally processes all command line arguments before displaying its
main window. With this option, the window is shown as soon as the first image
has been found and loaded.
.\"
.TP
.BR \-n ", " \-\-sort
Instead of storing images in the order they are given on the command line and
found within directories, sort them. The default order is by name (natural
order). See \fB\-\-sort\-key\fR to change the order.
.\"
.TP
.BR \-P ", " \-\-window\-position=\fIPOSITION\fR
Set the initial window position. \fIPOSITION\fR may either be
.RS
.IP x,y 5
screen coordinates, or
.IP off
to not position the window at all.
.RE
.\"
.TP
.BR \-r ", " \-\-additional\-from\-stdin
Read additional filenames/folders from the standard input. This option
conflicts with \fB\-\-commands\-from\-stdin\fR.
.\"
.TP
.BR \-s ", " \-\-slideshow
Start in slideshow mode. Slideshow mode can be toggled at runtime by pressing
\fBs\fR by default.
.\"
.TP
.BR \-t ", " \-\-scale\-images\-up
Scale images up to fill the whole screen. This can be toggled at runtime by
pressing \fBt\fR by default. See also \fB\-\-disable\-scaling\fR.
.\"
.TP
.BR \-T ", " \-\-window\-title=\fITITLE\fR
Set the title of the window. \fBpqiv\fR substitutes several variables into \fITITLE\fR:
.RS
.IP $BASEFILENAME 15
The base file name of the current file (e.g. `\fIimage.png\fR'),
.IP $FILENAME
The file name of the current file (e.g. `\fI/home/user/image.png\fR'),
.IP $WIDTH
The width of the current image in pixels,
.IP $HEIGHT
The height of the current image in pixels,
.IP $ZOOM
The current zoom level,
.IP $IMAGE_NUMBER
The index of the current image,
.IP $IMAGE_COUNT
The total number of images.
.PP
The default is `pqiv: $FILENAME ($WIDTHx$HEIGHT) $ZOOM% [$IMAGE_NUMBER/$IMAGE_COUNT]'.
.RE
.\"
.TP
.BR \-z ", " \-\-zoom\-level=\fIFLOAT\fR
Set the initial zoom level as a floating point value, i.e., 1.0 is 100%. This
only applies to the first image, other images are scaled according to the scale
mode (see \fB\-\-scale\-images\-up\fR and \fB\-\-disable\-scaling\fR) and
window size.
.\"
.TP
.BR \-1 ", " \-\-command\-1=\fICOMMAND\fR
Bind the external \fICOMMAND\fR to key 1. You can use 2..9 to bind further
commands. The \fBACTIONS\fR feature (see below) allows to bind further keys to
other commands. \fICOMMAND\fR is executed using the default shell processor.
`$1' is substituted with the current file name.
.RS
.PP
If \fICOMMAND\fR begins with `>', its standard output is displayed in a popup window.
.PP
If \fICOMMAND\fR begins with `|', the current image is piped to its standard
input, and its standard output is loaded as an image. This can be used to e.g.
process images.
.RE
.\"
.TP
.BR \-\-action=\fIACTION\fR
Execute a specific \fIACTION\fR when starting \fBpqiv\fR. The syntax is
.RS
.RS
command(parameter); command(parameter);
.RE
See the \fBACTIONS\fR section below for available commands.
.RE
.\"
.TP
.BR \-\-actions\-from\-stdin
Like \fB\-\-action\fR, but read actions from the standard input. See the
\fBACTIONS\fR section below for syntax and available commands. This option
conflicts with \fB\-\-additional\-from\-stdin\fR.
.\"
.TP
.BR \-\-bind\-key=\fIKEY BINDING\fR
Rebind a key to an action. The syntax is
.RS
.RS
key sequence { command(parameter); command(parameter); }
.RE
A key sequence may be one or more characters, or special characters supplied as
`<name>', where name is a GDK key specifier or a mouse button (`Mouse-1') or a
scrolling direction (`Mouse-Scroll-1'). If you e.g. use `a<Control>b', then a
user must hit `a' followed by control + `b' to trigger the command. It is possible
to bind `a' and `ab' as well. The action bound to `a' will then be slightly delayed
to allow a user to hit `b'. The semicolon separating commands is optional. See
\fBACTIONS\fR below for available commands.
.PP
If you need to know the name of a key specifier, you can run \fBxev\fR and
press the desired key. The name of the keysym will be printed in parentheses,
preceded by `keysym' and a hexadecimal representation. An alternative is to
run \fBxmodmap \-pk\fR. The command outputs the symbolic names in parentheses.
Or use the list at
\fIhttps://git.gnome.org/browse/gtk+/plain/gdk/gdkkeysyms.h\fR.
.RE
.\"
.TP
.BR \-\-browse
For each command line argument, additionally load all images from the image's
directory. \fBpqiv\fR will still start at the image that was given as the first
parameter.
.\"
.TP
.BR \-\-disable\-scaling
Completely disable scaling. This can be toggled at runtime by
pressing \fBt\fR by default. See also \fB\-\-scale\-images\-up\fR.
.\"
.TP
.BR \-\-end\-of\-files\-action=\fIACTION\fR
If all files have been viewed and the next image is to be viewed, either by the
user's request or because a slideshow is active, \fBpqiv\fR by default cycles
and restarts at the first image. This parameter can be used to modify this
behaviour. Valid choices for \fIACTION\fR are:
.RS
.IP quit 20
Quit \fBpqiv\fR,
.IP wait
Wait until a new image becomes available. This only makes sense if used with
e.g. \fB\-\-watch\-directories\fR,
.IP wrap\ (default)
Restart at the first image. In shuffle mode, choose a new random order,
.IP wrap-no-reshuffle
As wrap, but do not reshuffle in random mode.
.RE
.\"
.TP
.BR \-\-enforce\-window\-aspect\-ratio
Tell the window manager to enforce the aspect ratio of the window. If this flag
is set, then a compliant window manager will not allow users to resize
\fBpqiv\fR's window to a different aspect ratio.
This used to be the default behaviour, but window managers tend to have bugs in
the code handling forced aspect ratios. If the flag is not set and the aspect
ratios of the window and image do not match, then the image will be still be
drawn with the correct aspect ratio, with black borders added at the sides.
.\"
.TP
.BR \-\-fade\-duration=\fISECONDS\fR
With \fB\-\-fade\fR, make each fade this long. Floating point values are
accepted, e.g. 0.5 makes each fade take half a second.
.\"
.TP
.BR \-\-low\-memory
Try to keep memory usage to a minimum. \fBpqiv\fR by default e.g. preloads the
next and previous image to speed up navigation and caches scaled images to
speed up redraws. This flag disables such optimizations.
.\"
.TP
.BR \-\-max\-depth=\fILEVELS\fR
For parameters that are directories, \fBpqiv\fR searches recursively for
images. Use this parameter to limit the depth at which \fBpqiv\fR searches.  A
level of 0 disables recursion completely, i.e. if you call pqiv with a
directory as a parameter, it will not search it at all.
.\"
.TP
.BR \-\-recreate\-window
Workaround for window managers that do not handle resize requests correctly:
Instead of resizing, recreate the window whenever the image is changed. This
does not redraw images upon changes in zoom alone.
.\"
.TP
.BR \-\-shuffle
Display files in random order. This option conflicts with \fB\-\-sort\fR. Files
are reshuffled after all images have been shown, but within one cycle, the
order is stable. The reshuffling can be disabled using
\fB\-\-end\-of\-files\-action\fR. At runtime, you can use \fBControl + R\fR by
default to toggle shuffle mode; this retains the shuffled order, i.e., you can
disable shuffle mode, view a few images, then enable it again and continue
after the last image you viewed earlier in shuffle mode.
.\"
.TP
.BR \-\-show\-bindings
Display the keyboard and mouse bindings and exit. This displays the key
bindings in the format accepted by \fB\-\-bind\-key\fR. See there, and the
\fBACTIONS\fR section for details on available actions.
.\"
.TP
.BR \-\-sort\-key=\fIPROPERTY\fR
Key to use for sorting. Supported values for \fIPROPERTY\fR are:
.RS
.IP NAME 8
To sort by filename in natural order, e.g. \fIabc32d\fR before \fIabc112d\fR,
but \fIb1\fR after both,
.IP MTIME
To sort by file modification date.
.RE
.\"
.TP
.BR \-\-watch\-directories
Watch all directories supplied as parameters to \fBpqiv\fR for new files and
add them as they appear. In \fB\-\-sort\fR mode, files are sorted into the
correct position, else, they are appended to the end of the list.
See also \fB\-\-watch\-files\fR, which handles how changes to the image that is
currently being viewed are handled.
.\"
.TP
.BR \-\-watch\-files=\fIVALUE\fR
Watch files for changes on disk. Valid choices for \fIVALUE\fR are:
.RS
.IP "on (default)" 15
Watch files for changes, reload upon a change, and skip to the next file if a file is removed,
.IP changes-only
Watch files for changes, reload upon a change, but do nothing if a file is removed,
.IP off
Do not watch files for changes at all.
.PP
Note that a file that has been removed will still be removed from \fBpqiv\fR's
image list when it has been unloaded, i.e. if a user moves more than one image
away from it. (See also \fB\-\-low\-memory\fR.)
.RE
.\"
.\"
.SH ACTIONS
Actions are the building blocks for controlling \fBpqiv\fR. The syntax for
entering an action is
.RS
\fICOMMAND\fR(\fIPARAMETER\fR)
.RE
where \fICOMMAND\fR is one of the commands described in the following and
\fIPARAMETER\fR is the command's parameter. Strings are not quoted. Instead,
the closing parenthesis must be escaped by a backslash if it is used in a
string. E.g., `command(echo \\))' will output a single `)'. The available
commands are:
.TP
.BR add_file(STRING)
Add a file or directory.
.TP
.BR bind_key(STRING)
Override a key binding. Remember to quote closing parenthesis inside the new
definition by prepending a backslash. Useful in conjunction with
\fBsend_keys(STRING)\fR to set up cyclic bindings.
.TP
.BR command(STRING)
Execute the given command.
.TP
.BR flip_horizontally()
Flip the current image horizontally.
.TP
.BR flip_vertically()
Flip the current image vertically.
.TP
.BR goto_directory_relative(INT)
Jump to the \fIn\fR'th next or previous directory.
.TP
.BR goto_file_byindex(INT)
Jump to a file given by its number.
.TP
.BR goto_file_byname(STRING)
Jump to a file given by its displayed name.
.TP
.BR goto_file_relative(INT)
Jump to the \fIn\fR'th next or previous file.
.TP
.BR hardlink_current_image()
Hardlink the current image to \fI./.pqiv-select/\fR, or copy it if hardlinking is not possible.
.TP
.BR jump_dialog()
Display the jump dialog.
.TP
.BR nop()
Do nothing. Can be used to clear an existing binding.
.TP
.BR numeric_command(INT)
Execute the \fin\fR'th command defined via \fB\-\-command\-1\fR etc.
.TP
.BR output_file_list()
Output a list of all loaded files to the standard output.
.TP
.BR quit()
Quit pqiv.
.TP
.BR reload()
Reload the current image from disk.
.TP
.BR remove_file_byindex(INT)
Remove a file given by its number.
.TP
.BR remove_file_byname(STRING)
Remove a file given by its displayed name.
.TP
.BR reset_scale_level()
Reset the scale level to the default value.
.TP
.BR rotate_left()
Rotate the current image left by 90°.
.TP
.BR rotate_right()
Rotate the current image right by 90°.
.TP
.BR send_keys(STRING)
Emulate pressing a sequence of keys. This action currently does not support
special keys that do not have an ASCII representation. Useful in conjunction
with \fBbind_key(STRING)\fR to set up cyclic key bindings.
.TP
.BR set_cursor_visibility(INT)
Set the visibility of the cursor; 0 disables, other values enable visibility.
.TP
.BR set_scale_level_absolute(DOUBLE)
Set the scale level to the parameter value. 1.0 is 100%. See also
\fB\-\-zoom\-level\fR.
.TP
.BR set_scale_level_relative(DOUBLE)
Adjust the scale level multiplicatively by the parameter value.
.TP
.BR set_scale_mode_fit_px(INT,\ INT)
Always adjust the scale level such that each image fits the given dimensions.
.TP
.BR set_shift_align_corner(STRING)
Align the image to the window/screen border. Possible parameter values are the
cardinal directions, e.g. \fINE\fR will align the image to the north east, i.e. \
top right, corner. You can prepend the parameter by an additional \fIC\fR to
perform the adjustment only if the image dimensions exceed the available space,
and to center the image elsewise.
.TP
.BR set_shift_x(INT)
Set the shift in horizontal direction to a fixed value.
.TP
.BR set_shift_y(INT)
Set the shift in vertical direction to a fixed value.
.TP
.BR set_slideshow_interval_absolute(DOUBLE)
Set the slideshow interval to the parameter value, in seconds.
.TP
.BR set_slideshow_interval_relative(DOUBLE)
Adjust the slideshow interval additively by the parameter value. See also
\fB\-\-slideshow\-interval\fR.
.TP
.BR set_status_output(INT)
Set this to non-zero to make pqiv print status information for scripts to
stdout, once upon activation and then whenever the user moves between images.
The format is compatible with shell variable definitions. Variables currently
implemented are \fICURRENT_FILE_NAME\fR and \fICURRENT_FILE_INDEX\fR. An
output sweep always ends with an empty line.
.TP
.BR shift_x(INT)
Shift the current image in x direction.
.TP
.BR shift_y(INT)
Shift the current image in y direction.
.TP
.BR toggle_fullscreen()
Toggle fullscreen mode.
.TP
.BR toggle_info_box()
Toggle the visibility of the info box.
.TP
.BR toggle_scale_mode(INT)
Change the scale mode: Use 1 to disable scaling, 2 for automated scaledown
(default), 3 to always scale images up, and 4 to maintain the user-set zoom
level. 0 cycles through modes 1\-3.
.TP
.BR toggle_shuffle_mode(INT)
Toggle shuffle mode. Use 0 to cycle through the possible values, 1 to enable shuffle, and any other value to disable it.
.TP
.BR toggle_slideshow()
Toggle slideshow mode.
.\"
.SH DEFAULT KEY BINDINGS
.IP Space 20
Next file.
.IP Backspace
Previous file.
.IP a
Link the current image to \fI./.pqiv-select/\fR, or copy it if hardlinking is not possible.
.IP f
Toggle fullscreen mode.
.IP h/v
Flip the image horizontally or vertically.
.IP k/l
Rotate the image right or left.
.IP i
Toggle visibility of the info box.
.IP j
Show a dialog with a list of all files for quick selection.
.IP q
Quit \fBpqiv\fR
.IP r
Reload the current image.
.IP s
Toggle slideshow mode.
.IP t
Toggle the scale mode; cycle between scaling all images up, scaling large images down and no scaling at all.
.IP Plus/minus
Zoom.
.IP "Mouse buttons (fullscreen)"
Goto the next and previous files.
.IP "Mouse drag (fullscreen)"
Move the image.
.IP "Mouse drag with right button (fullscreen)"
Zoom.
.IP "Arrow keys"
Move the image.
.PP
This list omitted some advanced default bindings. Run `\fBpqiv
\-\-show\-bindings\fR' to display a complete list.
.\"
.SH CONFIGURATION FILE
Upon startup, \fBpqiv\fR parses the file \fI~/.pqivrc\fR. It should be a
INI-style key/value file with an \fIoptions\fR section. All long form
parameters are valid keys. To set a boolean flag, set the value to 1. A set
flag inverts the meaning of the associated parameter. E.g., if you set
`\fIfullscreen=1\fR', then \fBpqiv\fR will start in fullscreen mode unless you supply
\fB\-f\fR upon startup.
.PP
As an example,
.RS
.nf
[options]
fullscreen=1
sort=1
command-1=|convert - -blur 20 -
.fi
.RE
will make \fBpqiv\fR start in fullscreen by default, sort the file list and
bind a blur filter to key \fB1\fR. The \fB\-f\fR flag on the command line will
make \fBpqiv\fR not start in fullscreen, and \fB\-n\fR will make it not sort
the list.
.PP
You can place key bindings in the format of the \fB\-\-bind\-key\fR
parameter in a special \fI[keybindings]\fR section. E.g.,
.RS
.nf
[keybindings]
q { goto_file_relative(-1); }
w { goto_file_relative(1); }

x { send_keys(#1); }
<numbersign>1 { set_scale_level_absolute(1.); bind_key(x { send_keys(#2\\); }); }
<numbersign>2 { set_scale_level_absolute(.5); bind_key(x { send_keys(#3\\); }); }
<numbersign>3 { set_scale_level_absolute(0.25); bind_key(x { send_keys(#1\\); }); }
.fi
.RE
will remap \fIq\fR and \fIw\fR to move between images, and set up \fIx\fR to
cycle through 100%, 50% and 25% zoom levels.
.PP
For backwards compatibility with old versions of \fBpqiv\fR, if the file does
not start with a section definition, the first line will be parsed as command
line parameters.
.PP
You may place comments into the file by beginning a line with `;' or `#'.
Comments at the end of a line are not supported.
.SH EXAMPLES
.\"
.TP
\fBpqiv \-\-bind\-key="a { goto_file_byindex(0) }" \-\-sort foo bar.pdf\fR
Rebinds \fBa\fR to go back to the first image, and loads all files from the
\fIfoo\fR folder and \fIbar.pdf\fR, sorted.
.TP
\fBpqiv \-\-slideshow \-\-watch\-directories \-\-end\-of\-files\-action=wait \-\-slideshow\-interval=0.001 test\fR
Load all files from the \fItest\fR folder in a slideshow progressing very fast,
and in the end wait until new files become available. This effectively displays
new images as they appear in a directory and is useful e.g. if you output images
from a script that you later intent to combine into a movie and wish to monitor
progress.
.TP
\fBecho "output_file_list(); quit()" | pqiv \-\-actions\-from\-stdin test\fR
Output a list of all files from the \fItest\fR folder that \fBpqiv\fR can
handle and quit.
.\"
.SH BUGS
Please report any bugs on github, on https://github.com/phillipberndt/pqiv
.\"
.SH AUTHOR
Phillip Berndt (phillip dot berndt at googlemail dot com)