Module mojo.input

The input module allows programs to check for user input from a wide variety of devices such keyboards, mice, joysticks and touchsceens. More...

Declarations

Imports
`mojo.keycodes`	The keycodes module contains keyboard and input related constants.

Imported By
`mojo` , `mojo.app` , `mojo2`

Please note that only documented modules are listed here, there might be undocumented modules that import this one.

Functions
`AccelX : Float ()`	Returns the x compononent of the acceleration applied to the device, as measured by the device's accelerometer if present.
`AccelY : Float ()`	Returns the y compononent of the acceleration applied to the device, as measured by the device's accelerometer if present.
`AccelZ : Float ()`	Returns the z compononent of the acceleration applied to the device, as measured by the device's accelerometer if present.
`CountJoysticks : Int ( update:Bool=True )`	Returns the number of connected joysticks.
`DisableKeyboard : Int ()`	On the android and ios targets, this function disables the native virtual keyboard.
`EnableKeyboard : Int ()`	On the android and ios targets, this function enables the native virtual keyboard.
`GetChar : Int ()`	Returns the character code of the next character in the keyboard character queue, or 0 if no more characters are available.
`GetClipboard : String ()`	Returns the text that is stored inside the clipboard.
`JoyDown : Int ( button:Int, unit:Int=0 )`	Return 1 if the specified joystick button is currently held down, else 0.
`JoyHit : Int ( button:Int, unit:Int=0 )`	Return the number of times the specified joystick button has been pressed since the last OnUpdate.
`JoyX : Float ( index:Int=0, unit:Int=0 )`	Returns the x, or horizontal, state of a joystick.
`JoyY : Float ( index:Int=0, unit:Int=0 )`	Returns the y, or vertical, state of a joystick.
`JoyZ : Float ( index:Int=0, unit:Int=0 )`	On Playstation/Xbox style controllers, JoyZ returns the state of the analog shoulder controls.
`KeyDown : Int ( key:Int )`	Returns 1 if the specified key is currently held down, otherwise 0.
`KeyHit : Int ( key:Int )`	Returns the number of times the specified key has been hit since the last OnUpdate.
`MouseDown : Int ( button:Int )`	Returns 1 if the specified mouse button is currently held down, otherwise 0.
`MouseHit : Int ( button:Int )`	Returns the number of times the specified mouse button has been pressed since the last OnUpdate.
`MouseX : Float ()`	Returns the x coordinate of the mouse pointer.
`MouseY : Float ()`	Returns the y coordinate of the mouse pointer.
`MouseZ : Float ()`	Returns 1 or -1 if the mouse wheel was used since last update.
`PeekChar : Int ( index:Int )`	Returns the character of the character at the specified index in the keyboard character queue.
`SetClipboard : Void ( _text:String )`	Sets the clipboard text.
`SetMousePos : Void ( _x:Int, _y:Int )`	Sets the coordinates of the mouse pointer in the devices window.
`TouchDown : Int ( index:Int )`	Returns 1 if the finger specified by index is currently touching the touchscreen, otherwise 0.
`TouchHit : Int ( index:Int )`	Returns the number of times the specified finger has made contact with the touchscreen since the last OnUpdate.
`TouchX : Float ( index:Int )`	Returns the x coordinate of the finger on a touch screen device.
`TouchY : Float ( index:Int )`	Returns the y coordinate of the finger on a touch screen device.

Detailed Discussion

The input module allows programs to check for user input from a wide variety of devices such keyboards, mice, joysticks and touchsceens.

The input module uses a 'polling' input model, meaning that your program must continually check (or 'poll') the state of input devices. Polling should be performed during the OnUpdate phase of your program.

Please see the Key codes page for a full list of keyboard, mouse and joystick constants.

Functions Documentation

Function AccelX : Float ()

Returns the x compononent of the acceleration applied to the device, as measured by the device's accelerometer if present.

The value returned is in the range -1 to 1 inclusive.

If the device has no accelerometer, 0 is returned.

Accelerometer functionality is currently only available on the android, html5 and ios targets.

Function AccelY : Float ()

Returns the y compononent of the acceleration applied to the device, as measured by the device's accelerometer if present.

The value returned is in the range -1 to 1 inclusive.

