@DATABASE FreeWheel
@AUTHOR Alastair M. Robinson
@COPYRIGHT ©1999 - Alastair M. Robinson.

@NODE MAIN "FreeWheel V1.1a  -  ©1999, 2000 Alastair M. Robinson"

  @{b}Another little tool to fine-tune your mouse@{ub}
  This time especially for WheelMouse owners.

  Copyright ©1999, 2000 by  Alastair M. Robinson
  Freely distributable for non-commercial purposes.

Do you have a wheelmouse?

Are you disappointed with the amount of software which supports
the wheel?

If so, you'll love FreeWheel.

FreeWheel is a commodity which converts wheelmouse events into scrollbar
movement or cursor key movements.  It can also map several useful functions
to the wheel button, and even a fourth button.

FreeWheel is NOT a serial mouse driver - so you'll still need NewMouse
or equivalent to generate the mouse-wheel events in the first place!

@{"Legal" link Legal}

@{"Requirements" link Requirements}

@{"Features" link Features}

@{"Bugs/Problems" link Problems}

@{"Configuring" link Configuring}

@{"Credits" link Credits}

@ENDNODE


@NODE Problems "Known bugs and problems..."

@{b}Possibly fixed for V1.1:@{ub}
  The fake RawKey events generated by FreeWheel had an important field
  missing, which could cause CyberGuard hits with MUI programs.
@{b}This really should be fixed now!@{ub}

@{b}Problems yet to be resolved:@{ub}

FreeWheel is unable to nudge scrollgadgets created by the following programs:

  KingCon:
    Its scroll gadget is non-standard, and it doesn't listen for
    RawKey events.

  MUI:
    All MUI gadgets are non-standard, and as such don't respond to IDCMP
    messages.  Programs which use cursor up/down for scrolling will work
    however.  Alessandro Zummo has already written a patch for MUI
    (MUIWheel) allowing the most common classes to use the wheel.

  BGUI:
  ClassAct:
    Again, WheelMouse can't recognise the scrollbars generated by these
    GUI toolkits.  As with MUI, programs which respond to cursor-key
    movements will work.  If you want to see support for wheelmouse events
    in these packages, pester the authors; adding wheelmouse support should
    be very very easy for someone with access to the sourcecode, and very
    very hard without!

Not all programs recognise the shift-clicks generated by FreeWheel in
place of clicks of the third and fourth button.  Workbench works fine,
Imagine completely ignores the shift-clicks, and DrawStudio recognises
them but doesn't draw handles for shift-selected objects!
(This only applies to Shift+Click mode; using the buttons to simulate just
the shift key works fine.)

@ENDNODE


@NODE Requirements "What you need to run FreeWheel..."

FreeWheel's system requirements are pretty light -
you need:

»  An Amiga (surprise surprise...)

»  Kickstart 3.0 or higher

»  A mouse (preferably a PC wheelmouse)

»  A driver for your wheelmouse.  (Tested with Alessandro Zummo's
   NewMouse from Aminet, and my own mouse-port adapter-type-thing,
   which might soon appear on Aminet.)

@ENDNODE


@NODE Legal "The obligatory legal mumbo-jumbo..."

THIS SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND.  ALL USE IS
AT YOUR OWN RISK, AND THE AUTHOR CANNOT BE HELD RESPONSIBLE FOR DAMAGES OF ANY
KIND, ARISING FROM THE USE OR MISUSE OF THE PROGRAM OR ANY OF ITS ACCOMPANYING
FILES.

While this program is copyrighted, this is done merely to prevent others from
claiming it as their own work.  The name FreeWheel is intended to imply its
free status - you may pass the complete package on to whoever you wish, on
a non-profit basis.

Full source code is provided, in the hope that it will be of help and interest
to others.  You are encouraged to incorporate any of the source files into
your own projects, as long as they are freeware/shareware, and you credit me.

FreeWheel may be placed on the Cover CDs of Amiga magazines, and any other
Amiga CDs which contain predominantly Shareware, Freeware or PD software.

For any other commercial distribution or use of the source,
mail me at:blackfive@fakenhamweb.co.uk to discuss terms.

@ENDNODE


@NODE Configuring "How to configure FreeWheel...."

