vncviewer(1) Virtual Network Computing vncviewer(1)NAMEvncviewer - VNC viewer for X
SYNOPSISvncviewer [options] [host][:display#]
vncviewer [options] -listen [display#]
DESCRIPTIONvncviewer is a viewer (client) for Virtual Network Computing. This
manual page documents the version for the X window system.
If you run the viewer with no arguments it will prompt you for a VNC
server to connect to. Alternatively, specify the VNC server as an
argument, e.g.:
vncviewer snoopy:2
where 'snoopy' is the name of the machine, and '2' is the display num‐
ber of the VNC server on that machine. Either the machine name or dis‐
play number can be omitted. So for example ":1" means display number 1
on the same machine, and "snoopy" means "snoopy:0" i.e. display 0 on
machine "snoopy".
If the VNC server is successfully contacted, you will be prompted for a
password to authenticate you. If the password is correct, a window
will appear showing the desktop of the VNC server.
AUTOMATIC PROTOCOL SELECTION
From version 3.3.4 onwards, the viewer tests the speed of the connec‐
tion to the server and chooses the encoding and pixel format appropri‐
ately. This makes it much easier to use than previous versions where
the user had to specify arcane command line arguments.
The viewer starts out assuming the link is slow, using an 8-bit pixel
format and using the encoding with the best compression. If it turns
out that the link is fast enough it switches to full-colour mode and
will use an encoding which compresses less but is faster to generate,
thus improving the interactive feel. Automatic selection can be turned
off with the -noauto option, or from the popup window.
POPUP WINDOW
The viewer has a popup window containing a set of buttons which perform
various actions. It is usually brought up by pressing F8, but this is
customisable, as is the entire contents of the popup. Actions which
buttons in the popup window can perform include:
* switching in and out of full-screen mode
* quitting the viewer
* generating arbitrary key and mouse events, e.g. sending ctrl-alt-
del
* transferring the clipboard to or from the VNC server
* switching on or off automatic selection of encoding and pixel for‐
mat
* switching 8-bit mode on or off
By default, key presses in the popup window get sent to the VNC server
and dismiss the popup. So to get an F8 through to the VNC server sim‐
ply press it twice.
See the sections on customisation below for how to customise the con‐
tents of the popup window.
FULL SCREEN MODE
A full-screen mode is supported. This is particularly useful when con‐
necting to a remote screen which is the same size as your local one. If
the remote screen is bigger, you can scroll by bumping the mouse
against the edge of the screen.
Unfortunately this mode doesn't work completely with all window man‐
agers, since it breaks all the X window management conventions. It
tends to work better when the viewer is started in full-screen mode
than when switching to it from normal mode.
OPTIONS
You can get a list of options by giving -h as an option to vncviewer.
Most of these options can also be specified as X resources - see the
section on customisation below.
-via Xgateway
Makes the connection go though SSH to a gateway host. The gate‐
way should be the target host for best connection secrecy.
-listen [display-number]
Causes vncviewer to listen on port 5500 + display-number for
reverse connections from a VNC server. WinVNC supports reverse
connections initiated using the 'Add New Client' menu option or
the '-connect' command-line option. Xvnc supports reverse con‐
nections with a helper program called vncconnect.
-shared
When you make a connection to a VNC server, all other existing
connections are normally closed. This option requests that they
be left open, allowing you to share the desktop with someone
already using it.
-display Xdisplay
Specifies the X display on which the VNC viewer window should
appear.
-passwd password-file
If you are on a filesystem which gives you access to the pass‐
word file used by the server, you can specify it here to avoid
typing it in. It will usually be "~/.vnc/passwd".
-viewonly
Specifies that no keyboard or mouse events should be sent to the
server. Useful if you want to view a desktop without interfer‐
ing; often needs to be combined with -shared.
-fullscreen
Start in full-screen mode.
-geometry geometry
Standard X position and sizing specification.
-noauto
Turn off the automatic selection of encoding and pixel format.
Normally the viewer tests the speed of the connection to the
server and chooses the encoding and pixel format appropriately.
-8bit, -bgr233
This option implies -noauto. Tells the VNC server to send pix‐
els which are only 8 bits deep. If your server desktop is
deeper than this then it will translate the pixels before send‐
ing them. Less data will generally be sent over then network,
which can be a big advantage on slow links, but you may get some
colour mismatches. "BGR233" means an 8-bit true colour pixel
format, with the most significant two bits of each byte repre‐
senting the blue component, the next three bits representing
green and the least significant three representing red. This
format is also used by the java client.
-encodings encodings
This option implies -noauto. This option specifies a list of
encodings to use in order of preference, separated by spaces.
For example, to use only raw and CopyRect, specify "raw copy‐
rect".
-owncmap
Try to use a PseudoColor visual and a private colormap - this
allows the VNC server to control the colormap.
-truecolour
Try to use a TrueColor visual.
-depth d
This is only useful on a (real) X server which supports multiple
TrueColor depths. On such a display vncviewer will try to find
a Visual of the given depth. If successful this means that the
appropriate pixel format will be requested from the VNC server.
You cannot use this to force a particular depth from the VNC
server. The only option which does this is -bgr233.
CUSTOMISATION
The behaviour of vncviewer is extremely customisable using X resources.
You can set X resources by any of the usual means - in an app-defaults
file such as ".Xresources", or on the command line with the -xrm
option, e.g.:
vncviewer-xrm '*nColours:64'
See the X window system documentation for details.
The application resources are:
shareDesktop (option -shared)
Whether to leave other viewers connected. Default false.
viewOnly (option -viewonly)
Block mouse and keyboard events. Default false.
fullScreen (option -fullscreen)
Full screen mode. Default false.
passwordFile (option -passwd)
File from which to get the password (as generated by the vnc‐
passwd program). Default is null, i.e. to request password from
the user.
passwordDialog
Whether to use a dialog box to get the password (true) or get it
from the tty (false). Irrelevant if passwordFile is set.
Default false.
autoDetect (option -noauto turns off)
Whether to automatically select encoding and pixel format based
on the speed of the connection to the server. Default true.
encodings (option -encodings)
A list of encodings to use in order of preference, separated by
spaces. Default is null.
useBGR233 (option -8bit or -bgr233)
Always use the BGR233 (8-bit) pixel format on the wire, regard‐
less of the visual. Default is false, although autoDetect may
choose BGR233 anyway, and BGR233 is always used for non-True‐
Color visuals with forceOwnCmap false.
nColours
When using BGR233, try to allocate this many "exact" colours
from the BGR233 colour cube. When using a shared colormap, set‐
ting this resource lower leaves more colours for other X
clients. Irrelevant when using truecolour. Default is 256
(i.e. all of them).
useSharedColours
If the number of "exact" BGR233 colours successfully allocated
is less than 256 then the rest are filled in using the "nearest"
colours available. This resource says whether to only use the
"exact" BGR233 colours for this purpose, or whether to use other
clients' "shared" colours as well. Default true (i.e. use other
clients' colours).
forceOwnCmap (option -owncmap)
Try to use a PseudoColor visual and a private colormap - this
allows the VNC server to control the colormap. Default false.
forceTrueColour (option -truecolour)
Try to use a TrueColor visual. Default false.
requestedDepth (option -depth)
If forceTrueColour is true, try to use a visual of this depth.
Default 0 (i.e. any depth).
useSharedMemory
Whether to use the MIT shared memory extension if on the same
machine as the X server. Default true.
wmDecorationWidth, wmDecorationHeight
The total width and height taken up by window manager decora‐
tions. This is used to calculate the maximum size of the VNC
viewer window. Default is width 4, height 24.
bumpScrollTime, bumpScrollPixels
When in full screen mode and the VNC desktop is bigger than the
X display, scrolling happens whenever the mouse hits the edge of
the screen. The maximum speed of scrolling is bumpScrollPixels
pixels every bumpScrollTime milliseconds. The actual speed of
scrolling will be slower than this, of course, depending on how
fast your machine is. Default 20 pixels every 25 milliseconds.
popupButtonCount
The number of buttons in the popup window. See below for how to
customise the buttons.
rawDelay
This is useful for debugging VNC servers by checking exactly
which parts of the screen are being updated. For each update
rectangle vncviewer puts up a black rectangle for the given time
in milliseconds before putting up the pixel data. This only
highlights pixel data sent using the raw encoding. Default 0
(i.e. don't do it).
copyRectDelay
Similar to rawDelay, but highlights the areas copied using the
copyrect encoding.
CUSTOMISING THE POPUP WINDOW
Set the number of buttons with the popupButtonCount resource, e.g.:
*popupButtonCount: 2
For each button, set the label, and override the button press transla‐
tions, e.g.:
*popup*button1.label: Left mouse button click at 100,100
*popup*button1.translations: #override\n\
<Btn1Down>,<Btn1Up>: SendRFBEvent(ptr,100,100,1)\
SendRFBEvent(ptr,100,100,0)
*popup*button2.label: Send "Think thin!"
*popup*button2.translations: #override\n\
<Btn1Down>,<Btn1Up>:\
SendRFBEvent(key,T) SendRFBEvent(key,h)\
SendRFBEvent(key,i) SendRFBEvent(key,n)\
SendRFBEvent(key,k) SendRFBEvent(key,space)\
SendRFBEvent(key,t) SendRFBEvent(key,h)\
SendRFBEvent(key,i) SendRFBEvent(key,n)\
SendRFBEvent(key,exclam)
CUSTOMISING THE DESKTOP WINDOW
You can override translations on the desktop window. For example to
change the key used to bring up to popup window from F8 to Escape, and
make F12 switch in and out of full screen mode:
*desktop.translations: #override\n\
<Key>F8: SendRFBEvent()\n\
<Key>Escape: ShowPopup()\n\
<Key>F12: ToggleFullScreen()
X RESOURCE ACTIONS
These are the actions which you can use in X resource translations:
ShowPopup(), HidePopup()
Show and hide the popup window, respectively.
SendRFBEvent()
Send an RFB event to the VNC server. With no argument, simply sends
the RFB equivalent of the X event which caused the action. With
arguments, generates either key or pointer events depending on the
arguments:
SendRFBEvent(keydown,keysym)
SendRFBEvent(keyup,keysym)
SendRFBEvent(key,keysym) (short for keydown then keyup)
SendRFBEvent(ptr,x,y,buttonMask)
SendRFBEvent(ptr,buttonMask)
where
* keysym is the string representing an X keysym. The best way to
find these is to use "xev", or look in
/usr/include/X11/keysymdef.h and strip off the "XK_".
* x and y are the position of the pointer event. If not specified,
use the position of the X event which caused the action.
* buttonMask is a bit mask representing buttons 1 to 8 with bits 0
to 7 respectively, 0 meaning up, 1 meaning down (pressed). So 0
means no buttons, 1 means button 1 pressed, 5 means buttons 1 & 3
pressed, etc.
SelectionToVNC()
Send the local X selection or cut buffer to the VNC server. This is
usually invoked when the mouse enters the viewer window. With no
argument or an argument "new", this is only done if this is a "new"
selection, i.e. it hasn't already been sent. With an argument
"always", it is sent each time.
SelectionFromVNC()
Set the local X selection and cut buffer to the current value of the
VNC server "cut text". This is usually invoked when the mouse
leaves the viewer window. With no argument or an argument "new",
this is only done if there has been new "cut text" since the last
time it was called. With an argument "always", it is set each time.
Quit()
Quit the VNC viewer.
Pause()
Pause for a given number of milliseconds (100 by default). This is
sometimes useful to space out events generated by SendRFBEvent.
ToggleFullScreen()
Toggle in and out of full screen mode.
SetFullScreenState()
Sets the "state" resource of a toggle widget to reflect whether
we're in full screen mode.
ToggleBGR233()
Toggle 8-bit (BGR233) mode.
SetBGR233State()
Sets the "state" resource of a toggle widget to reflect whether
we're in 8-bit mode.
ToggleAuto()
Toggle automatic selection of encoding and format.
SetAutoState()
Sets the "state" resource of a toggle widget to reflect whether the
viewer is automatically selecting encoding and format.
ServerDialogDone(), PasswordDialogDone()
Used to tell the dialog boxes that entry has finished. Usually
invoked by the return key.
BUGSvncviewer uses the original X11 Athena widget set which is a little bit
out of date. On the plus side it is available in every installation of
the X window system.
SEE ALSOvncconnect(1), vncpasswd(1), vncserver(1), Xvnc(1)
http://www.realvnc.com
AUTHOR
Tristan Richardson, RealVNC Ltd.
VNC was originally developed by the RealVNC team while at Olivetti
Research Ltd / AT&T Laboratories Cambridge. It is now being maintained
by RealVNC Ltd. See http://www.realvnc.com for details.
RealVNC Ltd 15 August 2002 vncviewer(1)