UnbindKey: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(Added note about annoying bug that causes an hour lost debugging.)
 
(25 intermediate revisions by 14 users not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__
{{Server client function}}
Removes an existing key bind from the specified player.
Removes an existing key bind from the specified player.
Note: will remove all the binds from the current key if no command is specified
{{Note|unbindKey will only work on binds that were added by the same resource}}
 
{{Note|unbindKey on the server may return ''true'' on failure}}
{{Note|If you call unbindKey twice, it will break other scripts: [https://github.com/multitheftauto/mtasa-blue/issues/497 Issue 497]}}
==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">unbindKey ( player thePlayer, string key, [ string keyState, string command ] ) </syntaxhighlight>  
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool unbindKey ( player thePlayer, string key, string keyState, string command )
</syntaxhighlight>
<syntaxhighlight lang="lua">
bool unbindKey ( player thePlayer, string key [, string keyState, function handler ] )
</syntaxhighlight>  


===Required Arguments===  
===Required Arguments===  
*'''thePlayer:''' The player you wish to unbind the key of.
*'''thePlayer:''' The player you wish to unbind the key of.
*'''key:''' The key you wish to unbind. See [[Key names]] for a list of valid key names.
*'''key:''' The key you wish to unbind. See [[Key names]] for a list of valid key names.
*'''keyState:''' Can be either:
**'''"up":''' If the bound key triggered a function when the key was released
**'''"down":''' If the bound key triggered a function when the key was pressed
**'''"both":''' If the bound key triggered a function when the key was pressed and released
*'''command :''' (Syntax 1) The command you wish to unbind.
===Optional Arguments===
*'''keyState:''' is optional in Syntax 2.
*'''handler:''' (Syntax 2) The function you wish to unbind.
Note: If you do not specify ''handler'', any instances of ''key'' being bound will be unbound, whatever function they are bound to.
===Returns===
Returns '''true'' if the key was unbound, ''false'' if it was not previously bound or invalid arguments were passed to the function.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool unbindKey ( string key, string keyState, string command )
</syntaxhighlight>
<syntaxhighlight lang="lua">
bool unbindKey ( string key [, string keyState, function handler ] )
</syntaxhighlight>
===Required Arguments===
*'''key:''' The key you wish to unbind. See [[Key names]] for a list of valid key names.
*'''keyState:''' Can be either:
**'''"up":''' If the bound key triggered a function when the key was released
**'''"down":''' If the bound key triggered a function when the key was pressed
**'''"both":''' If the bound key triggered a function when the key was pressed and released
*'''command :''' (Syntax 1) The command you wish to unbind.


===Optional Arguments===
===Optional Arguments===
*'''keyState:''' A string containing the word "up" or "down" determining which bind you wish to remove.
*'''keyState:''' is optional in Syntax 2.
*'''command:''' The command you wish to unbind.
*'''handler:''' (Syntax 2) The function you wish to unbind.
Note: If you do not specify ''handler'', any instances of ''key'' being bound will be unbound, whatever function they are bound to.
 
===Returns===
Returns '''true'' if the key was unbound, ''false'' if it was not previously bound or invalid arguments were passed to the function.
</section>


==Example==
==Example==
This function will bind a player's 'F1' key-down to a command when they spawn, then remove it after it's been used once.
<section name="Server" class="server" show="true">
This function binds the player's ''F1'' key to a function ''goMoo'' which outputs a chat message when pressed. The key is then unbound so that it can effectively only be used once per life.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
addEventHandler ( "onPlayerSpawn", getRootElement(), "playerSpawn" ) -- make the playerSpawn function be called when a player spawns
-- define the function that will be called when F1 is pressed
function playerSpawn ( )
function goMoo( player )
  bindKey ( source, "F1", "down", "moo" ) -- bind the player's F1 key to the console function called 'moo'
    outputChatBox ( getPlayerName ( player ) .. " says Mooooooo!" )
    unbindKey ( player, "F1", "down", goMoo )   -- this function will no longer be triggered by the player, after removing the bind.
end
end


addCommandHandler ( "moo", "consoleMoo" ) -- create a console function called moo that triggers the function 'consoleMoo'
function playerSpawn ( )
function consoleMoo ( )
    bindKey ( source, "F1", "down", goMoo ) -- bind the player's F1 key to the 'goMoo' function defined above
  outputChatBox ( getClientName ( source ).." says Mooooooo!" )
  unbindKey ( source, "F1", "down", "moo" ) -- this function will no longer be triggered by the player, after removing the bind.
end
end
addEventHandler ( "onPlayerSpawn", root, playerSpawn ) -- make the playerSpawn function be called when a player spawns
</syntaxhighlight>
</syntaxhighlight>
</section>


==See Also==
==See Also==
{{Input functions}}
{{Input functions}}
[[pt-br:unbindKey]]

Latest revision as of 17:42, 29 July 2021

Removes an existing key bind from the specified player.

[[{{{image}}}|link=|]] Note: unbindKey will only work on binds that were added by the same resource
[[{{{image}}}|link=|]] Note: unbindKey on the server may return true on failure
[[{{{image}}}|link=|]] Note: If you call unbindKey twice, it will break other scripts: Issue 497

Syntax

Click to collapse [-]
Server
bool unbindKey ( player thePlayer, string key, string keyState, string command )
bool unbindKey ( player thePlayer, string key [, string keyState, function handler ] )

Required Arguments

  • thePlayer: The player you wish to unbind the key of.
  • key: The key you wish to unbind. See Key names for a list of valid key names.
  • keyState: Can be either:
    • "up": If the bound key triggered a function when the key was released
    • "down": If the bound key triggered a function when the key was pressed
    • "both": If the bound key triggered a function when the key was pressed and released
  • command : (Syntax 1) The command you wish to unbind.

Optional Arguments

  • keyState: is optional in Syntax 2.
  • handler: (Syntax 2) The function you wish to unbind.

Note: If you do not specify handler, any instances of key being bound will be unbound, whatever function they are bound to.

Returns

Returns 'true if the key was unbound, false if it was not previously bound or invalid arguments were passed to the function.

Click to collapse [-]
Client
bool unbindKey ( string key, string keyState, string command )
bool unbindKey ( string key [, string keyState, function handler ] )

Required Arguments

  • key: The key you wish to unbind. See Key names for a list of valid key names.
  • keyState: Can be either:
    • "up": If the bound key triggered a function when the key was released
    • "down": If the bound key triggered a function when the key was pressed
    • "both": If the bound key triggered a function when the key was pressed and released
  • command : (Syntax 1) The command you wish to unbind.

Optional Arguments

  • keyState: is optional in Syntax 2.
  • handler: (Syntax 2) The function you wish to unbind.

Note: If you do not specify handler, any instances of key being bound will be unbound, whatever function they are bound to.

Returns

Returns 'true if the key was unbound, false if it was not previously bound or invalid arguments were passed to the function.

Example

Click to collapse [-]
Server

This function binds the player's F1 key to a function goMoo which outputs a chat message when pressed. The key is then unbound so that it can effectively only be used once per life.

-- define the function that will be called when F1 is pressed
function goMoo( player )
    outputChatBox ( getPlayerName ( player ) .. " says Mooooooo!" )
    unbindKey ( player, "F1", "down", goMoo )   -- this function will no longer be triggered by the player, after removing the bind.
end

function playerSpawn ( )
    bindKey ( source, "F1", "down", goMoo ) -- bind the player's F1 key to the 'goMoo' function defined above
end
addEventHandler ( "onPlayerSpawn", root, playerSpawn ) -- make the playerSpawn function be called when a player spawns

See Also