@database CadOS input handling @node main "CadOS.input functions" TABLE OF CONTENTS @{" CadOS.input/SetMouseLimits " link SetMouseLimits} @{" CadOS.input/GetMouse " link GetMouse} @{" CadOS.input/ReadKey " link ReadKey} @{" CadOS.input/CheckKey " link CheckKey} @{" CadOS.input/FlushKeyboard " link FlushKeyboard} @{" CadOS.input/TranslateKey " link TranslateKey} @endnode @node SetMouseLimits CadOS.input/SetMouseLimits CadOS.input/SetMouseLimits NAME SetMouseLimits() SYNOPSIS SetMouseLimits(xmin,ymin,xmax,ymax) D0.w D1.w D2.w D3.w DESCRIPTION This sets the range of coordinates the mouse is allowed to travel through. You should always set this before using GetMouse(), or you will inherit the last used values, which could be anything. The actual starting coordinates for the mouse will always be (0,0), which you can take advantage of. As an example, you could map the mouse to area (0,0) (319,255) - or you could have (-160,-128) (159,127) which would centre the mouse in the middle of the coordinates. INPUTS xmin - The minimum X coordinate of the mouse. Can be negative. ymin - The minimum Y coordinate of the mouse. Can be negative. xmax - The maximum X coordinate of the mouse. Can be negative. ymax - The maximum Y coordinate of the mouse. Can be negative. RESULT nothing - the mouse limits are set EXAMPLE This example shows the use of the mouse routines for debugging - the programmer can waggle the mouse to try different values for DDFSTOP, on exit the returncode is the final one he chose. moveq #42,d0 move.w #250,d2 ; x ranges from 42 to 250 moveq #0,d1 ; y always equals 0 moveq #0,d3 jsr _SetMouseLimits .loop vsync jsr _GetMouse move.w d0,_custom+ddfstop btst.b #6,$bfe001 bne.s .loop move.l d0,retcode rts SEE ALSO @{" GetMouse " link GetMouse} @endnode @node GetMouse CadOS.input/GetMouse CadOS.input/GetMouse NAME GetMouse() SYNOPSIS xcoord, ycoord=GetMouse() D0.w D1.w DESCRIPTION This reads the latest movements of the mouse in the mouse port, to the mouse limits defined by SetMouseLimits(). Note that GetMouse does not give you an onscreen pointer of any sort - you have to provide one by yourself. RESULT xcoord - The X coordinate of the mouse ycoord - The Y coordinate of the mouse SEE ALSO @{" SetMouseLimits " link SetMouseLimits} @endnode @node ReadKey CadOS.input/ReadKey CadOS.input/ReadKey NAME ReadKey() SYNOPSIS rawkey = ReadKey() D0 DESCRIPTION This reads the keyboard, returning the latest key pressed or -1 to signify that no key has been pressed since it was last called. ReadKey does not actually wait until a user presses a key - it will return the latest rawcode ONLY if a new one has arrived from the keyboard. It will return -1 if no new key is here. It is a long -1, but you can also interpret it as a unsigned byte $FF if you wish, as you will never recieve an actual rawcode $FF. ReadKey understands special rawcodes $78,$F9-$FF from the keyboard and will not pass them on to you. ReadKey also updates a key up/down array that you can read with CheckKey. You are advised not to use the results of this for a keyboard-entry routine, you should use TranslateKey to turn the rawcodes into ASCII, as they will handle all keyboards (german z and y, Alt-F + e == é, etc), but with this routine on its own you can catch the 'special' keys, such as the cursor keys, delete, help and the function keys. NOTE You must seperate calls to ReadKey by at least 480 microseconds, possibly by using the CauseDelay call, or limiting your calls to once a frame. ReadKey makes a short indivisible 90ms CIAA-timed delay after reading the keyboard, to handshake with the keyboard. All interrupts are disabled during this time. ReadKey will, on Reset Warning from the Keyboard, halt all DMA and interrupts, and will immediately reset the Amiga with ColdReboot() RESULT rawkey - Most of the time, -1 will be returned, signifying that there is no new key pressed to read. Otherwise it will return the raw code of the latest key to be pressed or released. It will be in the range $00-$f8, if the key is <$80, then the key has been pressed, see CadOS.i for a list of raw keycodes, if the key is >=$80, then key-$80 is the keycode, but the key has been released. BUGS Due to a bug, spurious $00 rawcodes were returned, so I have disabled returning $00 rawcodes, which means the downpress of apostrope/tilde key will be lost. SEE ALSO @{" TranslateKey " link TranslateKey}, @{" CheckKey " link CheckKey}, @{" CadOS.system/CauseDelay " link CadOS_system.guide/CauseDelay} @endnode @node CheckKey CadOS.input/CheckKey CadOS.input/CheckKey NAME CheckKey() SYNOPSIS result = CheckKey(rawkey) D0 D0 DESCRIPTION This reads the keyboard, returning 1 if the rawkey requested is being held down, or 0 if it is not. INPUTS rawkey - The key to check the up/down status of RESULT result - 1 if rawkey is held down, 0 if not NOTE ReadKey is responsible for setting the status of flags that CheckKey looks at. You should call ReadKey at least once before calling CheckKey SEE ALSO @{" ReadKey " link ReadKey} @endnode @node FlushKeyboard CadOS.input/FlushKeyboard CadOS.input/FlushKeyboard NAME FlushKeyboard() SYNOPSIS void FlushKeyboard() DESCRIPTION This "flushes" the keyboard, it reads the keyboard until there are no more keys to read, it discards all the keys it has read. It uses CauseDelay(341) between calls to ReadKey. RESULT none - keyboard is flushed SEE ALSO @{" ReadKey " link ReadKey}, @{" CadOS.system/CauseDelay " link CadOS_system.guide/CauseDelay} @endnode @node TranslateKey CadOS.input/TranslateKey CadOS.input/TranslateKey NAME TranslateKey() SYNOPSIS key = TranslateKey(rawkey) D0 D0 DESCRIPTION This translates a rawkey to an ISO-Latin1 character (the Amiga's normal character set, codes 0-127 are ASCII, codes 128-255 are the foreign letters), it uses keymap.library/MapRawKey with the global keymap, as set by the user. INPUTS rawkey - A rawkey from ReadKey RESULT result - A ISO-Latin1 character from 1-255, or 0 if no key. NOTE Takes all the modifier and dead-keys into effect, using CheckKey. Don't feed in fake values or you'll get crap results. EXAMPLE Keyboard input routine lea keybuffer,a0 .again vsync jsr do_my_screen_update jsr _ReadKey cmp.b #-1,d0 beq.s .again cmp.b #KEY_RETURN,d0 beq.s .exit jsr _TranslateKey tst.b d0 beq.s .noput move.b d0,(a0)+ .noput cmp.l #keybuffer+BUFFERSIZE-1,a0 bne.s .exit .exit move.b #0,(a0)+ rts SEE ALSO @{" ReadKey " link ReadKey}, @{" CheckKey " link CheckKey} @endnode