VNCviewer for X (3.3.3 onwards)

If you just run the viewer from the command line, it will prompt you for a VNC server to connect to:

Alternatively, specify the VNC server as an argument, e.g.:

where 'snoopy' is the name of the machine, and '2' is the display number of the VNC server on that machine. Either the machine 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.

Popup window

• 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

See the section on customisation below for how to customise the contents of the popup window.

Full screen mode

Unfortunately this mode doesn't work completely with all window managers, 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.

Command line options

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

-bgr233

Tells the VNC server to send pixels which are only 8 bits deep. If your server desktop 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 the server may have to work a bit harder, and you may get some colour mismatches. "BGR233" means an 8-bit true colour pixel format, with the most significant two bits of each byte representing 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 specifies a list of encodings to use in order of preference, separated by spaces. The default is "copyrect hextile corre rre", or "raw copyrect hextile corre rre" for a VNC server on the same machine. For example, to use only raw and CopyRect, specify "raw copyrect".

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

-listen

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 now supports reverse connections with a helper program called vncconnect. It is also used for our internal version of VNC - see http://www.uk.research.att.com/vnc/internalversion.html.

Customisation and X resources

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

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

 *popupButtonCount: 2

 *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)

How to customise the desktop window

  *desktop.translations: #override\n\
    <Key>F8: SendRFBEvent()\n\
    <Key>Escape: ShowPopup()\n\
    <Key>F12: ToggleFullScreen()

Actions

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

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

    TransientShell  serverDialog
      Dialog          dialog

    TransientShell  passwordDialog
      Dialog          dialog

    TransientShell   popup
      Form             buttonForm
        Command/Toggle   button1
               .            .
               .            .
        Command/Toggle   buttonN

go back to documentation