
TightVNC 1.3dev7: Xt-based VNC viewer
=====================================

TightVNC is Copyright (C) 2001-2004 Constantin Kaplinsky.  All Rights Reserved.
VNC is Copyright (C) 1999 AT&T Laboratories Cambridge.  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
