Skip to content

DOCS: Update ButtonControl API docs #2070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 4, 2024
Merged

DOCS: Update ButtonControl API docs #2070

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9bf6802
API doc update
stefanunity Dec 3, 2024
ce2ea7b
fix docs error
stefanunity Dec 4, 2024
e109c57
one more doc error fix
stefanunity Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 58 additions & 16 deletions Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ namespace UnityEngine.InputSystem.Controls
/// An axis that has a trigger point beyond which it is considered to be pressed.
/// </summary>
/// <remarks>
/// By default stored as a single bit. In that format, buttons will only yield 0
/// By default, stored as a single bit. In that format, buttons will only yield 0
/// and 1 as values. However, buttons return are <see cref="AxisControl"/>s and
/// yield full floating-point values and may thus have a range of values. See
/// <see cref="pressPoint"/> for how button presses on such buttons are handled.
Expand Down Expand Up @@ -46,6 +46,9 @@ public class ButtonControl : AxisControl
///
/// <example>
/// <code>
/// using UnityEngine;
/// using UnityEngine.InputSystem.Controls;
///
/// public class MyDevice : InputDevice
/// {
/// [InputControl(parameters = "pressPoint=0.234")]
Expand All @@ -56,25 +59,38 @@ public class ButtonControl : AxisControl
/// </code>
/// </example>
/// </remarks>
/// <seealso cref="InputSettings.defaultButtonPressPoint"/>
Copy link
Collaborator

@lyndon-unity lyndon-unity Dec 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than just removing these you can embed into the remarks section using the following in a sentence.
It is worth doing this as the links are useful.

<see cref="InputSettings.defaultButtonPressPoint"/>

/// <seealso cref="pressPointOrDefault"/>
/// <seealso cref="isPressed"/>
public float pressPoint = -1;

/// <summary>
/// Return <see cref="pressPoint"/> if set, otherwise return <see cref="InputSettings.defaultButtonPressPoint"/>.
/// </summary>
/// <value>Effective value to use for press point thresholds.</value>
/// <seealso cref="InputSettings.defaultButtonPressPoint"/>
public float pressPointOrDefault => pressPoint > 0 ? pressPoint : s_GlobalDefaultButtonPressPoint;

/// <summary>
/// Default-initialize the control.
/// Default-initialize the button control.
/// </summary>
/// <remarks>
/// The default format for the control is <see cref="InputStateBlock.FormatBit"/>.
/// The control's minimum value is set to 0 and the maximum value to 1.
/// The default format for the button control is <see cref="InputStateBlock.FormatBit"/>.
/// The button control's minimum value is set to 0 and the maximum value to 1.
/// </remarks>
/// <example>
/// <code>
/// using UnityEngine;
/// using UnityEngine.InputSystem.Controls;
///
/// public class ButtonControlExample : MonoBehaviour
/// {
/// void Start()
/// {
/// var myButton = new ButtonControl();
/// }
///
/// //...
/// }
/// </code>
/// </example>
/// <seealso cref="AxisControl"/>
public ButtonControl()
{
m_StateBlock.format = InputStateBlock.FormatBit;
Expand All @@ -85,10 +101,39 @@ public ButtonControl()
/// <summary>
/// Whether the given value would be considered pressed for this button.
/// </summary>
/// <param name="value">Value for the button.</param>
/// <param name="value">Value to check for if the button would be considered pressed or not.</param>
/// <returns>True if <paramref name="value"/> crosses the threshold to be considered pressed.</returns>
/// <seealso cref="pressPoint"/>
/// <seealso cref="InputSettings.defaultButtonPressPoint"/>
/// <remarks>
/// The default format for the control is <see cref="InputStateBlock.FormatBit"/>.
/// The control's minimum value is set to 0 and the maximum value to 1.
/// See <see cref="InputSettings.defaultButtonPressPoint"/> for the default press point.
/// </remarks>
/// <example>
/// <code>
/// using UnityEngine;
/// using UnityEngine.InputSystem.Controls;
///
/// public class IsValueConsideredPressedExample : MonoBehaviour
/// {
/// void Start()
/// {
/// var myButton = new ButtonControl();
/// var valueToTest = 0.5f;
///
/// if (myButton.IsValueConsideredPressed(valueToTest))
/// {
/// Debug.Log("myButton is considered pressed at: " + valueToTest.ToString());
/// }
/// else
/// {
/// Debug.Log("myButton is not considered pressed at: " + valueToTest.ToString());
/// }
/// }
///
/// //...
/// }
/// </code>
/// </example>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public new bool IsValueConsideredPressed(float value)
{
Expand Down Expand Up @@ -149,9 +194,6 @@ public ButtonControl()
/// ]]>
/// </code>
/// </example>
/// <seealso cref="InputSettings.defaultButtonPressPoint"/>
/// <seealso cref="pressPoint"/>
/// <seealso cref="InputSystem.onAnyButtonPress"/>
public bool isPressed
{
get
Expand Down Expand Up @@ -276,8 +318,8 @@ public bool wasPressedThisFrame
/// {
/// void Update()
/// {
/// bool buttonPressed = Gamepad.current.aButton.wasReleasedThisFrame;
/// bool spaceKeyPressed = Keyboard.current.spaceKey.wasReleasedThisFrame;
/// bool buttonReleased = Gamepad.current.aButton.wasReleasedThisFrame;
/// bool spaceKeyReleased = Keyboard.current.spaceKey.wasReleasedThisFrame;
/// }
/// }
/// </code>
Expand Down
Loading