
                    VNC Viewer for OS/2 PM, Version 1.00
		    
                        akira@sra.co.jp

_What is VNC ?

    VNC stands for Virtual Network Computing, developed by ORL.

        Jan. 1999, ORL has been acquired by AT&T to form AT&T
        Laboratories Cambridge.

    See  VNC site <http://www.uk.research.att.com/vnc/> for details.

_VNC Viewer for OS/2 PM

    There are two VNC viewer's for OS/2, XFree86/2 version and Java
    Version. X version requires X server, and Java version requires a
    lot of memory (resource monitor says it eat up  over 10MB of memory).

    VNC viewer is orginally, thin client.  X/Java version is FAT
    client for my environment. So I start porting VNC viewer for native
    PM. It requires no additional programs (but  requires TCP /IP, of
    course), and eat up less memory (so  start up faster).

_Setting up VNC Server

    You need to start VNC server before using VNC viewer.  There are VNC
    servers for Unix, Win95/NT, Mac in VNC site.  See,
    
        <http://www.uk.research.att.com/vnc/>

    for setting servers (especially, see FAQ page if you have trouble).

_Start VNC Viewer

    Setting up VNC server is bit difficult, but viewer side is quite
    easy.  You only to put executable 'vncview.exe' into a directory
    in a PATH, and simply type command, or create program object and
    double click it.

        This program was written for EMX/GCC.  You need EMX runtime 
	(0.9c or later) to run this program.

    From command line, start VNC viewer with

        vncview [ <host:display> ] [ <option> ... ]

    Connecting server is specified with 'host:display' format, as

        snoopy:2

    'host:display' may be changed with 'session dialog' after program
    startup.

        If you connecting to UNIX server, server report host and display
        number on it startup.
	If you connecting to Windows Server, display number is usually 0.

    There are following options.  Options are also changed with 'option
    dialog' after program startup.

    Pixel Format
    
        -true       Request '32 bits True Color' to server.  Viewer hold
	            display image with 24 bits true color.

	-bgr233     Request 'bgr233' 8 bits pixel format to server. 
                    Viewer hold disoplay image with 8 bits bitmap.

	-tiny       Request 'bgr233' 8 bits pixel format to server.
                    Viewer convert it to default 16 colors.

	-gray       Request 'bgr233' 8 bits pixel format to server.
                    Viewer convert it to 4 level gray scales.

        Default is '-true' color. PM converts any bitmap to real display
	depth.  So, you can use any pixel format without your local
        display.  But each format have onw problems.
	
          o Server convert colors if you request 'BGR233' format.  If
            you using graphic apllications requring exact colors, then
	    use True Color format.

          o True Color uses lot of (three times) network traffic than
            BGR233.  If you using slow network, or slow server, then
	    try BGR233 format.

          o If you using PM with 256, or 16 colors, color conversion in
            local PM side eat up lot of processor power.  In those case,
	    try '-tiny' option.  It convert BGR233 colors to default 16
	    colors.

          o '-tiny' reduces colors, but it sometimes cause trouble on
	    visual effects.  On those case, try 'gray' scaling.

    Encoding    
    
        -hextile    prefer Hextile encoding
	-corre      prefer CoRRE encoding
	-rre        prefer RRE encoding
	-raw        prefer RAW encoding

        Default prefers 'Hextile' encoding.  But for current version,
        rectangle fill (used by Hextile/RRE/CoRRE) is bit slow.  If you
	think it slow, and using fast network, then try 'Raw' encoding.
	
	Off course, 'Raw' encoding performs no compression, so, it causes
	tourble on slow network. 

            I noticed Java Version running on OS/2 also speed up on 'Raw'
	    encoding.

        'CopyRect' encoding is always effective in this version.

    Misc. options

	-shared     share disktop with another viewer

        -viewonly   disable mouse/key inputs
            
        -deiconify  request to restore on 'BELL' if iconified.

        -dialogAtCenter
	-dialogAtMouse
	            specify position of dialogs. With '-dialogAtCenter',
		    all dialogs are shown at center of screen. With 
		    '-dialogAtMouse', all dialogs are shown at near
                    mouse pointer.  Default is near mouse position.

        -passwd passwd-file
	            If you can access to server's passwd file, this
                    option supress password dialog.  It is useful when
                    using with Xvnc for OS/2.

        -keymap keymapfile
	            With 'keymapfile', you can specify mappings between
		    PM's scan key code and VNC's key definition.  With
                    this, you can distinguish right/left Shift/Control
		    keys usually not distinguished, or send NLS keys to
		    VNC server.
		    
		        See 'Keymap File' section for more details.

