cock.setCapture

Assumes "input capture" mode.

Function

Synopsis

cock.setCapture ( self, map, option, eventlock, updatelock, nomouse, callback )

Arguments

table self
An object to use.
string map
Control map to capture controls into.
string option
Optional. Map option to capture controls to. Will revert to defaultOption if not provided.
boolean eventlock
Optional. Specifies whether or not lock game's input event handlers during capture mode. Will use "false" if not provided.
boolean updatelock
Optional. Specifies whether or not lock game's update function during capture mode. Will use "false" if not provided.
boolean nomouse
Optional. Specifies whether or not capture mouse motion. Will use "false" if not provided.
boolean callback
Optional. Specifies whether or not call controlcaptured callback on input capture. Will use "true" if not provided.

Remarks

Locking input handlers may be necessary to avoid undesired activity during capturing the input. This includes both LÖVE and COCK input handler callbacks. Locking update function serves same purpose, but due to processing data in it, locking it is generally not desired. If you use cock.current.* fields to process user input in update function, then you are encouraged to lock it. Alternatively, make sure no such processing happens when the library is in "input capture" mode. Locking option for love.draw and other functions is not provided because it is assumed that activity in corresponding functions won't interfere with input capture.

Because mouse have normally specifically defined unique function in the game, there's an option to ignore mouse motion during input capture to ensure that none of such can be captured. If this is enabled, the libary will temporary set the mouse to the screen center, and will reset it back once input is captured. It is up to the programmer to hide and show mouse cursor before and after mouse position shifting respectively.

Not calling controlcaptured callback is equivalent to instantly binding captured input to specified map and option. Requesting to call it while having no controlcaptured callback defined is effectively equivalent to the same. Doing so if the callback is defined results in plain call to the callback with "longdata" arranged argument with no additional side-effects going along. User must manually call cock.bind to use obtained data.

NOTE: Assuming input capture mode without cancelling previous input capture mode of any other object will instantly bluescreen the game (stack overflow). This is due to internal structure. If you want capture input to several objects simultaneously, you define a controlcaptured callback that would bind obtained data across several objects, and only assume input mode once.

See also


Retrieved from "http://love2d.org/w/index.php?title=cock.setCapture&oldid=11602"