Help file for !VNCViewer
~~~~~~~~~~~~~~~~~~~~~~~

 Application  :VNCViewer
     Purpose  :A RiscOS VNCViewer for use with ORL's Remote
               Frame Buffer protocol
     Version  :0.09
      Author  :Leo White
        Date  :4/3/98

 Leo White, 1998

--------------------------------------------------------------------

  VNCViewer is a Risc OS client for ORLs Remote Frame Buffer protocol.
It can be used to connect up to any machine running a VNC server and
display that machines desktop in a window on your Risc OS desktop.
This is similar in function to the standard XServer/Xclient programs,
but all the programs are run on the Remote machine.  All the VNCViewer
does is display the desktop display and send mouse and key events.
This means that you can quit VNCViewer on one machine, run it on another
and have exactly the same desktop display shown as when you last saw it.
Useful if you use a number of computers, or if your computer happens to
crash, then no data is lost.  Unlike with an X Server.

  VNCViewer implements all the protocols as defined by ORL's RFB
protocol.  And hopefully they all work properly :)  As far as I can
tell they do.

  Currently only 8, 16 and 32 bpp displays are supported. 1 bit
mode will be added eventually.

  VNCViewer was produced from the documentation released by ORL,
and is not a port of the X or windows viewers.  Hopefully this
has resulted in a smaller and more efficent program that uses
features of Risc OS that a straight port may not have.

  For more details on the RFB protocol, or to download a
VNC server for X or windows, go to
http://www.uk.research.att.com/VNC/


Instructions
~~~~~~~~~~~~

  The iconbar icon.
    Clicking select on this will open either the Connect window, or
the main window.  Depending whether or not you already have a connection
established.  clicking adjust on this icon will open the options window.

  The menu.

    Info        - Opens the info window
    Connect     - Opens the connect window to initiate a fresh connection.
    Options     - Opens the options window.
    Stats       - Opens the network statistics window.
    Save        - Allows you to save the display and the servers text buffer.
    Full Screen - Removes the window furniture so it covers the entire screen.
    Single Task - Enters single tasking mode.
    Refresh     - Causes the entire display to be redrawn.
    Send C-A-D  - Sends the Ctrl-Alt-Delete keypress (Only works when connecting to
                  an NT machine).
    Disconnect  - Disconnect the viewer.
    Quit        - Quits VNCViewer.

  The main window

    This displays the remote desktop.  Any pointer clicks on it, or
    keypresses will be passed to the server for processing.

  The connect window

    This is where you initiate a connection to the server.  The
    window will except address in both numeric and word format.
    The address is then followed by a ':' and the number of the
    display to connect up to (This is displayed when the server
    is run on a Unix/Linux machine, and is usually 0 for a Windows
    Server)
    Next to this is a menu icon, which when clicked on will open
    a menu containing the strings stored in the !VNCViewer.hosts file.
    When one of these menu items are clicked on, they are copied into
    the server icon.  This saves you typing them out each time.
    The format of the hosts file is the number of entries on the first
    line, followed by the appropiate number of entries, each on a seperate
    line.

  The connecting Window.

    This displays status messages about how the connection is
    going and if it fails to connect will tell you why.

  The password window.

    This window pops up when you need to type in your password.
    Once the password is typed in, press return to send it, and
    the appropiate authentication routines will run.  I specifically
    overwrite the password, so hopefully it will not be too easy to get
    at :) Pressing Escape instead will cancel the connection process.

  The options window

    Encoding Type - Selects which encoding types to support

    BPP - Sets what BPP display to use (Only effective before connecting)

    Shared - Set if you wish to allow several viewers to connect up
             to the same display simultaneously.

    Always Track Mouse - Set if you wish the mouse to always be tracked,
                         clear if you want the mouse to only be tracked
                         when VNCViewer has the input focus.

    Poll Time - How often the display is checked for changes.

    Mouse Update - How often the mouse position is sent. This
    		   value indicates how many polls between each
    		   update.  Button clicks pass the value through
    		   immediately of course.

    Disable nagle Algorithm - Basically the nagle algortihm collects
                   together small packets of information to create
                   a single large packet which is then sent across
                   the network (And therefore reducing network load).
                   Disabling this algortihm may increase responsivness
                   as small packets of data (i.e mouse button clicks and
                   key clicks) will be sent immediately instead of being
                   combined with other packets.
                   
    OK - Confirms the changes

    Cancel - Aborts the changes

    Save - Saves the current options


  The Statistics window

    This window displays details on the current display type (BPP, size)
    and information on what type of encoding information is sent over
    the network, and the average network usage since the connection was
    first made.

    This will at a later date be changed so it shows the number of KBytes
    sent, but currently my VNC server dies long before it has a chance to
    overflow the values.
    
    The KBytes/sec value represensts the amount of data sent and received across
    the network connection in the last 5 seconds. So its a fairly current indication
    of how much network bandwidth you are using.

  The save window

    From here you can save a sprite of the current remote desktop display, or
    the text contents of the remote machines clipboard.  If this always produces
    a blank text file then its possible your server doesn't support this feature.

  Full screen mode

    If the Risc OS desktop size and the remote desktop size are the same, then
    this option will become available.  Basically it removes all the window furniture,
    and opens up the window so it covers the entire screen.  Unfortunately there
    is a border around the window that cannot be removed (At least not without
    the new nested window manager).
    When in this mode, clicking menu in the top left hand corner of the screen will
    open the icon bar menu.  Allowing you to turn off this option or select any
    of the other menu options as normal.
    If you change modes whilst in full screen mode, the window will revert back
    to its normal state (Even if you just change the colour depth)

  Single tasking mode

    When this option is selected, VNCViewer changes the screen size so that it
    is the same as the server. And will enter a single tasking routine to process
    the VNC session. Basically it means that any other wimp applicatons running will
    not be able to use the processor until you exit fom single tasking mode.
    As no other wimp tasks can interrupt VNCViewer in this state, it should mean
    the VNC session is faster and more responsive. Assuming your network connection
    is of a reasonable speed.
    
    To exit from single tasking mode, move the mouse pointer to the top left corner
    of the screen and press and hold down the menu button until VNCViewer
    switches back to the multi tasking display.
    
    Under Risc OS 3.5+ VNCViewer will switch to any mode that the machine can 
    support. On Risc OS 3.1 machines VNCViewer only supports single tasking
    in mode 28 at present.

