XV: Modifying xv Behavior, part 1/4

# Modifying xv Behavior

xv supports literally dozens of command line options and X11 resources. Fortunately, it is doubtful that you'll ever need to use more than a small few. The rest are provided mainly for that 'one special case' application of xv... Note that you do not have to specify the entire option name, only enough characters to uniquely identify the option. Thus, '`-geom`' is a fine abbreviation of '`-geometry`'.

## Command Line Options Overview

If you start xv with the command '`xv -help`', the current (wildly out of control) list of options will be displayed:

> `xv [-] [-/+24] [-/+2xlimit] [-/+4x3] [-/+8] [-/+acrop] [-aspect w:h] [-best24] [-bg color] [-black color] [-bw width] [-/+cecmap] [-cegeometry geom] [-/+cemap] [-cgamma rval gval bval] [-cgeometry geom] [-/+clear] [-/+close] [-/+cmap] [-cmtgeometry geom] [-/+cmtmap] [-crop x y w h] [-cursor char#] [-DEBUG level] [-dir directory] [-display disp] [-/+dither] [-drift dx dy] [-expand exp | hexp:vexp] [-fg color] [-/+fixed] [-flist fname] [-gamma val] [-geometry geom] [-grabdelay seconds] [-gsdev str] [-gsgeom geom] [-gsres int] [-help] [-/+hflip] [-hi color] [-/+hist] [-/+hsv] [-icgeometry geom] [-/+iconic] [-igeometry geom] [-/+imap] [-/+lbrowse] [-lo color] [-/+loadclear] [-/+max] [-/+maxpect] [-mfn font] [-/+mono] [-name str] [-ncols #] [-/+ninstall] [-/+nodecor] [-/+nofreecols] [-/+nolimits] [-/+nopos] [-/+noqcheck] [-/+noresetroot] [-/+norm] [-/+nostat] [-/+owncmap] [-/+perfect] [-/+poll] [-preset #] [-quick24] [-/+quit] [-/+random] [-/+raw] [-rbg color] [-rfg color] [-/+rgb] [-RM] [-rmode #] [-/+root] [-rotate deg] [-/+rv] [-/+rw] [-slow24] [-/+smooth] [-/+stdcmap] [-tgeometry geom] [-/+vflip] [-/+viewonly] [-visual type] [-/+vsdisable] [-vsgeometry geom] [-/+vsmap] [-/+vsperfect] [-wait seconds] [-white color] [-/+wloop] [filename ...]`

Yes, as a matter of fact, I am a little embarrassed about it.

