View source for BindKey

{{Server client function}}
__NOTOC__
Binds a player's key to a handler function or command, which will be called when the key is pressed. 

==Syntax== 
<section name="Server - Syntax 1" class="server" show="true">
<syntaxhighlight lang="lua">bool bindKey ( player thePlayer, string key, string keyState, function handlerFunction,  [ var arguments, ... ] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to bind the key of.
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys and [[control names]] for a list of possible controls.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''handlerFunction:''' The function that will be triggered when the player's key is pressed. This function should have the form:
:<syntaxhighlight lang="lua">function functionName ( player keyPresser, string key, string keyState, [ var arguments, ... ] )</syntaxhighlight>
:The values passed to this function are:
:*'''keyPresser:''' The player who pressed the key
:*'''key:''' The key that was pressed
:*'''keyState:''' The state of the key that was pressed, ''down'' if it was pressed, ''up'' if it was released.
:*'''arguments''' The optional arguments you specified when calling [[bindKey]] (see below).
</section>

{{New feature|3|1.0|
<section name="Server - Syntax 2" class="server" show="true">
This alternative syntax allows you to bind a key with a command.  This will also allow users to customize the control in their Settings menu.  Use in conjunction with [[addCommandHandler]] to add handler functions to the keybind.

<syntaxhighlight lang="lua">bool bindKey ( player thePlayer, string key, string keyState, string commandName, [ string arguments ] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to bind the key of.
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''commandName:''' The name of the command that the key should be binded to.  
===Optional Arguments===
*'''arguments''' Space delimited arguments that are entered as if one was typing the command.
</section>
}}

<section name="Client - Syntax 1" class="client" show="true">
<syntaxhighlight lang="lua">bool bindKey ( string key, string keyState, function handlerFunction,  [ var arguments, ... ] ) </syntaxhighlight>

===Required Arguments===
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys and [[control names]] for a list of possible controls.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
<!--*'''bindName:''' The name for this key bind when it appears in the client's settings dialog.-->
*'''handlerFunction:''' The function that will be triggered when the player's key is pressed. This function should have the form:
:<syntaxhighlight lang="lua">function functionName ( string key, string keyState, [ var arguments, ... ] )</syntaxhighlight>
:The values passed to this function are:
:*'''key:''' The key that was pressed
:*'''keyState:''' The state of the key that was pressed, ''down'' if it was pressed, ''up'' if it was released.
:*'''arguments''' The optional arguments you specified when calling [[bindKey]] (see below).
</section>

{{New feature|3|1.0|
<section name="Client - Syntax 2" class="client" show="true">
This alternative syntax allows you to bind a key with a command.  This will also allow users to customize the control in their Settings menu.  Use in conjunction with [[addCommandHandler]] to add handler functions to the keybind.

<syntaxhighlight lang="lua">bool bindKey ( string key, string keyState, string commandName, [ string arguments ] )</syntaxhighlight>

===Required Arguments===
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''commandName:''' The name of the command that the key should be binded to.  
*'''arguments''' Space delimited arguments that are entered as if one was typing the command.
</section>
}}

===Optional Arguments=== 
{{OptionalArg}} 
*'''arguments:''' Any arguments you may want to pass to the function when the key is pressed by the user. Any number of arguments of  can be specified, each being passed to the designated function. You may not pass functions.

===Returns===
Returns ''true'' if the key was bound, ''false'' otherwise.

==Example==
Example 1
<section name="Server" class="server" show="true">
This example will bind a player's 'F1' key and 'fire' control to 1 input function.
<syntaxhighlight lang="lua">
function funcInput ( player, key, keyState )
  outputChatBox ( getPlayerName ( player) .. " " .. (keyState == "down" and "pressed" or "released") .. " the " .. key .. " key!" )
end

function bindTheKeys ( player, commandName )
  bindKey ( player, "F1", "down", funcInput )   -- bind the player's F1 down key
  bindKey ( player, "F1", "up", funcInput )     -- bind the player's F1 up key
  bindKey ( player, "fire", "both", funcInput ) -- bind the player's fire down and up control
end
addCommandHandler ( "bindme", bindTheKeys )
</syntaxhighlight>
</section>

Example 2
<section name="Client" class="client" show="true">
This example will bind a player's 'F1' key and 'fire' control to 1 input function, clientside.
<syntaxhighlight lang="lua">
function funcInput ( key, keyState )
  outputChatBox ( "You " .. (keyState == "down" and "pressed" or "let go of") .. " the " .. key .. " key!" )
end
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
This example says how cool is the MTA:SA is if players wants to move.
<syntaxhighlight lang="lua">
function fanFunction()
  bindKey (source,"forwards","down",
    function(player,key,state)
      outputChatBox (getPlayerName (player) .. "#FFFF00 thinks MTA:SA is so cool.",getRootElement(),255,255,0,true)
    end
  )
end
addEventHandler ("onPlayerLogin",getRootElement(),fanFunction)
</syntaxhighlight>
</section>

==See Also==
{{Input functions}}