MWheel V2.00
============

Geschrieben von Armin Diedering
Email: mwheel@ardisoft.de
Web:   http://www.ardisoft.de/


Was ist MWheel?
===============

MWheel ist ein Programm, das Mausraddrehungen der betreffenden Application
meldet.

MWheel ist kein Hardwaretreiber. MWheel stellt aber eine Schnittstelle zur
Verfgung, ber der ein Hardwaretreiber Raddrehungen in das System
einbringen kann.

Programme dessen Fenster gescrollt werden sollen mssen MWheel nicht einmal
kennen. Wenn das Rad ber ein Fenster eines Programms, das MWheel nicht
kennt, gedreht, dann werden WM_ARROWED-Ereignisse simuliert. Als es wird so
getan, als ob einen Scrollpfeil angeklickt wurde.
Und wenn das Fenster gar keine Slider-/Arrow-Elemente besizt? Dann werden
Cursortasten simuliert.


Einschrnkungen?
================

MWheel funktioniert nur mit Applikationen, die auch die AES-Trap-#2-API
benutzen. Leider gehrt das Original-ATARI-Desktop nicht dazu. Daher lassen
sich auch dessen Fenster nicht scrollen.


Installation
============

MWheel gehrt in den AUTO-Ordner. Zu Testzwecken kann es auch
nachtrglich vom Desktop aus gestartet werden.

MWheel bentigt zwingend das Programm Trapper von Manfred Schwind (ehemals
Lippert).
Eventuell wird noch ein Cookie-Programm bentigt, weil weder Trapper noch
MWheel bei Bedarf einen Cookie-Jar anlegen.

Mit dem CPX-Modul MWheel.cpx kann MWheel konfiguriert werden (Drehrichtung,
Zeilen je Dreh usw.)

Treiber Module benutzen die Erweiterung "*.MWX" und werden automatisch
nachgeladen.


Freeware
========

MWheel darf beliebig - aber nur zusammen mit folgenden Dateien und
selbstredend unverndert - weitergegeben werden.

mwheel.prg					MWheel
mwheel.cpx					das Konfigurations-CPX
mwheel.txt					dieser Text
mwheel.h						ein Header-File fr Programmierer

mwhl-mpc.mwx				ein Wheel-Treiber fr Magic PC
mwhl-mpc.txt
mwhl-joy.mwx				der Joystick als Wheels
mwhl-joy.txt
mwhl-ser.mwx				ein Wheel-Treiber fr serielle Muse
mwhl-ser.txt
mwhl-eif.mwx				ein Treiber fr das Tastatur-/Maus-Interface Eiffel
mwhl-eif.txt

setter.gem\					Setter-Programm zum configurieren von mwhl-ser, wheelan
								und mwhl-jer

trapper\						Trapper von Manfred Schwind

xTrapper\xTrapper.prg	Starthilfe fr Trapper
xTrapper\xTrapper.txt
xTrapper\TrapTest.prg	Testet ob xTrapper ntig ist

xaAES\xaMWheel.prg		Spezial-MWheel fr xaAES ab Release 1.11.2004
xaAES\xaMWheel.txt
xaAES\moose.adi			Spezielles moose.adi fr xaMWheel und xaAES


Internes
========

MWheel erweitert die AES-Funktionen appl_getinfo, evnt_button, evnt_multi
und ab v2.00 (wegen XaAES-Komptibilitt) auch wind_set und wind_get. Fr
evnt_button und evnt_multi werden dabei neue Bindings erforderlich.
MWheel bindet Mausrder als zustzliche Maustaste ein. Dadurch kann eine
Applikation per wind_update(BEG_MCTRL) Mausrad-Ereignisse einfangen.
Ansonsten geht die Meldung an die Applikation, ber dessen Fenster sich der
Mauszeiger befindet.


appl_getinfo
------------

Bei appl_getinfo Opcode 8 wird in ap_gout3 ein Bit-Vektor der verfgbaren
Mausrder zurckgegeben.


wind_set(wi_handle, WF_WHEEL, wi_sw1, wi_sw2, ...)
--------------------------------------------------

