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 `Couldn't load image' error on those other files.
938 Images are identified by their extensions.
939
941 Once you've selected a file to view, it's shown in the viewer (the
942 right-hand part of xzgv's window). This section describes what you can
943 do while viewing the picture.
944 Like the selector, the viewer has its own menu --- right-click anywhere
946 on the viewer (or press `F10' or `Menu') to show it --- and a similar
947 help menu (see The Selector Menu).
948
950 When using the mouse to control xzgv, it doesn't matter whether the
951 selector or the viewer has keyboard focus --- mouse operations tran‐
952 scend such petty boundaries. :-) But keyboard control is (of necessity)
953 effectively modal, and so you need to `exit' the viewer in order to
954 have keyboard control over the selector again. You also need to exit
955 the viewer if you've enabled auto-hide mode.
956 Exiting the viewer is simple:
958 `Esc'
960 `Tab'
961 `Viewer menu, Exit to Selector'
962 Exit the viewer. This also returns the selector to its former
963 size, if it was previously `hidden'.
964 Another way of exiting the viewer is to middle-click on it, but this
966 mouse-only approach is really only of use when the selector is `hid‐
967 den'.
968
970 A picture may well be too large to fit entirely in the viewer window.
971 There are two main things which can help you see more of the picture at
972 once:
973 - Make the xzgv window larger. You could `maximize' it with your window
975 manager, or you could start xzgv with a larger window using `--geome‐
976 try' or fullscreen mode (see Options). The fullscreen mode gives xzgv
977 the maximum window size possible, but needs co-operation from your win‐
978 dow manager (and alas, many are not as willing as one might like) ---
979 in some cases you may even find `--geometry 100%x100%' to be more
980 effective.
981 - Hide the selector. To do this, either use auto-hide mode (see File
983 Selector Options), or hide the selector explicitly (see Hiding the
984 Selector).
985 But of course, these are only partial solutions to the problem; there
987 will inevitably always be pictures larger than your screen can show at
988 once. In general, then, there are two ways to see the whole of the pic‐
989 ture.
990 Scrolling
992 Scrolling is the default approach to handling big pictures in xzgv.
993 When the viewer is started up, the top-left of the picture is shown ---
994 you can either drag the picture around with the mouse (i.e. click and
995 hold the button down, then move the mouse around), or use the scroll‐
996 bars, or use the cursor keys (and others) to move around the rest of
997 the picture:
998 `Cursor Up'
1000 `K'
1001 Move up 100 pixels. `Ctrl-Cursor Up' and `k' both move up 10
1002 pixels.
1003 `Cursor Down'
1005 `J'
1006 Move down 100 pixels. `Ctrl-Cursor Down' and `j' both move down
1007 10 pixels.
1008 `Cursor Left'
1010 `H'
1011 Move left 100 pixels. `Ctrl-Cursor Left' and `h' both move left
1012 10 pixels.
1013 `Cursor Right'
1015 `L'
1016 Move right 100 pixels. `Ctrl-Cursor Right' and `l' both move
1017 right 10 pixels.
1018 `Page Up'
1020 `Shift-Cursor Up'
1021 `Ctrl-u'
1022 Move up (nearly) the window height. (It moves by 90% of the
1023 height.)
1024 `Page Down'
1026 `Shift-Cursor Down'
1027 `Ctrl-v'
1028 Move down (nearly) the window height.
1029 `-'
1031 `Shift-Cursor Left'
1032 Move left (nearly) a window-length. (It moves by 90% of it.)
1033 `='
1035 `Shift-Cursor Right'
1036 Move right (nearly) a window-length.
1037 `Home'
1039 `Ctrl-a'
1040 Move to the top-left of the picture.
1041 `End'
1043 `Ctrl-e'
1044 Move to the bottom-right of the picture.
1045 Zoom Mode
1047 An alternative way of viewing the whole picture, one which lets you see
1048 the picture onscreen all at once no matter how big (or small) it is, is
1049 zoom mode.
1050 Zoom mode's name derives from the idea of `zooming' a small file up to
1052 fit the window. But in reality, it is more often used to reduce a large
1053 file to fit.
1054 Zoom mode is not the default, and has to be enabled. Once enabled, it
1056 stays on until you turn it off again (or until you enable scaling, or
1057 select Normal (see Scaling)).
1058 `z'
1060 `Viewer menu, Options, Zoom (fit to window)'
1061 Toggle zoom mode.
1062 `Alt-r'
1064 `Viewer menu, Options, When Zooming Reduce Only'
1065 When in zoom mode, only reduce pictures to fit. This can be use‐
1066 ful when going through a lot of unpredictably-sized pictures, as
1067 it means that you can see all of a big picture easily without
1068 also meaning that tiny little icons assume a scale of Biblical
1069 proportions. :-)
1070 `Alt-p'
1072 `Viewer menu, Options, When Zooming Panorama'
1073 When in zoom mode, resize to make the most proportional dimen‐
1074 sion fit and allow scrolling on the other dimension. This can be
1075 useful when viewing iamges that do not adjust nicely to the win‐
1076 dow size but you want to see them as big as possible while using
1077 the most space available. The cause for this function was to
1078 better read comics, so you can guess it works like a `fit page
1079 width' option, but is not limited to horizontal adjustment.
1080 The way zoom mode reduces a file to fit the window is (relatively)
1082 quick but harsh, and may make the picture look a bit ugly. In future
1083 there may be a smoothing option like zgv's vkludge, but for now I'm
1084 afraid the fairly crude resize is all that's available.
1085 There is in fact an alternative to zoom mode, as you can scale down an
1087 image instead. This is generally only useful for very large images,
1088 however; zoom mode tends to be the Right Thing for the most part.
1089
1091 You can scale a picture --- this makes it appear larger (or smaller)
1092 onscreen. xzgv acts much as if the scaled picture were the real pic‐
1093 ture; for example, the cursor keys scroll around in steps of 100 scaled
1094 pixels, even if this means moving a fraction of a pixel (or many pix‐
1095 els) in the original picture (and similarly for movement with the
1096 mouse).
1097 The main limitation of scaling (other than how much it slows things
1099 down :-), at least when scaling up) is that you can only scale by inte‐
1100 ger values, so you can only make each pixel in the image twice as
1101 wide/high, or three times as wide/high, or four times, and so on.
1102 (It may seem odd saying e.g. `twice as wide/high' rather than `twice
1104 the size', but technically `twice the size' would be referring to scal‐
1105 ing up the width (and height) by about 1.414...)
1106 Normally, xzgv does no scaling, which could be considered a ratio of
1108 1:1. Scaling up increases that ratio. How it is increased depends on
1109 which option/key you use:
1110 `d'
1112 `Viewer menu, Scaling, Double Scaling'
1113 Increase the ratio by doubling it --- this leads to ratios of
1114 2:1, 4:1, 8:1...
1115 `s'
1117 `Viewer menu, Scaling, Add 1 to Scaling'
1118 Increase the ratio by adding one --- leads to ratios of 2:1,
1119 3:1, 4:1...
1120 There are similar commands to decrease the ratio:
1122 `D (Shift-d)'
1124 `Viewer menu, Scaling, Halve Scaling'
1125 Decrease the ratio by halving it.
1126 `S (Shift-s)'
1128 `Viewer menu, Scaling, Sub 1 from Scaling'
1129 Decrease the ratio by subtracting one.
1130 Usually the double/halve scalings are more useful.
1132 Note that you can also double/halve the scaling by using shift-left-
1134 click on the viewer to double, and shift-right-click to halve. This
1135 still changes scale `around' the middle of the window though (rather
1136 than around the point clicked on, as you might expect), which is a lit‐
1137 tle strange and may possibly be changed in future.
1138 When you scale `below' 1:1, the above commands lead to ratios of (e.g.)
1140 1:2, 1:4, 1:8, etc. --- that is, the ratios work the same way, but the
1141 other way around. This gives you an increasingly small image.
1142 The scaling ratio is never decreased below 1:32. It is also never
1144 increased beyond the point where the overall image size would exceed
1145 32767x32767 --- this limit is due to the combination of X's limit on
1146 window sizes, and the implementation used by xzgv for scaling.
1147 One problem with scaling up, given the way it's currently implemented,
1149 is that it's not well-suited to dithered display --- so if you're run‐
1150 ning on an 8-bit server, dragging the image around slowly when using
1151 scaling (especially scaling with interpolation) may result in some
1152 nasty, streaky, undithered-looking parts of the picture. :-(
1153 You can undo the effect of scaling (up or down) at any time:
1155 `n'
1157 `Viewer menu, Scaling, Normal'
1158 Resume `normal' display --- disables scaling mode, and also zoom
1159 mode.
1160 Normally, scaling up works by simply making the pixels into larger and
1162 larger squares (in effect), which remain the same colour. However, you
1163 can enable a feature called `interpolation' which smoothly graduates
1164 the colour change between the top-left corners of each pixel. This is
1165 very slow, but looks nice.
1166 `i'
1168 `Viewer menu, Options, Interpolate when Scaling'
1169 Toggle interpolation in scaling mode.
1170 (If you like the appearance of scaling with interpolation, you may also
1172 be interested in a program I wrote called pnminterp, which can scale up
1173 a PGM or PPM file while applying this effect. These days it's part of
1174 the netpbm package.)
1175 Scaling down, however, is implemented a bit like a special-case zoom
1177 mode, and currently there are no ways of making that look nicer. :-/
1178 xzgv normally `reverts' scaling (returning the scale to 1:1) back to
1180 normal when you view a new picture. However, it's possible to disable
1181 this behaviour (see Viewer Options).
1182 There is also support for an alternative form of scaling --- decoupled,
1184 or axis-specific, scaling. When you scale in this way, only one axis of
1185 the image is scaled at once. For example, you might choose to effec‐
1186 tively double the height of an image (with the width left unchanged).
1187 Indeed, this sort of scaling is useful for temporarily correcting pic‐
1188 tures intended for display using pixels twice as wide or high as nor‐
1189 mal.
1190 `x'
1192 `Viewer menu, Scaling, X Only, Double Scaling'
1193 Increase the (x axis) ratio by doubling it.
1194 `X (Shift-x)'
1196 `Viewer menu, Scaling, X Only, Halve Scaling'
1197 Decrease the (x axis) ratio by halving it.
1198 `Alt-x'
1200 `Viewer menu, Scaling, X Only, Add 1 to Scaling'
1201 Increase the (x axis) ratio by adding one.
1202 `Alt-Shift-x'
1204 `Viewer menu, Scaling, X Only, Sub 1 from Scaling'
1205 Decrease the (x axis) ratio by subtracting one.
1206 `y'
1208 `Viewer menu, Scaling, Y Only, Double Scaling'
1209 Increase the (y axis) ratio by doubling it.
1210 `Y (Shift-y)'
1212 `Viewer menu, Scaling, Y Only, Halve Scaling'
1213 Decrease the (y axis) ratio by halving it.
1214 `Alt-y'
1216 `Viewer menu, Scaling, Y Only, Add 1 to Scaling'
1217 Increase the (y axis) ratio by adding one.
1218 `Alt-Shift-y'
1220 `Viewer menu, Scaling, Y Only, Sub 1 from Scaling'
1221 Decrease the (y axis) ratio by subtracting one.
1222 There are also mouse shortcuts for scaling up/down a single axis; con‐
1224 trol-left-click scales up, and control-right-click scales down. By
1225 default this acts on the y axis, but the active axis can be toggled
1226 with `Alt-c', or by toggling the `Ctl+Click Scales X Axis' option (see
1227 Viewer Options).
1228 Interpolation is not currently supported in situations where the x
1230 scaling does not match the y scaling.
1231
1233 Sometimes when viewing a picture you will want to flip it horizontally
1234 or vertically, or rotate it:
1235 `m'
1237 `Viewer menu, Orientation, Mirror (horiz)'
1238 `Mirror' the picture (flip it horizontally).
1239 `f'
1241 `Viewer menu, Orientation, Flip (vert)'
1242 `Flip' the picture (flip it vertically).
1243 `r'
1245 `Viewer menu, Orientation, Rotate Right'
1246 Rotate the picture 90 degrees clockwise.
1247 `R (Shift-r)'
1249 `Viewer menu, Orientation, Rotate Left'
1250 Rotate the picture 90 degrees anti-clockwise. (Any US readers
1251 surprised and/or annoyed by my not saying `counter-clockwise'
1252 will realise why the menus say rotate right/left. :-))
1253 `N (Shift-n)'
1255 `Viewer menu, Orientation, Normal'
1256 Restore the picture orientation to normal. This undoes the
1257 effect of any mirrors, flips, and/or rotations.
1258 xzgv normally `reverts' the picture orientation (the way the picture
1260 has been transformed by mirror/flip/rotate) back to normal when you
1261 view a new picture. However, it's possible to disable this (see Viewer
1262 Options), so that any new pictures are mirrored, flipped, and/or
1263 rotated in the same way.
1264
1266 It's possible to go directly to the previous or next file (or tagged
1267 file) in the directory, or to tag a file, without having to pick the
1268 file from the file selector by hand. These commands are particularly
1269 useful when using xzgv from the keyboard, but there's also a notable
1270 mouse shortcut for moving to the next image.
1271 `Space'
1273 `Viewer menu, Next Image'
1274 Move to next file in dir, and view it. You can also click on the
1275 picture/viewer to do this. (If you find this interferes with
1276 dragging the picture around (though it shouldn't), or just don't
1277 like it, it can be disabled (see Config Variables).)
1278 `b'
1280 `Viewer menu, Previous Image'
1281 Move to previous file in dir, and view it.
1282 `Ctrl-Space'
1284 `Viewer menu, Tagging, Tag then Next'
1285 Tag current file, then move to next file in dir and view it.
1286 `/'
1288 `Viewer menu, Tagging, Next Tagged'
1289 Move to next tagged file in dir, and view it.
1290 `?'
1292 `Viewer menu, Tagging, Previous Tagged'
1293 Move to previous tagged file in dir, and view it.
1294
1296 When running on small screens, or in a small window, it can get a bit
1297 annoying to lose viewer space by having the selector constantly dis‐
1298 played when you don't actually need it. The usual solution to this
1299 problem is to enable auto-hide mode. But what if some pictures you're
1300 viewing are small and some large? It can sometimes be nearly as annoy‐
1301 ing having the selector hidden to `make room for' a small picture which
1302 didn't need it. So for that reason, or perhaps if you just don't like
1303 auto-hide mode :-), you may prefer to leave auto-hide off and explic‐
1304 itly hide the selector when necessary:
1305 `Z (shift-z)'
1307 `Viewer menu, Window, Hide Selector'
1308 Hide the selector. (This is actually a toggle, of sorts; `hide
1309 selector' when it's already hidden unhides it.)
1310 You can also hide or unhide the selector by middle-clicking on the
1312 viewer.
1313
1315 Generally it's easy enough to use your window manager to change windows
1316 etc., but when running fullscreen this can sometimes be a little prob‐
1317 lematic. For this reason, xzgv has built-in support for `iconifying'
1318 itself:
1319 `Ctrl-z'
1321 `Viewer menu, Window, Minimize'
1322 Minimize the xzgv window.
1323
1325 As with the selector, various options can be disabled/enabled which
1326 relate to the viewer.
1327 These settings can also be altered using command-line options (see
1329 Options) and/or config file settings (see Configuring xzgv).
1330 `z'
1332 `Viewer menu, Options, Zoom (fit to window)'
1333 Toggle zoom mode, discussed in more detail elsewhere (see Zoom
1334 Mode).
1335 `Alt-r'
1337 `Viewer menu, Options, When Zooming Reduce Only'
1338 Toggle reduce-only in zoom mode, also covered elsewhere (see
1339 Zoom Mode).
1340 `Alt-p'
1342 `Viewer menu, Options, When Zooming Panorama'
1343 Toggle panorama view in zoom mode, also covered elsewhere (see
1344 Zoom Mode).
1345 `i'
1347 `Viewer menu, Options, Interpolate when Scaling'
1348 Toggle interpolation when a picture is being scaled-up. Again,
1349 this has already been mentioned (see Scaling).
1350 `Alt-c'
1352 `Viewer menu, Options, Ctl+Click Scales X Axis'
1353 Toggle the axis scaled when you control-click (or control-right-
1354 click) on the image. The default is to scale the y axis.
1355 `F (shift-f)'
1357 `Viewer menu, Options, Dither in 15 & 16-bit'
1358 Toggle dithering in 15/16-bit modes. This increases the apparent
1359 colour depth making gradations look much better, but it's slower
1360 than undithered rendering, and can (in 16-bit) slightly distort
1361 a picture's colour balance. (The `F' key was chosen for this as
1362 the dither toggle is functionally similar to zgv's `fakecols'
1363 toggle.)
1364 `Viewer menu, Options, Revert Scaling For New Pic'
1366 Normally xzgv returns the scaling back down to 1 (normal) when a
1367 new picture is selected. By disabling this, you can retain scal‐
1368 ing across picture selection. (There is currently no keyboard
1369 shortcut for this fairly-seldom-changed option --- to toggle it
1370 from the keyboard, you should use the popup menu (press `F10'),
1371 and select the menu item.)
1372 `Viewer menu, Options, Revert Orient. For New Pic'
1374 Similarly, xzgv returns to the picture's true orientation (not
1375 mirrored, rotated, etc.) on selecting a new picture. Disabling
1376 this option means that any mirrors/flips/rotates applied persist
1377 across multiple images. (No keyboard shortcut --- see above.)
1378 `Viewer menu, Options, Use Exif Orientation'
1380 Toggle support for Exif orientation. Devices which create JPEG
1381 files in the Exif format (e.g. many digital cameras) may add an
1382 orientation tag to the file, which says how the camera was being
1383 held when the picture was taken. When this tag is present, xzgv
1384 can adjust the image to compensate for a camera being held on
1385 its side. (This isn't done by default as it misrepresents the
1386 true image, which could be confusing if you don't know why it's
1387 happening.) Enabling this option may be useful if you take pic‐
1388 tures with your camera on its side, but don't want to have to
1389 rotate the pictures before being able to view them properly. Of
1390 course, for this to work your camera has to be inserting the
1391 orientation tag in the first place --- but it can't hurt to try
1392 it and see. (No keyboard shortcut --- see above.)
1393
1395 Picture files are stored in a variety of different forms, or `file for‐
1396 mats'. xzgv, via gdk, supports many.
1397
1399 The format a file is in is identified by its content. The file-reading
1400 code relies on libgdk to determine the file type and read the file cor‐
1401 rectly; generally this uses the format's `magic number' to determine
1402 file type --- e.g. a JPEG/JFIF file starts with the (hex) bytes `FF
1403 D8'. So if you start xzgv with xzgv foo, and foo is in a supported for‐
1404 mat (such as JPEG), the format will be figured out and the file loaded
1405 even though the `extension' is absent.
1406
1408 Many aspects of the way xzgv works can be modified by using a configu‐
1409 ration file.
1410
1412 A configuration file lets you alter aspects of xzgv's behaviour. xzgv
1413 supports two possible config files --- a system-wide one,
1414 /etc/xzgv.conf; and one for each user in their home directory,
1415 $HOME/.xzgvrc. Both are optional. If $HOME/.xzgvrc exists, it is used
1416 instead of /etc/xzgv.conf.
1417 Before describing the format of config files, it may help to give an
1419 example file:
1420 # Sample xzgv config file
1422 # Comment lines begin with `#' and are ignored,
1423 # as are blank lines.
1424 # make pics fit window
1426 zoom on
1427 # hog the screen :-)
1428 fullscreen on
1429 It is a line-based format. Each line (or rather, each line which is not
1431 a comment line and is not blank) assigns a value to a single predefined
1432 `variable'. xzgv has many such variables it lets you modify in this
1433 way. For example, the fullscreen option above controls whether or not
1434 xzgv tries to use the whole screen for its window. If it is given the
1435 value `on'/`y'/`yes'/`1' it does; if `off'/`n'/`no'/`0', it doesn't.
1436 Most variables are of this yes-or-no `boolean' type.
1437 Since the variables set in a config file have a direct effect on how
1439 xzgv works, it can be easier to simply call them `settings'. Indeed,
1440 such terminology is used on occasion in this documentation.
1441
1443 There are various types of variable:
1444 - Boolean. These are on-or-off, yes-or-no variables. Most of xzgv's
1446 config file variables are of this type.
1447 - Integer. These are whole numbers. The meaning of the number depends
1449 on what the variable is used for.
1450 - Geometry. This window size-and/or-position specification format is
1452 only used for the `geometry' setting. See Options, for a description of
1453 how this type works.
1454
1456 Currently, most configuration variables (settings) in xzgv can also be
1457 set by command-line options; indeed, the name of the setting in all
1458 such cases is identical to that for the long version of the option
1459 (e.g. `fullscreen', `auto-hide'). As such, they're documented in the
1460 section which discusses command-line options and the like (see
1461 Options).
1462 However, there are some settings only available in the config file:
1464 click-for-next
1466 This is enabled by default, allowing you to click on the viewer
1467 to skip to the next image. If disabled, clicking on the viewer
1468 does nothing.
1469
1471 Here I (RJM) attempt to explain why I did things the way I did. This is
1472 presented in a question-and-answer format of sorts.
1473
1475 Previously, this section concentrated on xv; that may have made sense
1476 when I originally wrote it, and still makes a certain limited amount of
1477 sense for zgv, but for xzgv it was looking increasingly dated. And so
1478 here I am writing an update. :-)
1479 I originally wrote xzgv as I simply wasn't happy with the viewers for X
1481 that I was aware of at the time (mid-1999). At the time of writing
1482 (late 2000), other key things about xzgv are becoming apparent, partly
1483 through responses I've been getting to it:
1484 o It's `fast'. No, it doesn't do any particular operation faster than
1486 other viewers as far as I know (well, maybe thumbnail updates :-));
1487 rather, the interface tries not to get in your way. Click on a file‐
1488 name, and the picture appears. No multiplicity of toolbars or windows,
1489 it's just there.
1490 o As with zgv, it tries to do one thing well, viewing pictures. It
1492 isn't perfect in this regard, I'll admit, but at least it stays well
1493 clear of picture editing.
1494 o It's, er, quite a lot like zgv. Some of us old fogies like this. :-)
1496 I won't pretend xzgv is The Ultimate Viewer For Everyone. Some people
1498 will prefer other approaches, or just simply prefer other viewers.
1499 (Some people may even still use xv, ghod forbid.) There are a few view‐
1500 ers which you may like to try if you don't think much of xzgv:
1501 o gqview. This seems to be well-regarded. I find it a bit gimmicky and
1503 kitchen-sink-ish; not quite as `pure' or focused as xzgv, IMHO. I think
1504 more people use it than xzgv though.
1505 o xli. I'm not sure if this is maintained these days, but it's not too
1507 bad a viewer. No thumbnails or file selector though. (These days I
1508 mostly use this for setting the root window pixmap, something I don't
1509 think belongs in a viewer, but which xli does happen to be quite good
1510 at.)
1511 o qiv. If I read between the lines correctly, this is essentially a
1513 modern replacement for xli.
1514 o gtksee. I've not tried this, but I think the idea is that it's an
1516 ACDSee clone, and there seem to be an awful lot of people who want a
1517 clone of that. Which is their problem. :^)
1518 o Electric Eyes. To be honest, I think this has been outclassed by
1520 other viewers these days, which shows how far we've come.
1521 Ah, you say, what of xv? Well, we've emphatically reached the point
1523 where no-one need use xv any more. Anyone using xv these days really
1524 should drop that pile of ill-conceived non-Free crap and use one of the
1525 better viewers now available. It's that simple.
1526
1528 It's a fscking viewer, dammit. If you want xv you know where to find
1529 it.
1530 (OTOH, if you want a decent image editor, use the Gimp.)
1532
1534 For years, I maintained a conventional `man page' for zgv (which xzgv
1535 was loosely based on). But over time, I realised just how impossibly
1536 confusing the zgv man page had become.
1537 So I wanted to rewrite zgv's documentation in a more sensible way, in
1539 some other format than a man page. I wanted an established, well-sup‐
1540 ported format with structure and cross-referencing. I felt this made it
1541 a choice between HTML and texinfo. HTML seemed to me to be a moving
1542 target like no other, and not as well supported on text-only terminals
1543 as Info (and thus texinfo). (This latter point is admittedly not too
1544 relevant as far as xzgv is concerned.) When I noticed that a converter
1545 existed to convert texinfo to HTML in any case, the case was closed.
1546 xzgv's documentation was then based on zgv's --- the documentation is
1547 probably more similar than the programs are. :-)
1548 Don't get me wrong --- I like man pages. And even with the excellent
1550 Texinfo documentation and Emacs' very helpful Texinfo mode, writing
1551 texinfo is hardly easy. (Without Texinfo mode's node- and menu-update
1552 commands, I personally would find it near-impossible!) But big man
1553 pages just aren't that good for reference, and this is made worse by
1554 the relative lack of structure.
1555
1557 The conventional way to write texinfo is to follow each sentence with
1558 two spaces after the dot (or whatever ends the sentence). Many people
1559 normally write this way in a non-texinfo context too. But a sizeable
1560 proportion of people normally write text with only one space after the
1561 dot --- and I'm one of them.
1562 The Texinfo documentation gives the impression that two-space must be
1564 used; it says ``it is important to put two spaces at the end of sen‐
1565 tences in Texinfo documents.'' But the only circumstance in which spac‐
1566 ing from the texinfo file is preserved at all (in any sense other than
1567 `there is a space here') is when the texinfo is converted to Info for‐
1568 mat. So, in fact, the decision to use two-space depends on how the
1569 author wants Info output to appear --- this is a subjective decision
1570 which should be entirely down to the preference of the author, despite
1571 the Texinfo documentation's attempt to make two-space sound like an
1572 objective you-must-do-this kind of thing.
1573 You might wonder what the problem with using one-space is, then. Well,
1575 `makeinfo' has to reformat paragraphs, and whenever it needs to insert
1576 space at (what appears to it to be) the end of a sentence, it inserts
1577 two spaces. This behaviour cannot be altered, unlike in Emacs (sen‐
1578 tence-end-double-space; see Fill Commands in the emacs info file) and
1579 GNU fmt (-u; see fmt invocation in the textutils info file). Also,
1580 attempting to `fix' the output Info with sed doesn't work properly
1581 because the `tags' used to find nodes quickly are then incorrect. These
1582 could of course also be fixed, but this would involve a lot more work
1583 than a simple sed invocation.
1584 So realistically, anyone who writes texinfo with one-space has to put
1586 up with the occasional two-space sentence end being inserted into their
1587 text --- worse still, the current `makeinfo' formatting algorithm seems
1588 to insert two spaces even after abbreviations (such as `e.g.' and
1589 `etc.'), which breaks even two-space texinfo. (This is particularly
1590 ironic, by the way, since two-space partisans' main argument in favour
1591 of the practice is often the way it makes it possible to tell the dif‐
1592 ference between abbreviations and the end of a sentence.)
1593 One last point may be worth noting; I am not the first person to write
1595 texinfo files using one-space. At the time of writing, it is used in
1596 the texinfo documentation for BFD, gdbm, GTK/GDK, (Linux) IPC, and
1597 viper, and I expect there are instances I'm not aware of.
1598
1600 All (non-trivial) programs have bugs. Anyone who denies this...
1601 - clearly hasn't written too many programs.
1603 - is wrong. ;-)
1605 It follows that xzgv, like everything else, always has some bugs. Usu‐
1607 ally these are not too serious, or I'd have fixed them before releasing
1608 xzgv. But either way, bugs and other problems with xzgv are noted here.
1609
1611 - In zoom mode, it copes with resizing the window as a whole, but
1612 doesn't when you change the size of the pane (apart from when hid‐
1613 ing/showing selector or resizing from keyboard, but that's only 'cos I
1614 kludged it :-)).
1615 - When scaling up and dithering, you end up with a crappy-looking pic‐
1617 ture if you drag the picture around slowly (since each exposed bit is
1618 dithered independently, with no regard given to matching up to any pre‐
1619 vious error-diffusion).
1620 - Scaling up is slow. Not sure if I can do much about this.
1622 - Using an alignment widget to centre the viewer window results in some
1624 annoying `bounce' in certain resizing situations etc.
1625 - Thumbnails don't look so great in palette-based (e.g. 8-bit) modes.
1627 - When dragging an image around, if you quickly move the mouse pointer
1629 over from the image area to the selector area, the image seems to
1630 `jump' a little. I think this may have something to do with the paned
1631 window's window-splitting bit, but I'm not sure. Also, it jumps when
1632 moving across scrollbar sliders and the paned window splitter handle.
1633 - It doesn't apply any tranparency mask. The practical result of this
1635 seems to be purple transparent bits in thumbnails and scaled-up images,
1636 and black transparent bits elsewhere. This doesn't affect PNG files,
1637 though.
1638 - If a GIF file is corrupted in such a way that the decompressed image
1640 has a larger number of pixels in it, the extra pixels will be ignored
1641 and no error or warning will be generated.
1642 - If you look up `joe code' in a dictionary, right next to ``see zgv''
1644 it now says ``but for really in-depth insight into the joe code nature,
1645 see xzgv''. :-)
1646
1648 - Thumbnails are given an accurate width/height `IMGINFO' comment, but
1649 are always claimed to be "RGB".
1650 - xzgv doesn't duplicate zgv's behaviour of generating thumbnails under
1652 ~/.xvpics/_foo_bar_baz if it can't generate them in
1653 /foo/bar/baz/.xvpics. I doubt anything else supported it, and it com‐
1654 plicated lots of things unnecessarily. This isn't particularly subopti‐
1655 mal, but as an incompatibility with zgv it merits mention.
1656
1658 - Only the first image of a multiple-image GIF is used. (These days,
1659 multiple-image GIFs are usually animations.)
1660
1662 If you find xzgv does something wrong, which you suspect might be a
1663 fault of some sort (a bug) in the program, it is best to report it as I
1664 may not be aware of the problem. (But first, check it is not a `known
1665 bug'. See Known Bugs. It is not usually helpful to report a bug I
1666 already know about.)
1667 It is important to include as much detail in a bug report as you can.
1669 Here are some details you should include:
1670 o The version of xzgv you are running. `xzgv --version' reports this.
1672 o The versions of GTK+ you are using. `xzgv --version-gtk' reports the
1674 GTK+ version being used by xzgv.
1675 o The bitdepth your X server is running in (common depths are 16-bit,
1677 24-bit, and 32-bit). If you don't know what depth you're running in,
1678 try `xdpyinfo|grep depth'.
1679 o A description of the bug --- what effects it has, the circumstances
1681 it occurs in, and so on. Does it only happen for certain types of file?
1682 Only when in 8-bit modes? Only when dithering is enabled? Even `irrele‐
1683 vant' details can sometimes be useful.
1684 o Finally, if you are a programmer and believe you have managed to fix
1686 the bug yourself, patches are gratefully accepted. :-) You should gen‐
1687 erate the patch using `diff -c' or (preferably) `diff -u'.
1688 Then, please file a bug report in the SourceForge bug tracker. See
1690 https://sourceforge.net/p/xzgv.
1691
1693 Bugs in the documentation can sometimes cause as much trouble as bugs
1694 in the program; if you notice a problem in the documentation, it's a
1695 good idea to report it.
1696 For reports of documentation bugs, you should include these details:
1698 o The version of xzgv the documentation is for.
1700 o If it is a problem in one specific section of the documentation,
1702 specify which part it is (by this I mean the heading it comes under;
1703 texinfophiles should read this as `the node name' :-)).
1704 o The format of the documentation you saw the problem in (e.g. info,
1706 man page, HTML).
1707 o A description of the problem.
1709
1711 See Reporting Bugs, for details of where to send the bug report. If
1712 you want to suggest a feature you'd like in xzgv, or a change to an
1713 existing feature, contact me; see See Reporting Bugs for the address.
1714 Future changes etc. are listed in the TODO file.
1716
1718 Russell Marks <rus@svgalib.org> and others; see the section ACKNOWL‐
1719 EDGEMENTS for details.
1720
1722 zgv(1), xv(1), cjpeg(1), djpeg(1), pbm(5), pgm(5), ppm(5), mrf(5)
1723Version 0.9 9th August 2017 XZGV(1)