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.
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 val'
137 `--gamma val'
138 [Not supported in 0.9.] Set the gamma adjustment used (see Gamma
139 Adjustment). The default is 1.0. This also sets the `initial
140 value' used when resetting the gamma adjustment.
141 `-g geom'
143 `--geometry geom'
144 Set the xzgv window's geometry (position and/or size) to geom.
145 The geometry string should be in the usual X format, with the
146 extension that positions/sizes may have a `%' suffix meaning
147 that they are treated as percentages of the screen width/height.
148 The default geometry is `92%x85%'.
149 For those unfamiliar with the way `geometry' works, here's a
151 brief description of the syntax. It's `WxH', or `+X+Y', or
152 `WxH+X+Y', where `W' is width, `H' height, `X' the x position,
153 and `Y' the y position. The first form specifies only the size,
154 the second only the position --- the `WxH+X+Y' form specifies
155 both.
156 Now, the `+X+Y' bit normally specifies where the top-left of the
158 window is. But you can use `-' instead of `+' for the x and/or y
159 position, in which case it specifies the gap between the
160 right/bottom of the window and the right/bottom of the screen.
161 (Note, however, that any window frame your window manager adds
162 to the window is disregarded in this calculation, so you may
163 need to experiment somewhat to get the desired position.) You
164 can also use negative numbers with both `+' and `-' --- so
165 `+-50+0' puts the window partly off the left of the screen, and
166 `+0--50' puts it partly off the bottom of the screen --- but
167 this is of questionable value. :-)
168 Finally, as mentioned above, xzgv extends this syntax by allow‐
170 ing you to use `%' to specify percentages of the screen
171 width/height rather than pixels, e.g. `50%x30%-30%-20%'. It also
172 allows you to use real numbers such as `12.34', which can be
173 useful with `%'.
174 `-h'
176 `--help'
177 Display a list of options and a terse description of what the
178 options do.
179 `--image-bigness-threshold numpix'
181 Set the boundary numpix after which images are considered `big',
182 and are no longer rendered all-at-once (which gives much nicer
183 scrolling, but is harder on memory and can be slow for big
184 images) but are instead rendered piece-by-piece. Units are num‐
185 ber of pixels in image (i.e. width times height), and the
186 default is 2000000 pixels.
187 `--interpolate'
189 Interpolate between the picture's pixels when scaling up (see
190 Scaling). This usually looks nicer, but it's rather slow.
191 `--mouse-scale-x'
193 If enabled, control-clicking on the viewer scales only the X
194 axis. (The default is to scale only the Y axis.)
195 `--revert-orient'
197 (Note that this is normally enabled; use `--revert-orient=off'
198 to disable it.) If disabled, orientation (flip/mirror/rotate)
199 state is retained between pictures (see Viewer Options).
200 `--revert-scale'
202 (Note that this is normally enabled; use `--revert-scale=off' to
203 disable it.) If disabled, scaling is retained between pictures
204 (see Viewer Options).
205 `--selector-width'
207 Set the default/initial size of the selector in pixels. The nor‐
208 mal setting is 200.
209 `-T'
211 `--show-tagged'
212 Show names of currently-tagged files on exiting xzgv. (They're
213 listed to stdout, one per line.) This can be useful when you
214 want to select multiple files graphically and work on them with
215 something else.
216 `--show-thumbnail-messages'
218 Show on the status bar when thumbnails are being read. The sta‐
219 tus bar must be enabled for these messages to be visible, of
220 course. :-)
221 `-k'
223 `--skip-parent'
224 For the first directory shown, skip the cursor past .. (the par‐
225 ent dir). This can be useful when you'd like to immediately use
226 space to `page' through the dir.
227 `-o order'
229 `--sort-order order'
230 Set the initial sorting order used in the selector. Possible
231 settings are `name', `ext', `size', and `date' (or `time'); only
232 the first char of the setting (`n'/`e'/`s'/`d'/`t') need be
233 given. The default is name order.
234 `--sort-timestamp-type type'
236 Set the timestamp type to use when using time/date sorting
237 order. Possible settings are `mtime' (default), `ctime', and
238 `atime'; only the first char of the setting (`m'/`c'/`a') need
239 be given.
240 `--statusbar'
242 Show a status bar below the selector; this, for example, says
243 when a picture is being read.
244 `-t'
246 `--thin-rows'
247 Use rows a third the normal height in the selector. This can be
248 very useful on lower-resolution screens, or if you're really
249 interested in filenames, not thumbnails.
250 `-v'
252 `--version'
253 Show version number.
254 `--version-gtk'
256 Show version number of GTK+ xzgv is using.
257 `-z'
259 `--zoom'
260 Fit picture to viewer window, whatever its actual size (see Zoom
261 Mode).
262 `-r'
264 `--zoom-reduce-only'
265 When in zoom mode, only reduce pictures to fit; i.e. make big
266 pictures viewable all-at-once while leaving small picures
267 intact.
268 If started with `xzgv files', xzgv hides the file selector and treats
270 the file or files as if they were the sole contents of a directory. (It
271 also automatically loads the first file.) As such, you can use the Next
272 Image and Previous Image commands to navigate between the images, or do
273 Exit to Selector and use the selector directly.
274 If started with `xzgv start-dir', xzgv starts up as usual, but with the
276 selector starting on the directory specified (rather than the current
277 directory).
278 Settings which are either on or off (boolean) are, as you might expect,
280 enabled by using e.g. `-z' or `--zoom'. However, there's an alternative
281 long-option form for setting these, resembling how they're set in con‐
282 fig files --- the syntax is `--option=state', where state is
283 `on'/`y'/`yes'/`1' to enable the option, or `off'/`n'/`no'/`0' to dis‐
284 able it. The most useful thing about this is that it allows you to dis‐
285 able options which were previously enabled, by using e.g. `--zoom=off'.
286 (Readers used to the way GNU-style long options work should note that,
288 since this `on'/`off'/etc. arg is optional, you can't use the `--option
289 arg' form in this case; it must be `--option=arg' for it to work.)
290
292 Much of this manual is taken up by a description of xzgv's various com‐
293 mands in its file selector and viewer. Most of these are available both
294 from the keyboard, and from popup menus. (A popup menu appears when you
295 press `F10' or `Menu', or right-click on the selector or the viewer;
296 each has its own menu.) So in the manual, you will often see things
297 rather like this:
298 `key'
300 `Selector menu, Menu the item is in, Menu item'
301 Description of what the key/menu item does.
302 Sometimes the key given has a `(Selector)' or `(Viewer)' suffix; this
304 is because some keypresses in xzgv are specific to the selector or the
305 viewer, and won't work unless the relevant part of xzgv has the key‐
306 board focus.
307
309 Usually, on starting up xzgv, you'll want to use the file selector ---
310 the list of files on the left. (The other subwindow (on the right) is
311 the viewer.) The selector lets you pick files to view (among other
312 things). It lists the subdirectories and picture files in the current
313 directory, along with small `thumbnail' versions of the pictures if
314 they exist.
315
317 Almost all selector commands are available from the selector's pop-up
318 menu, which appears when you right-click anywhere on the selector. (You
319 can also press `F10' or `Menu' to bring up the menu, but as there are
320 keyboard shortcuts for just about everything in xzgv, this isn't often
321 that useful. :-))
322 Usually, it doesn't matter where on the selector you right-click. How‐
324 ever, a few commands on the File menu operate on a single file, the one
325 selected by the keyboard cursor. A problem when using the mouse, you
326 might think --- but when you right-click on the selector, as well as
327 popping up the menu, xzgv moves this cursor to the file you right-
328 clicked on (if any). (You can see this by the way a hollow box is drawn
329 around the file.) So to use e.g. Details on the File menu, you need to
330 right-click on the file you want details on.
331 Both the selector and viewer have `Help' menus, most items of which
333 refer you to this manual:
334 `F1'
336 `Selector menu, Help, Contents'
337 `Viewer menu, Help, Contents'
338 View the manual's overall contents.
339 `Selector menu, Help, The File Selector'
341 View the manual's section on the file selector.
342 `Viewer menu, Help, The Viewer'
344 View the manual's section on the viewer.
345 `Selector menu, Help, Index'
347 `Viewer menu, Help, Index'
348 View the manual's concept index.
349 `Selector menu, Help, About'
351 `Viewer menu, Help, About'
352 Give some brief information about xzgv, including the version
353 number and homepage.
354 Currently, the way xzgv lets you read the manual is a bit crude; it
356 runs the `info' program (see Top in the info-stnd info file) in an
357 `xterm'.
358
360 You can exit xzgv either by using one of two exit keypresses, or by
361 selecting the appropriate option from the selector's popup menu:
362 `q'
364 `Ctrl-q'
365 `Selector menu, Exit xzgv'
366 Quit xzgv.
367 (There's also an exit option on the selector's File menu (`Selector
369 menu, File, Exit'), as `Exit' is generally on any File menu.)
370
372 (This section is deliberately early on in the manual, as thumbnails are
373 probably the most important feature of the file selector, so it's best
374 that you know how to create/update them sooner rather than later.)
375 Thumbnails are small versions of the pictures they represent, and are
377 displayed by the file selector if they exist. xzgv uses xv-compatible
378 thumbnails --- if you create thumbnails with xv they will work with
379 xzgv, and vice versa. xzgv's thumbnails are also compatible with the
380 Gimp, and zgv.
381 If no thumbnail exists for a file, a small `document' icon appears
383 instead (similar to the `folder' icon used for directories).
384 Updating Thumbnails
386 While thumbnails can be made relatively quickly, it's by no means an
387 instant process. For this reason, thumbnails have to be created in
388 advance, and are stored as files in their own right in a subdirectory
389 .xvpics.
390 xzgv never creates/updates thumbnails without you telling it to. So, if
392 you enter a directory where the picture files don't have any thumb‐
393 nails, or where the thumbnails seem to be out of date, you should press
394 `u', or select Update Thumbnails from the selector's menu. (Even if
395 the thumbnails can't be written (say, if you don't have permission to
396 write them), the selector will still show the updated thumbnails until
397 you leave the directory.)
398 Alternatively, you can create/update thumbnails for the current direc‐
400 tory and all subdirectories by using `Alt-u' or Recursive Update. But
401 be warned that a recursive update can take some time!
402 `u'
404 `Selector menu, Update Thumbnails'
405 Create thumbnails for any files which don't have them, and
406 update thumbnails which are older than the corresponding file.
407 While this is going on, a window appears showing how far through
408 the process xzgv is.
409 While the update is in progress, you can abort it by clicking on
411 the Cancel button, or pressing `Esc' or `Enter', or by clicking
412 the delete-window button (if your window manager provides one)
413 on the title bar. xzgv will stop once it has finished the thumb‐
414 nail it is currently working on (if any).
415 `Alt-u'
417 `Selector menu, Recursive Update'
418 Create/update thumbnails for all files in the current directory
419 and all subdirectories. This can take some time, so you are
420 prompted to confirm you really want to do this (see Dialog
421 Boxes). Progress is indicated in much the same way as for a nor‐
422 mal update, but only for the directory currently being updated
423 --- the overall progress is not indicated, other than by the
424 current dir being (as ever) displayed in the main window's
425 title. You can abort a recursive thumbnail update in the same
426 ways as for a normal update (see above).
427 By default, xzgv behaves a little oddly when doing a recursive
429 update, to give some consistency with the normal update. See
430 Thumbnail Issues, for details.
431 Thumbnail Issues
433 Dealing with thumbnails can be `interesting' at times, and there are a
434 few ways this influences things:
435 - xzgv doesn't read the thumbnails in a directory all at once. Instead,
437 it just reads the directory contents, then starts up what is effec‐
438 tively a kind of background task to read in the thumbnails. So xzgv may
439 not be quite as responsive as usual for a short time after entering a
440 directory with many thumbnails (say, a few hundred) --- but on the
441 other hand, at least it is responding. :-)
442 - The `background task' makes a special effort to show thumbnails for
444 the files currently visible in the selector first, no matter how much
445 you move around the list, but it reads them all in eventually.
446 - The thumbnails used in xzgv require 256 colours to display. This can
448 be a problem if you're running X in 256 colours or less as, even if
449 you're running an 8-bit (256 colour) server, there will almost
450 inevitably be fewer colours available. Currently, xzgv just uses what‐
451 ever gdk reports as the closest match to each individual colour used in
452 thumbnails. This gives a tolerable result on 8-bit servers, assuming
453 gdk was able to allocate a large number of colours; however, it gives
454 terrible results if it couldn't, or if running on 4-bit or 1-bit
455 servers. Sorry about this --- it should be fixed in future (either by
456 using gdk to draw the thumbnail pixmaps, or by dithering them `by hand'
457 to suit the colours available).
458 - Finally, when doing a recursive thumbnail update, xzgv (by default)
460 reads existing thumbnails in a directory before updating any. Or
461 rather, it reads thumbnails for those files currently visible in the
462 selector. This can slow things down very slightly, but keeps the `look
463 and feel' consistent with the normal update. (Still, you can disable
464 this with the `--fast-recursive-update' command-line option (see Invok‐
465 ing xzgv) or equivalent config file entry (see Configuring xzgv).)
466
468 The file selector is simply a list of subdirectories and filenames,
469 along with any thumbnails that exist for them. The list is normally in
470 asciibetical order (but you can change this; see Changing the Sorting
471 Order). Names of directories are shown first, and they are shown in
472 order at the beginning of the list, before all the picture files. Long
473 filenames may not fit in the visible part of the file selector display;
474 if so, there will be a horizontal scrollbar you can use to see the rest
475 of the name(s) (you can use cursor left/right to do this from the key‐
476 board).
477 The list is very often larger than can fit on the screen at once. If
479 this is the case, only part is shown at a time, but you can move around
480 the list using the (vertical) scrollbar, or with cursor up/down and the
481 like.
482 If you find the selector window to be too small vertically, and would
484 like to see more files at once, you can start xzgv fullscreen by using
485 the -f option (see Options), and/or use `thin rows' mode (see File
486 Selector Options).
487 If you find the selector too small (or too big) horizontally, you can
489 change this by moving the splitter line's `handle' (a small square but‐
490 ton between the selector and viewer, near the bottom of the window),
491 which changes the relative sizes of the selector and viewer. You can
492 move it by dragging it with the mouse, or with these keys:
493 `['
495 Move the window split left.
496 `Ctrl-['
498 Move the window split left more slowly.
499 `]'
501 Move the window split right.
502 `Ctrl-]'
504 Move the window split right more slowly.
505 `~'
507 Reset the window split to its default position.
508 You can also set the initial/default size of the selector --- in
510 effect, the position of the window split --- using `--selector-width'
511 (see Options) or the config file option `selector-width'.
512
514 This section is mainly for those of us more inclined to the keyboard
515 side of the force. :-) Mouse-happy types can freely skip it.
516 When the selector has the keyboard focus, the cursor (or in GTK+ jar‐
518 gon, the `focus row') is normally shown as a hollow box around one of
519 the list's rows. This serves the following functions:
520 - It selects a file for view commands to operate on.
522 - It determines which part of the list is shown, as the part of the
524 list shown onscreen always contains the cursor (unless you move around
525 using the mouse).
526 There are several commands for moving the cursor. In summary, most
528 `special' keys like the cursors do what you'd imagine they do, but in
529 more detail:
530 `Cursor Up'
532 `k'
533 Move up.
534 `Cursor Down'
536 `j'
537 Move down.
538 `Page Up'
540 `Ctrl-u'
541 Move the cursor back roughly a page.
542 `Page Down'
544 `Ctrl-v'
545 Move the cursor forward roughly a page.
546 `Ctrl-Home'
548 `Ctrl-a'
549 Move the cursor to the start of the list.
550 `Ctrl-End'
552 `Ctrl-e'
553 Move the cursor to the end of the list.
554 `g'
556 `''
557 Move the cursor to the first filename starting with the next key
558 pressed, which would generally be a letter or number. Case is
559 significant; `a' and `A' are different. If no key is pressed
560 within 2 seconds, the command is cancelled.
561 If no files start with the specified character, it moves to the
563 first file which starts with a later char (in asciibetical
564 order). If there are none for which this is the case, it moves
565 to the last file --- unless there are no files (just directo‐
566 ries), in which case it has no effect.
567
569 To view a file from the selector, you can click on it, or press `Enter'
570 after moving the cursor to the relevant file, or right-click on the
571 file and choose `File' then `Open'.
572 `Enter'
574 `Left-click-on-file'
575 `Selector menu, File, Open'
576 View the chosen picture file, or if a subdirectory is chosen,
577 make that the current directory.
578
580 See The Viewer, for details of how the viewer works. If xzgv has a
581 serious problem reading a file, it will give an error. Errors are
582 shown in dialogs which appear in the middle of the screen --- they stay
583 there until you click Ok (or press `Enter' or `Esc').
584 xzgv also uses similar dialog boxes for other things:
586 - Getting confirmation that you want to do something. `Enter' or `y'
588 picks `yes'; `Esc' or `n' picks no. (Again, you can click on the rele‐
589 vant button with the mouse to do the same.)
590 - Showing progress when updating a thumbnail. This is a slightly
592 unusual dialog, in that it automatically disappears when the update is
593 complete. However, it does provide a Cancel button which you can click
594 to abort the update (pressing `Enter' or `Esc' does the same).
595 - Reading a directory name. Here you should type the directory name
597 then click Ok (or press `Enter'), or click Cancel (or press `Esc') to
598 abort. The text-input `widget' used allows a certain amount of editing,
599 including these keys:
600 `Cursor Left'
602 `Ctrl-b'
603 Move the cursor left. (A vertical bar shows the cursor posi‐
604 tion.)
605 `Cursor Right'
607 `Ctrl-f'
608 Move the cursor right.
609 `Home'
611 `Ctrl-a'
612 Move the cursor to the start of the line.
613 `End'
615 `Ctrl-e'
616 Move the cursor to the end of the line.
617 `Backspace'
619 `Ctrl-h'
620 Delete char to the left of the cursor. (Note that `Backspace' is
621 (usually) the key above the main `Enter' key; it is often
622 labelled simply as an arrow.)
623 `Delete'
625 `Ctrl-d'
626 Delete the char the cursor is on.
627 You can also set the X selection (by selecting text with the mouse, or
629 holding `Shift' while moving the cursor) to allow pasting text into
630 other programs, and you can cut/copy/paste text in the usual ways:
631 `Shift-Delete'
633 `Ctrl-x'
634 Cut text.
635 `Ctrl-Insert'
637 `Ctrl-c'
638 Copy text.
639 `Shift-Insert'
641 `Ctrl-v'
642 Paste text.
643 You can paste text from (some) other programs using the latter command,
645 too.
646
648 Usually, when you view a file, the viewer subwindow keeps displaying it
649 until you view a different file. However, if you `close' the file, the
650 viewer stops displaying the file and returns to its initial state.
651 `Ctrl-w'
653 `Selector menu, File, Close'
654 `Close' the currently-viewed file, clearing the viewer subwin‐
655 dow.
656
658 The listing the selector gives for a file is pretty sparse --- just the
659 filename and (if the file has one) the accompanying thumbnail. While
660 this does keep things simple, you sometimes want to know how much space
661 a file takes up, when it was last modified, the dimensions of the
662 image, that kind of thing. So, you can show details of a single file
663 using the `file details' command:
664 `:'
666 `;'
667 `Selector menu, File, Details'
668 Show various details about the file pointed to by the keyboard
669 cursor. See The Selector Menu, for how to choose the file
670 details are given for when using the mouse. (Basically, you
671 right-click on the file when popping up the menu.)
672 Most of the details shown come from the OS (by using the `stat(2)' sys‐
674 tem call), and should always be available unless you have limited per‐
675 missions for the directory the file is in. The file dimensions
676 (width/height), however, come from the file's thumbnail. If it doesn't
677 have one, or if it's unreadable, or if it has one and it's readable but
678 it doesn't mention the original image's width/height, then the Details
679 from thumbnail area is greyed out.
680 (In explanation of the latter point --- pre-5.0 versions of zgv did not
682 generate width/height comments in thumbnails, so zgv users in particu‐
683 lar may find the width/height details missing. (xzgv has always been
684 ok, though, it's just zgv which had this problem.) Worse yet, versions
685 5.0 and 5.1 generated them with incorrect sizes for most JPEGs. To fix
686 either problem for a given directory, do `rm -fr .xvpics' in that dir
687 from a shell prompt and recreate the thumbnails with zgv 5.2 or later,
688 or xzgv/xv/Gimp.)
689
691 The file selector is not restricted to working on one file at a time.
692 You can `tag' as many (or as few) files as you wish, and certain com‐
693 mands described in this section will act on them.
694 Initially, all files are untagged, and the filenames usually appear in
696 black (though this depends on the GTK+ theme you're using). Tagged
697 files appear in red.
698 Tag and Untag Commands
700 There are several ways to tag or untag files. The keyboard-based ones
701 which work on individual files (also available on the Tagging menu)
702 move the cursor down one row afterwards, to make tagging or untagging
703 multiple files easier.
704 To tag or untag a single file with the mouse, control-click (i.e. hold
706 down the control key and click) on the relevant filename or thumbnail
707 in the selector. It's true that you could use Tag and/or Untag on the
708 Tagging menu (see The Selector Menu, for how to choose the file
709 tagged/untagged when doing it this way), but this is usually much less
710 convenient than using control-click. (The menu entries for those are
711 really just for completeness.)
712 There is also a command available in the viewer to tag the currently-
714 viewed file. See Changing Picture, for details.
715 `='
717 `+'
718 `Keypad +'
719 `0'
720 `Selector menu, Tagging, Tag'
721 Tag file.
722 `-'
724 `Keypad -'
725 `9'
726 `Selector menu, Tagging, Untag'
727 Untag file.
728 `Alt ='
730 `Alt-Keypad +'
731 `Alt-0'
732 `Selector menu, Tagging, Tag All'
733 Tag all files.
734 `Alt -'
736 `Alt-Keypad -'
737 `Alt-9'
738 `Selector menu, Tagging, Untag All'
739 Untag all files.
740 `Alt-o'
742 `Selector menu, Tagging, Toggle All'
743 Toggle all tags. This inverts the tagged state, so that all pre‐
744 viously tagged files become untagged, and all previously
745 untagged files become tagged.
746 Currently there is no way to toggle a (single) file's tag state from
748 the keyboard.
749 Moving Between Tagged Files
751 These commands let you search for (move to) the next or previous tagged
752 file (if any). Note that `next' and `previous' here are relative to the
753 keyboard cursor's position; if you use these from the menu, be careful
754 to right-click on the file you want to start the search from.
755 `/'
757 `Selector menu, Tagging, Next Tagged'
758 Move to next tagged file in dir.
759 `?'
761 `Selector menu, Tagging, Previous Tagged'
762 Move to previous tagged file in dir.
763 Equivalent commands are also available in the viewer (see Changing Pic‐
765 ture).
766 Copying/Moving Files
768 You can copy or move tagged files to a directory you specify. If no
769 files are tagged, xzgv copies/moves the file the cursor is currently on
770 --- unless the cursor is on a subdirectory, in which case it gives an
771 error.
772 `C (Shift-c)'
774 `Selector menu, File, Copy'
775 Copy tagged files (or the current file) to a given directory.
776 xzgv asks for the destination directory using a dialog (see Dia‐
777 log Boxes) and copies the files there. If it comes to copy a
778 file but there is an existing file in the dir with the same
779 name, the file is not copied and nor are any of the remaining
780 files.
781 `M (Shift-m)'
783 `Selector menu, File, Move'
784 Move tagged files (or the current file) similarly.
785
787 As well as copying/moving files, you can rename them:
788 `Ctrl-n'
790 `Selector menu, File, Rename file'
791 Rename the current file or directory --- xzgv will refuse to
792 overwrite any existing files/directories. The new name must
793 remain in the current directory. (See Copying/Moving Files, for
794 how to move a file to a different directory (albeit keeping the
795 same name).) See The Selector Menu, for how to choose the file
796 renamed when using the mouse. (Basically, you right-click on
797 the file when popping up the menu.)
798 I know `Ctrl-n' isn't the most mnemonic keypress possible for `rename',
800 but all the good ones were taken. :-/
801
803 Deleting a file is pretty straightforward:
804 `Ctrl-d'
806 `Selector menu, File, Delete file'
807 Delete the file pointed to by the keyboard cursor (and any
808 accompanying thumbnail). See The Selector Menu, for how to
809 choose the file deleted when using the mouse. (Basically, you
810 right-click on the file when popping up the menu.)
811 Note that only one file is deleted (hence `Delete file'); there is cur‐
813 rently no way to delete all tagged files.
814
816 The easiest way to change the current directory in xzgv is usually to
817 click on a directory entry in the file list (or move the cursor to it
818 and press `Enter'). Selecting the `..' entry moves to the parent direc‐
819 tory of the current one.
820 There is an alternative though:
822 (Note that the key for this command is shift-`g', not `g'.)
824 `G'
826 `Selector menu, Directory, Change'
827 Go to a specified directory. xzgv asks for the destination
828 directory using a dialog box which you should type the dir's
829 name into (see Dialog Boxes), and moves to that directory if it
830 exists.
831
833 Normally, xzgv reads a directory once (on starting up, or when a new
834 directory is selected). So if the contents of the directory are changed
835 by another program, this is not automatically reflected. You can, how‐
836 ever, explicitly tell xzgv to `rescan' the directory (reread the con‐
837 tents), which will update xzgv's notion of what's in it:
838 `Ctrl-r'
840 `Selector menu, Directory, Rescan'
841 Rescan the current directory.
842
844 Normally, the files are listed in asciibetical order by name. However,
845 you can instead have the file list sorted by size, last-modified
846 date/time, or by `extension' (the file type).
847 (Only the order of files can be altered; directories are always listed
849 first, and always in name order.)
850 `Alt-n'
852 `Selector menu, Directory, Sort by Name'
853 Sort by name. This is the default.
854 `Alt-e'
856 `Selector menu, Directory, Sort by Extension'
857 Sort by extension.
858 `Alt-s'
860 `Selector menu, Directory, Sort by Size'
861 Sort by size. The biggest files are listed last.
862 `Alt-d'
864 `Selector menu, Directory, Sort by Time & Date'
865 Sort by time/date. The newest files are listed last.
866 You can set the default sort order via the command-line (see Invoking
868 xzgv) or a config file (see Configuring xzgv).
869 There are three possible timestamps you can use for the `Time & Date'
871 sorting order:
872 `Alt-Shift-m'
874 `Selector menu, Directory, Time & Date Type, Modification Time (mtime)'
875 Use the last-modified time (`mtime'). This is the default.
876 `Alt-Shift-c'
878 `Selector menu, Directory, Time & Date Type, Attribute Change Time
879 (ctime)'
880 Use the last-attribute-change time (`ctime'). Note that this is
881 not always the time the file was created, which it's sometimes
882 mistaken for; for example, moving a file with `mv' will usually
883 change the ctime.
884 `Alt-Shift-a'
886 `Selector menu, Directory, Time & Date Type, Access Time (atime)'
887 Use the last-accessed time (`mtime'). The selector order is not
888 automatically updated when xzgv reads files, since this would
889 probably be annoying; do a manual rescan if need be.
890
892 Various aspects of the file selector's behaviour can be configured
893 while xzgv is running, by using these toggle commands (which enable the
894 feature if it was previously disabled, and vice versa).
895 These settings can also be altered using command-line options (see
897 Options) and/or config file settings (see Configuring xzgv).
898 `Alt-a'
900 `Selector menu, Options, Auto Hide'
901 Toggle the auto-hiding of the selector when a picture is viewed
902 (off by default). This is handy for small screens/windows, or
903 for old-time zgv users who just dig that groovy modal interface,
904 er, man. :-)
905 `Alt-b'
907 `Selector menu, Options, Status Bar'
908 Toggle status bar at the bottom of the selector (off by
909 default). This displays messages in certain circumstances ---
910 normally, it just says when a picture is being read.
911 `Selector menu, Options, Thumbnail Msgs'
913 Toggle reading-thumbnails messages (default is off), only visi‐
914 ble if the status bar is enabled. These messages make it clear
915 when all thumbnails have been read, but having something flash
916 up every time you change directory is generally just annoying.
917 `v'
919 `Selector menu, Options, Thin Rows'
920 Toggle `thin rows' mode (off by default), in which thumbnails
921 are shown at a third their normal size so that many more files
922 can be shown at once. (The odd keyboard shortcut for this is
923 inherited from zgv's `visual' mode toggle, which had a roughly
924 similar effect.)
925
927 Once you've selected a file to view, it's shown in the viewer (the
928 right-hand part of xzgv's window). This section describes what you can
929 do while viewing the picture.
930 Like the selector, the viewer has its own menu --- right-click anywhere
932 on the viewer (or press `F10' or `Menu') to show it --- and a similar
933 help menu (see The Selector Menu).
934
936 When using the mouse to control xzgv, it doesn't matter whether the
937 selector or the viewer has keyboard focus --- mouse operations tran‐
938 scend such petty boundaries. :-) But keyboard control is (of necessity)
939 effectively modal, and so you need to `exit' the viewer in order to
940 have keyboard control over the selector again. You also need to exit
941 the viewer if you've enabled auto-hide mode.
942 Exiting the viewer is simple:
944 `Esc'
946 `Tab'
947 `Viewer menu, Exit to Selector'
948 Exit the viewer. This also returns the selector to its former
949 size, if it was previously `hidden'.
950 Another way of exiting the viewer is to middle-click on it, but this
952 mouse-only approach is really only of use when the selector is `hid‐
953 den'.
954
956 A picture may well be too large to fit entirely in the viewer window.
957 There are two main things which can help you see more of the picture at
958 once:
959 - Make the xzgv window larger. You could `maximize' it with your window
961 manager, or you could start xzgv with a larger window using `--geome‐
962 try' or fullscreen mode (see Options). The fullscreen mode gives xzgv
963 the maximum window size possible, but needs co-operation from your win‐
964 dow manager (and alas, many are not as willing as one might like) ---
965 in some cases you may even find `--geometry 100%x100%' to be more
966 effective.
967 - Hide the selector. To do this, either use auto-hide mode (see File
969 Selector Options), or hide the selector explicitly (see Hiding the
970 Selector).
971 But of course, these are only partial solutions to the problem; there
973 will inevitably always be pictures larger than your screen can show at
974 once. In general, then, there are two ways to see the whole of the pic‐
975 ture.
976 Scrolling
978 Scrolling is the default approach to handling big pictures in xzgv.
979 When the viewer is started up, the top-left of the picture is shown ---
980 you can either drag the picture around with the mouse (i.e. click and
981 hold the button down, then move the mouse around), or use the scroll‐
982 bars, or use the cursor keys (and others) to move around the rest of
983 the picture:
984 `Cursor Up'
986 `K'
987 Move up 100 pixels. `Ctrl-Cursor Up' and `k' both move up 10
988 pixels.
989 `Cursor Down'
991 `J'
992 Move down 100 pixels. `Ctrl-Cursor Down' and `j' both move down
993 10 pixels.
994 `Cursor Left'
996 `H'
997 Move left 100 pixels. `Ctrl-Cursor Left' and `h' both move left
998 10 pixels.
999 `Cursor Right'
1001 `L'
1002 Move right 100 pixels. `Ctrl-Cursor Right' and `l' both move
1003 right 10 pixels.
1004 `Page Up'
1006 `Shift-Cursor Up'
1007 `Ctrl-u'
1008 Move up (nearly) the window height. (It moves by 90% of the
1009 height.)
1010 `Page Down'
1012 `Shift-Cursor Down'
1013 `Ctrl-v'
1014 Move down (nearly) the window height.
1015 `-'
1017 `Shift-Cursor Left'
1018 Move left (nearly) a window-length. (It moves by 90% of it.)
1019 `='
1021 `Shift-Cursor Right'
1022 Move right (nearly) a window-length.
1023 `Home'
1025 `Ctrl-a'
1026 Move to the top-left of the picture.
1027 `End'
1029 `Ctrl-e'
1030 Move to the bottom-right of the picture.
1031 Zoom Mode
1033 An alternative way of viewing the whole picture, one which lets you see
1034 the picture onscreen all at once no matter how big (or small) it is, is
1035 zoom mode.
1036 Zoom mode's name derives from the idea of `zooming' a small file up to
1038 fit the window. But in reality, it is more often used to reduce a large
1039 file to fit.
1040 Zoom mode is not the default, and has to be enabled. Once enabled, it
1042 stays on until you turn it off again (or until you enable scaling, or
1043 select Normal (see Scaling)).
1044 `z'
1046 `Viewer menu, Options, Zoom (fit to window)'
1047 Toggle zoom mode.
1048 `Alt-r'
1050 `Viewer menu, Options, When Zooming Reduce Only'
1051 When in zoom mode, only reduce pictures to fit. This can be use‐
1052 ful when going through a lot of unpredictably-sized pictures, as
1053 it means that you can see all of a big picture easily without
1054 also meaning that tiny little icons assume a scale of Biblical
1055 proportions. :-)
1056 The way zoom mode reduces a file to fit the window is (relatively)
1058 quick but harsh, and may make the picture look a bit ugly. In future
1059 there may be a smoothing option like zgv's vkludge, but for now I'm
1060 afraid the fairly crude resize is all that's available.
1061 There is in fact an alternative to zoom mode, as you can scale down an
1063 image instead. This is generally only useful for very large images,
1064 however; zoom mode tends to be the Right Thing for the most part.
1065
1067 You can scale a picture --- this makes it appear larger (or smaller)
1068 onscreen. xzgv acts much as if the scaled picture were the real pic‐
1069 ture; for example, the cursor keys scroll around in steps of 100 scaled
1070 pixels, even if this means moving a fraction of a pixel (or many pix‐
1071 els) in the original picture (and similarly for movement with the
1072 mouse).
1073 The main limitation of scaling (other than how much it slows things
1075 down :-), at least when scaling up) is that you can only scale by inte‐
1076 ger values, so you can only make each pixel in the image twice as
1077 wide/high, or three times as wide/high, or four times, and so on.
1078 (It may seem odd saying e.g. `twice as wide/high' rather than `twice
1080 the size', but technically `twice the size' would be referring to scal‐
1081 ing up the width (and height) by about 1.414...)
1082 Normally, xzgv does no scaling, which could be considered a ratio of
1084 1:1. Scaling up increases that ratio. How it is increased depends on
1085 which option/key you use:
1086 `d'
1088 `Viewer menu, Scaling, Double Scaling'
1089 Increase the ratio by doubling it --- this leads to ratios of
1090 2:1, 4:1, 8:1...
1091 `s'
1093 `Viewer menu, Scaling, Add 1 to Scaling'
1094 Increase the ratio by adding one --- leads to ratios of 2:1,
1095 3:1, 4:1...
1096 There are similar commands to decrease the ratio:
1098 `D (Shift-d)'
1100 `Viewer menu, Scaling, Halve Scaling'
1101 Decrease the ratio by halving it.
1102 `S (Shift-s)'
1104 `Viewer menu, Scaling, Sub 1 from Scaling'
1105 Decrease the ratio by subtracting one.
1106 Usually the double/halve scalings are more useful.
1108 Note that you can also double/halve the scaling by using shift-left-
1110 click on the viewer to double, and shift-right-click to halve. This
1111 still changes scale `around' the middle of the window though (rather
1112 than around the point clicked on, as you might expect), which is a lit‐
1113 tle strange and may possibly be changed in future.
1114 When you scale `below' 1:1, the above commands lead to ratios of (e.g.)
1116 1:2, 1:4, 1:8, etc. --- that is, the ratios work the same way, but the
1117 other way around. This gives you an increasingly small image.
1118 The scaling ratio is never decreased below 1:32. It is also never
1120 increased beyond the point where the overall image size would exceed
1121 32767x32767 --- this limit is due to the combination of X's limit on
1122 window sizes, and the implementation used by xzgv for scaling.
1123 One problem with scaling up, given the way it's currently implemented,
1125 is that it's not well-suited to dithered display --- so if you're run‐
1126 ning on an 8-bit server, dragging the image around slowly when using
1127 scaling (especially scaling with interpolation) may result in some
1128 nasty, streaky, undithered-looking parts of the picture. :-(
1129 You can undo the effect of scaling (up or down) at any time:
1131 `n'
1133 `Viewer menu, Scaling, Normal'
1134 Resume `normal' display --- disables scaling mode, and also zoom
1135 mode.
1136 Normally, scaling up works by simply making the pixels into larger and
1138 larger squares (in effect), which remain the same colour. However, you
1139 can enable a feature called `interpolation' which smoothly graduates
1140 the colour change between the top-left corners of each pixel. This is
1141 very slow, but looks nice.
1142 `i'
1144 `Viewer menu, Options, Interpolate when Scaling'
1145 Toggle interpolation in scaling mode.
1146 (If you like the appearance of scaling with interpolation, you may also
1148 be interested in a program I wrote called pnminterp, which can scale up
1149 a PGM or PPM file while applying this effect. These days it's part of
1150 the netpbm package.)
1151 Scaling down, however, is implemented a bit like a special-case zoom
1153 mode, and currently there are no ways of making that look nicer. :-/
1154 xzgv normally `reverts' scaling (returning the scale to 1:1) back to
1156 normal when you view a new picture. However, it's possible to disable
1157 this behaviour (see Viewer Options).
1158 There is also support for an alternative form of scaling --- decoupled,
1160 or axis-specific, scaling. When you scale in this way, only one axis of
1161 the image is scaled at once. For example, you might choose to effec‐
1162 tively double the height of an image (with the width left unchanged).
1163 Indeed, this sort of scaling is useful for temporarily correcting pic‐
1164 tures intended for display using pixels twice as wide or high as nor‐
1165 mal.
1166 `x'
1168 `Viewer menu, Scaling, X Only, Double Scaling'
1169 Increase the (x axis) ratio by doubling it.
1170 `X (Shift-x)'
1172 `Viewer menu, Scaling, X Only, Halve Scaling'
1173 Decrease the (x axis) ratio by halving it.
1174 `Alt-x'
1176 `Viewer menu, Scaling, X Only, Add 1 to Scaling'
1177 Increase the (x axis) ratio by adding one.
1178 `Alt-Shift-x'
1180 `Viewer menu, Scaling, X Only, Sub 1 from Scaling'
1181 Decrease the (x axis) ratio by subtracting one.
1182 `y'
1184 `Viewer menu, Scaling, Y Only, Double Scaling'
1185 Increase the (y axis) ratio by doubling it.
1186 `Y (Shift-y)'
1188 `Viewer menu, Scaling, Y Only, Halve Scaling'
1189 Decrease the (y axis) ratio by halving it.
1190 `Alt-y'
1192 `Viewer menu, Scaling, Y Only, Add 1 to Scaling'
1193 Increase the (y axis) ratio by adding one.
1194 `Alt-Shift-y'
1196 `Viewer menu, Scaling, Y Only, Sub 1 from Scaling'
1197 Decrease the (y axis) ratio by subtracting one.
1198 There are also mouse shortcuts for scaling up/down a single axis; con‐
1200 trol-left-click scales up, and control-right-click scales down. By
1201 default this acts on the y axis, but the active axis can be toggled
1202 with `Alt-c', or by toggling the `Ctl+Click Scales X Axis' option (see
1203 Viewer Options).
1204 Interpolation is not currently supported in situations where the x
1206 scaling does not match the y scaling.
1207
1209 Sometimes when viewing a picture you will want to flip it horizontally
1210 or vertically, or rotate it:
1211 `m'
1213 `Viewer menu, Orientation, Mirror (horiz)'
1214 `Mirror' the picture (flip it horizontally).
1215 `f'
1217 `Viewer menu, Orientation, Flip (vert)'
1218 `Flip' the picture (flip it vertically).
1219 `r'
1221 `Viewer menu, Orientation, Rotate Right'
1222 Rotate the picture 90 degrees clockwise.
1223 `R (Shift-r)'
1225 `Viewer menu, Orientation, Rotate Left'
1226 Rotate the picture 90 degrees anti-clockwise. (Any US readers
1227 surprised and/or annoyed by my not saying `counter-clockwise'
1228 will realise why the menus say rotate right/left. :-))
1229 `N (Shift-n)'
1231 `Viewer menu, Orientation, Normal'
1232 Restore the picture orientation to normal. This undoes the
1233 effect of any mirrors, flips, and/or rotations.
1234 xzgv normally `reverts' the picture orientation (the way the picture
1236 has been transformed by mirror/flip/rotate) back to normal when you
1237 view a new picture. However, it's possible to disable this (see Viewer
1238 Options), so that any new pictures are mirrored, flipped, and/or
1239 rotated in the same way.
1240
1242 [Brightness and contrast changing is not supported in xzgv 0.9.] xzgv
1243 provides support for changing brightness and contrast, though given the
1244 way it has to redraw the image to do so, it can be a little slow.
1245 Currently there is no way to do this with the mouse; this should be
1247 fixed soon.
1248 `,'
1250 Decrease contrast.
1251 `.'
1253 Increase contrast.
1254 `<'
1256 Decrease brightness.
1257 `>'
1259 Increase brightness.
1260 `:'
1262 `;'
1263 Reset contrast and brightness to normal. (`*' is also supported,
1264 for hysterical raisins.) Note that this deliberately does not
1265 affect the gamma adjustment.
1266 Any contrast change is applied before any brightness change, and any
1268 gamma adjustment is applied before both.
1269
1271 [Gamma is not supported in xzgv 0.9.] Ah yes, gamma. What fun. The
1272 basic problem is this --- differing displays have differing intensity
1273 response curves. ``This has made a lot of people very angry and been
1274 widely regarded as a bad move.'' :-)
1275 It means that you need some way of adjusting how brightly you display
1277 the picture to compensate. But since we're dealing with response
1278 curves, this isn't just a matter of changing the brightness in a linear
1279 fashion.
1280 That doesn't seem so hard to deal with, right? All you need is to get
1282 the gamma (a number which specifies how much the curve bends) for the
1283 image, and for the screen, divide one by the other and adjust as appro‐
1284 priate. Joy.
1285 But, given that the problem has existed since we started displaying
1287 more than eight colours, you won't be surprised to find that it's
1288 already been fixed. And the fixes all tend to clash, and everybody has
1289 a different notion of how to fix it. The usual `fix' is to assume that
1290 whoever made the image made it with a gamma matching the gamma of your
1291 display, so you can just stuff the bits right on the screen. Since this
1292 is easy, it's the most widespread approach. But it's a bit stupid, so
1293 not everyone does it. Combine that with the lack of gamma specification
1294 in most image formats, and the often-bogus values specified by people
1295 in those that do, and hey presto --- the image gamma could be just
1296 about anything. And the screen's gamma also tends not to be easily
1297 determined.
1298 So how on earth do you deal with something like that in a remotely sane
1300 fashion?
1301 The answer chosen in xzgv is to just live with the fact that the proba‐
1303 bility of automatically obtaining correct values for both the screen
1304 and image gamma is basically zero. Once you accept that, the sensible
1305 thing to do is to make it very easy and fast to change gamma adjustment
1306 to commonly-required values. So here's how to do it:
1307 `1'
1309 Set gamma adjustment to 1.0, i.e. no adjustment. This is the
1310 default setting.
1311 `2'
1313 Set gamma adjustment to 2.2. This is useful for viewing linear-
1314 gamma files (one classic example being raytracer output) on an
1315 average PC monitor.
1316 `3'
1318 Set gamma adjustment to 1 divided by 2.2, i.e. roughly 0.45.
1319 This is useful for the reverse --- viewing average-PC-monitor-
1320 gamma files on a linear-gamma display. Historically I believe
1321 the classic example would have been viewing PC files on a Mac,
1322 but I don't know how true that is these days.
1323 `4'
1325 Set gamma adjustment to its initial value, as specified by a
1326 `--gamma' command-line option (see Options) or equivalent config
1327 file setting (see Configuring xzgv). The default value used if
1328 none was specified is 1.0.
1329 A brief clarification is probably in order. The gamma adjustment value
1331 which you set in xzgv is actually inverted from (i.e. one divided by)
1332 the true adjustment value used. This is (believe it or not :-))
1333 intended to avoid confusion by reflecting the fact that screen gamma is
1334 the one most widely considered/well known.
1335 You can also tweak the adjustment more precisely, in a similar way to
1337 brightness/contrast:
1338 `Alt-,'
1340 Decrease gamma adjustment (divide it by 1.05).
1341 `Alt-.'
1343 Increase gamma adjustment (multiply it by 1.05).
1344 Note that `:', and the other keys which reset the brightness/contrast,
1346 deliberately avoid resetting the gamma adjustment.
1347 As with brightness/contrast, there is currently no way to adjust gamma
1349 with the mouse; this should be fixed soon. (But the 1/2/3/4 keyboard-
1350 based method is likely to still be the faster method.)
1351
1353 It's possible to go directly to the previous or next file (or tagged
1354 file) in the directory, or to tag a file, without having to pick the
1355 file from the file selector by hand. These commands are particularly
1356 useful when using xzgv from the keyboard, but there's also a notable
1357 mouse shortcut for moving to the next image.
1358 `Space'
1360 `Viewer menu, Next Image'
1361 Move to next file in dir, and view it. You can also click on the
1362 picture/viewer to do this. (If you find this interferes with
1363 dragging the picture around (though it shouldn't), or just don't
1364 like it, it can be disabled (see Config Variables).)
1365 `b'
1367 `Viewer menu, Previous Image'
1368 Move to previous file in dir, and view it.
1369 `Ctrl-Space'
1371 `Viewer menu, Tagging, Tag then Next'
1372 Tag current file, then move to next file in dir and view it.
1373 `/'
1375 `Viewer menu, Tagging, Next Tagged'
1376 Move to next tagged file in dir, and view it.
1377 `?'
1379 `Viewer menu, Tagging, Previous Tagged'
1380 Move to previous tagged file in dir, and view it.
1381
1383 When running on small screens, or in a small window, it can get a bit
1384 annoying to lose viewer space by having the selector constantly dis‐
1385 played when you don't actually need it. The usual solution to this
1386 problem is to enable auto-hide mode. But what if some pictures you're
1387 viewing are small and some large? It can sometimes be nearly as annoy‐
1388 ing having the selector hidden to `make room for' a small picture which
1389 didn't need it. So for that reason, or perhaps if you just don't like
1390 auto-hide mode :-), you may prefer to leave auto-hide off and explic‐
1391 itly hide the selector when necessary:
1392 `Z (shift-z)'
1394 `Viewer menu, Window, Hide Selector'
1395 Hide the selector. (This is actually a toggle, of sorts; `hide
1396 selector' when it's already hidden unhides it.)
1397 You can also hide or unhide the selector by middle-clicking on the
1399 viewer.
1400
1402 Generally it's easy enough to use your window manager to change windows
1403 etc., but when running fullscreen this can sometimes be a little prob‐
1404 lematic. For this reason, xzgv has built-in support for `iconifying'
1405 itself:
1406 `Ctrl-z'
1408 `Viewer menu, Window, Minimize'
1409 Minimize the xzgv window.
1410
1412 As with the selector, various options can be disabled/enabled which
1413 relate to the viewer.
1414 These settings can also be altered using command-line options (see
1416 Options) and/or config file settings (see Configuring xzgv).
1417 `z'
1419 `Viewer menu, Options, Zoom (fit to window)'
1420 Toggle zoom mode, discussed in more detail elsewhere (see Zoom
1421 Mode).
1422 `Alt-r'
1424 `Viewer menu, Options, When Zooming Reduce Only'
1425 Toggle reduce-only in zoom mode, also covered elsewhere (see
1426 Zoom Mode).
1427 `i'
1429 `Viewer menu, Options, Interpolate when Scaling'
1430 Toggle interpolation when a picture is being scaled-up. Again,
1431 this has already been mentioned (see Scaling).
1432 `Alt-c'
1434 `Viewer menu, Options, Ctl+Click Scales X Axis'
1435 Toggle the axis scaled when you control-click (or control-right-
1436 click) on the image. The default is to scale the y axis.
1437 `F (shift-f)'
1439 `Viewer menu, Options, Dither in 15 & 16-bit'
1440 Toggle dithering in 15/16-bit modes. This increases the apparent
1441 colour depth making gradations look much better, but it's slower
1442 than undithered rendering, and can (in 16-bit) slightly distort
1443 a picture's colour balance. (The `F' key was chosen for this as
1444 the dither toggle is functionally similar to zgv's `fakecols'
1445 toggle.)
1446 `Viewer menu, Options, Revert Scaling For New Pic'
1448 Normally xzgv returns the scaling back down to 1 (normal) when a
1449 new picture is selected. By disabling this, you can retain scal‐
1450 ing across picture selection. (There is currently no keyboard
1451 shortcut for this fairly-seldom-changed option --- to toggle it
1452 from the keyboard, you should use the popup menu (press `F10'),
1453 and select the menu item.)
1454 `Viewer menu, Options, Revert Orient. For New Pic'
1456 Similarly, xzgv returns to the picture's true orientation (not
1457 mirrored, rotated, etc.) on selecting a new picture. Disabling
1458 this option means that any mirrors/flips/rotates applied persist
1459 across multiple images. (No keyboard shortcut --- see above.)
1460 `Viewer menu, Options, Use Exif Orientation'
1462 Toggle support for Exif orientation. Devices which create JPEG
1463 files in the Exif format (e.g. many digital cameras) may add an
1464 orientation tag to the file, which says how the camera was being
1465 held when the picture was taken. When this tag is present, xzgv
1466 can adjust the image to compensate for a camera being held on
1467 its side. (This isn't done by default as it misrepresents the
1468 true image, which could be confusing if you don't know why it's
1469 happening.) Enabling this option may be useful if you take pic‐
1470 tures with your camera on its side, but don't want to have to
1471 rotate the pictures before being able to view them properly. Of
1472 course, for this to work your camera has to be inserting the
1473 orientation tag in the first place --- but it can't hurt to try
1474 it and see. (No keyboard shortcut --- see above.)
1475
1477 Picture files are stored in a variety of different forms, or `file for‐
1478 mats'. xzgv, via gdk, supports many.
1479
1481 The format a file is in is identified by its content. The file-reading
1482 code relies on libgdk to determine the file type and read the file cor‐
1483 rectly; generally this uses the format's `magic number' to determine
1484 file type --- e.g. a JPEG/JFIF file starts with the (hex) bytes `FF
1485 D8'. So if you start xzgv with xzgv foo, and foo is in a supported for‐
1486 mat (such as JPEG), the format will be figured out and the file loaded
1487 even though the `extension' is absent.
1488
1490 Many aspects of the way xzgv works can be modified by using a configu‐
1491 ration file.
1492
1494 A configuration file lets you alter aspects of xzgv's behaviour. xzgv
1495 supports two possible config files --- a system-wide one,
1496 /etc/xzgv.conf; and one for each user in their home directory,
1497 $HOME/.xzgvrc. Both are optional. If $HOME/.xzgvrc exists, it is used
1498 instead of /etc/xzgv.conf.
1499 Before describing the format of config files, it may help to give an
1501 example file:
1502 # Sample xzgv config file
1504 # Comment lines begin with `#' and are ignored,
1505 # as are blank lines.
1506 # make pics fit window
1508 zoom on
1509 # hog the screen :-)
1510 fullscreen on
1511 It is a line-based format. Each line (or rather, each line which is not
1513 a comment line and is not blank) assigns a value to a single predefined
1514 `variable'. xzgv has many such variables it lets you modify in this
1515 way. For example, the fullscreen option above controls whether or not
1516 xzgv tries to use the whole screen for its window. If it is given the
1517 value `on'/`y'/`yes'/`1' it does; if `off'/`n'/`no'/`0', it doesn't.
1518 Most variables are of this yes-or-no `boolean' type.
1519 Since the variables set in a config file have a direct effect on how
1521 xzgv works, it can be easier to simply call them `settings'. Indeed,
1522 such terminology is used on occasion in this documentation.
1523
1525 There are various types of variable:
1526 - Boolean. These are on-or-off, yes-or-no variables. Most of xzgv's
1528 config file variables are of this type.
1529 - Integer (currently unused). These are whole numbers. The meaning of
1531 the number depends on what the variable is used for.
1532 - Real (floating-point). This can be a whole number or a decimal frac‐
1534 tion. Only the gamma variable is of this type.
1535 - Geometry. This window size-and/or-position specification format is
1537 only used for the `geometry' setting. See Options, for a description of
1538 how this type works.
1539
1541 Currently, most configuration variables (settings) in xzgv can also be
1542 set by command-line options; indeed, the name of the setting in all
1543 such cases is identical to that for the long version of the option
1544 (e.g. `fullscreen', `auto-hide'). As such, they're documented in the
1545 section which discusses command-line options and the like (see
1546 Options).
1547 However, there are some settings only available in the config file:
1549 click-for-next
1551 This is enabled by default, allowing you to click on the viewer
1552 to skip to the next image. If disabled, clicking on the viewer
1553 does nothing.
1554
1556 Here I (RJM) attempt to explain why I did things the way I did. This is
1557 presented in a question-and-answer format of sorts.
1558
1560 Previously, this section concentrated on xv; that may have made sense
1561 when I originally wrote it, and still makes a certain limited amount of
1562 sense for zgv, but for xzgv it was looking increasingly dated. And so
1563 here I am writing an update. :-)
1564 I originally wrote xzgv as I simply wasn't happy with the viewers for X
1566 that I was aware of at the time (mid-1999). At the time of writing
1567 (late 2000), other key things about xzgv are becoming apparent, partly
1568 through responses I've been getting to it:
1569 o It's `fast'. No, it doesn't do any particular operation faster than
1571 other viewers as far as I know (well, maybe thumbnail updates :-));
1572 rather, the interface tries not to get in your way. Click on a file‐
1573 name, and the picture appears. No multiplicity of toolbars or windows,
1574 it's just there.
1575 o As with zgv, it tries to do one thing well, viewing pictures. It
1577 isn't perfect in this regard, I'll admit, but at least it stays well
1578 clear of picture editing.
1579 o It's, er, quite a lot like zgv. Some of us old fogies like this. :-)
1581 I won't pretend xzgv is The Ultimate Viewer For Everyone. Some people
1583 will prefer other approaches, or just simply prefer other viewers.
1584 (Some people may even still use xv, ghod forbid.) There are a few view‐
1585 ers which you may like to try if you don't think much of xzgv:
1586 o gqview. This seems to be well-regarded. I find it a bit gimmicky and
1588 kitchen-sink-ish; not quite as `pure' or focused as xzgv, IMHO. I think
1589 more people use it than xzgv though.
1590 o xli. I'm not sure if this is maintained these days, but it's not too
1592 bad a viewer. No thumbnails or file selector though. (These days I
1593 mostly use this for setting the root window pixmap, something I don't
1594 think belongs in a viewer, but which xli does happen to be quite good
1595 at.)
1596 o qiv. If I read between the lines correctly, this is essentially a
1598 modern replacement for xli.
1599 o gtksee. I've not tried this, but I think the idea is that it's an
1601 ACDSee clone, and there seem to be an awful lot of people who want a
1602 clone of that. Which is their problem. :^)
1603 o Electric Eyes. To be honest, I think this has been outclassed by
1605 other viewers these days, which shows how far we've come.
1606 Ah, you say, what of xv? Well, we've emphatically reached the point
1608 where no-one need use xv any more. Anyone using xv these days really
1609 should drop that pile of ill-conceived non-Free crap and use one of the
1610 better viewers now available. It's that simple.
1611
1613 It's a fscking viewer, dammit. If you want xv you know where to find
1614 it.
1615 (OTOH, if you want a decent image editor, use the Gimp.)
1617
1619 For years, I maintained a conventional `man page' for zgv (which xzgv
1620 was loosely based on). But over time, I realised just how impossibly
1621 confusing the zgv man page had become.
1622 So I wanted to rewrite zgv's documentation in a more sensible way, in
1624 some other format than a man page. I wanted an established, well-sup‐
1625 ported format with structure and cross-referencing. I felt this made it
1626 a choice between HTML and texinfo. HTML seemed to me to be a moving
1627 target like no other, and not as well supported on text-only terminals
1628 as Info (and thus texinfo). (This latter point is admittedly not too
1629 relevant as far as xzgv is concerned.) When I noticed that a converter
1630 existed to convert texinfo to HTML in any case, the case was closed.
1631 xzgv's documentation was then based on zgv's --- the documentation is
1632 probably more similar than the programs are. :-)
1633 Don't get me wrong --- I like man pages. And even with the excellent
1635 Texinfo documentation and Emacs' very helpful Texinfo mode, writing
1636 texinfo is hardly easy. (Without Texinfo mode's node- and menu-update
1637 commands, I personally would find it near-impossible!) But big man
1638 pages just aren't that good for reference, and this is made worse by
1639 the relative lack of structure.
1640
1642 The conventional way to write texinfo is to follow each sentence with
1643 two spaces after the dot (or whatever ends the sentence). Many people
1644 normally write this way in a non-texinfo context too. But a sizeable
1645 proportion of people normally write text with only one space after the
1646 dot --- and I'm one of them.
1647 The Texinfo documentation gives the impression that two-space must be
1649 used; it says ``it is important to put two spaces at the end of sen‐
1650 tences in Texinfo documents.'' But the only circumstance in which spac‐
1651 ing from the texinfo file is preserved at all (in any sense other than
1652 `there is a space here') is when the texinfo is converted to Info for‐
1653 mat. So, in fact, the decision to use two-space depends on how the
1654 author wants Info output to appear --- this is a subjective decision
1655 which should be entirely down to the preference of the author, despite
1656 the Texinfo documentation's attempt to make two-space sound like an
1657 objective you-must-do-this kind of thing.
1658 You might wonder what the problem with using one-space is, then. Well,
1660 `makeinfo' has to reformat paragraphs, and whenever it needs to insert
1661 space at (what appears to it to be) the end of a sentence, it inserts
1662 two spaces. This behaviour cannot be altered, unlike in Emacs (sen‐
1663 tence-end-double-space; see Fill Commands in the emacs info file) and
1664 GNU fmt (-u; see fmt invocation in the textutils info file). Also,
1665 attempting to `fix' the output Info with sed doesn't work properly
1666 because the `tags' used to find nodes quickly are then incorrect. These
1667 could of course also be fixed, but this would involve a lot more work
1668 than a simple sed invocation.
1669 So realistically, anyone who writes texinfo with one-space has to put
1671 up with the occasional two-space sentence end being inserted into their
1672 text --- worse still, the current `makeinfo' formatting algorithm seems
1673 to insert two spaces even after abbreviations (such as `e.g.' and
1674 `etc.'), which breaks even two-space texinfo. (This is particularly
1675 ironic, by the way, since two-space partisans' main argument in favour
1676 of the practice is often the way it makes it possible to tell the dif‐
1677 ference between abbreviations and the end of a sentence.)
1678 One last point may be worth noting; I am not the first person to write
1680 texinfo files using one-space. At the time of writing, it is used in
1681 the texinfo documentation for BFD, gdbm, GTK/GDK, (Linux) IPC, and
1682 viper, and I expect there are instances I'm not aware of.
1683
1685 All (non-trivial) programs have bugs. Anyone who denies this...
1686 - clearly hasn't written too many programs.
1688 - is wrong. ;-)
1690 It follows that xzgv, like everything else, always has some bugs. Usu‐
1692 ally these are not too serious, or I'd have fixed them before releasing
1693 xzgv. But either way, bugs and other problems with xzgv are noted here.
1694
1696 - In zoom mode, it copes with resizing the window as a whole, but
1697 doesn't when you change the size of the pane (apart from when hid‐
1698 ing/showing selector or resizing from keyboard, but that's only 'cos I
1699 kludged it :-)).
1700 - When scaling up and dithering, you end up with a crappy-looking pic‐
1702 ture if you drag the picture around slowly (since each exposed bit is
1703 dithered independently, with no regard given to matching up to any pre‐
1704 vious error-diffusion).
1705 - Scaling up is slow. Not sure if I can do much about this.
1707 - Using an alignment widget to centre the viewer window results in some
1709 annoying `bounce' in certain resizing situations etc.
1710 - Thumbnails don't look so great in palette-based (e.g. 8-bit) modes.
1712 - When dragging an image around, if you quickly move the mouse pointer
1714 over from the image area to the selector area, the image seems to
1715 `jump' a little. I think this may have something to do with the paned
1716 window's window-splitting bit, but I'm not sure. Also, it jumps when
1717 moving across scrollbar sliders and the paned window splitter handle.
1718 - It doesn't apply any tranparency mask. The practical result of this
1720 seems to be purple transparent bits in thumbnails and scaled-up images,
1721 and black transparent bits elsewhere. This doesn't affect PNG files,
1722 though.
1723 - If a GIF file is corrupted in such a way that the decompressed image
1725 has a larger number of pixels in it, the extra pixels will be ignored
1726 and no error or warning will be generated.
1727 - If you look up `joe code' in a dictionary, right next to ``see zgv''
1729 it now says ``but for really in-depth insight into the joe code nature,
1730 see xzgv''. :-)
1731
1733 - Thumbnails are given an accurate width/height `IMGINFO' comment, but
1734 are always claimed to be "RGB".
1735 - xzgv doesn't duplicate zgv's behaviour of generating thumbnails under
1737 ~/.xvpics/_foo_bar_baz if it can't generate them in
1738 /foo/bar/baz/.xvpics. I doubt anything else supported it, and it com‐
1739 plicated lots of things unnecessarily. This isn't particularly subopti‐
1740 mal, but as an incompatibility with zgv it merits mention.
1741
1743 - Only the first image of a multiple-image GIF is used. (These days,
1744 multiple-image GIFs are usually animations.)
1745
1747 If you find xzgv does something wrong, which you suspect might be a
1748 fault of some sort (a bug) in the program, it is best to report it as I
1749 may not be aware of the problem. (But first, check it is not a `known
1750 bug'. See Known Bugs. It is not usually helpful to report a bug I
1751 already know about.)
1752 It is important to include as much detail in a bug report as you can.
1754 Here are some details you should include:
1755 o The version of xzgv you are running. `xzgv --version' reports this.
1757 o The versions of GTK+ you are using. `xzgv --version-gtk' reports the
1759 GTK+ version being used by xzgv.
1760 o The bitdepth your X server is running in (common depths are 8-bit
1762 (256 colours), 15-bit, 16-bit, 24-bit, and 32-bit). If you don't know
1763 what depth you're running in, try `xdpyinfo|grep depth'.
1764 o A description of the bug --- what effects it has, the circumstances
1766 it occurs in, and so on. Does it only happen for certain types of file?
1767 Only when in 8-bit modes? Only when dithering is enabled? Even `irrele‐
1768 vant' details can sometimes be useful.
1769 o Finally, if you are a programmer and believe you have managed to fix
1771 the bug yourself, patches are gratefully accepted. :-) You should gen‐
1772 erate the patch using `diff -c' or (preferably) `diff -u'.
1773 So, if you think you've found a bug in xzgv, report it by emailing me
1775 at <rrt@sc3d.org>.
1776
1778 Bugs in the documentation can sometimes cause as much trouble as bugs
1779 in the program; if you notice a problem in the documentation, it's a
1780 good idea to report it.
1781 For reports of documentation bugs, you should include these details:
1783 o The version of xzgv the documentation is for.
1785 o If it is a problem in one specific section of the documentation,
1787 specify which part it is (by this I mean the heading it comes under;
1788 texinfophiles should read this as `the node name' :-)).
1789 o The format of the documentation you saw the problem in (e.g. info,
1791 man page, HTML).
1792 o A description of the problem.
1794
1796 See Reporting Bugs, for details of where to send the bug report. If
1797 you want to suggest a feature you'd like in xzgv, or a change to an
1798 existing feature, contact me at <rus@svgalib.org>.
1799 xzgv is rather a moving target at the moment, so for now future changes
1801 etc. are only listed in the TODO file. Normal service will be resumed
1802 once things settle down a bit. :-)
1803
1805 Russell Marks <rus@svgalib.org> and others; see the section ACKNOWL‐
1806 EDGEMENTS for details.
1807
1809 zgv(1), xv(1), cjpeg(1), djpeg(1), pbm(5), pgm(5), ppm(5), mrf(5)
1810Version 0.9 9th September 2007 XZGV(1)