--------------------------------------------------------------------

  Known Bugs.


  8 bit fixed colour mode is not very well supported at the moment, and
may crash VNCViewer :(  This will be fixed in a later release.

  Erm I think thats it at the moment, but I'm sure there are more :)
If you find any mail me and I'll try to fix it.


--------------------------------------------------------------------

Program History
~~~~~~~~~~~~~~~

Version 0.01 06-06-98
~~~~~~~~~~~~~~~~~~~~

-Supports only the one protocol, and does not cope with failed
 logins very well.
-Mouse and keyboard are not fully supported.

Version 0.02 28-06-98
~~~~~~~~~~~~~~~~~~~~~

-Another couple of protocols are added.
-Mouse and keybord support is improved
-Login sequence made more multitasking
-Password window is now used instead of a fixed string

Version 0.03 Thu 02nd July 1998
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-All the protocols are added
-Bug fixed where mouse button clicks only processed when mouse is moving
-Reliance on Null polls removed.

Version 0.04 Wed 08th July 1998
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Added 16bpp and 32bpp support
-Finally got around to filling in the options window

Version 0.05 Sun 12th July 1998
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Fixed the No password connection routines
-Added limited Fixed colour map support. If not running
 a true colour display VNCViewer will use the default
 Risc OS palette.  This gives the correct colours when
 connecting up to VNCServe.

Version 0.06 Sat 18th July 1998
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Fixed bug where passwords less than 8 chars in length would fail
 on the first attempt
-Changed options code so that new encoding types are only sent if
 they actually are different
-Added saving of options
-Added code to automatically release modifier keys when input foceus
 is lost.
-Added an extra check to see when the pointer leaves the main window
-Added option to specify how often the mouse position is updated
-Disconnect option now actually works.  Although the memory used
 isn't currently freed up, VNCViewer will reuse it if possible
 next time you connect.

Version 0.07 Fri 19th September 1998
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Major rewrite.  Should now have better support for dropped connection.
-Fixed a bug in the disconnect code, that would kill VNCViewer
 if an incorrect password, or destination was entered after
 disconnecting from an existing Display.
-Added a number of new options (Full screen, stats window, etc.)

Version 0.08 Wed 04th November 1998
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Added removing of window border in full screen mode (Only works on
 Window manager 3.80 or later)
-Fixed bug where going into full screen mode didn't give VNCViewer
 the input focus.
-Fixed bug in hosts menu where the hosts file said there were more
 entries than actually existed
-Added disable nagle algorithm option
-Fixed problems with detecting button up requests on single clicks.
-Should be slightly faster

Version 0.09 Thu 04th March 1999
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Finished implementing Single tasking mode
-Rewrote a number of functions to speed up VNCViewer
-Changed the KBytes/Sec value in the Statistics window to give a
 more accurate value.
-Fixed a couple of small bugs that allowed windows to be opened 
 before the connection was fully established.

----------------------------------------------------------------
Acknowledgements
~~~~~~~~~~~~~~~~

VNCViewer uses the C Swi interface written by Peter Naulls.
This swi interface is much faster than the standard ones (Supposedly,
I'm not about to rip them out and use kernel swi calls just to
check *grins*) and thanks to Peter for writing it and allowing
it to be used in Freeware and Shareware programs.

Thanks to ORL for developing VNC (Virtual Network Computing) and
releasing details of the Remote Frame Buffer protocol so I could
write this program.

Also thanks to Phillip Camp for writing the VNCViewer module, it
saved me the trouble of doing it myself *grins*  See the file
!VNCViewer.Resources.!Help for conditions of use for this module.

----------------------------------------------------------------

Disclaimer
~~~~~~~~~~

  This software is provided as is.  The author cannot take responsibility
for any loss of data or any other problems consequent upon the use of
this program.

----------------------------------------------------------------

Conditions of Use
~~~~~~~~~~~~~~~~~

  This software is freeware.  It may be freely distributed as long as no
money is exchanged, apart from cost of distribution i.e. cost of discs,
and that all the original file are included.  

----------------------------------------------------------------

Contacting The Author
~~~~~~~~~~~~~~~~~~~~~

  If you wish to contact me, e.g. to tell me about any bugs,
improvements etc. Or if you just want to send me large amounts of
money :) (Well you never know), then you can use the following
methods.

email specific to this program: vncviewer@brighteyes.u-net.com
general email : lptw1@ukc.ac.uk  (Should be valid for a few more years yet)
		lptw1@brighteyes.u-net.com

or send mail to

L P T White
208 New Road
West Parley
Ferndown
Dorset
BH22 8EN

Any mail arriving here will be sent on to me at University. So could take
a while to reach me.