Fr wind_set gibt es einen neuen Parameter WF_WHEEL (40). Hiermit kann kann
fr ein Fenster (wi_handle!=0) bzw. fr alle knftigen Fenster der
Applikation (wi_handle=0) eine er-weiterte Wheel-Behandlung eingeschaltet
(wi_sw1=1) bzw. ausgeschaltet (wi_sw1=0) werden. Wenn die erweiterte
Wheel-Behandlung aktiviert (wi_sw1=1) ist, dann wird mit wi_sw2 der Modus
festgelegt und es werden dann auch keine Cursortasten mehr simuliert.

XaAES definiert 3 Modi:

- WHL_RAWWHEEL (wi_sw2 = 0)
   Wenn WHL_RAWWHEEL gewhlt wird, dann wird beim Eintreffen von
   Wheelereignissen eine WM_WHEEL-Message verschickt:
      Message[0] = WM_WHEEL (345)
      Message[1] = ID des Senders
      Message[2] = ...
      Message[3] = Fenster Handle
      Message[4] = Maus X
      Message[5] = Maus Y
      Message[6] = Status der Umschalttasten
      Message[7] = Wheel-Info

      Wheel-Info:
         Bits 15-12  Wheel ID
         Bits 11-8   Richtung und Orientierung:
                     0->Up; 1->Down; 2->Left; 3->Right
                     15->keine Zuordnung
         Bits 7-0    Drehweite

      Bei MWheel setz die Bits 8-11 fr Rad 1 auf 0 bzw. 1 und fr Rad 2 auf
      2 bzw. 3. Fr Allen anderen Rdern wird 15 gesetzt.
      Die Drehweite ist, unabhngig von den Bits 8-11, immer mit Vorzeichen behaftet.

- WHL_ARROWWHEEL (wi_sw2 = 1) standard
   Bei WHL_ARROWWHEEL verschickt MWheel eine erweiterte ARROWED-Nachrichten:
      Message[0] = WM_ARROWED (24)
      Message[1] = ID des Senders
      Message[2] = ...
      Message[3] = Fenster Handle
      Message[4] = HI-Byte ' Drehweite / LO-Byte ' WA_xxxxxx & 0x7
      Message[5] = Maus X
      Message[6] = Maus Y
      Message[7] = Status der Umschalttasten

- WHL_SLDRWHEEL (wi_sw2 = 2)
   Dieser Modus wird zwar von XaAES definiert aber nicht von MWheel
   untersttzt.



wind_get(wi_handle, WF_WHEEL, wi_sw1, wi_sw2, ...)
--------------------------------------------------

Natrlich gibt es fr wind_set(.., WF_WHEEL, ..) auch ein entsprechendes
wind_get-Gegenstck.


evnt_button
-----------

Fr evnt_button wird ein neues Binding erforderlich, weil dieser Funktion
ein zustzlicher Parameter bergeben werden kann.

Deklaration:   WORD evnt_button ( WORD ev_bclicks, WORD ev_bmask,
                                  WORD ev_bstate,  WORD *ev_bmx,
                                  WORD *ev_bmy,    WORD *ev_bbutton,
                                  WORD *ev_bkstate, WORD *ev_bwhlpbuff );


Der Parameter ev_bwhlpbuff ist ein Zeiger auf den 16 WORDs (32 Byte) groen
Wheel-Puffer. Wenn in ev_bbutton Bit-7 (0x80) gesetzt ist, dann sind die
Werte im Wheel-Buffer gltig. Im Wheel-Buffer wird fr jedes verfgbare Rad
die Drehweite (vorzeichenbehaftet) eingetragen.
Soll auf ein Mausrad-Ereignis gewartet werden, dann mu Bit-7 auch in
ev_bmask gesetzt werden.

GEM_Arrays: control        control[0]        21    Opcode der Funktion
            control+2      control[1]        3     # Eintrge in int_in
            control+4      control[2]        5     # Eintrge in int_out
            control+6      control[3]        1     # Eintrge in addr_in
            control+8      control[4]        0     # Eintrge in addr_out

            int_in         int_in[0]         ev_bclicks
            int_in+2       int_in[1]         ev_bmask
            int_in+4       int_in[2]         ev_bstate

            int_out        int_out[0]        Return-Wert
            int_out+2      int_out[1]        ev_bmx
            int_out+4      int_out[2]        ev_bmy
            int_out+6      int_out[3]        ev_bbutton
            int_out+8      int_out[4]        ev_bkstate

            addr_in        addr_in[0]        ev_bwhlpbuff


evnt_multi
----------

