BlitzMax/Modules/User input/Polled input

The polled input module provides an easy way to detect keyboard and mouse input.

The functions in this module are only available when your program is running in Graphics mode. When working on GUI applications, you should use events instead.

=Functions=

AppSuspended
Function AppSuspended

Description: Get app suspended state

Returns: True if application is currently suspended.

AppTerminate
Function AppTerminate

Description: Return app terminate state

Returns: True if user has requested to terminate application

Example:

Graphics 640,480,0

While Not AppTerminate Or Not Confirm( "Terminate?" )

Cls DrawText MouseX+","+MouseY,0,0 Flip

Wend

KeyHit
Function KeyHit( key )

Description: Check for key hit

Returns: Number of times key has been hit.

Information: The returned value represents the number of the times key has been hit since the last call to KeyHit with the same key.

See the key codes module for a list of valid key codes.

Example: ' keyhit.bmx

' the following code draws a circle every time the ' program detects the spacebar has been pressed ' and exits when it detects the ESCAPE key has ' been pressed

graphics 640,480 while not keyhit(KEY_ESCAPE) cls if keyhit(KEY_SPACE) drawoval 0,0,640,480 flip wend

KeyDown
Function KeyDown( key )

Description: Check for key state

Returns: True if key is currently down

Information: See the key codes module for a list of valid keycodes.

Example: ' keydown.bmx

' the following code draws a circle if the ' program detects the spacebar is pressed ' and exits when it detects the ESCAPE key has ' been pressed

Graphics 640,480 While Not KeyHit(KEY_ESCAPE) Cls If KeyDown(KEY_SPACE) DrawOval 0,0,640,480 Flip Wend

GetChar
Function GetChar

Description: Get next character

Returns: The character code of the next character.

Information: As the user hits keys on the keyboard, BlitzMax records the character codes of these keystrokes into an internal 'character queue'.

GetChar removes the next character code from this queue and returns it the application.

If the character queue is empty, 0 is returned.

FlushKeys
Function FlushKeys

Description: Flush key states and character queue.

Information: FlushKeys resets the state of all keys to 'off', and resets the character queue used by GetChar.

MouseX
Function MouseX

Description: Get mouse x location

Returns: Mouse x axis location

Information: The returned value is relative to the left of the screen.

Example: ' mousex.bmx

' the following tracks the position of the mouse

graphics 640,480 while not keyhit(KEY_ESCAPE) cls drawoval mousex-10,mousey-10,20,20 flip wend

MouseY
Function MouseY

Description: Get mouse y location

Returns: Mouse y axis location

Information: The returned value is relative to the top of the screen.

Example: ' mousey.bmx

' the following tracks the position of the mouse

graphics 640,480 while not keyhit(KEY_ESCAPE) cls drawrect mousex-10,mousey-10,20,20 flip wend

MouseZ
Function MouseZ

Description: Get mouse wheel

Returns: Mouse wheel value

Information: The mouse wheel value increments when the mouse wheel is rolled 'away' from the user, and decrements when the mouse wheel is rolled 'towards' the user.

Example: ' mousez.bmx

' prints mousez the mousewheel position

Graphics 640,480 While Not keyhit(KEY_ESCAPE) cls drawtext "MouseZ="+MouseZ,0,0 flip Wend

MouseXSpeed
Function MouseXSpeed

Description: Get mouse x speed

Returns: Mouse x speed

MouseYSpeed
Function MouseYSpeed

Description: Get mouse y speed

Returns: Mouse y speed

MouseZSpeed
Function MouseZSpeed

Description: Get mouse z speed

Returns: Mouse z speed

FlushMouse
Function FlushMouse

Description: Flush mouse button states

Information: FlushMouse resets the state of all mouse buttons to 'off'.

MouseHit
Function MouseHit( button )

Description: Check for mouse button click

Returns: Number of times button has been clicked.

Information: The returned value represents the number of the times button has been clicked since the last call to MouseHit with the same button.

button should be 1 for the left mouse button, 2 for the right mouse button or 3 for the middle mouse button.

Example: ' mousehit.bmx

graphics 640,480

while not keyhit(KEY_ESCAPE) cls if mousehit(1) drawrect 0,0,200,200 if mousehit(2) drawrect 200,0,200,200 if mousehit(3) drawrect 400,0,200,200 flip wend

MouseDown
Function MouseDown( button )

Description: Check for mouse button down state

Returns: True if button is currently down

Information: button should be 1 for the left mouse button, 2 for the right mouse button or 3 for the middle mouse button.

Example: ' mousedown.bmx

graphics 640,480

while not keyhit(KEY_ESCAPE) cls if mousedown(1) drawrect 0,0,200,200 if mousedown(2) drawrect 200,0,200,200 if mousedown(3) drawrect 400,0,200,200 flip wend

WaitKey
Function WaitKey

Description: Wait for a key press

Returns: The keycode of the pressed key

Information: WaitKey suspends program execution until a key has been hit. The keycode of this key is then returned to the application.

See the key codes module for a list of valid keycodes.

WaitChar
Function WaitChar

Description: Wait for a key press

Returns: The character code of the pressed key

Information: WaitChar suspends program execution until a character is available from GetChar. This character is then returned to the application.

WaitMouse
Function WaitMouse

Description: Wait for mouse button click

Returns: The clicked button

Information: WaitMouse suspends program execution until a mouse button is clicked.

WaitMouse returns 1 if the left mouse button was clicked, 2 if the right mouse button was clicked or 3 if the middle mouse button was clicked.