vncviewer(1)

NAME

vncviewer - VNC viewer for X

SYNOPSIS

vncviewer [options] [host][:display#]
vncviewer [options] -listen [display#]

DESCRIPTION

vncviewer is a viewer (client) for Virtual Network Comput

ing. 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 number of the VNC server on that machine. Either the ma

chine name or display 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 connection to the server and chooses the encoding and pixel

format appropriately. This makes it much easier to use than pre

vious 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 compres

sion. 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 op

tion, 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 per

form include:

* switching in and out of full-screen mode

* quitting the viewer

* generating arbitrary key and mouse events, e.g. send

ing ctrl-alt-del

* transferring the clipboard to or from the VNC server

* switching on or off automatic selection of encoding

and pixel format

* 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 simply press it twice.

See the sections on customisation below for how to cus

tomise the contents of the popup window.

FULL SCREEN MODE

A full-screen mode is supported. This is particularly

useful when connecting 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 managers, since it breaks all the X window management con

ventions. 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 re

sources - see the section on customisation below.

-via Xgateway

Makes the connection go though SSH to a gateway

host. The gateway 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 connections 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 re

quests 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 password 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 interfering; 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 connec

tion to the server and chooses the encoding and pixel format ap

propriately.

-8bit, -bgr233

This option implies -noauto. Tells the VNC server

to send pixels which are only 8 bits deep. If your server desk

top is deeper than this then it will translate the pixels before

sending 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

copyrect".

-owncmap

Try to use a PseudoColor visual and a private col

ormap - 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 sup

ports 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 vncpasswd 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 password

File 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. De

fault 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, regardless of the visual. Default is false, although au

toDetect may choose BGR233 anyway, and BGR233 is always used for

non-TrueColor visuals with forceOwnCmap false.

nColours

When using BGR233, try to allocate this many "ex

act" colours from the BGR233 colour cube. When using a shared

colormap, setting 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 successful

ly 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 col

ormap - this allows the VNC server to control the colormap. De

fault 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 man

ager decorations. 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 be

low for how to customise the buttons.

rawDelay

This is useful for debugging VNC servers by check

ing 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. De

fault 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 re

source, e.g.:

*popupButtonCount: 2

For each button, set the label, and override the button

press translations, e.g.:

*popup*button1.label: Left mouse button click at 100,100
*popup*button1.translations: #override

<Btn1Down>,<Btn1Up>: SendRFBEvent(ptr,100,100,1)

SendRFBEvent(ptr,100,100,0)

*popup*button2.label: Send "Think thin!"
*popup*button2.translations: #override

<Btn1Down>,<Btn1Up>: SendRFBEvent(key,T) SendRF

BEvent(key,h) SendRFBEvent(key,i) SendRFBEvent(key,n)

SendRFBEvent(key,k) SendRFBEvent(key,space) SendRF

BEvent(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 <Key>F8:

SendRFBEvent() <Key>Escape: ShowPopup()

<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/in

clude/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 argu

ment "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 de

fault). 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 for

mat.

ServerDialogDone(), PasswordDialogDone()

Used to tell the dialog boxes that entry has finished.

Usually invoked by the return key.

BUGS

vncviewer 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 ALSO

vncconnect(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)