Fr evnt_multi gibt es 2 Mglichkeiten an die Wheelereignisse zu kommen.
Bei der neuen XaAES-Methode wird ein neuer Ereignistyp MU_WHEEL (0x0040)
eingefhrt. Tritt dann ein Wheelereignis ein, dann findet man in
ev_mmokstate (int_out[4]) die Wheelnummer und in ev_mbreturn (int_out[6])
die Dreweite.

Bei der "alten" MWheel-Methode ist wie bei evnt_button ein neues Binding
erforderlich.

Deklaration    WORD evnt_multi ( WORD ev_mflags, WORD ev_mbclicks,
                                 WORD ev_mbmask, WORD ev_mbstate,
                                 WORD ev_mm1flags, WORD ev_mm1x,
                                 WORD ev_mm1y, WORD ev_mm1width,
                                 WORD ev_mm1height, WORD ev_mm2flags,
                                 WORD ev_mm2x, WORD ev_mm2y,
                                 WORD ev_mm2width, WORD ev_mm2height,
                                 WORD *ev_mmgpbuff, WORD ev_mtlocount,
                                 WORD ev_mthicount, WORD *ev_mmox,
                                 WORD *ev_mmoy, WORD *ev_mmbutton,
                                 WORD *ev_mmokstate, WORD *ev_mkreturn,
                                 WORD *ev_mbreturn, WORD *ev_mwhlpbuff );

Auch evnt_multi wird wie schon evnt_button um einen Parameter erweitert.
ev_mwhlpbuff entspricht hierbei ev_bwhlpbuff bei evnt_button.

GEM_Arrays: control        control[0]        25    Opcode der Funktion
            control+2      control[1]        16    # Eintrge in int_in
            control+4      control[2]        7     # Eintrge in int_out
            control+6      control[3]        2     # Eintrge in addr_in
            control+8      control[4]        0     # Eintrge in addr_out

            int_in         int_in[0]         ev_mflags
            int_in+2       int_in[1]         ev_mbclicks
            int_in+4       int_in[2]         ev_mbmask
            int_in+6       int_in[3]         ev_mbstate
            int_in+8       int_in[4]         ev_mm1flags
            int_in+10      int_in[5]         ev_mm1x
            int_in+12      int_in[6]         ev_mm1y
            int_in+14      int_in[7]         ev_mm1width
            int_in+16      int_in[8]         ev_mm1height
            int_in+18      int_in[9]         ev_mm2flags
            int_in+20      int_in[10]        ev_mm2x
            int_in+22      int_in[11]        ev_mm2y
            int_in+24      int_in[12]        ev_mm2width
            int_in+26      int_in[13]        ev_mm2height
            int_in+28      int_in[14]        ev_mtlocount
            int_in+30      int_in[15]        ev_mthicount

            int_out        int_out[0]        Return-Wert
            int_out+2      int_out[1]        ev_mmox
            int_out+4      int_out[2]        ev_mmoy
            int_out+6      int_out[3]        ev_mmbutton
            int_out+8      int_out[4]        ev_mmokstate
            int_out+10     int_out[5]        ev_mkreturn
            int_out+12     int_out[6]        ev_mbreturn

            addr_in        addr_in[0]        ev_mmgpbuff
            addr_in+4      addr_in[1]        ev_mwhlpbuff



Fr Hardware-Maustreiber-Programmierer
======================================

MWheel trgt sich in den Cookie-Jar ein und verwendet dabei die ID 'MWHL'.
Der Cookie-Wert ist ein Zeiger auf folgende Struktur:

typedef struct
{
	WORD	mwhl_version;
	char*	mwhl_info;
	WORD	(*mwhl_wheeled)(WORD Value[16]);
	WORD	(*mwhl_service)(LONG Opcode, ...);
	WORD	mwhl_wheels;
	LONG	mwhl_control;
	WORD	mwhl_step[16];
	WORD	mwhl_direction;
	WORD	mwhl_delay;
}MWHL_Cookie;

mhwl_version:     Version von MHweel im BCD Format (z.B. 0x0100 fr v1.00)

mhwl_info:        Nullterminierter String mit Programminformationen