If the device has no accelerometer, 0 is returned.

Accelerometer functionality is currently only available on the andriod, html5 and ios targets.

Function AccelZ : Float ()

Returns the z compononent of the acceleration applied to the device, as measured by the device's accelerometer if present.

The value returned is in the range -1 to 1 inclusive.

If the device has no accelerometer, 0 is returned.

Accelerometer functionality is currently only available on the android,html5 and ios targets.

Function CountJoysticks : Int ( update:Bool=True )

Returns the number of connected joysticks.

This function is only currently supported for the glfw3 and html5 target. It will return 0 for all other targets.

If update is true, then the OS is queried to determine the number of joysticks connected. This can be slow, so should be done sparringly.

If update is false, then CountJoysticks() returns the result of the last OS query. The OS is always queried the first time CountJoysticks is called.

Function DisableKeyboard : Int ()

On the android and ios targets, this function disables the native virtual keyboard. On all other targets, both EnableKeyboard and DisableKeyboard have no effect.

See also

EnableKeyboard

Function EnableKeyboard : Int ()

On the android and ios targets, this function enables the native virtual keyboard. On all other targets, both EnableKeyboard and DisableKeyboard have no effect.

A virtual keyboard is a graphical representation of a keyboard overlaid on the display that allows users to enter text by means of touching symbols representing keys.

After enabling the virtual keyboard, you program will be able to use GetChar to receive keystrokes, just as if there were a real keyboard present. It is up to the program to eventually call DisableKeyboard when appropriate, for example, when GetChar returns 13 (ie: the 'Enter' key) or 27 (ie: the 'Esc' key).

On the GLFW, HTML5, Flash and XNA (Windows) targets, keyboard support is always assumed to be available and your program can always use GetChar to receive keystrokes.

On the XNA XBOX and Windows Phone 7 targets, keyboard support is currently unavailable.

See also

DisableKeyboard

Function GetChar : Int ()

Returns the character code of the next character in the keyboard character queue, or 0 if no more characters are available. The character is removed from the keyboard character queue.

The keyboard queue contains characters codes as opposed to the key codes used by KeyDown and KeyUp. Character codes differ from key codes in that they are generally printable and may be modified by the shift, control and alt keys. Character codes also 'repeat' at a rate determined by the OS.

The mapping from key codes to character codes is controlled by the underlying OS, but in practice will generally map to ASCII codes.

The input module also provides special character code mappings for a number of unprintable keys:

CHAR_TAB, CHAR_BACKSPACE, CHAR_ENTER, CHAR_ESCAPE, CHAR_PAGEUP, CHAR_PAGEDOWN, CHAR_END, CHAR_HOME, CHAR_LEFT, CHAR_UP, CHAR_RIGHT, CHAR_DOWN, CHAR_INSERT, CHAR_DELETE

Example

Import mojo

Class MyApp Extends App

Field text$="Type something:"

Method OnCreate()
SetUpdateRate 30
End

Method OnUpdate()
Repeat
Local char=GetChar()
If Not char Exit
If char>=32
text+=String.FromChar( char )
Endif
Forever
End

Method OnRender()
Cls
DrawText text,0,0
End
End

Function Main()
New MyApp
End

Function GetClipboard : String ()

Returns the text that is stored inside the clipboard.

Please note that clipboard can be prefilled from other programs. If you want it to be empty, sent an empty string via SetClipboard.

Works only for GLFW and on the Android target.

Function JoyDown : Int ( button:Int, unit:Int=0 )

Return 1 if the specified joystick button is currently held down, else 0.

The button parameter should be one of the following constants:

Joystick button	Description
JOY_A	'A' on Xbox 360 controller, 'Cross' on PS3
JOY_B	'B' on Xbox 360 controller, 'Circle' on PS3
JOY_X	'X' on XBox 360 controller, 'Square' on PS3
JOY_Y	'Y' on XBox 360 controller, 'Triangle' on PS3
JOY_LB	Left shoulder button
JOY_RB	Right Shoulder button
JOY_BACK	'Back' on Xbox 360 controller, 'Select' on PS3
JOY_START	Start button
JOY_LEFT	Directional pad Left button
JOY_UP	Directional pad Up button
JOY_RIGHT	Directional pad Right button
JOY_DOWN	Directional pad Down button
JOY_LSB	Left stick button
JOY_RSB	Right stick button
JOY_MENU	Menu button

