translators
8,445
edits
Changes
Jump to navigation
Jump to search
Modding:Modder Guide/APIs/Input (view source)
Revision as of 19:18, 2 June 2018
, 19:18, 2 June 2018create page
{{../../header}}
{{SMAPI upcoming|2.6-beta.16}}
The input API lets you check and suppress controller/keyboard/mouse state.
==Check input==
===Button state===
You can check if any controller/keyboard/mouse button is currently pressed by calling the <tt>IsDown(button)</tt> method. For example:
<source lang="c#">
bool isShiftPressed = this.Helper.Input.IsDown(SButton.LeftShift) || this.Helper.Input.IsDown(SButton.RightShift);
</source>
===Cursor position===
The <tt>GetCursorPosition()</tt> method provides the cursor position in three coordinate systems:
* <tt>ScreenPixels</tt> is the pixel position relative to the top-left corner of the visible screen, adjusted for game zoom.
* <tt>Tile</tt> is the [[Modding:Modder Guide/Game Fundamentals#Tiles|tile position]] under the cursor.
* <tt>GrabTile</tt> is the tile position that the game considers under the cursor for the purposes of clicking actions. This automatically accounts for controller mode. This may be different than <tt>Tile</tt> if that's too far from the player.
For example:
<source lang="c#">
// draw text at the cursor position
ICursorPosition cursorPos = this.Helper.Input.GetCursorPosition();
Game1.spriteBatch.DrawString(Game1.smallFont, "some text", cursorPos.ScreenPixels, Color.Black);
</source>
===Scroll wheel value===
You can get the current mouse scroll wheel value by calling the <tt>GetMouseScrollValue()</tt> method. Note that this is the ''absolute'' scroll value; it's only meaningful when comparing to a previous scroll value. For example:
<source lang="c#">
// detect when the player scrolls the mouse wheel.
// This assumes you create a custom LastScrollValue field to keep track of the previous value.
int scrollValue = this.Helper.Input.GetMouseScrollValue();
int scrollChange = scrollValue - this.LastScrollValue;
this.LastScrollValue = scrollValue;
</source>
==Input suppression==
You can prevent the game from handling any controller/keyboard/mouse button press (including clicks) by ''suppressing'' it. This suppression will remain in effect until the player releases the button. This won't prevent other mods from handling it.
For example, this will prevent the game from seeing that the <tt>LeftShift</tt> button is pressed:
<source lang="c#">
this.Helper.Input.Suppress(SButton.LeftShift);
</source>
That works for clicks too:
<source lang="c#">
this.Helper.Input.Suppress(SButton.MouseLeft);
</source>
You can also check if a button is being suppressed:
<source lang="c#">
if (this.Helper.Input.IsSuppressed(SButton.LeftShift))
// left shift button is being suppressed
</source>
==See also==
* [[../Events#Input|Input events]]
* [[Modding:Key bindings]] for a list of valid <tt>SButton</tt> values
{{SMAPI upcoming|2.6-beta.16}}
The input API lets you check and suppress controller/keyboard/mouse state.
==Check input==
===Button state===
You can check if any controller/keyboard/mouse button is currently pressed by calling the <tt>IsDown(button)</tt> method. For example:
<source lang="c#">
bool isShiftPressed = this.Helper.Input.IsDown(SButton.LeftShift) || this.Helper.Input.IsDown(SButton.RightShift);
</source>
===Cursor position===
The <tt>GetCursorPosition()</tt> method provides the cursor position in three coordinate systems:
* <tt>ScreenPixels</tt> is the pixel position relative to the top-left corner of the visible screen, adjusted for game zoom.
* <tt>Tile</tt> is the [[Modding:Modder Guide/Game Fundamentals#Tiles|tile position]] under the cursor.
* <tt>GrabTile</tt> is the tile position that the game considers under the cursor for the purposes of clicking actions. This automatically accounts for controller mode. This may be different than <tt>Tile</tt> if that's too far from the player.
For example:
<source lang="c#">
// draw text at the cursor position
ICursorPosition cursorPos = this.Helper.Input.GetCursorPosition();
Game1.spriteBatch.DrawString(Game1.smallFont, "some text", cursorPos.ScreenPixels, Color.Black);
</source>
===Scroll wheel value===
You can get the current mouse scroll wheel value by calling the <tt>GetMouseScrollValue()</tt> method. Note that this is the ''absolute'' scroll value; it's only meaningful when comparing to a previous scroll value. For example:
<source lang="c#">
// detect when the player scrolls the mouse wheel.
// This assumes you create a custom LastScrollValue field to keep track of the previous value.
int scrollValue = this.Helper.Input.GetMouseScrollValue();
int scrollChange = scrollValue - this.LastScrollValue;
this.LastScrollValue = scrollValue;
</source>
==Input suppression==
You can prevent the game from handling any controller/keyboard/mouse button press (including clicks) by ''suppressing'' it. This suppression will remain in effect until the player releases the button. This won't prevent other mods from handling it.
For example, this will prevent the game from seeing that the <tt>LeftShift</tt> button is pressed:
<source lang="c#">
this.Helper.Input.Suppress(SButton.LeftShift);
</source>
That works for clicks too:
<source lang="c#">
this.Helper.Input.Suppress(SButton.MouseLeft);
</source>
You can also check if a button is being suppressed:
<source lang="c#">
if (this.Helper.Input.IsSuppressed(SButton.LeftShift))
// left shift button is being suppressed
</source>
==See also==
* [[../Events#Input|Input events]]
* [[Modding:Key bindings]] for a list of valid <tt>SButton</tt> values