BindKey: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(Added string to the handler function prototypes for consistency and clarity.)
No edit summary
(21 intermediate revisions by 17 users not shown)
Line 5: Line 5:
==Syntax==  
==Syntax==  
<section name="Server - Syntax 1" class="server" show="true">
<section name="Server - Syntax 1" class="server" show="true">
<syntaxhighlight lang="lua">bindKey ( player thePlayer, string key, string keyState, function handlerFunction,  [ var arguments, ... ] )</syntaxhighlight>
<syntaxhighlight lang="lua">bool bindKey ( player thePlayer, string key, string keyState, function handlerFunction,  [ var arguments, ... ] )</syntaxhighlight>


===Required Arguments===
===Required Arguments===
Line 24: Line 24:


{{New feature|3|1.0|
{{New feature|3|1.0|
<section name="Server - Syntax 2" class="server" show="false">
<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.
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">bindKey ( player thePlayer, string key, string keyState, string commandName, string arguments )</syntaxhighlight>
<syntaxhighlight lang="lua">bool bindKey ( player thePlayer, string key, string keyState, string commandName, [ string arguments ] )</syntaxhighlight>


===Required Arguments===
===Required Arguments===
Line 37: Line 37:
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
**'''"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.   
*'''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.
*'''arguments''' Space delimited arguments that are entered as if one was typing the command.
</section>
</section>
Line 42: Line 43:


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


===Required Arguments===
===Required Arguments===
Line 60: Line 61:


{{New feature|3|1.0|
{{New feature|3|1.0|
<section name="Client - Syntax 2" class="client" show="false">
<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.
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">bindKey ( string key, string keyState, string commandName, string arguments )</syntaxhighlight>
<syntaxhighlight lang="lua">bool bindKey ( string key, string keyState, string commandName, [ string arguments ] )</syntaxhighlight>


===Required Arguments===
===Required Arguments===
Line 78: Line 79:
===Optional Arguments===  
===Optional Arguments===  
{{OptionalArg}}  
{{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.
*'''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==
Line 86: Line 90:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
function funcInput ( player, key, keyState )
function funcInput ( player, key, keyState )
   local state = "let go of"
   outputChatBox ( getPlayerName ( player) .. " " .. (keyState == "down" and "pressed" or "released") .. " the " .. key .. " key!" )
  if ( keyState == "down" ) then
    state = "pressed"
  end
  outputChatBox ( getClientName ( player) .. " " .. state .. " the " .. key .. " key!" )
end
end


Line 107: Line 107:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
function funcInput ( key, keyState )
function funcInput ( key, keyState )
  local state = "let go of"
outputChatBox( "You " .. (keyState == "down" and "pressed" or "let go of") .. " the " .. key .. " key!" )
  if ( keyState == "down" ) then
    state = "pressed"
  end
  outputChatBox ( "You " .. state .. " the " .. key .. " key!" )
end
end


function bindTheKeys ()
function bindTheKeys ( commandName )
  bindKey ( "F1", "down", funcInput )  -- bind the player's F1 down key
bindKey( "F1", "down", funcInput )  -- bind the player's F1 down key
  bindKey ( "F1", "up", funcInput )    -- bind the player's F1 up key
bindKey( "F1", "up", funcInput )    -- bind the player's F1 up key
  bindKey ( "fire", "both", funcInput ) -- bind the player's fire down and up control
bindKey( "fire", "both", funcInput ) -- bind the player's fire down and up control
end
end
addCommandHandler ( "bindme", bindTheKeys )
addCommandHandler ( "bindme", bindTheKeys )
</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.",root,255,255,0,true)
    end
  )
end
addEventHandler ("onPlayerLogin",root,fanFunction)
</syntaxhighlight>
</syntaxhighlight>
</section>
</section>
Line 125: Line 135:
==See Also==
==See Also==
{{Input functions}}
{{Input functions}}
[[pt-br:bindKey]]

Revision as of 08:42, 4 November 2020

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

Syntax

Click to collapse [-]
Server - Syntax 1
bool bindKey ( player thePlayer, string key, string keyState, function handlerFunction,  [ var arguments, ... ] )

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:
function functionName ( player keyPresser, string key, string keyState, [ var arguments, ... ] )
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).
Click to collapse [-]
Server - Syntax 2

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.

bool bindKey ( player thePlayer, string key, string keyState, string commandName, [ string arguments ] )

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.
Click to collapse [-]
Client - Syntax 1
bool bindKey ( string key, string keyState, function handlerFunction,  [ var arguments, ... ] ) 

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
  • handlerFunction: The function that will be triggered when the player's key is pressed. This function should have the form:
function functionName ( string key, string keyState, [ var arguments, ... ] )
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).
Click to collapse [-]
Client - Syntax 2

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.

bool bindKey ( string key, string keyState, string commandName, [ string arguments ] )

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.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.

  • 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

Click to collapse [-]
Server

This example will bind a player's 'F1' key and 'fire' control to 1 input function.

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 )

Example 2

Click to collapse [-]
Client

This example will bind a player's 'F1' key and 'fire' control to 1 input function, clientside.

function funcInput ( key, keyState )
	outputChatBox( "You " .. (keyState == "down" and "pressed" or "let go of") .. " the " .. key .. " key!" )
end

function bindTheKeys ( commandName )
	bindKey( "F1", "down", funcInput )   -- bind the player's F1 down key
	bindKey( "F1", "up", funcInput )     -- bind the player's F1 up key
	bindKey( "fire", "both", funcInput ) -- bind the player's fire down and up control
end
addCommandHandler ( "bindme", bindTheKeys )
Click to collapse [-]
Server

This example says how cool is the MTA:SA is if players wants to move.

function fanFunction()
  bindKey (source,"forwards","down",
    function(player,key,state)
      outputChatBox (getPlayerName (player) .. "#FFFF00 thinks MTA:SA is so cool.",root,255,255,0,true)
    end
  )
end
addEventHandler ("onPlayerLogin",root,fanFunction)

See Also