mwhl_wheeled:     Diese Funktion mu ein Hardware-Treiber aufrufen um die
                  Rad-Ereignisse einzuspeisen. Die Funktion erwartet nach
                  C-Konvention die Parameter auf dem Stack bergeben (in
                  Pure-C schreibt man dafr "cdecl"). Der Rckgabewert wird
                  wie in C blich ber das Register D0 zurckgeliefert. Die
                  Funktion kann - nach C-Konvention - die Register
                  D0,D1,D2,A0 und A1 verndern.

                  Value:  Ist ein Zeiger auf 16 WORDs, die die Drehweiten
                          enthalten.

                  Return: Wurden die Drehweiten angenommen, dann liefert
                          mwhl_wheeled E_OK. Anderenfalls ist ein Fehler
                          aufgetreten.

mwhl_service:      Fr diese Funktionen gelten die gleichen
					    Aufruf-Konventionen wie bei mwhl_wheeled. Diese Funktion
					    hat eine variable Anzahl von Parametern (abhngig von
					    Opcode). Durch einen Fehler in der ersten Version, sollte
					    diese Funktion erst ab Version 1.1 (mhwl_version>=0x110)
					    verwendet werden.

                   Opcode: Legt fest, was die Funktion machen soll.

                   Return: von Opcode abhngig

                   Funtionen:  1 - den Opcode 1 verwendet ausschlielich
                                   MWHL-SER.MWX. Dieser Opcode wird
                                   zuknftig nicht mehr verwendet. Und
                                   bleibt daher undokumentiert.

                               2 - mit Opcode 2 kann man ganz bequem
                                   Mausbewegungen einschleusen.
										 	    #define MWHL_MOVE_MOUSE 2
											    WORD X,Y;
											    mwhl_service(MWHL_MOVE_MOUSE,X,Y);

											    X & Y: in X und Y werden die
											           Bewgungsdaten relativ zur
											           aktuellen Mausposition
											           bergeben.

                               3 - mit Opcode 3 kann man Mausbutton-
                                   Ereignisse einschleusen.
											    #define MWHL_SET_BUTTON 3
											    WORD Mask,Button;
											    mwhl_service(MWHL_SET_BUTTON,Mask,Button);

											    Maske:  jedes gesetzte Bit markiert den
											            Button, dessen Status gesetzt
											            bzw. gelscht werden soll
											    Button: in Button wird der neue Status
											            des Maus-Buttons bergeben.

mwhl_wheels:       Ein Bit-Vektor der verfgbaren Mausrder. Dieser
                   Bit-Vektor wird bei appl_getinfo Opcode 8 in ap_gout3
                   zurckgegeben. Ein Maus-Treiber mu hier die
                   entsprechenden Bits der von ihm untersttzten Rder
                   setzen.

mwhl_control:      Fr diverse Einstellungen

                   Bit-0  schaltet WM_ARROWED-Emulation Ein bzw. Aus
                   Bit-1  erlaubt auch WM_ARROWED-Emulation fr Fenster #0

mwhl_step[16]:     Fr jedes Rad kann eine Scrollweite angegeben werden, die
                   bei einem Dreh gemeldet werden soll. Praktisch wird
                   einfach die Drehweite, die mit mwhl_wheeled gemeldet
                   wird, mit den Werten aus mwhl_step multipliziert.
                   Allerdings gilt das nur fr Drehs innerhalb der
                   Delay-Zeit (siehe mwhl_delay). Daduch kann man, durch
                   langsames Drehen des Rades, fein scrollen.

mwhl_direction:    Legt die Richtung der Radereignisse fest. Wird z.B. Bit-0
                   gesetzt, dann wird auch die Richtung von Rad-0 umgedreht.

mwhl_delay:        Da eine Raddrehung wie ein Mausklick behandelt wird, wird
                   sie auch etwas verzgert gemeldet (Mausklicks werden in
                   der Regel verzgert gemeldet, damit das System
                   Doppelklicks registrieren kann). Um ein "Ruckeln" zu
                   vermeiden, wartet MWheel (wenn es ein Radereignis
                   gemeldet hat) direkt auf einen weiteren Dreh, der dann
                   ohne verzgerung weitergemeldet wird. Diese Wartezeit
                   wird mit mwhl_delay festgelegt (in ms).


Guideline
=========

Grundstzlich sollte die Applikation kontextabhngig entscheiden, was mit
den gemeldeten Raddrehungen passieren soll und welches Rad (wenn es denn
mehrere gibt) fr welche Aufgabe verwendet werden soll.