See also

JoyHit

Function JoyHit : Int ( button:Int, unit:Int=0 )

Return the number of times the specified joystick button has been pressed since the last OnUpdate.

The button parameter should be one of the following constants:

Joystick button	Description
JOY_A	'A' on Xbox 360 controller, 'Cross' on PS3
JOY_B	'B' on Xbox 360 controller, 'Circle' on PS3
JOY_X	'X' on XBox 360 controller, 'Square' on PS3
JOY_Y	'Y' on XBox 360 controller, 'Triangle' on PS3
JOY_LB	Left shoulder button
JOY_RB	Right Shoulder button
JOY_BACK	'Back' on Xbox 360 controller, 'Select' on PS3
JOY_START	Start button
JOY_LEFT	Directional pad Left button
JOY_UP	Directional pad Up button
JOY_RIGHT	Directional pad Right button
JOY_DOWN	Directional pad Down button
JOY_LSB	Left stick button
JOY_RSB	Right stick button
JOY_MENU	Menu button

See also

JoyDown

Function JoyX : Float ( index:Int=0, unit:Int=0 )

Returns the x, or horizontal, state of a joystick.

The return value will be in the range -1 to +1, with -1 representing 'left' and +1 representing 'right'.

In the case of controllers with 2 joysticks, the index parameter should be 0 for the left hand joystick, or 1 for the right hand joystick.

Note: On the XNA target, JoyX, JoyY and JoyZ will all return 0 until a joystick button is pressed. This is to comply with xbox live publishing guidelines that state that it must be possible to use any of the 4 controllers to play a game. Mojo will therefore wait until a button is pressed (usually in response to a 'press button to start' style message on the title page) before deciding which controller is in use.

Function JoyY : Float ( index:Int=0, unit:Int=0 )

Returns the y, or vertical, state of a joystick.

The return value will be in the range -1 to +1, with -1 representing 'down' and +1 representing 'up'.

In the case of controllers with 2 joysticks, the index parameter should be 0 for the left hand joystick, or 1 for the right hand joystick.

Function JoyZ : Float ( index:Int=0, unit:Int=0 )

On Playstation/Xbox style controllers, JoyZ returns the state of the analog shoulder controls.

The returned value will be in the range 0 to 1, with 0 indicating 'unpressed' and 1 indicating 'fully pressed'.

The index parameter should be 0 for the left handler shoulder control, or 1 for the right hand shoulder control.

Note: On the XNA target, JoyX, JoyY and JoyZ will all return 0 until a joystick button is pressed. This is to comply with xbox live publishing guidelines that state that it must be possible to use any of the 4 controllers to play a game. Mojo will therefore wait until a controller button is pressed (usually in response to a 'press button to start' style message on the title page) before deciding which controller is in use.

Function KeyDown : Int ( key:Int )

Returns 1 if the specified key is currently held down, otherwise 0.

See also

Key codes, KeyHit

Function KeyHit : Int ( key:Int )

Returns the number of times the specified key has been hit since the last OnUpdate.

Note that any on/off style 'buttons' on any device can be read using the KeyDown and KeyHit commands. For example, to read the state of the left mouse button you can use KeyDown( KEY_LMB ) in addition to MouseDown( MOUSE_LEFT ).

See also

Key codes, KeyDown

Example

Import mojo

Class MyApp Extends App

Field lineY

Method OnCreate()
lineY=DeviceHeight()/2
SetUpdateRate 30
End

Method OnUpdate()

Local hit=KeyHit( KEY_LMB ) 'Uses KeyHit to check the left mouse button. You could also use MouseHit( MOUSE_LEFT )

If hit And MouseY()<lineY
Print "You clicked above the line."
Else If hit And MouseY()>=lineY
Print "You clicked on or below the line."
End
End

Method OnRender()
Cls
DrawLine 0,lineY,DeviceWidth(),lineY
End
End

Function Main()
New MyApp
End

Function MouseDown : Int ( button:Int )