FreeWheel is configured through a simple GadTools GUI:
To show the GUI, you can use the Commodites Exchange, run the program a
second time, or use a hotkey (default ctrl alt m).

The window has three cycle gadgets, a slider and a string gadget,
which are as follows:

Scroll window:
  This item determines whether scroll events affect the currently selected
  window, or the window under the pointer.

Middle button:
Fourth button:
  These gadgets determine the program's behaviour when the wheel (middle)
  button and fourth button (if present) are pressed:

  » Ignore  -  the button is ignored.

  » Shift  -  Simulates the left-shift key.

  » Shift + click  -  a left-button-click with shift held down is simulated.

  » Wheel depth arrange  -  rolling the wheel with the button held down will
    cause the window under the pointer to be pushed back, or pulled forward,
    depending on which way you roll the wheel.

  » Shift + depth arrange  -  combines the Shift and Wheel depth arrange
    modes; you can use the wheel button as left shift, and roll it for
    depth arranging.

  » Cycle screens  -  the topmost screen is sent to the back.

Mouse speed:
  This allows you to adjust the mouse's speed with very fine control, just
  like my previous Commodity, FreeMouse.
  @{b}New for V1.1@{ub} - You can now set the horizontal and vertical speeds
  separately.  This is useful if you're working in a screen mode which doesn't
  have square pixels.

Click to front:
  When this is checked, a double-click in a window's border will bring that
  window to the front.

Click to back:
  When this is checked, a double-click in the border of the frontmost window
  will send it to the back.  Remember that a window is not necessarily the
  frontmost window just because it isn't obscured by other windows.

Hot key:
  This string gadget contains a description of the commodities hotkey which
  is used to bring up the GUI.

@ENDNODE


@NODE Features "Features...."

So what does FreeWheel actually do?

»   @{b}New for V1.1@{ub} - The Horizontal and Vertical mouse speeds can now be set
    individually.  Useful if you're working a screen mode which doesn't have
    square pixels.

»   @{b}New for V1.1@{ub} - Screens can now be cycled with a double-click of the
    middle/wheel button.

»   @{b}New for V1.1@{ub} - Horizontal scrollers and sliders can now be moved
    with the wheel.  To do this, you need to have the pointer over the gadget.

»   It allows programs not specifically written for wheelmice to be scrolled
    by the wheel.  If the window has a normal proportional gadget, it will
    be nudged, otherwise cursor-key presses will be sent to the window.

»   It allows several useful functions to be assigned to the wheel-button
    and to a fourth button if present.

»   It provides fractional scaling of mouse movements.  The mouse speed can
    be adjusted continuously from 33% to 300%, just like my previous
    Commodity, FreeMouse.

»   It provides my personally favoured Click-To-Front behaviour.  Double-click
    anywhere within the border of a window and it will jump to the front.

What doesn't FreeWheel do?

»   It does NOT provide a serial mouse driver.  You will still need a driver
    for your wheelmouse.  FreeWheel has been tested with Alessandro Zummo's
    NewMouse, and FreeWheel watches for newmouse standard events.
    I'm told that it works with Power Computing's Punchinello.
    It has also been tested with a homebrew Serial-mouse-to-Amiga-Mouseport
    adapter.

@ENDNODE


@NODE Credits "Credits...."

FreeMouse was written over the Christmas break of 1999, and updated in
March 2000 by Alastair M. Robinson.

It was compiled with VBCC 0.7, which is totally brilliant.  The provided
build script should work as long as both VBCC and the Native Developers Kit
includes (which can be obtained on the Amiga Developers CD) are installed.

I can be reached at the following address:

Alastair M. Robinson
 The Old Chapel,
  Syderstone,
   Kings Lynn,
    Norfolk,
     PE31 8SD,
      (England)

EMail:blackfive@fakenhamweb.co.uk

Greetings to:

Alessandro Zummo for writing NewMouse, MUIWheel & IntuiWheel.

Olivier Fabre for requesting features, and commenting on FreeMouse.

Steve Hall for allowing me to wire up his Amiga between his PC
and its mouse, to eavesdrop on the communication between the
two!

Everyone on the Amiga-C mailing list.

Everyone who has mailed me regarding this and previous projects of mine.

The Amiga community for surviving the Dark Age of Wintel.

@ENDNODE