One big change starting in xv 3.10: In the past, most of the command-line options were toggles, in that they would normally turn some feature on, but if you had an X resource that also turned that feature on, then they would turn that feature off. Now, they are absolute settings. For instance, '`-rv'` turns on reverse video mode, regardless of the setting of the '`xv.reverse'` resource, and '`+rv'` turns off reverse video mode, regardless of the setting of the '`xv.reverse'` resource. (Thanks Peder!)

## General Options

Note: In the following sections, the part of the option name shown in boldface is the shortest allowable abbreviation of the option in question.

-he`lp`
  Print usage instructions, listing the current available command-line options. Any unrecognized option will do this as well.
-dis`play` disp
  Specifies the display that xv should attempt to connect to. If you don't specify a display, xv will use the environment variable `$DISPLAY` .
-fg color
  Sets the foreground color used by the windows.
  (Resource name: `foreground` . Type: string)
-bg color
  Sets the background color used by the windows.
  (Resource name: `background` . Type: string)
-hi color
  Sets the highlight color used for the top-left edges of the control buttons.
  (Resource name: `highlight` . Type: string)
-lo color
  Sets the lowlight color used for the bottom-right edges of the control buttons, and also the background of some windows.
  (Resource name: `lowlight` . Type: string)
-bw bwidth
  Sets the width of the border on the windows. Your window manager may choose to ignore this, however.
  (Resource name: `borderWidth` . Type: integer)

## Image Sizing Options

-ge`ometry` geom
  Lets you specify the size and placement of the 'image' window. It's most useful when you only specify a position, and let xv choose the size. If you specify a size as well, xv will create a window of that size, unless `-fixed` is specified. The geom argument is in the form of a normal X geometry string (e.g. "300x240" or "+10+10" or "400x300+10+10")
  (Resource name: `geometry` . Type: string)
-/+fi`xed`
  Only used in conjunction with the `-geometry` option. If you specify a window size with the `-geometry` option, xv will normally stretch the picture to exactly that size. This is not always desirable, as it may seriously distort the aspect ratio of the picture. Specifying the `-fixed` option corrects this behavior by instructing xv to use the specified geometry size as a maximum window size. It will preserve the original aspect ratio of the picture. ( `+fixed` turns off this feature, forcing the image to be exactly the size specified by the `-geometry` option.)

  For example, if you give a rectangular geometry of '320x240', and you try to display a square picture with a size of '256x256', the window opened will actually be '240x240', which is the largest square that still fits in the '320x240' rectangle that was specified.

  (Resource name: `fixed` . Type: boolean)

-e`xpand` exp
  Lets you specify an initial expansion or compression factor for the picture. You can specify floating-point values. Values larger than zero multiply the picture's dimensions by the given factor. (i.e., an expand factor of '3' will make a 320x200 image display as 960x600).

  Factors less than zero are treated as reciprocals. (i.e., an expand factor of '-4' makes the picture 1/4 th its normal size.). '0' is not a valid expansion factor.

  You can also specify a pair of expansion values, separated by a colon, to set different horizontal and vertical expansion ratios. For instance, '3:2' would expand images 3x horizontally, and 2x vertically.

  (Resource name: `expand` . Type: string)

-as`pect` w:h
  Lets you set an initial aspect ratio, and also sets the value used by the Aspect command. The aspect ratio of nearly every X display (and, in fact, any civilized graphics display) is 1:1. What this means is that pixels appear to be 'square'. A 100 pixel wide by 100 pixel high box will appear on the screen as a square. Unfortunately, this is not the case with some screens and digitizers. The `-aspect` option lets you stretch the picture so that the picture appears correctly on your display. Unlike the other size- related options, this one doesn't care what the size of the overall picture is. It operates on a pixel-by-pixel basis, stretching each image pixel slightly, in either width or height, depending on the ratio.

  Aspect ratios greater than '1:1' (e.g., '4:3') make the picture wider than normal. Aspect ratios less than '1:1' (e.g. '2:3') make the picture taller than normal. (Useful aspect ratio: A 512x480 image that was supposed to fill a standard 4x3 video screen (produced by many video digitizers) should be displayed with an aspect ratio of '5:4')

  (Resource name: `aspect` . Type: string)

## Color Allocation Options

-nc`ols` nc
  Sets the maximum number of colors that xv will use. By default, this is 'as many as it can get'. However, you can set this to smaller values for interesting effect. If you set it to '0', it will display the picture by dithering with 'black' and 'white'. (The actual colors used can be set by the `- black` and `-white` options, below.)

  The other major use of this option is to limit the number of colors used when putting up an image that's going to be hanging around for a while. (i.e., an image in the root window) You may want to limit the number of colors used for such images so that other programs will still have some colorcells available for their own use.

  (Resource name: `ncols` . Type: integer)

-/+rw
  Tells xv to use read/write color cells. Normally, xv allocates colors read- only, which allows it to share colors with other programs. If you use read/write color cells, no other program can use the colors that xv is using, and vice-versa. The major reason to do such a thing is that using read/write color cells allows the Apply function in the xv color editor window to operate much faster. ( `+rw` forces xv to use read-only color, the default)

  (Resource name: `rwColor` . Type: boolean)

-/+pe`rfect`
  Makes xv try 'extra hard' to get all the colors it wants. In particular, when `-perfect` is specified, xv will allocate and install its own colormap if (and only if) it was unable to allocate all the desired colors. This option is not allowed in conjunction with the `-root` option.

  (Resource name: `perfect` . Type: boolean)

-/+o`wncmap`
  Like '`-perfect'`, only this option forces xv to always allocate and install its own colormap, thereby leaving the default colormap untouched.

  (Resource name: `ownCmap` . Type: boolean)

-/+st`dcmap`
  Puts xv into Use Std. Colormap mode. All images will be shown dithered using the same set of colors. This lets you run multiple copies of xv to display multiple images simultaneously, and still have enough colors to go around.

  (Resource name: `useStdCmap` . Type: boolean)

-/+cec`map`
  Specifies whether xv installs the image's colormap in the xv color editor window, as well as in the image's window. By default, the program does not install the colormap in the color editor window, as this often makes the color editor window unreadable. Note, however that the Colormap Editor tool will be appear somewhat misleading. (This option only applies when the '`-perfect'` or '`-owncmap'` options create their own colormaps.)

  (Resource name: `ceditColorMap` . Type boolean)

-/+ni`nstall`
  Prevents xv from 'installing' its own colormap, when the `-perfect` or `-owncmap` options are in effect. Instead of installing the colormap, it will merely 'ask the window manager, nicely' to take care of it. This is the correct way to install a colormap (i.e., ask the WM to do it), unfortunately, it doesn't actually seem to work in many window managers, so the default behavior is for xv to handle installation itself. However, this has been seen to annoy one window manager (dxwm), so this option is provided if your WM doesn't like programs installing their own colormaps.

  (Resource name: `ninstall` . Type: boolean)