TightVNC Viewer version 1.3.10
Xt-based VNC viewer
=======================================================================
This distribution is based on the standard VNC source and includes new
TightVNC-specific features and fixes, such as additional low-bandwidth
optimizations, major GUI improvements, and more.
Copyright (C) 1999 AT&T Laboratories Cambridge.
Copyright (C) 2000 Tridia Corp.
Copyright (C) 2002-2003 RealVNC Ltd.
Copyright (C) 2001-2004 HorizonLive.com, Inc.
Copyright (C) 2000-2006 Constantin Kaplinsky
Copyright (C) 2000-2009 TightVNC Group
All rights reserved.
This software is distributed under the GNU General Public Licence as published
by the Free Software Foundation.
Features
--------
* Xt-based, so it's a better behaved X application (sets window class, etc).
* Can be customised through X resources instead of awkward command-line options
(of course there are still command-line options for common cases).
* Specifying the VNC server to connect to can be done either on the
command-line as before, or with a dialog window. Either the host 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".
* The password can be entered in a dialog window, or taken from the tty, or a
password file.
* A full-screen mode with "bump scrolling" is supported. This doesn't work
completely with all window managers, since it breaks all the rules of the
ICCCM. It tends to work better when the viewer is started in full-screen
mode than when switching to it from normal mode.
* Supports the PRIMARY selection as well as the cut buffer. The selection is
normally transferred to and from the VNC server when the mouse enters or
leaves the viewer window. This behaviour is customisable through resources.
Note that at the time of writing Xvnc still only supports the cut buffer.
* 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 selection to or from the VNC server
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.
* Although still single-threaded, it behaves much like a multi-threaded client.
The main thread of the program just dispatches VNC protocol messages. X
events are automatically processed whenever reading from the VNC connection
would block.
So for example, over a slow link, key and mouse presses are sent to the
server even when drawing a screen update. Previously they would only have
been sent at the end of the update. In some cases this can save time by
skipping intermediate screen states.
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 '*passwordDialog: true'.
The file Vncviewer contains the same resource settings as the "fallback
resources" embedded in the executable. You can copy this file into
/usr/lib/X11/app-defaults (or equivalent) and edit it for site-wide
customisations.
The application resources are:
shareDesktop (options -shared/-noshared)
Whether to leave other viewers connected. Default true.
viewOnly (option -viewonly)
Block mouse and keyboard events. Default false.
fullScreen (option -fullscreen)
Full screen mode. Default false.
grabKeyboard
Grab keyboard in full screen mode. This can help to solve problems with
losing keyboard focus. Default false.
raiseOnBeep (option -noraiseonbeep)
Raise viewer window on remote beep (bell) event.
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.
This option affects only the standard VNC authentication.
userLogin (option -user)
User name for Unix login authentication. Default is null, i.e. to use
current user name. If this option is set, the viewer will prefer Unix
login authentication over the standard VNC authentication.
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.
encodings (option -encodings)
A list of encodings to use in order of preference, separated by spaces.
Default is null, which actually means "copyrect hextile corre rre", or "raw
copyrect hextile corre rre" for a VNC server on the same machine.
compressLevel (option -compresslevel)
Compression level for Zlib and Tight encodings in the range 0..9,
where 1 is fast compression, 9 is best compression (value 0 should
not be used).
qualityLevel (option -quality)
Image quality level for JPEG compression in Tight encoding in the
range 0..9 where 0 is worst image quality and best compression,
and 9 is good image quality and worse compression. Default 6.
enableJPEG (option -nojpeg)
Request JPEG compression in Tight encoding. Default true.
useRemoteCursor (option -nocursorshape)
Use cursor shape updates to track remote mouse cursor locally on
the viewer side. Default true.
useBGR233 (option -bgr233)
Always use the BGR233 (8-bit) pixel format on the wire, regardless of the
visual. Default is false (though BGR233 is used anyway for non-TrueColor
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, 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 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 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 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.
How to customise 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 translations,
e.g.:
*popup*button1.label: Send 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)
How to customise 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()
Actions
-------
These are the actions which you can use in 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 events depending on the arguments:
SendRFBEvent(fbupdate)
SendRFBEvent(keydown,<keysym>)
SendRFBEvent(keyup,<keysym>)
SendRFBEvent(key,<keysym>) (short for keydown followed by 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.
RunCommand(arg1,...)
Run a command or program. The first argument is the name of the
command. Additional arguments are arguments to the command. Example:
RunCommand(emacs, /home/joe/TODO)
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.
ServerDialogDone()
PasswordDialogDone()
Used to tell the dialog boxes that entry has finished. Usually invoked by
the return key.
Widget hierarchy
----------------
Main window:
Vncviewer vncviewer
Form form
Viewport viewport
Core desktop
Server dialog box:
TransientShell serverDialog
Dialog dialog
Password dialog box:
TransientShell passwordDialog
Dialog dialog
Popup window:
TransientShell popup
Form buttonForm
Command/Toggle button1
. .
. .
Command/Toggle buttonN