Trotzdem mchte ich hier ein paar grundlegende Richtlinien vorgeben (an die
sich ein Programm aber nicht unbedingt halten mu aber sollte).

- Raddrehungen werden mit vorzeichenbehaftete Drehweiten gemeldet. Fr das
  Scrollen gilt folgendes:
  - positive Werte scrollen nach oben bzw. rechts
  - negative Werte scrollen nach unten bzw. links

- das Rad 0 ist das Haupt-Rad und ist universell (kontextabhngig)

- den Rdern 1-15 werden feste Funktionen zugeordnet

- Rad 0 ist standardmig fr das vertikale scrollen verantwortlich

  - der Kontext "Alternate-Taste" (bis v1.6 Control-Taste) schaltet auf
    horizontales scrollen um

- Rad 1 ist fr das horizontale scrollen verantwortlich

- Rder 2-15 sind noch unbelegt


Fragen und Antworten
====================

F:  Was passiert mit Programmen, die nicht das neue Binding verwenden?

A:  Wenn diese Programme evnt_multi verwenden und auf ein Message-Ereignis
    (MU_MESAG) warten, dann bekommen sie von MWheel WM_ARROWED-Nachrichten
    untergeschoben. Dieses Verhalten kann mit dem CPX-Modul abgeschaltet
    werden.


F:  Funktioniert MWheel auf jeder TOS-Plattform?

A:  Ich gehe einmal stark davon aus. Getestet habe ich MWheel allerdings nur
    mit MagiC-PC und einem ATARI 1040 STFM mit TOS 1.02



History
=======

V2.00, 27.11.2004
-----------------

- MWheel ist jetzt kompatibel zu XaAES

V1.50, 18.10.2004
-----------------

- Unabhnging vom *.MWX kann ein Mausbeschleuniger aktiviert werden.
- MWheel vertrgt sich jetzt mit zControl

V1.41, 29.9.2004
----------------

- Unabhnging vom *.MWX kann ein Linkshnder-Modus aktiviert werden. Dabei
  wird einfach die linke und rechte Maustaste getauscht.
- MWheel fr Treiber erweitert, die die Service-Funktionen, die mit der
  Version 1.4 eingefhrt wurden, verwenden (z.B. Milan und JeryyST)
  erweitert. Es jetzt mglich die 3. Taste als Doppelklick zu programmieren.

V1.40, 24.9.2004
----------------

- MWheel um Service-Funktionen erweitert, die u.a. vom Milan- und
  vom JeryyST-Treiber verwendet werden.

V1.33, 26.8.2002
----------------

- MWheel so umgeschrieben, da der Patch aus v1.32 nicht mehr ntig ist. MWheel
  funktioniert nun auch ohne CPX.

V1.32, 20.8.2002
----------------

- ein Patch fr nur TOS-Systeme, der eine Unvertrglichkeit zwischen NVDI
  und Trapper ausbgelt. (der Patch befindet sich im CPX-Modul)

V1.31, 15.8.2002
----------------

- Da MagiXDesk Abstrzt, wenn man versucht den Desktop-Hintergrund zu
  scrollen, lassen sich jetzt WM_ARROWED-Nachrichten fr Fenster #0
  abstellen bzw. sind bereits standardmig abgestellt.

V1.30, 9.8.2002
----------------

- bei der Installation mu nicht mehr darauf geachtet werden, da MWheel
  nach Trapper ausgefhrt wird.
- Treiber die sich im AUTO-Ordner befinden und die Dateierweiterung "*.MWX"
  haben werden jetzt automatisch nachgeladen. Dadurch mu man bei den
  Treibern auch nicht mehr auf die Boot-Reihenfolge achten.

V1.20, 5.6.2002
----------------

- Treiber fr serielle Muse wieder ausgelagert
- kleinen Fehler beseitigt der dazu fhrte,
  da das Scrollrad manchmal "hakte"
- serieller Treiber jetzt im MWheel-Packet enthalten (Freeware)

V1.10, 7.2.2002
----------------

- MWheel mit integrierten Treiber fr serielle Muse (kommerzielle Version)

V1.01, 19.1.2002
----------------

- 2. Rad scrollt jetzt in beide Richtungen

V1.0, 17.12.2001
----------------

- Erste Version


Viel Spa mit MWheel & Co.,
Armin Diedering