Returns 1 if the specified mouse button is currently held down, otherwise 0.

The button parameter should be one of:

Mouse button	Description
MOUSE_LEFT	Left mouse button
MOUSE_RIGHT	Right mouse button
MOUSE_MIDDLE	Middle mouse button

See also

MouseHit

Function MouseHit : Int ( button:Int )

Returns the number of times the specified mouse button has been pressed since the last OnUpdate.

The button parameter should be one of:

Mouse button	Description
MOUSE_LEFT	Left mouse button
MOUSE_RIGHT	Right mouse button
MOUSE_MIDDLE	Middle mouse button

See also

MouseDown

Function MouseX : Float ()

Returns the x coordinate of the mouse pointer.

On devices with a touch screen but no mouse, MouseX will instead return TouchX( 0 ).

See also

MouseY, MouseZ, TouchX, SetMousePos

Example

Import mojo

Class MyApp Extends App

Method OnCreate()
SetUpdateRate 30
End

Method OnUpdate()
End

Method OnRender()
Cls
DrawText "MouseX="+MouseX+", MouseY="+MouseY,0,0
DrawCircle MouseX,MouseY,10
End
End

Function Main()
New MyApp
End

Function MouseY : Float ()

Returns the y coordinate of the mouse pointer.

On devices with a touch screen but no mouse, MouseY will instead return TouchY( 0 ).

See also

MouseX, MouseZ, TouchY, SetMousePos

Function MouseZ : Float ()

Returns 1 or -1 if the mouse wheel was used since last update.

Works only for the GLFW and HTML5 targets.

Example

Import mojo

Class MyApp Extends App

Method OnCreate()
SetUpdateRate 30
End

Method OnUpdate()
End

Method OnRender()
Cls
DrawText "MouseX="+MouseX+", MouseY="+MouseY+", MouseZ="+MouseZ,0,0
End
End

Function Main()
New MyApp
End

Function PeekChar : Int ( index:Int )

Returns the character of the character at the specified index in the keyboard character queue. The character is NOT removed from the keyboard character queue.

If there is no character at the specified index, 0 is returned.

Function SetClipboard : Void ( _text:String )

Sets the clipboard text.

Works only for GLFW and on the Android target.

Function SetMousePos : Void ( _x:Int, _y:Int )

Sets the coordinates of the mouse pointer in the devices window.

Works only for GLFW target.

See also

MouseX, MouseY, MouseZ

Function TouchDown : Int ( index:Int )

Returns 1 if the finger specified by index is currently touching the touchscreen, otherwise 0.

Note that index refers to the order touches have been made. The first finger to touch the touchscreen will be assigned index 0. If another finger then also touches the touchscreen, it will be assigned index 1 and so on.

If a finger is touching, you can get its x and y coordinates using the TouchX and TouchY commands.

On devices with a mouse but no touch screen, TouchDown( 0 ) will instead return MouseDown( MOUSE_LEFT ).

See also

TouchX, TouchY, TouchHit, MouseDown

Example

Import mojo

Class MyApp Extends App

Field touching

Method OnCreate()
SetUpdateRate 30
End

Method OnUpdate()
touching=0
For Local i=0 Until 32
If TouchDown( i ) touching+=1
Next
End

Method OnRender()
Cls
DrawText touching,0,0
End
End

Function Main()
New MyApp
End

Function TouchHit : Int ( index:Int )

Returns the number of times the specified finger has made contact with the touchscreen since the last OnUpdate.

If a finger is touching, you can get its x and y coordinates using the TouchX and TouchY commands.

On devices with a mouse but no touch screen, TouchHit( 0 ) will instead return MouseHit( MOUSE_LEFT ).

See also

TouchX, TouchY, TouchDown, MouseHit

Function TouchX : Float ( index:Int )

Returns the x coordinate of the finger on a touch screen device.

On devices with a mouse but no touch screen, TouchX( 0 ) will instead return MouseX.

See also

TouchY, TouchHit, TouchDown, MouseX

Function TouchY : Float ( index:Int )

Returns the y coordinate of the finger on a touch screen device.

On devices with a mouse but no touch screen, TouchY( 0 ) will instead return MouseY.

See also

TouchX, TouchDown, TouchHit, MouseY