home *** CD-ROM | disk | FTP | other *** search
/ ST-Computer Leser 2002 January / STC_CD_01_2002.iso / APP / MWHEEL / MWHEEL.TXT < prev    next >
Text File  |  2002-01-09  |  12KB  |  312 lines
  1. MWheel V1.00
  2. ============
  3.  
  4. Geschrieben von Armin Diedering
  5. Email: Armin@Diedering.de
  6. Web:   http://www.ardisoft.de/
  7.  
  8.  
  9. Was ist MWheel?
  10. ===============
  11.  
  12. MWheel ist ein Programm, das Mausraddrehungen der betreffenden Application
  13. meldet.
  14.  
  15. Im gegensatz zu Wheel von Holger Weets (ST-Guide) versendet MWheel keine
  16. AES-Nachrichten (Message) sondern erweitert die Maustasten. Eine Radbewegung
  17. wird als Maus-Klick interpretiert. Der Vorteil dabei ist, da₧ Radbewegungen
  18. per wind_update(BEG_MCTRL) eingefangen werden können. Somit kann das Mausrad
  19. auch in modale Dialoge verwendet werden.
  20.  
  21. MWheel ist kein Hardwaretreiber. MWheel stellt aber eine Schnittstelle zur
  22. Verfügung, über der ein Hardwaretreiber Raddrehungen in das System
  23. einbringen kann.
  24.  
  25.  
  26. Installation
  27. ============
  28.  
  29. MWheel gehört in den AUTO-Ordner. Zu Testzwecken kann es auch
  30. nachträglich vom Desktop aus gestartet werden.
  31.  
  32. MWheel benötigt zwingend das Programm Trapper von Manfred Lippert (Jinnee).
  33. Dabei mu₧ MWheel nach Trapper ausgeführt werden.
  34.  
  35. Mit dem CPX-Modul MWheel.cpx kann MWheel configuriert werden (Drehrichtung,
  36. Zeilen je Dreh usw.)
  37.  
  38.  
  39. Freeware
  40. ========
  41.  
  42. MWheel darf beliebig - aber nur zusammen mit folgenden Dateien und
  43. selbstredend unverändert - weitergegeben werden.
  44.  
  45. mwheel.prg                MWheel
  46. mwheel.cpx                das Configurations-Tool
  47. mwheel.txt                dieser Text
  48. mwheel.h                    ein Header-File für Programmierer
  49.  
  50. mwhl-mpc.prg            ein Wheel-Treiber für Magic PC
  51. mwhl-mpc.txt
  52. mwhl-joy.prg            der Joystick als Wheels
  53. mwhl-joy.txt
  54.  
  55.  
  56. Für Programmierer
  57. =================
  58.  
  59. MWheel erweitert die AES-Funktionen appl_getinfo, evnt_button und
  60. evnt_multi. Für evnt_button und evnt_multi werden dabei neue Bindings
  61. erforderlich.
  62. MWheel bindet Mausräder als zusätzliche Maustaste ein. Dadurch kann eine
  63. Applikation per wind_update(BEG_MCTRL) Mausrad-Ereignisse einfangen.
  64. Ansonsten geht die Meldung an die Applikation, über dessen Fenster sich der
  65. Mauszeiger befindet.
  66.  
  67.  
  68. appl_getinfo
  69. ------------
  70.  
  71. Bei appl_getinfo Opcode 8 wird in ap_gout3 ein Bit-Vektor der verfügbaren
  72. Mausräder zurückgegeben.
  73.  
  74.  
  75. evnt_button
  76. -----------
  77.  
  78. Für evnt_button wird ein neues Binding erforderlich, weil dieser Funktion
  79. ein zusätzlicher Parameter übergeben werden kann.
  80.  
  81. Deklaration:   WORD evnt_button ( WORD ev_bclicks, WORD ev_bmask,
  82.                                   WORD ev_bstate,  WORD *ev_bmx,
  83.                                   WORD *ev_bmy,    WORD *ev_bbutton,
  84.                                   WORD *ev_bkstate, WORD *ev_bwhlpbuff );
  85.  
  86.  
  87. Der Parameter ev_bwhlpbuff ist ein Zeiger auf den 16 WORDs (32 Byte) gro₧en
  88. Wheel-Puffer. Wenn in ev_bbutton Bit-7 (0x80) gesetzt ist, dann sind die
  89. Werte im Wheel-Buffer gültig. Im Wheel-Buffer wird für jedes verfügbare Rad
  90. die Drehweite (vorzeichenbehaftet) eingetragen.
  91. Soll auf ein Mausrad-Ereignis gewartet werden, dann mu₧ Bit-7 auch in
  92. ev_bmask gesetzt werden.
  93.  
  94. GEM_Arrays: control        control[0]        21    Opcode der Funktion
  95.             control+2      control[1]        3     # Einträge in int_in
  96.             control+4      control[2]        5     # Einträge in int_out
  97.             control+6      control[3]        1     # Einträge in addr_in
  98.             control+8      control[4]        0     # Einträge in addr_out
  99.  
  100.             int_in         int_in[0]         ev_bclicks
  101.             int_in+2       int_in[1]         ev_bmask
  102.             int_in+4       int_in[2]         ev_bstate
  103.  
  104.             int_out        int_out[0]        Return-Wert
  105.             int_out+2      int_out[1]        ev_bmx
  106.             int_out+4      int_out[2]        ev_bmy
  107.             int_out+6      int_out[3]        ev_bbutton
  108.             int_out+8      int_out[4]        ev_bkstate
  109.  
  110.             addr_in        addr_in[0]        ev_bwhlpbuff
  111.  
  112.  
  113. evnt_multi
  114. ----------
  115.  
  116. Für evnt_multi wird ebenfalls ein neues Binding erforderlich.
  117.  
  118. Deklaration    WORD evnt_multi ( WORD ev_mflags, WORD ev_mbclicks,
  119.                                  WORD ev_mbmask, WORD ev_mbstate,
  120.                                  WORD ev_mm1flags, WORD ev_mm1x,
  121.                                  WORD ev_mm1y, WORD ev_mm1width,
  122.                                  WORD ev_mm1height, WORD ev_mm2flags,
  123.                                  WORD ev_mm2x, WORD ev_mm2y,
  124.                                  WORD ev_mm2width, WORD ev_mm2height,
  125.                                  WORD *ev_mmgpbuff, WORD ev_mtlocount,
  126.                                  WORD ev_mthicount, WORD *ev_mmox,
  127.                                  WORD *ev_mmoy, WORD *ev_mmbutton,
  128.                                  WORD *ev_mmokstate, WORD *ev_mkreturn,
  129.                                  WORD *ev_mbreturn, WORD *ev_mwhlpbuff );
  130.  
  131. Auch evnt_multi wird wie schon evnt_button um einen Parameter erweitert.
  132. ev_mwhlpbuff entspricht hierbei ev_bwhlpbuff bei evnt_button.
  133.  
  134. GEM_Arrays: control        control[0]        25    Opcode der Funktion
  135.             control+2      control[1]        16    # Einträge in int_in
  136.             control+4      control[2]        7     # Einträge in int_out
  137.             control+6      control[3]        2     # Einträge in addr_in
  138.             control+8      control[4]        0     # Einträge in addr_out
  139.  
  140.             int_in         int_in[0]         ev_mflags
  141.             int_in+2       int_in[1]         ev_mbclicks
  142.             int_in+4       int_in[2]         ev_mbmask
  143.             int_in+6       int_in[3]         ev_mbstate
  144.             int_in+8       int_in[4]         ev_mm1flags
  145.             int_in+10      int_in[5]         ev_mm1x
  146.             int_in+12      int_in[6]         ev_mm1y
  147.             int_in+14      int_in[7]         ev_mm1width
  148.             int_in+16      int_in[8]         ev_mm1height
  149.             int_in+18      int_in[9]         ev_mm2flags
  150.             int_in+20      int_in[10]        ev_mm2x
  151.             int_in+22      int_in[11]        ev_mm2y
  152.             int_in+24      int_in[12]        ev_mm2width
  153.             int_in+26      int_in[13]        ev_mm2height
  154.             int_in+28      int_in[14]        ev_mtlocount
  155.             int_in+30      int_in[15]        ev_mthicount
  156.  
  157.             int_out        int_out[0]        Return-Wert
  158.             int_out+2      int_out[1]        ev_mmox
  159.             int_out+4      int_out[2]        ev_mmoy
  160.             int_out+6      int_out[3]        ev_mmbutton
  161.             int_out+8      int_out[4]        ev_mmokstate
  162.             int_out+10     int_out[5]        ev_mkreturn
  163.             int_out+12     int_out[6]        ev_mbreturn
  164.  
  165.             addr_in        addr_in[0]        ev_mmgpbuff
  166.             addr_in+4      addr_in[1]        ev_mwhlpbuff
  167.  
  168.  
  169.  
  170. Für Hardware-Maustreiber-Programmierer
  171. ======================================
  172.  
  173. MWheel trägt sich in den Cookie-Jar ein und verwendet dabei die ID 'MWHL'.
  174. Der Cookie-Wert ist ein Zeiger auf folgende Struktur:
  175.  
  176. typedef struct
  177. {
  178.     WORD    mwhl_version;
  179.     char*    mwhl_info;
  180.     WORD    (*mwhl_wheeled)(WORD Value[16]);
  181.     WORD    (*mwhl_service)(LONG Opcode, ...);
  182.     WORD    mwhl_wheels;
  183.     LONG    mwhl_control;
  184.     WORD    mwhl_step[16];
  185.     WORD    mwhl_direction;
  186.     WORD    mwhl_delay;
  187. }MWHL_Cookie;
  188.  
  189. mhwl_version:     Version von MHweel im BCD Format (z.B. 0x0100 für v1.00)
  190.  
  191. mhwl_info:        Nullterminierter String mit Programminformationen
  192.  
  193. mwhl_wheeled:     Diese Funktion mu₧ ein Hardware-Treiber aufrufen um die
  194.                   Rad-Ereignisse einzuspeisen. Die Funktion erwartet nach
  195.                   C-Konvention die Parameter auf dem Stack übergeben (in
  196.                   Pure-C schreibt man dafür "cdecl"). Der Rückgabewert wird
  197.                   wie in C üblich über das Register D0 zurückgeliefert. Die
  198.                   Funktion kann - nach C-Konvention - die Register
  199.                   D0,D1,D2,A0 und A1 verändern.
  200.  
  201.                   Value:  Ist ein Zeiger auf 16 WORDs, die die Drehweiten
  202.                           enthalten.
  203.  
  204.                   Return: Wurden die Drehweiten angenommen, dann liefert
  205.                           mwhl_wheeled E_OK. Anderenfalls ist ein Fehler
  206.                           aufgetreten.
  207.  
  208. mwhl_service:      Für diese Funktionen gelten die gleichen
  209.                         Aufruf-Konventionen wie bei mwhl_wheeled. Diese Funktion
  210.                         hat eine variable Anzahl von Parametern (abhängig von
  211.                         Opcode).
  212.  
  213.                    mwhl_service ist z.Z. ohne Funktion.
  214.  
  215.                    Opcode: Legt fest, was die Funktion machen soll.
  216.  
  217.                    Return: von Opcode abhängig
  218.  
  219. mwhl_wheels:       Ein Bit-Vektor der verfügbaren Mausräder. Dieser
  220.                    Bit-Vektor wird bei appl_getinfo Opcode 8 in ap_gout3
  221.                    zurückgegeben. Ein Maus-Treiber mu₧ hier die
  222.                    entsprechenden Bits der von ihm unterstützten Räder
  223.                    setzen.
  224.  
  225. mwhl_control:      Für diverse Einstellungen
  226.  
  227.                    Bit-0  schaltet WM_ARROWED-Emulation Ein bzw. Aus
  228.  
  229. mwhl_step[16]:     Für jedes Rad kann eine Scrollweite angegeben werden, die
  230.                    bei einem Dreh gemeldet werden soll. Praktisch wird
  231.                    einfach die Drehweite, die mit mwhl_wheeled gemeldet
  232.                    wird, mit den Werten aus mwhl_step multipliziert.
  233.                    Allerdings gilt das nur für Drehs innerhalb der
  234.                    Delay-Zeit (siehe mwhl_delay). Daduch kann man durch
  235.                    langsames Drehen des Rads fein scrollen.
  236.  
  237. mwhl_direction:    Legt die Richtung der Radereignisse fest. Wird z.B. Bit-0
  238.                    gesetzt, dann wird auch die Richtung von Rad-0 umgedreht.
  239.  
  240. mwhl_delay:        Da eine Raddrehung wie ein Mausklick behandelt wird, wird
  241.                    sie auch etwas verzögert gemeldet (Mausklicks werden in
  242.                    der Regel verzögert gemeldet, damit das System
  243.                    Doppelklicks registrieren kann). Um ein "Ruckeln" zu
  244.                    vermeiden, wartet MWheel (wenn es ein Radereignis
  245.                    gemeldet hat) direkt auf einen weiteren Dreh, der dann
  246.                    ohne verzögerung weitergemeldet wird. Diese Wartezeit
  247.                    wird mit mwhl_delay festgelegt (in ms).
  248.  
  249.  
  250. Guideline
  251. =========
  252.  
  253. Grundsätzlich sollte die Applikation kontextabhängig entscheiden, was mit
  254. den gemeldeten Raddrehungen passieren soll und welches Rad (wenn es denn
  255. mehrere gibt) für welche Aufgabe verwendet werden soll.
  256.  
  257. Trotzdem möchte ich hier ein paar grundlegende Richtlinien vorgeben (an die
  258. sich ein Programm aber nicht unbedingt halten mu₧ aber sollte).
  259.  
  260. - Raddrehungen werden mit vorzeichenbehaftete Drehweiten gemeldet. Für das
  261.   Scrollen gilt folgendes:
  262.   - positive Werte scrollen nach oben bzw. rechts
  263.   - negative Werte scrollen nach unten bzw. links
  264.  
  265. - das Rad 0 ist das Haupt-Rad und ist universell (kontextabhängig)
  266.  
  267. - den Rädern 1-15 werden feste Funktionen zugeordnet
  268.  
  269. - Rad 0 ist standardmä₧ig für das vertikale scrollen verantwortlich
  270.  
  271.   - der Kontext "Control-Taste" schaltet auf horizontales scrollen um
  272.  
  273. - Rad 1 ist für das horizontale scrollen verantwortlich
  274.  
  275. - Räder 2-15 sind noch unbelegt
  276.  
  277.  
  278. Fragen und Antworten
  279. ====================
  280.  
  281. F:  Was passiert mit Programmen, die nicht das neue Binding verwenden?
  282.  
  283. A:  Wenn diese Programme evnt_multi verwenden und auf ein Message-Ereignis
  284.     (MU_MESAG) warten, dann bekommen sie von MWheel WM_ARROWED-Nachrichten
  285.     untergeschoben. Dieses Verhalten kann mit dem CPX-Modul abgeschaltet
  286.     werden.
  287.  
  288.  
  289. F:  Funktioniert MWheel auf jeder TOS-Plattform?
  290.  
  291. A:  Ich gehe einmal stark davon aus. Getestet habe ich MWheel allerdings nur
  292.     mit MagiC und einem ATARI 1040 STFM mit TOS 1.02
  293.  
  294.  
  295.  
  296. History
  297. =======
  298.  
  299. V1.01, 19.1.2002
  300. ----------------
  301.  
  302. - 2. Rad scrollt jetzt in beide Richtungen
  303.  
  304. V1.0, 17.12.2001
  305. ----------------
  306.  
  307. - Erste Version
  308.  
  309.  
  310. Viel Spa₧ mit MWheel,
  311. Armin Diedering
  312.