1XZGV(1) Graphics Software XZGV(1)
2
6 xzgv - picture viewer for X, with thumbnail-based file selector
7
9 xzgv [options] [dir | file ...]
10
12 (NB: This man page is automagically generated from xzgv's texinfo file,
13 and so may look a bit odd. We apologise for the inconvenience. :-))
14 xzgv is a picture viewer for X, with a thumbnail-based file selector.
16 The thumbnails used (thumbnails being small `preview' versions of the
17 pictures) are compatible with xv, zgv, and the Gimp. The kinds of pic‐
18 tures xzgv allows to be viewed are raster-format pictures (sometimes
19 called `bitmaps' and/or `pixmaps'); things like GIF files, JPEG files,
20 PNG files, and so on.
21 Most of the time, you will probably want to use xzgv's file selector
23 (see The File Selector) to pick which file(s) to view. This is what
24 appears on the left-hand side of the window when you start xzgv as just
25 `xzgv' (see Options). It displays a list of subdirectories and picture
26 files in the current directory, along with small `thumbnail' versions
27 of the pictures if they exist. (If no thumbnails appear in a given
28 directory, or if they are missing for some files, you can create/update
29 them by pressing `u'. See Updating Thumbnails.)
30 When you've picked a file to view, you can view it by clicking on it,
32 or pressing `Enter'. This reads the picture and displays it in the
33 right-hand part of the window, the viewer (see The Viewer). You can
34 then move around the picture (if it is larger than will fit) by drag‐
35 ging it with the mouse, or using the scrollbars, or the cursor keys.
36 You can then select another image with the file selector (though you
37 need to press `Esc' or `Tab' first if using the keyboard), or you can
38 quit xzgv by pressing `q'.
39 While xzgv works much like any other X program, and is certainly mouse-
41 friendly :-), it's also designed to be keyboard-friendly. Everything
42 in xzgv can be done entirely from the keyboard. Much of this keyboard
43 support works like the original zgv (a similar console-based picture
44 viewer for Linux).
45 This overview is, as you might expect, only the very simplest of intro‐
47 ductions to what xzgv can do, and describes only a very basic use of
48 xzgv. xzgv can do a lot more; read on to find out what.
49
51 xzgv was primarily written by Russell Marks, also the author of this
52 manual. It is maintained by Reuben Thomas, who ported it to Gtk+ 2.
53 Costa Sapuntzakis contributed code for much faster JPEG thumbnail gen‐
55 eration (to zgv, which I adapted for xzgv).
56 The directory/file icons used were loosely based on gmc's dir-
58 close.xpm. I think Tuomas Kuosmanen was responsible for that, judging
59 from the change log.
60 `mkinstalldirs' is straight from the `texinfo' package, and was written
62 by Noah Friedman. (This is also used during installation.)
63 Huge thanks go to the many people responsible for GTK+, without which
65 xzgv would almost certainly not have happened. (But no thanks for Elec‐
66 tric Eyes, which was nearly nice enough for me not to bother with xzgv
67 at all! :-))
68 getopt*.[ch] are from the GNU libc.
70
72 Normally you'd invoke xzgv as plain `xzgv' (perhaps via a window man‐
73 ager menu, or GNOME/KDE menu, etc.). However, you can directly specify
74 files to view, or a start directory, on the command-line. In addition,
75 there are various options.
76 (If you're new to xzgv, you should probably skip the rest of this sec‐
78 tion for now and come back to it later.)
79 The general format of the xzgv command-line goes roughly like this:
81 xzgv [options] [dir | file ...]
83 Two types of options are supported --- the traditional Unix single-let‐
85 ter options, and GNU-style long options. Most options can be used in
86 either way, and both forms are listed in the table below.
87 Note that all options are processed after any configuration file(s).
89 Config file settings are just like the long-option names below minus
90 the `--' (see Configuring xzgv), though a few command-line options are
91 not permitted as config file settings (e.g. `help'), and vice versa.
92 Here's what the options do:
94 `-a'
96 `--auto-hide'
97 Automatically hide selector when a picture is selected, allowing
98 the viewer to use the whole window.
99 `--careful-jpeg'
101 Enable libjpeg `fancy upsampling'. xzgv defaults to using the
102 faster method; as the libjpeg documentation puts it, ``The vis‐
103 ual impact of the sloppier method is often very small.''
104 `--delete-single-prompt'
106 (Note that this is normally enabled; use `--delete-single-
107 prompt=off' to disable it.) If disabled, xzgv will immediately
108 delete a file when told to, without prompting for confirmation.
109 (It's `single' because deleting multiple files at once will be
110 supported in future, and that will have a separate prompt over‐
111 ride.)
112 `--dither-hicol'
114 Use dithering in 15/16-bit, whatever the default setting is.
115 See Viewer Options, for a discussion of benefits/drawbacks. You
116 can also use `--dither-hicol=off' to disable this.
117 `--exif-orient'
119 In JPEG files, use Exif orientation tags (inserted by e.g. digi‐
120 tal cameras) to correct image orientation before display. See
121 Viewer Options, for details.
122 `--fast-recursive-update'
124 When doing a recursive thumbnail update, don't read existing
125 thumbnails before updating. This is pretty much obsolete as of
126 xzgv 0.7, as the speed increase is now negligible. But, it may
127 still be useful if you want to update a huge number of small
128 directories for which few if any updates are needed.
129 `-f'
131 `--fullscreen'
132 Run fullscreen, using the entire screen for xzgv's window, with‐
133 out even any window-manager decorations (window frame, title
134 bar, etc.) if possible.
135 `-g geom'
137 `--geometry geom'
138 Set the xzgv window's geometry (position and/or size) to geom.
139 The geometry string should be in the usual X format, with the
140 extension that positions/sizes may have a `%' suffix meaning
141 that they are treated as percentages of the screen width/height.
142 The default geometry is `92%x85%'.
143 For those unfamiliar with the way `geometry' works, here's a
145 brief description of the syntax. It's `WxH', or `+X+Y', or
146 `WxH+X+Y', where `W' is width, `H' height, `X' the x position,
147 and `Y' the y position. The first form specifies only the size,
148 the second only the position --- the `WxH+X+Y' form specifies
149 both.
150 Now, the `+X+Y' bit normally specifies where the top-left of the
152 window is. But you can use `-' instead of `+' for the x and/or y
153 position, in which case it specifies the gap between the
154 right/bottom of the window and the right/bottom of the screen.
155 (Note, however, that any window frame your window manager adds
156 to the window is disregarded in this calculation, so you may
157 need to experiment somewhat to get the desired position.) You
158 can also use negative numbers with both `+' and `-' --- so
159 `+-50+0' puts the window partly off the left of the screen, and
160 `+0--50' puts it partly off the bottom of the screen --- but
161 this is of questionable value. :-)
162 Finally, as mentioned above, xzgv extends this syntax by allow‐
164 ing you to use `%' to specify percentages of the screen
165 width/height rather than pixels, e.g. `50%x30%-30%-20%'. It also
166 allows you to use real numbers such as `12.34', which can be
167 useful with `%'.
168 `-h'
170 `--help'
171 Display a list of options and a terse description of what the
172 options do.
173 `--image-bigness-threshold numpix'
175 Set the boundary numpix after which images are considered `big',
176 and are no longer rendered all-at-once (which gives much nicer
177 scrolling, but is harder on memory and can be slow for big
178 images) but are instead rendered piece-by-piece. Units are num‐
179 ber of pixels in image (i.e. width times height), and the
180 default is 2000000 pixels.
181 `-i'
183 `--images-only'
184 Shows only directories and image file types in the selector,
185 identified by their extensions.
186 `--interpolate'
188 Interpolate between the picture's pixels when scaling up (see
189 Scaling). This usually looks nicer, but it's rather slow.
190 `--mouse-scale-x'
192 If enabled, control-clicking on the viewer scales only the X
193 axis. (The default is to scale only the Y axis.)
194 `--revert-orient'
196 (Note that this is normally enabled; use `--revert-orient=off'
197 to disable it.) If disabled, orientation (flip/mirror/rotate)
198 state is retained between pictures (see Viewer Options).
199 `--revert-scale'
201 (Note that this is normally enabled; use `--revert-scale=off' to
202 disable it.) If disabled, scaling is retained between pictures
203 (see Viewer Options).
204 `--selector-width'
206 Set the default/initial size of the selector in pixels. The nor‐
207 mal setting is 200.
208 `-T'
210 `--show-tagged'
211 Show names of currently-tagged files on exiting xzgv. (They're
212 listed to stdout, one per line.) This can be useful when you
213 want to select multiple files graphically and work on them with
214 something else.
215 `--show-thumbnail-messages'
217 Show on the status bar when thumbnails are being read. The sta‐
218 tus bar must be enabled for these messages to be visible, of
219 course. :-)
220 `-k'
222 `--skip-parent'
223 For the first directory shown, skip the cursor past .. (the par‐
224 ent dir). This can be useful when you'd like to immediately use
225 space to `page' through the dir.
226 `-o order'
228 `--sort-order order'
229 Set the initial sorting order used in the selector. Possible
230 settings are `name', `ext', `size', and `date' (or `time'); only
231 the first char of the setting (`n'/`e'/`s'/`d'/`t') need be
232 given. The default is name order.
233 `--sort-timestamp-type type'
235 Set the timestamp type to use when using time/date sorting
236 order. Possible settings are `mtime' (default), `ctime', and
237 `atime'; only the first char of the setting (`m'/`c'/`a') need
238 be given.
239 `--statusbar'
241 Show a status bar below the selector; this, for example, says
242 when a picture is being read.
243 `-t'
245 `--thin-rows'
246 Use rows a third the normal height in the selector. This can be
247 very useful on lower-resolution screens, or if you're really
248 interested in filenames, not thumbnails.
249 `-v'
251 `--version'
252 Show version number.
253 `--version-gtk'
255 Show version number of GTK+ xzgv is using.
256 `-z'
258 `--zoom'
259 Fit picture to viewer window, whatever its actual size (see Zoom
260 Mode).
261 `-r'
263 `--zoom-reduce-only'
264 When in zoom mode, only reduce pictures to fit; i.e. make big
265 pictures viewable all-at-once while leaving small picures
266 intact.
267 `-p'
269 `--zoom-panorama'
270 When in zoom mode, adjust only the most proportional dimension
271 to fit, and allow scrolling on the other dimension; i.e. like a
272 fit page width option in PDF readers, but not limited to hori‐
273 zontal adjusting.
274 If started with `xzgv files', xzgv hides the file selector and treats
276 the file or files as if they were the sole contents of a directory. (It
277 also automatically loads the first file.) As such, you can use the Next
278 Image and Previous Image commands to navigate between the images, or do
279 Exit to Selector and use the selector directly.
280 If started with `xzgv start-dir', xzgv starts up as usual, but with the
282 selector starting on the directory specified (rather than the current
283 directory).
284 Settings which are either on or off (boolean) are, as you might expect,
286 enabled by using e.g. `-z' or `--zoom'. However, there's an alternative
287 long-option form for setting these, resembling how they're set in con‐
288 fig files --- the syntax is `--option=state', where state is
289 `on'/`y'/`yes'/`1' to enable the option, or `off'/`n'/`no'/`0' to dis‐
290 able it. The most useful thing about this is that it allows you to dis‐
291 able options which were previously enabled, by using e.g. `--zoom=off'.
292 (Readers used to the way GNU-style long options work should note that,
294 since this `on'/`off'/etc. arg is optional, you can't use the `--option
295 arg' form in this case; it must be `--option=arg' for it to work.)
296
298 Much of this manual is taken up by a description of xzgv's various com‐
299 mands in its file selector and viewer. Most of these are available both
300 from the keyboard, and from popup menus. (A popup menu appears when you
301 press `F10' or `Menu', or right-click on the selector or the viewer;
302 each has its own menu.) So in the manual, you will often see things
303 rather like this:
304 `key'
306 `Selector menu, Menu the item is in, Menu item'
307 Description of what the key/menu item does.
308 Sometimes the key given has a `(Selector)' or `(Viewer)' suffix; this
310 is because some keypresses in xzgv are specific to the selector or the
311 viewer, and won't work unless the relevant part of xzgv has the key‐
312 board focus.
313
315 Usually, on starting up xzgv, you'll want to use the file selector ---
316 the list of files on the left. (The other subwindow (on the right) is
317 the viewer.) The selector lets you pick files to view (among other
318 things). It lists the subdirectories and picture files in the current
319 directory, along with small `thumbnail' versions of the pictures if
320 they exist.
321
323 Almost all selector commands are available from the selector's pop-up
324 menu, which appears when you right-click anywhere on the selector. (You
325 can also press `F10' or `Menu' to bring up the menu, but as there are
326 keyboard shortcuts for just about everything in xzgv, this isn't often
327 that useful. :-))
328 Usually, it doesn't matter where on the selector you right-click. How‐
330 ever, a few commands on the File menu operate on a single file, the one
331 selected by the keyboard cursor. A problem when using the mouse, you
332 might think --- but when you right-click on the selector, as well as
333 popping up the menu, xzgv moves this cursor to the file you right-
334 clicked on (if any). (You can see this by the way a hollow box is drawn
335 around the file.) So to use e.g. Details on the File menu, you need to
336 right-click on the file you want details on.
337 Both the selector and viewer have `Help' menus, most items of which
339 refer you to this manual:
340 `F1'
342 `Selector menu, Help, Contents'
343 `Viewer menu, Help, Contents'
344 View the manual's overall contents.
345 `Selector menu, Help, The File Selector'
347 View the manual's section on the file selector.
348 `Viewer menu, Help, The Viewer'
350 View the manual's section on the viewer.
351 `Selector menu, Help, Index'
353 `Viewer menu, Help, Index'
354 View the manual's concept index.
355 `Selector menu, Help, About'
357 `Viewer menu, Help, About'
358 Give some brief information about xzgv, including the version
359 number and homepage.
360 Currently, the way xzgv lets you read the manual is a bit crude; it
362 runs the `info' program (see Top in the info-stnd info file) in an
363 `xterm'.
364
366 You can exit xzgv either by using one of two exit keypresses, or by
367 selecting the appropriate option from the selector's popup menu:
368 `q'
370 `Ctrl-q'
371 `Selector menu, Exit xzgv'
372 Quit xzgv.
373 (There's also an exit option on the selector's File menu (`Selector
375 menu, File, Exit'), as `Exit' is generally on any File menu.)
376
378 (This section is deliberately early on in the manual, as thumbnails are
379 probably the most important feature of the file selector, so it's best
380 that you know how to create/update them sooner rather than later.)
381 Thumbnails are small versions of the pictures they represent, and are
383 displayed by the file selector if they exist. xzgv uses xv-compatible
384 thumbnails --- if you create thumbnails with xv they will work with
385 xzgv, and vice versa. xzgv's thumbnails are also compatible with the
386 Gimp, and zgv.
387 If no thumbnail exists for a file, a small `document' icon appears
389 instead (similar to the `folder' icon used for directories).
390 Updating Thumbnails
392 While thumbnails can be made relatively quickly, it's by no means an
393 instant process. For this reason, thumbnails have to be created in
394 advance, and are stored as files in their own right in a subdirectory
395 .xvpics.
396 xzgv never creates/updates thumbnails without you telling it to. So, if
398 you enter a directory where the picture files don't have any thumb‐
399 nails, or where the thumbnails seem to be out of date, you should press
400 `u', or select Update Thumbnails from the selector's menu. (Even if
401 the thumbnails can't be written (say, if you don't have permission to
402 write them), the selector will still show the updated thumbnails until
403 you leave the directory.)
404 Alternatively, you can create/update thumbnails for the current direc‐
406 tory and all subdirectories by using `Alt-u' or Recursive Update. But
407 be warned that a recursive update can take some time!
408 `u'
410 `Selector menu, Update Thumbnails'
411 Create thumbnails for any files which don't have them, and
412 update thumbnails which are older than the corresponding file.
413 While this is going on, a window appears showing how far through
414 the process xzgv is.
415 While the update is in progress, you can abort it by clicking on
417 the Cancel button, or pressing `Esc' or `Enter', or by clicking
418 the delete-window button (if your window manager provides one)
419 on the title bar. xzgv will stop once it has finished the thumb‐
420 nail it is currently working on (if any).
421 `Alt-u'
423 `Selector menu, Recursive Update'
424 Create/update thumbnails for all files in the current directory
425 and all subdirectories. This can take some time, so you are
426 prompted to confirm you really want to do this (see Dialog
427 Boxes). Progress is indicated in much the same way as for a nor‐
428 mal update, but only for the directory currently being updated
429 --- the overall progress is not indicated, other than by the
430 current dir being (as ever) displayed in the main window's
431 title. You can abort a recursive thumbnail update in the same
432 ways as for a normal update (see above).
433 By default, xzgv behaves a little oddly when doing a recursive
435 update, to give some consistency with the normal update. See
436 Thumbnail Issues, for details.
437 Thumbnail Issues
439 Dealing with thumbnails can be `interesting' at times, and there are a
440 few ways this influences things:
441 - xzgv doesn't read the thumbnails in a directory all at once. Instead,
443 it just reads the directory contents, then starts up what is effec‐
444 tively a kind of background task to read in the thumbnails. So xzgv may
445 not be quite as responsive as usual for a short time after entering a
446 directory with many thumbnails (say, a few hundred) --- but on the
447 other hand, at least it is responding. :-)
448 - The `background task' makes a special effort to show thumbnails for
450 the files currently visible in the selector first, no matter how much
451 you move around the list, but it reads them all in eventually.
452 - The thumbnails used in xzgv require 256 colours to display. This can
454 be a problem if you're running X in 256 colours or less as, even if
455 you're running an 8-bit (256 colour) server, there will almost
456 inevitably be fewer colours available. Currently, xzgv just uses what‐
457 ever gdk reports as the closest match to each individual colour used in
458 thumbnails. This gives a tolerable result on 8-bit servers, assuming
459 gdk was able to allocate a large number of colours; however, it gives
460 terrible results if it couldn't, or if running on 4-bit or 1-bit
461 servers. Sorry about this --- it should be fixed in future (either by
462 using gdk to draw the thumbnail pixmaps, or by dithering them `by hand'
463 to suit the colours available).
464 - Finally, when doing a recursive thumbnail update, xzgv (by default)
466 reads existing thumbnails in a directory before updating any. Or
467 rather, it reads thumbnails for those files currently visible in the
468 selector. This can slow things down very slightly, but keeps the `look
469 and feel' consistent with the normal update. (Still, you can disable
470 this with the `--fast-recursive-update' command-line option (see Invok‐
471 ing xzgv) or equivalent config file entry (see Configuring xzgv).)
472
474 The file selector is simply a list of subdirectories and filenames,
475 along with any thumbnails that exist for them. The list is normally in
476 asciibetical order (but you can change this; see Changing the Sorting
477 Order). Names of directories are shown first, and they are shown in
478 order at the beginning of the list, before all the picture files. Long
479 filenames may not fit in the visible part of the file selector display;
480 if so, there will be a horizontal scrollbar you can use to see the rest
481 of the name(s) (you can use cursor left/right to do this from the key‐
482 board).
483 The list is very often larger than can fit on the screen at once. If
485 this is the case, only part is shown at a time, but you can move around
486 the list using the (vertical) scrollbar, or with cursor up/down and the
487 like.
488 If you find the selector window to be too small vertically, and would
490 like to see more files at once, you can start xzgv fullscreen by using
491 the -f option (see Options), and/or use `thin rows' mode (see File
492 Selector Options).
493 If you find the selector too small (or too big) horizontally, you can
495 change this by moving the splitter line's `handle' (a small square but‐
496 ton between the selector and viewer, near the bottom of the window),
497 which changes the relative sizes of the selector and viewer. You can
498 move it by dragging it with the mouse, or with these keys:
499 `['
501 Move the window split left.
502 `Ctrl-['
504 Move the window split left more slowly.
505 `]'
507 Move the window split right.
508 `Ctrl-]'
510 Move the window split right more slowly.
511 `~'
513 Reset the window split to its default position.
514 You can also set the initial/default size of the selector --- in
516 effect, the position of the window split --- using `--selector-width'
517 (see Options) or the config file option `selector-width'.
518
520 This section is mainly for those of us more inclined to the keyboard
521 side of the force. :-) Mouse-happy types can freely skip it.
522 When the selector has the keyboard focus, the cursor (or in GTK+ jar‐
524 gon, the `focus row') is normally shown as a hollow box around one of
525 the list's rows. This serves the following functions:
526 - It selects a file for view commands to operate on.
528 - It determines which part of the list is shown, as the part of the
530 list shown onscreen always contains the cursor (unless you move around
531 using the mouse).
532 There are several commands for moving the cursor. In summary, most
534 `special' keys like the cursors do what you'd imagine they do, but in
535 more detail:
536 `Cursor Up'
538 `k'
539 Move up.
540 `Cursor Down'
542 `j'
543 Move down.
544 `Page Up'
546 `Ctrl-u'
547 Move the cursor back roughly a page.
548 `Page Down'
550 `Ctrl-v'
551 Move the cursor forward roughly a page.
552 `Ctrl-Home'
554 `Ctrl-a'
555 Move the cursor to the start of the list.
556 `Ctrl-End'
558 `Ctrl-e'
559 Move the cursor to the end of the list.
560 `g'
562 `''
563 Move the cursor to the first filename starting with the next key
564 pressed, which would generally be a letter or number. Case is
565 significant; `a' and `A' are different. If no key is pressed
566 within 2 seconds, the command is cancelled.
567 If no files start with the specified character, it moves to the
569 first file which starts with a later char (in asciibetical
570 order). If there are none for which this is the case, it moves
571 to the last file --- unless there are no files (just directo‐
572 ries), in which case it has no effect.
573
575 To view a file from the selector, you can click on it, or press `Enter'
576 after moving the cursor to the relevant file, or right-click on the
577 file and choose `File' then `Open'.
578 `Enter'
580 `Left-click-on-file'
581 `Selector menu, File, Open'
582 View the chosen picture file, or if a subdirectory is chosen,
583 make that the current directory.
584
586 See The Viewer, for details of how the viewer works. If xzgv has a
587 serious problem reading a file, it will give an error. Errors are
588 shown in dialogs which appear in the middle of the screen --- they stay
589 there until you click Ok (or press `Enter' or `Esc').
590 xzgv also uses similar dialog boxes for other things:
592 - Getting confirmation that you want to do something. `Enter' or `y'
594 picks `yes'; `Esc' or `n' picks no. (Again, you can click on the rele‐
595 vant button with the mouse to do the same.)
596 - Showing progress when updating a thumbnail. This is a slightly
598 unusual dialog, in that it automatically disappears when the update is
599 complete. However, it does provide a Cancel button which you can click
600 to abort the update (pressing `Enter' or `Esc' does the same).
601 - Reading a directory name. Here you should type the directory name
603 then click Ok (or press `Enter'), or click Cancel (or press `Esc') to
604 abort. The text-input `widget' used allows a certain amount of editing,
605 including these keys:
606 `Cursor Left'
608 `Ctrl-b'
609 Move the cursor left. (A vertical bar shows the cursor posi‐
610 tion.)
611 `Cursor Right'
613 `Ctrl-f'
614 Move the cursor right.
615 `Home'
617 `Ctrl-a'
618 Move the cursor to the start of the line.
619 `End'
621 `Ctrl-e'
622 Move the cursor to the end of the line.
623 `Backspace'
625 `Ctrl-h'
626 Delete char to the left of the cursor. (Note that `Backspace' is
627 (usually) the key above the main `Enter' key; it is often
628 labelled simply as an arrow.)
629 `Delete'
631 `Ctrl-d'
632 Delete the char the cursor is on.
633 You can also set the X selection (by selecting text with the mouse, or
635 holding `Shift' while moving the cursor) to allow pasting text into
636 other programs, and you can cut/copy/paste text in the usual ways:
637 `Shift-Delete'
639 `Ctrl-x'
640 Cut text.
641 `Ctrl-Insert'
643 `Ctrl-c'
644 Copy text.
645 `Shift-Insert'
647 `Ctrl-v'
648 Paste text.
649 You can paste text from (some) other programs using the latter command,
651 too.
652
654 Usually, when you view a file, the viewer subwindow keeps displaying it
655 until you view a different file. However, if you `close' the file, the
656 viewer stops displaying the file and returns to its initial state.
657 `Ctrl-w'
659 `Selector menu, File, Close'
660 `Close' the currently-viewed file, clearing the viewer subwin‐
661 dow.
662
664 The listing the selector gives for a file is pretty sparse --- just the
665 filename and (if the file has one) the accompanying thumbnail. While
666 this does keep things simple, you sometimes want to know how much space
667 a file takes up, when it was last modified, the dimensions of the
668 image, that kind of thing. So, you can show details of a single file
669 using the `file details' command:
670 `:'
672 `;'
673 `Selector menu, File, Details'
674 Show various details about the file pointed to by the keyboard
675 cursor. See The Selector Menu, for how to choose the file
676 details are given for when using the mouse. (Basically, you
677 right-click on the file when popping up the menu.)
678 Most of the details shown come from the OS (by using the `stat(2)' sys‐
680 tem call), and should always be available unless you have limited per‐
681 missions for the directory the file is in. The file dimensions
682 (width/height), however, come from the file's thumbnail. If it doesn't
683 have one, or if it's unreadable, or if it has one and it's readable but
684 it doesn't mention the original image's width/height, then the Details
685 from thumbnail area is greyed out.
686 (In explanation of the latter point --- pre-5.0 versions of zgv did not
688 generate width/height comments in thumbnails, so zgv users in particu‐
689 lar may find the width/height details missing. (xzgv has always been
690 ok, though, it's just zgv which had this problem.) Worse yet, versions
691 5.0 and 5.1 generated them with incorrect sizes for most JPEGs. To fix
692 either problem for a given directory, do `rm -fr .xvpics' in that dir
693 from a shell prompt and recreate the thumbnails with zgv 5.2 or later,
694 or xzgv/xv/Gimp.)
695
697 The file selector is not restricted to working on one file at a time.
698 You can `tag' as many (or as few) files as you wish, and certain com‐
699 mands described in this section will act on them.
700 Initially, all files are untagged, and the filenames usually appear in
702 black (though this depends on the GTK+ theme you're using). Tagged
703 files appear in red.
704 Tag and Untag Commands
706 There are several ways to tag or untag files. The keyboard-based ones
707 which work on individual files (also available on the Tagging menu)
708 move the cursor down one row afterwards, to make tagging or untagging
709 multiple files easier.
710 To tag or untag a single file with the mouse, control-click (i.e. hold
712 down the control key and click) on the relevant filename or thumbnail
713 in the selector. It's true that you could use Tag and/or Untag on the
714 Tagging menu (see The Selector Menu, for how to choose the file
715 tagged/untagged when doing it this way), but this is usually much less
716 convenient than using control-click. (The menu entries for those are
717 really just for completeness.)
718 There is also a command available in the viewer to tag the currently-
720 viewed file. See Changing Picture, for details.
721 `='
723 `+'
724 `Keypad +'
725 `0'
726 `Selector menu, Tagging, Tag'
727 Tag file.
728 `-'
730 `Keypad -'
731 `9'
732 `Selector menu, Tagging, Untag'
733 Untag file.
734 `Alt ='
736 `Alt-Keypad +'
737 `Alt-0'
738 `Selector menu, Tagging, Tag All'
739 Tag all files.
740 `Alt -'
742 `Alt-Keypad -'
743 `Alt-9'
744 `Selector menu, Tagging, Untag All'
745 Untag all files.
746 `Alt-o'
748 `Selector menu, Tagging, Toggle All'
749 Toggle all tags. This inverts the tagged state, so that all pre‐
750 viously tagged files become untagged, and all previously
751 untagged files become tagged.
752 Currently there is no way to toggle a (single) file's tag state from
754 the keyboard.
755 Moving Between Tagged Files
757 These commands let you search for (move to) the next or previous tagged
758 file (if any). Note that `next' and `previous' here are relative to the
759 keyboard cursor's position; if you use these from the menu, be careful
760 to right-click on the file you want to start the search from.
761 `/'
763 `Selector menu, Tagging, Next Tagged'
764 Move to next tagged file in dir.
765 `?'
767 `Selector menu, Tagging, Previous Tagged'
768 Move to previous tagged file in dir.
769 Equivalent commands are also available in the viewer (see Changing Pic‐
771 ture).
772 Copying/Moving Files
774 You can copy or move tagged files to a directory you specify. If no
775 files are tagged, xzgv copies/moves the file the cursor is currently on
776 --- unless the cursor is on a subdirectory, in which case it gives an
777 error.
778 `C (Shift-c)'
780 `Selector menu, File, Copy'
781 Copy tagged files (or the current file) to a given directory.
782 xzgv asks for the destination directory using a dialog (see Dia‐
783 log Boxes) and copies the files there. If it comes to copy a
784 file but there is an existing file in the dir with the same
785 name, the file is not copied and nor are any of the remaining
786 files.
787 `M (Shift-m)'
789 `Selector menu, File, Move'
790 Move tagged files (or the current file) similarly.
791
793 As well as copying/moving files, you can rename them:
794 `Ctrl-n'
796 `Selector menu, File, Rename file'
797 Rename the current file or directory --- xzgv will refuse to
798 overwrite any existing files/directories. The new name must
799 remain in the current directory. (See Copying/Moving Files, for
800 how to move a file to a different directory (albeit keeping the
801 same name).) See The Selector Menu, for how to choose the file
802 renamed when using the mouse. (Basically, you right-click on
803 the file when popping up the menu.)
804 I know `Ctrl-n' isn't the most mnemonic keypress possible for `rename',
806 but all the good ones were taken. :-/
807
809 Deleting a file is pretty straightforward:
810 `Ctrl-d'
812 `Selector menu, File, Delete file'
813 Delete the file pointed to by the keyboard cursor (and any
814 accompanying thumbnail). See The Selector Menu, for how to
815 choose the file deleted when using the mouse. (Basically, you
816 right-click on the file when popping up the menu.)
817 Note that only one file is deleted (hence `Delete file'); there is cur‐
819 rently no way to delete all tagged files.
820
822 The easiest way to change the current directory in xzgv is usually to
823 click on a directory entry in the file list (or move the cursor to it
824 and press `Enter'). Selecting the `..' entry moves to the parent direc‐
825 tory of the current one.
826 There is an alternative though:
828 (Note that the key for this command is shift-`g', not `g'.)
830 `G'
832 `Selector menu, Directory, Change'
833 Go to a specified directory. xzgv asks for the destination
834 directory using a dialog box which you should type the dir's
835 name into (see Dialog Boxes), and moves to that directory if it
836 exists.
837
839 Normally, xzgv reads a directory once (on starting up, or when a new
840 directory is selected). So if the contents of the directory are changed
841 by another program, this is not automatically reflected. You can, how‐
842 ever, explicitly tell xzgv to `rescan' the directory (reread the con‐
843 tents), which will update xzgv's notion of what's in it:
844 `Ctrl-r'
846 `Selector menu, Directory, Rescan'
847 Rescan the current directory.
848
850 Normally, the files are listed in asciibetical order by name. However,
851 you can instead have the file list sorted by size, last-modified
852 date/time, or by `extension' (the file type).
853 (Only the order of files can be altered; directories are always listed
855 first, and always in name order.)
856 `Alt-n'
858 `Selector menu, Directory, Sort by Name'
859 Sort by name. This is the default.
860 `Alt-e'
862 `Selector menu, Directory, Sort by Extension'
863 Sort by extension.
864 `Alt-s'
866 `Selector menu, Directory, Sort by Size'
867 Sort by size. The biggest files are listed last.
868 `Alt-d'
870 `Selector menu, Directory, Sort by Time & Date'
871 Sort by time/date. The newest files are listed last.
872 You can set the default sort order via the command-line (see Invoking
874 xzgv) or a config file (see Configuring xzgv).
875 There are three possible timestamps you can use for the `Time & Date'
877 sorting order:
878 `Alt-Shift-m'
880 `Selector menu, Directory, Time & Date Type, Modification Time (mtime)'
881 Use the last-modified time (`mtime'). This is the default.
882 `Alt-Shift-c'
884 `Selector menu, Directory, Time & Date Type, Attribute Change Time
885 (ctime)'
886 Use the last-attribute-change time (`ctime'). Note that this is
887 not always the time the file was created, which it's sometimes
888 mistaken for; for example, moving a file with `mv' will usually
889 change the ctime.
890 `Alt-Shift-a'
892 `Selector menu, Directory, Time & Date Type, Access Time (atime)'
893 Use the last-accessed time (`mtime'). The selector order is not
894 automatically updated when xzgv reads files, since this would
895 probably be annoying; do a manual rescan if need be.
896
898 Various aspects of the file selector's behaviour can be configured
899 while xzgv is running, by using these toggle commands (which enable the
900 feature if it was previously disabled, and vice versa).
901 These settings can also be altered using command-line options (see
903 Options) and/or config file settings (see Configuring xzgv).
904 `Alt-a'
906 `Selector menu, Options, Auto Hide'
907 Toggle the auto-hiding of the selector when a picture is viewed
908 (off by default). This is handy for small screens/windows, or
909 for old-time zgv users who just dig that groovy modal interface,
910 er, man. :-)
911 `Alt-b'
913 `Selector menu, Options, Status Bar'
914 Toggle status bar at the bottom of the selector (off by
915 default). This displays messages in certain circumstances ---
916 normally, it just says when a picture is being read.
917 `Selector menu, Options, Thumbnail Msgs'
919 Toggle reading-thumbnails messages (default is off), only visi‐
920 ble if the status bar is enabled. These messages make it clear
921 when all thumbnails have been read, but having something flash
922 up every time you change directory is generally just annoying.
923 `v'
925 `Selector menu, Options, Thin Rows'
926 Toggle `thin rows' mode (off by default), in which thumbnails
927 are shown at a third their normal size so that many more files
928 can be shown at once. (The odd keyboard shortcut for this is
929 inherited from zgv's `visual' mode toggle, which had a roughly
930 similar effect.)
931 `Alt-i'
933 `Selector menu, Directory, Images Only'
934 Toggle the option to show only directories and image files in
935 the selector (off by default). This is handy in directories
936 where images and other file types are intermingled and you want
937 to avoid the by their extensions.
938
940 Once you've selected a file to view, it's shown in the viewer (the
941 right-hand part of xzgv's window). This section describes what you can
942 do while viewing the picture.
943 Like the selector, the viewer has its own menu --- right-click anywhere
945 on the viewer (or press `F10' or `Menu') to show it --- and a similar
946 help menu (see The Selector Menu).
947
949 When using the mouse to control xzgv, it doesn't matter whether the
950 selector or the viewer has keyboard focus --- mouse operations tran‐
951 scend such petty boundaries. :-) But keyboard control is (of necessity)
952 effectively modal, and so you need to `exit' the viewer in order to
953 have keyboard control over the selector again. You also need to exit
954 the viewer if you've enabled auto-hide mode.
955 Exiting the viewer is simple:
957 `Esc'
959 `Tab'
960 `Viewer menu, Exit to Selector'
961 Exit the viewer. This also returns the selector to its former
962 size, if it was previously `hidden'.
963 Another way of exiting the viewer is to middle-click on it, but this
965 mouse-only approach is really only of use when the selector is `hid‐
966 den'.
967
969 A picture may well be too large to fit entirely in the viewer window.
970 There are two main things which can help you see more of the picture at
971 once:
972 - Make the xzgv window larger. You could `maximize' it with your window
974 manager, or you could start xzgv with a larger window using `--geome‐
975 try' or fullscreen mode (see Options). The fullscreen mode gives xzgv
976 the maximum window size possible, but needs co-operation from your win‐
977 dow manager (and alas, many are not as willing as one might like) ---
978 in some cases you may even find `--geometry 100%x100%' to be more
979 effective.
980 - Hide the selector. To do this, either use auto-hide mode (see File
982 Selector Options), or hide the selector explicitly (see Hiding the
983 Selector).
984 But of course, these are only partial solutions to the problem; there
986 will inevitably always be pictures larger than your screen can show at
987 once. In general, then, there are two ways to see the whole of the pic‐
988 ture.
989 Scrolling
991 Scrolling is the default approach to handling big pictures in xzgv.
992 When the viewer is started up, the top-left of the picture is shown ---
993 you can either drag the picture around with the mouse (i.e. click and
994 hold the button down, then move the mouse around), or use the scroll‐
995 bars, or use the cursor keys (and others) to move around the rest of
996 the picture:
997 `Cursor Up'
999 `K'
1000 Move up 100 pixels. `Ctrl-Cursor Up' and `k' both move up 10
1001 pixels.
1002 `Cursor Down'
1004 `J'
1005 Move down 100 pixels. `Ctrl-Cursor Down' and `j' both move down
1006 10 pixels.
1007 `Cursor Left'
1009 `H'
1010 Move left 100 pixels. `Ctrl-Cursor Left' and `h' both move left
1011 10 pixels.
1012 `Cursor Right'
1014 `L'
1015 Move right 100 pixels. `Ctrl-Cursor Right' and `l' both move
1016 right 10 pixels.
1017 `Page Up'
1019 `Shift-Cursor Up'
1020 `Ctrl-u'
1021 Move up (nearly) the window height. (It moves by 90% of the
1022 height.)
1023 `Page Down'
1025 `Shift-Cursor Down'
1026 `Ctrl-v'
1027 Move down (nearly) the window height.
1028 `-'
1030 `Shift-Cursor Left'
1031 Move left (nearly) a window-length. (It moves by 90% of it.)
1032 `='
1034 `Shift-Cursor Right'
1035 Move right (nearly) a window-length.
1036 `Home'
1038 `Ctrl-a'
1039 Move to the top-left of the picture.
1040 `End'
1042 `Ctrl-e'
1043 Move to the bottom-right of the picture.
1044 Zoom Mode
1046 An alternative way of viewing the whole picture, one which lets you see
1047 the picture onscreen all at once no matter how big (or small) it is, is
1048 zoom mode.
1049 Zoom mode's name derives from the idea of `zooming' a small file up to
1051 fit the window. But in reality, it is more often used to reduce a large
1052 file to fit.
1053 Zoom mode is not the default, and has to be enabled. Once enabled, it
1055 stays on until you turn it off again (or until you enable scaling, or
1056 select Normal (see Scaling)).
1057 `z'
1059 `Viewer menu, Options, Zoom (fit to window)'
1060 Toggle zoom mode.
1061 `Alt-r'
1063 `Viewer menu, Options, When Zooming Reduce Only'
1064 When in zoom mode, only reduce pictures to fit. This can be use‐
1065 ful when going through a lot of unpredictably-sized pictures, as
1066 it means that you can see all of a big picture easily without
1067 also meaning that tiny little icons assume a scale of Biblical
1068 proportions. :-)
1069 `Alt-p'
1071 `Viewer menu, Options, When Zooming Panorama'
1072 When in zoom mode, resize to make the most proportional dimen‐
1073 sion fit and allow scrolling on the other dimension. This can be
1074 useful when viewing iamges that do not adjust nicely to the win‐
1075 dow size but you want to see them as big as possible while using
1076 the most space available. The cause for this function was to
1077 better read comics, so you can guess it works like a
1078 The way zoom mode reduces a file to fit the window is (relatively)
1080 quick but harsh, and may make the picture look a bit ugly. In future
1081 there may be a smoothing option like zgv's vkludge, but for now I'm
1082 afraid the fairly crude resize is all that's available.
1083 There is in fact an alternative to zoom mode, as you can scale down an
1085 image instead. This is generally only useful for very large images,
1086 however; zoom mode tends to be the Right Thing for the most part.
1087
1089 You can scale a picture --- this makes it appear larger (or smaller)
1090 onscreen. xzgv acts much as if the scaled picture were the real pic‐
1091 ture; for example, the cursor keys scroll around in steps of 100 scaled
1092 pixels, even if this means moving a fraction of a pixel (or many pix‐
1093 els) in the original picture (and similarly for movement with the
1094 mouse).
1095 The main limitation of scaling (other than how much it slows things
1097 down :-), at least when scaling up) is that you can only scale by inte‐
1098 ger values, so you can only make each pixel in the image twice as
1099 wide/high, or three times as wide/high, or four times, and so on.
1100 (It may seem odd saying e.g. `twice as wide/high' rather than `twice
1102 the size', but technically `twice the size' would be referring to scal‐
1103 ing up the width (and height) by about 1.414...)
1104 Normally, xzgv does no scaling, which could be considered a ratio of
1106 1:1. Scaling up increases that ratio. How it is increased depends on
1107 which option/key you use:
1108 `d'
1110 `Viewer menu, Scaling, Double Scaling'
1111 Increase the ratio by doubling it --- this leads to ratios of
1112 2:1, 4:1, 8:1...
1113 `s'
1115 `Viewer menu, Scaling, Add 1 to Scaling'
1116 Increase the ratio by adding one --- leads to ratios of 2:1,
1117 3:1, 4:1...
1118 There are similar commands to decrease the ratio:
1120 `D (Shift-d)'
1122 `Viewer menu, Scaling, Halve Scaling'
1123 Decrease the ratio by halving it.
1124 `S (Shift-s)'
1126 `Viewer menu, Scaling, Sub 1 from Scaling'
1127 Decrease the ratio by subtracting one.
1128 Usually the double/halve scalings are more useful.
1130 Note that you can also double/halve the scaling by using shift-left-
1132 click on the viewer to double, and shift-right-click to halve. This
1133 still changes scale `around' the middle of the window though (rather
1134 than around the point clicked on, as you might expect), which is a lit‐
1135 tle strange and may possibly be changed in future.
1136 When you scale `below' 1:1, the above commands lead to ratios of (e.g.)
1138 1:2, 1:4, 1:8, etc. --- that is, the ratios work the same way, but the
1139 other way around. This gives you an increasingly small image.
1140 The scaling ratio is never decreased below 1:32. It is also never
1142 increased beyond the point where the overall image size would exceed
1143 32767x32767 --- this limit is due to the combination of X's limit on
1144 window sizes, and the implementation used by xzgv for scaling.
1145 One problem with scaling up, given the way it's currently implemented,
1147 is that it's not well-suited to dithered display --- so if you're run‐
1148 ning on an 8-bit server, dragging the image around slowly when using
1149 scaling (especially scaling with interpolation) may result in some
1150 nasty, streaky, undithered-looking parts of the picture. :-(
1151 You can undo the effect of scaling (up or down) at any time:
1153 `n'
1155 `Viewer menu, Scaling, Normal'
1156 Resume `normal' display --- disables scaling mode, and also zoom
1157 mode.
1158 Normally, scaling up works by simply making the pixels into larger and
1160 larger squares (in effect), which remain the same colour. However, you
1161 can enable a feature called `interpolation' which smoothly graduates
1162 the colour change between the top-left corners of each pixel. This is
1163 very slow, but looks nice.
1164 `i'
1166 `Viewer menu, Options, Interpolate when Scaling'
1167 Toggle interpolation in scaling mode.
1168 (If you like the appearance of scaling with interpolation, you may also
1170 be interested in a program I wrote called pnminterp, which can scale up
1171 a PGM or PPM file while applying this effect. These days it's part of
1172 the netpbm package.)
1173 Scaling down, however, is implemented a bit like a special-case zoom
1175 mode, and currently there are no ways of making that look nicer. :-/
1176 xzgv normally `reverts' scaling (returning the scale to 1:1) back to
1178 normal when you view a new picture. However, it's possible to disable
1179 this behaviour (see Viewer Options).
1180 There is also support for an alternative form of scaling --- decoupled,
1182 or axis-specific, scaling. When you scale in this way, only one axis of
1183 the image is scaled at once. For example, you might choose to effec‐
1184 tively double the height of an image (with the width left unchanged).
1185 Indeed, this sort of scaling is useful for temporarily correcting pic‐
1186 tures intended for display using pixels twice as wide or high as nor‐
1187 mal.
1188 `x'
1190 `Viewer menu, Scaling, X Only, Double Scaling'
1191 Increase the (x axis) ratio by doubling it.
1192 `X (Shift-x)'
1194 `Viewer menu, Scaling, X Only, Halve Scaling'
1195 Decrease the (x axis) ratio by halving it.
1196 `Alt-x'
1198 `Viewer menu, Scaling, X Only, Add 1 to Scaling'
1199 Increase the (x axis) ratio by adding one.
1200 `Alt-Shift-x'
1202 `Viewer menu, Scaling, X Only, Sub 1 from Scaling'
1203 Decrease the (x axis) ratio by subtracting one.
1204 `y'
1206 `Viewer menu, Scaling, Y Only, Double Scaling'
1207 Increase the (y axis) ratio by doubling it.
1208 `Y (Shift-y)'
1210 `Viewer menu, Scaling, Y Only, Halve Scaling'
1211 Decrease the (y axis) ratio by halving it.
1212 `Alt-y'
1214 `Viewer menu, Scaling, Y Only, Add 1 to Scaling'
1215 Increase the (y axis) ratio by adding one.
1216 `Alt-Shift-y'
1218 `Viewer menu, Scaling, Y Only, Sub 1 from Scaling'
1219 Decrease the (y axis) ratio by subtracting one.
1220 There are also mouse shortcuts for scaling up/down a single axis; con‐
1222 trol-left-click scales up, and control-right-click scales down. By
1223 default this acts on the y axis, but the active axis can be toggled
1224 with `Alt-c', or by toggling the `Ctl+Click Scales X Axis' option (see
1225 Viewer Options).
1226 Interpolation is not currently supported in situations where the x
1228 scaling does not match the y scaling.
1229
1231 Sometimes when viewing a picture you will want to flip it horizontally
1232 or vertically, or rotate it:
1233 `m'
1235 `Viewer menu, Orientation, Mirror (horiz)'
1236 `Mirror' the picture (flip it horizontally).
1237 `f'
1239 `Viewer menu, Orientation, Flip (vert)'
1240 `Flip' the picture (flip it vertically).
1241 `r'
1243 `Viewer menu, Orientation, Rotate Right'
1244 Rotate the picture 90 degrees clockwise.
1245 `R (Shift-r)'
1247 `Viewer menu, Orientation, Rotate Left'
1248 Rotate the picture 90 degrees anti-clockwise. (Any US readers
1249 surprised and/or annoyed by my not saying `counter-clockwise'
1250 will realise why the menus say rotate right/left. :-))
1251 `N (Shift-n)'
1253 `Viewer menu, Orientation, Normal'
1254 Restore the picture orientation to normal. This undoes the
1255 effect of any mirrors, flips, and/or rotations.
1256 xzgv normally `reverts' the picture orientation (the way the picture
1258 has been transformed by mirror/flip/rotate) back to normal when you
1259 view a new picture. However, it's possible to disable this (see Viewer
1260 Options), so that any new pictures are mirrored, flipped, and/or
1261 rotated in the same way.
1262
1264 It's possible to go directly to the previous or next file (or tagged
1265 file) in the directory, or to tag a file, without having to pick the
1266 file from the file selector by hand. These commands are particularly
1267 useful when using xzgv from the keyboard, but there's also a notable
1268 mouse shortcut for moving to the next image.
1269 `Space'
1271 `Viewer menu, Next Image'
1272 Move to next file in dir, and view it. You can also click on the
1273 picture/viewer to do this. (If you find this interferes with
1274 dragging the picture around (though it shouldn't), or just don't
1275 like it, it can be disabled (see Config Variables).)
1276 `b'
1278 `Viewer menu, Previous Image'
1279 Move to previous file in dir, and view it.
1280 `Ctrl-Space'
1282 `Viewer menu, Tagging, Tag then Next'
1283 Tag current file, then move to next file in dir and view it.
1284 `/'
1286 `Viewer menu, Tagging, Next Tagged'
1287 Move to next tagged file in dir, and view it.
1288 `?'
1290 `Viewer menu, Tagging, Previous Tagged'
1291 Move to previous tagged file in dir, and view it.
1292
1294 When running on small screens, or in a small window, it can get a bit
1295 annoying to lose viewer space by having the selector constantly dis‐
1296 played when you don't actually need it. The usual solution to this
1297 problem is to enable auto-hide mode. But what if some pictures you're
1298 viewing are small and some large? It can sometimes be nearly as annoy‐
1299 ing having the selector hidden to `make room for' a small picture which
1300 didn't need it. So for that reason, or perhaps if you just don't like
1301 auto-hide mode :-), you may prefer to leave auto-hide off and explic‐
1302 itly hide the selector when necessary:
1303 `Z (shift-z)'
1305 `Viewer menu, Window, Hide Selector'
1306 Hide the selector. (This is actually a toggle, of sorts; `hide
1307 selector' when it's already hidden unhides it.)
1308 You can also hide or unhide the selector by middle-clicking on the
1310 viewer.
1311
1313 Generally it's easy enough to use your window manager to change windows
1314 etc., but when running fullscreen this can sometimes be a little prob‐
1315 lematic. For this reason, xzgv has built-in support for `iconifying'
1316 itself:
1317 `Ctrl-z'
1319 `Viewer menu, Window, Minimize'
1320 Minimize the xzgv window.
1321
1323 As with the selector, various options can be disabled/enabled which
1324 relate to the viewer.
1325 These settings can also be altered using command-line options (see
1327 Options) and/or config file settings (see Configuring xzgv).
1328 `z'
1330 `Viewer menu, Options, Zoom (fit to window)'
1331 Toggle zoom mode, discussed in more detail elsewhere (see Zoom
1332 Mode).
1333 `Alt-r'
1335 `Viewer menu, Options, When Zooming Reduce Only'
1336 Toggle reduce-only in zoom mode, also covered elsewhere (see
1337 Zoom Mode).
1338 `Alt-p'
1340 `Viewer menu, Options, When Zooming Panorama'
1341 Toggle panorama view in zoom mode, also covered elsewhere (see
1342 Zoom Mode).
1343 `i'
1345 `Viewer menu, Options, Interpolate when Scaling'
1346 Toggle interpolation when a picture is being scaled-up. Again,
1347 this has already been mentioned (see Scaling).
1348 `Alt-c'
1350 `Viewer menu, Options, Ctl+Click Scales X Axis'
1351 Toggle the axis scaled when you control-click (or control-right-
1352 click) on the image. The default is to scale the y axis.
1353 `F (shift-f)'
1355 `Viewer menu, Options, Dither in 15 & 16-bit'
1356 Toggle dithering in 15/16-bit modes. This increases the apparent
1357 colour depth making gradations look much better, but it's slower
1358 than undithered rendering, and can (in 16-bit) slightly distort
1359 a picture's colour balance. (The `F' key was chosen for this as
1360 the dither toggle is functionally similar to zgv's `fakecols'
1361 toggle.)
1362 `Viewer menu, Options, Revert Scaling For New Pic'
1364 Normally xzgv returns the scaling back down to 1 (normal) when a
1365 new picture is selected. By disabling this, you can retain scal‐
1366 ing across picture selection. (There is currently no keyboard
1367 shortcut for this fairly-seldom-changed option --- to toggle it
1368 from the keyboard, you should use the popup menu (press `F10'),
1369 and select the menu item.)
1370 `Viewer menu, Options, Revert Orient. For New Pic'
1372 Similarly, xzgv returns to the picture's true orientation (not
1373 mirrored, rotated, etc.) on selecting a new picture. Disabling
1374 this option means that any mirrors/flips/rotates applied persist
1375 across multiple images. (No keyboard shortcut --- see above.)
1376 `Viewer menu, Options, Use Exif Orientation'
1378 Toggle support for Exif orientation. Devices which create JPEG
1379 files in the Exif format (e.g. many digital cameras) may add an
1380 orientation tag to the file, which says how the camera was being
1381 held when the picture was taken. When this tag is present, xzgv
1382 can adjust the image to compensate for a camera being held on
1383 its side. (This isn't done by default as it misrepresents the
1384 true image, which could be confusing if you don't know why it's
1385 happening.) Enabling this option may be useful if you take pic‐
1386 tures with your camera on its side, but don't want to have to
1387 rotate the pictures before being able to view them properly. Of
1388 course, for this to work your camera has to be inserting the
1389 orientation tag in the first place --- but it can't hurt to try
1390 it and see. (No keyboard shortcut --- see above.)
1391
1393 Picture files are stored in a variety of different forms, or `file for‐
1394 mats'. xzgv, via gdk, supports many.
1395
1397 The format a file is in is identified by its content. The file-reading
1398 code relies on libgdk to determine the file type and read the file cor‐
1399 rectly; generally this uses the format's `magic number' to determine
1400 file type --- e.g. a JPEG/JFIF file starts with the (hex) bytes `FF
1401 D8'. So if you start xzgv with xzgv foo, and foo is in a supported for‐
1402 mat (such as JPEG), the format will be figured out and the file loaded
1403 even though the `extension' is absent.
1404
1406 Many aspects of the way xzgv works can be modified by using a configu‐
1407 ration file.
1408
1410 A configuration file lets you alter aspects of xzgv's behaviour. xzgv
1411 supports two possible config files --- a system-wide one,
1412 /etc/xzgv.conf; and one for each user in their home directory,
1413 $HOME/.xzgvrc. Both are optional. If $HOME/.xzgvrc exists, it is used
1414 instead of /etc/xzgv.conf.
1415 Before describing the format of config files, it may help to give an
1417 example file:
1418 # Sample xzgv config file
1420 # Comment lines begin with `#' and are ignored,
1421 # as are blank lines.
1422 # make pics fit window
1424 zoom on
1425 # hog the screen :-)
1426 fullscreen on
1427 It is a line-based format. Each line (or rather, each line which is not
1429 a comment line and is not blank) assigns a value to a single predefined
1430 `variable'. xzgv has many such variables it lets you modify in this
1431 way. For example, the fullscreen option above controls whether or not
1432 xzgv tries to use the whole screen for its window. If it is given the
1433 value `on'/`y'/`yes'/`1' it does; if `off'/`n'/`no'/`0', it doesn't.
1434 Most variables are of this yes-or-no `boolean' type.
1435 Since the variables set in a config file have a direct effect on how
1437 xzgv works, it can be easier to simply call them `settings'. Indeed,
1438 such terminology is used on occasion in this documentation.
1439
1441 There are various types of variable:
1442 - Boolean. These are on-or-off, yes-or-no variables. Most of xzgv's
1444 config file variables are of this type.
1445 - Integer. These are whole numbers. The meaning of the number depends
1447 on what the variable is used for.
1448 - Geometry. This window size-and/or-position specification format is
1450 only used for the `geometry' setting. See Options, for a description of
1451 how this type works.
1452
1454 Currently, most configuration variables (settings) in xzgv can also be
1455 set by command-line options; indeed, the name of the setting in all
1456 such cases is identical to that for the long version of the option
1457 (e.g. `fullscreen', `auto-hide'). As such, they're documented in the
1458 section which discusses command-line options and the like (see
1459 Options).
1460 However, there are some settings only available in the config file:
1462 click-for-next
1464 This is enabled by default, allowing you to click on the viewer
1465 to skip to the next image. If disabled, clicking on the viewer
1466 does nothing.
1467
1469 Here I (RJM) attempt to explain why I did things the way I did. This is
1470 presented in a question-and-answer format of sorts.
1471
1473 Previously, this section concentrated on xv; that may have made sense
1474 when I originally wrote it, and still makes a certain limited amount of
1475 sense for zgv, but for xzgv it was looking increasingly dated. And so
1476 here I am writing an update. :-)
1477 I originally wrote xzgv as I simply wasn't happy with the viewers for X
1479 that I was aware of at the time (mid-1999). At the time of writing
1480 (late 2000), other key things about xzgv are becoming apparent, partly
1481 through responses I've been getting to it:
1482 o It's `fast'. No, it doesn't do any particular operation faster than
1484 other viewers as far as I know (well, maybe thumbnail updates :-));
1485 rather, the interface tries not to get in your way. Click on a file‐
1486 name, and the picture appears. No multiplicity of toolbars or windows,
1487 it's just there.
1488 o As with zgv, it tries to do one thing well, viewing pictures. It
1490 isn't perfect in this regard, I'll admit, but at least it stays well
1491 clear of picture editing.
1492 o It's, er, quite a lot like zgv. Some of us old fogies like this. :-)
1494 I won't pretend xzgv is The Ultimate Viewer For Everyone. Some people
1496 will prefer other approaches, or just simply prefer other viewers.
1497 (Some people may even still use xv, ghod forbid.) There are a few view‐
1498 ers which you may like to try if you don't think much of xzgv:
1499 o gqview. This seems to be well-regarded. I find it a bit gimmicky and
1501 kitchen-sink-ish; not quite as `pure' or focused as xzgv, IMHO. I think
1502 more people use it than xzgv though.
1503 o xli. I'm not sure if this is maintained these days, but it's not too
1505 bad a viewer. No thumbnails or file selector though. (These days I
1506 mostly use this for setting the root window pixmap, something I don't
1507 think belongs in a viewer, but which xli does happen to be quite good
1508 at.)
1509 o qiv. If I read between the lines correctly, this is essentially a
1511 modern replacement for xli.
1512 o gtksee. I've not tried this, but I think the idea is that it's an
1514 ACDSee clone, and there seem to be an awful lot of people who want a
1515 clone of that. Which is their problem. :^)
1516 o Electric Eyes. To be honest, I think this has been outclassed by
1518 other viewers these days, which shows how far we've come.
1519 Ah, you say, what of xv? Well, we've emphatically reached the point
1521 where no-one need use xv any more. Anyone using xv these days really
1522 should drop that pile of ill-conceived non-Free crap and use one of the
1523 better viewers now available. It's that simple.
1524
1526 It's a fscking viewer, dammit. If you want xv you know where to find
1527 it.
1528 (OTOH, if you want a decent image editor, use the Gimp.)
1530
1532 For years, I maintained a conventional `man page' for zgv (which xzgv
1533 was loosely based on). But over time, I realised just how impossibly
1534 confusing the zgv man page had become.
1535 So I wanted to rewrite zgv's documentation in a more sensible way, in
1537 some other format than a man page. I wanted an established, well-sup‐
1538 ported format with structure and cross-referencing. I felt this made it
1539 a choice between HTML and texinfo. HTML seemed to me to be a moving
1540 target like no other, and not as well supported on text-only terminals
1541 as Info (and thus texinfo). (This latter point is admittedly not too
1542 relevant as far as xzgv is concerned.) When I noticed that a converter
1543 existed to convert texinfo to HTML in any case, the case was closed.
1544 xzgv's documentation was then based on zgv's --- the documentation is
1545 probably more similar than the programs are. :-)
1546 Don't get me wrong --- I like man pages. And even with the excellent
1548 Texinfo documentation and Emacs' very helpful Texinfo mode, writing
1549 texinfo is hardly easy. (Without Texinfo mode's node- and menu-update
1550 commands, I personally would find it near-impossible!) But big man
1551 pages just aren't that good for reference, and this is made worse by
1552 the relative lack of structure.
1553
1555 The conventional way to write texinfo is to follow each sentence with
1556 two spaces after the dot (or whatever ends the sentence). Many people
1557 normally write this way in a non-texinfo context too. But a sizeable
1558 proportion of people normally write text with only one space after the
1559 dot --- and I'm one of them.
1560 The Texinfo documentation gives the impression that two-space must be
1562 used; it says ``it is important to put two spaces at the end of sen‐
1563 tences in Texinfo documents.'' But the only circumstance in which spac‐
1564 ing from the texinfo file is preserved at all (in any sense other than
1565 `there is a space here') is when the texinfo is converted to Info for‐
1566 mat. So, in fact, the decision to use two-space depends on how the
1567 author wants Info output to appear --- this is a subjective decision
1568 which should be entirely down to the preference of the author, despite
1569 the Texinfo documentation's attempt to make two-space sound like an
1570 objective you-must-do-this kind of thing.
1571 You might wonder what the problem with using one-space is, then. Well,
1573 `makeinfo' has to reformat paragraphs, and whenever it needs to insert
1574 space at (what appears to it to be) the end of a sentence, it inserts
1575 two spaces. This behaviour cannot be altered, unlike in Emacs (sen‐
1576 tence-end-double-space; see Fill Commands in the emacs info file) and
1577 GNU fmt (-u; see fmt invocation in the textutils info file). Also,
1578 attempting to `fix' the output Info with sed doesn't work properly
1579 because the `tags' used to find nodes quickly are then incorrect. These
1580 could of course also be fixed, but this would involve a lot more work
1581 than a simple sed invocation.
1582 So realistically, anyone who writes texinfo with one-space has to put
1584 up with the occasional two-space sentence end being inserted into their
1585 text --- worse still, the current `makeinfo' formatting algorithm seems
1586 to insert two spaces even after abbreviations (such as `e.g.' and
1587 `etc.'), which breaks even two-space texinfo. (This is particularly
1588 ironic, by the way, since two-space partisans' main argument in favour
1589 of the practice is often the way it makes it possible to tell the dif‐
1590 ference between abbreviations and the end of a sentence.)
1591 One last point may be worth noting; I am not the first person to write
1593 texinfo files using one-space. At the time of writing, it is used in
1594 the texinfo documentation for BFD, gdbm, GTK/GDK, (Linux) IPC, and
1595 viper, and I expect there are instances I'm not aware of.
1596
1598 All (non-trivial) programs have bugs. Anyone who denies this...
1599 - clearly hasn't written too many programs.
1601 - is wrong. ;-)
1603 It follows that xzgv, like everything else, always has some bugs. Usu‐
1605 ally these are not too serious, or I'd have fixed them before releasing
1606 xzgv. But either way, bugs and other problems with xzgv are noted here.
1607
1609 - In zoom mode, it copes with resizing the window as a whole, but
1610 doesn't when you change the size of the pane (apart from when hid‐
1611 ing/showing selector or resizing from keyboard, but that's only 'cos I
1612 kludged it :-)).
1613 - When scaling up and dithering, you end up with a crappy-looking pic‐
1615 ture if you drag the picture around slowly (since each exposed bit is
1616 dithered independently, with no regard given to matching up to any pre‐
1617 vious error-diffusion).
1618 - Scaling up is slow. Not sure if I can do much about this.
1620 - Using an alignment widget to centre the viewer window results in some
1622 annoying `bounce' in certain resizing situations etc.
1623 - Thumbnails don't look so great in palette-based (e.g. 8-bit) modes.
1625 - When dragging an image around, if you quickly move the mouse pointer
1627 over from the image area to the selector area, the image seems to
1628 `jump' a little. I think this may have something to do with the paned
1629 window's window-splitting bit, but I'm not sure. Also, it jumps when
1630 moving across scrollbar sliders and the paned window splitter handle.
1631 - It doesn't apply any tranparency mask. The practical result of this
1633 seems to be purple transparent bits in thumbnails and scaled-up images,
1634 and black transparent bits elsewhere. This doesn't affect PNG files,
1635 though.
1636 - If a GIF file is corrupted in such a way that the decompressed image
1638 has a larger number of pixels in it, the extra pixels will be ignored
1639 and no error or warning will be generated.
1640 - If you look up `joe code' in a dictionary, right next to ``see zgv''
1642 it now says ``but for really in-depth insight into the joe code nature,
1643 see xzgv''. :-)
1644
1646 - Thumbnails are given an accurate width/height `IMGINFO' comment, but
1647 are always claimed to be "RGB".
1648 - xzgv doesn't duplicate zgv's behaviour of generating thumbnails under
1650 ~/.xvpics/_foo_bar_baz if it can't generate them in
1651 /foo/bar/baz/.xvpics. I doubt anything else supported it, and it com‐
1652 plicated lots of things unnecessarily. This isn't particularly subopti‐
1653 mal, but as an incompatibility with zgv it merits mention.
1654
1656 - Only the first image of a multiple-image GIF is used. (These days,
1657 multiple-image GIFs are usually animations.)
1658
1660 If you find xzgv does something wrong, which you suspect might be a
1661 fault of some sort (a bug) in the program, it is best to report it as I
1662 may not be aware of the problem. (But first, check it is not a `known
1663 bug'. See Known Bugs. It is not usually helpful to report a bug I
1664 already know about.)
1665 It is important to include as much detail in a bug report as you can.
1667 Here are some details you should include:
1668 o The version of xzgv you are running. `xzgv --version' reports this.
1670 o The versions of GTK+ you are using. `xzgv --version-gtk' reports the
1672 GTK+ version being used by xzgv.
1673 o The bitdepth your X server is running in (common depths are 16-bit,
1675 24-bit, and 32-bit). If you don't know what depth you're running in,
1676 try `xdpyinfo|grep depth'.
1677 o A description of the bug --- what effects it has, the circumstances
1679 it occurs in, and so on. Does it only happen for certain types of file?
1680 Only when in 8-bit modes? Only when dithering is enabled? Even `irrele‐
1681 vant' details can sometimes be useful.
1682 o Finally, if you are a programmer and believe you have managed to fix
1684 the bug yourself, patches are gratefully accepted. :-) You should gen‐
1685 erate the patch using `diff -c' or (preferably) `diff -u'.
1686 Then, please file a bug report in the SourceForge bug tracker. See
1688 https://sourceforge.net/p/xzgv.
1689
1691 Bugs in the documentation can sometimes cause as much trouble as bugs
1692 in the program; if you notice a problem in the documentation, it's a
1693 good idea to report it.
1694 For reports of documentation bugs, you should include these details:
1696 o The version of xzgv the documentation is for.
1698 o If it is a problem in one specific section of the documentation,
1700 specify which part it is (by this I mean the heading it comes under;
1701 texinfophiles should read this as `the node name' :-)).
1702 o The format of the documentation you saw the problem in (e.g. info,
1704 man page, HTML).
1705 o A description of the problem.
1707
1709 See Reporting Bugs, for details of where to send the bug report. If
1710 you want to suggest a feature you'd like in xzgv, or a change to an
1711 existing feature, contact me; see See Reporting Bugs for the address.
1712 Future changes etc. are listed in the TODO file.
1714
1716 Russell Marks <rus@svgalib.org> and others; see the section ACKNOWL‐
1717 EDGEMENTS for details.
1718
1720 zgv(1), xv(1), cjpeg(1), djpeg(1), pbm(5), pgm(5), ppm(5), mrf(5)
1721Version 0.9 9th August 2017 XZGV(1)