_Session / Option Dialog

    VNC viewer shows 'session dialog' on its startup.
    
        +---+-----------------------------------------------------+
        |   | PM VNC Viewer - connect to                          |
        +---+-----------------------------------------------------+
	| +-----+               +---------------+---+ +---------+ |
        | | VNC |  VNC Server : |               | V | | Connect | |
        | |     |               +---------------+---+ +---------+ |
        | +-----+                                     +---------+ | 
        |                         Use host:display    | Cancel  | |
        |                                             +---------+ |
        |                         e.g. snoopy:2       +---------+ |
        |                                             |Options..| |
        |                                             +---------+ |
	+---------------------------------------------------------+

    Server name field shows server name (host:display) given in command
    line.  If no server specified, then it shows last server name.
    Server name field is pull down list, it holds servers previously
    used.  You can select those servers from it.

    For confirm options, push 'Options' button, and invoke 'option
    dialog'.

        +---------------------------------------------+
	| Session Options for <snoopy:1>              |
        +---------------------------------------------+
        |                   +-------------------+---+ |
        | Pixel Format      | True Color        | V | |
        |                   +-------------------+---+ |
        |                   +-------------------+---+ |
        | Preferred Encoding| Hextile           | V | |
        |                   +-------------------+---+ |
        |                                 +---------+ |
        |    o Request shared session     | Connect | |
        |                                 +---------+ |
        |    o View only                  +---------+ |
        |                                 | Back    | |
        |    o Deiconify on Bell          +---------+ |
        +---------------------------------------------+
	
    If you specify some options on command line, those options are shown
    in this dialog.  If you specified nothing, then, last setting for
    selected server are shown.  Otherwise, default settings are used.

    Select server to connect, confirm options, and then push 'Connect'
    button to start connection to VNC server.

_Authentication

    If specified VNC server exist and working, then server request user
    authentication.

        +---+-----------------------------------------------------+
        |   | PM VNC Viewer - authentication                      |
        +---+-----------------------------------------------------+
        |                                             +---------+ |
        | +------+                  +---------------+ |    OK   | |
        | | VNC  | Session password:|               | +---------+ |
        | |      |                  +---------------+ +---------+ |
        | +------+                                    | Cancel  | |
        |                                             +---------+ |
        +---------------------------------------------------------;

    Password is one you set in server side.  It is 'vncpasswd' for Xvnc,
    or 'Property' for WinVNC.

    If you use '-passwd' option, this dialog is not appear.

_Remote Desktop

    If password was correct, then VNC session begin and viewer displays
    remote desktop image.  
    
    If you once connected to given server, previous window's position
    and size are used.  Connecting to new server, and remote  desktop 
    is smaller than PM screen, then entire desktop will shown.  
    Otherwise, part of remote desktop will shown.

    You can change local window size with dragging size border, but you
    cannot enlarge local window larger than remote desktop.  If local
    window is smaller than remote desktop, then scrool bar appears.
    
    When minimized, viewer not send request (FramebufferUpdateRequest)
    to server.  You can reduce network traffic, server load by
    minimizing viewer.

_Key and Mouse

    If local mouse is in local window, then mouse movements, button
    clicks are send to remote desktop.  If local window get focus, then
    also key events are send to remote desktop.

    But, this viewer does not change PM's standard hooks, and they are
    all process in PM side.  For example,
    
        CTRL-ALT-DEL        Reboot OS/2
        CTRL-ESC            Shows task list
	ALT-TAB             Chnages local side focus
	
    If you want to use those hooked key combinations to remote machine,
    use menu or keyboard accelerators.  All ALT key combinations are
    processed locally, and never send to remote machine.
    
_Menu and Accelerator

    Menu Items                      Accelerator
    -----------------------------+--------------
    Connection options...           Alt-O
    Connection info                 Alt-I
    Request screen refresh          Alt-R
    Copy                            Alt-Y       remote to local clipboard
    Paste                           Alt-P       paste to remote desktop
    Send Control Key
            Ctrl Key Toggle         Alt-C
	    Ctrl Key Down
	    Ctrl Key Up
    Send Alt Key
            Alt Key Toggle          Alt-A
            Alt Key Down
	    Alt Key Up
    Send Function Key
            F1 ... F12
    Send C-A-D                      Alt-D
    Send Ctrl-Esc                   Alt-E
    Send Alt-Tab                    Alt-T
    About VNC Viewer                Alt-B

    Ctl/Alt key status is shown in 'CTL' 'ALT' window in titlebar.  You
    can toggle their state with clicking those windows, and also you can
    use popup menu on those windows.

_Keymap File

    Keymap file defines mappings between PM's scan key code and VNC key
    events send to VNC server.
    
    This viewer usually does not check scan key code (in WM_CHAR message).
    Because, scan key code depend on your keyboard, and no generic way to
    handle scan key codes.

    But for this, viewer does not distinguish left/right shift/control
    keys (both send as left side one), and cannot distinguish keypad
    keys.  
    
    This causes some remote applications does not work correctly. So fix
    this problem, I introduced scan key mapping to VNC key events.

        With this function, you can distinguish left/right control/shift
	keys or enable NLS keys.

    Keymap file is a text file, each line defines mapping between PM's
    scan key code to VNC's key event code.  Lines beginning with '#' are
    treated as comment line.  For example, following definition
    distinguishes right Shift/Control keys on my keyboard.

    # Right Shift Key   -> XK_Shift_R
    36 FFE2
    # Right Control Key -> XK_Control_R
    5B FFE4

    First digits defines PM's scan key code (in hex-decimal).  This is
    keyboard dependent, so adjust to your environment.  I use good old
    'keylook' sample in Petzold's book to confirm these values.
    
    Next digits defines key event code send to VNC server. It is really
    X keysym definition.  Take a look at 'keysymdef.h' in the archive to
    describe value of key event.

    Archive contains two sample keymap files, works on my environment.
    
        right.map   Distinguish right Shift/Control keys
	keypad.map  Distinguish keypad keys.

    Of course, they works only my local environment.  If you want to use
    those mapping, adjust scan key code to your environment.
