Skip to content

Commit 5fb8129

Browse files
moomijimoomiji
committed
chore: update documentation comments
1 parent b90e13f commit 5fb8129

7 files changed

Lines changed: 156 additions & 95 deletions

File tree

‎src/MaaFramework.Binding.Native/Interop/Framework/Instance/MaaController.cs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,12 +200,36 @@ public static partial class MaaController
200200
[LibraryImport("MaaFramework", StringMarshalling = StringMarshalling.Utf8)]
201201
public static partial MaaCtrlId MaaControllerPostScreencap(MaaControllerHandle ctrl);
202202

203+
/// <summary>
204+
/// Post a scroll action to the controller.
205+
/// </summary>
206+
/// <param name="ctrl">The controller handle.</param>
207+
/// <param name="dx">The horizontal scroll delta. Positive values scroll right, negative values scroll left.</param>
208+
/// <param name="dy">The vertical scroll delta. Positive values scroll up, negative values scroll down.</param>
209+
/// <returns>The control id of the scroll action.</returns>
210+
/// <remarks>
211+
/// <para>Not all controllers support scroll. If not supported, the action will fail.</para>
212+
/// <para>Scroll is supported by Win32 controllers and custom controllers that implement scroll.</para>
213+
/// <para>If the controller does not support scroll, the action will fail. Use MaaControllerStatus or<br/>
214+
/// MaaControllerWait to check the result.</para>
215+
/// <para>The dx/dy values are sent directly as scroll increments. Using multiples of 120 (WHEEL_DELTA) is<br/>
216+
/// recommended for best compatibility.</para>
217+
/// </remarks>
203218
[LibraryImport("MaaFramework", StringMarshalling = StringMarshalling.Utf8)]
204219
public static partial MaaCtrlId MaaControllerPostScroll(MaaControllerHandle ctrl, int dx, int dy);
205220

206221
[LibraryImport("MaaFramework", StringMarshalling = StringMarshalling.Utf8)]
207222
public static partial MaaCtrlId MaaControllerPostInactive(MaaControllerHandle ctrl);
208223

224+
/// <summary>Post a shell command to the controller.</summary>
225+
/// <param name="ctrl">The controller handle.</param>
226+
/// <param name="cmd">The shell command to execute.</param>
227+
/// <param name="timeout">Timeout in milliseconds. Default is 20000 (20 seconds).</param>
228+
/// <returns>The control id of the shell action.</returns>
229+
/// <remarks>
230+
/// <para>This is only valid for ADB controllers. If the controller is not an ADB controller, the action will fail.</para>
231+
/// <para>Supported by ADB controllers and custom controllers that implement the shell callback.</para>
232+
/// </remarks>
209233
[LibraryImport("MaaFramework", StringMarshalling = StringMarshalling.Utf8)]
210234
public static partial MaaCtrlId MaaControllerPostShell(MaaControllerHandle ctrl, string cmd, long timeout);
211235

‎src/MaaFramework.Binding/Enums/Controllers/AdbInputMethods.cs‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,22 @@ namespace MaaFramework.Binding;
1414

1515
/// <summary>
1616
/// Adb input method flags
17-
/// <para>Use bitwise OR to set the methods you need.</para>
18-
/// <para>MaaFramework will select the first available method according to priority.</para>
17+
///
18+
/// <para>Use bitwise OR to set the methods you need.
19+
/// <br/>MaaFramework will select the first available method according to priority.</para>
20+
///
1921
/// <para>Priority (high to low): EmulatorExtras > Maatouch > MinitouchAndAdbKey > AdbShell</para>
22+
///
2023
/// <para>Default: All methods except EmulatorExtras</para>
21-
/// <code>| Method | Speed | Compatibility | Notes |</code>
22-
/// <code>|----------------------|-------|---------------|---------------------------------------|</code>
23-
/// <code>| AdbShell | Slow | High | |</code>
24-
/// <code>| MinitouchAndAdbKey | Fast | Medium | Key press still uses AdbShell |</code>
25-
/// <code>| Maatouch | Fast | Medium | |</code>
26-
/// <code>| EmulatorExtras | Fast | Low | Emulators only: MuMu 12 |</code>
24+
///
25+
/// <code>| Method | Speed | Compatibility | Notes |
26+
/// <br/>|----------------------|-------|---------------|---------------------------------------|
27+
/// <br/>| AdbShell | Slow | High | |
28+
/// <br/>| MinitouchAndAdbKey | Fast | Medium | Key press still uses AdbShell |
29+
/// <br/>| Maatouch | Fast | Medium | |
30+
/// <br/>| EmulatorExtras | Fast | Low | Emulators only: MuMu 12 |
31+
/// </code>
32+
///
2733
/// </summary>
2834
[Flags]
2935
public enum AdbInputMethods : System.UInt64

‎src/MaaFramework.Binding/Enums/Controllers/AdbScreencapMethods.cs‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,26 @@ namespace MaaFramework.Binding;
1414

1515
/// <summary>
1616
/// Adb screencap method flags.
17-
/// <para>Use bitwise OR to set the methods you need.</para>
18-
/// <para>MaaFramework will test all provided methods and use the fastest available one.</para>
17+
///
18+
/// <para>Use bitwise OR to set the methods you need.
19+
/// <br/>MaaFramework will test all provided methods and use the fastest available one.</para>
20+
///
1921
/// <para>Default: All methods except RawByNetcat, MinicapDirect, MinicapStream</para>
20-
/// <para>Note: MinicapDirect and MinicapStream use lossy JPEG encoding, which may</para>
21-
/// <para>significantly reduce template matching accuracy. Not recommended.</para>
22-
/// <code>| Method | Speed | Compatibility | Encoding | Notes |</code>
23-
/// <code>|-----------------------|------------|---------------|----------|-------------------------------------|</code>
24-
/// <code>| EncodeToFileAndPull | Slow | High | Lossless | |</code>
25-
/// <code>| Encode | Slow | High | Lossless | |</code>
26-
/// <code>| RawWithGzip | Medium | High | Lossless | |</code>
27-
/// <code>| RawByNetcat | Fast | Low | Lossless | |</code>
28-
/// <code>| MinicapDirect | Fast | Low | Lossy | |</code>
29-
/// <code>| MinicapStream | Very Fast | Low | Lossy | |</code>
30-
/// <code>| EmulatorExtras | Very Fast | Low | Lossless | Emulators only: MuMu 12, LDPlayer 9 |</code>
22+
///
23+
/// <para>Note: MinicapDirect and MinicapStream use lossy JPEG encoding, which may
24+
/// <br/>significantly reduce template matching accuracy. Not recommended.</para>
25+
///
26+
/// <code>| Method | Speed | Compatibility | Encoding | Notes |
27+
/// <br/>|-----------------------|------------|---------------|----------|-------------------------------------|
28+
/// <br/>| EncodeToFileAndPull | Slow | High | Lossless | |
29+
/// <br/>| Encode | Slow | High | Lossless | |
30+
/// <br/>| RawWithGzip | Medium | High | Lossless | |
31+
/// <br/>| RawByNetcat | Fast | Low | Lossless | |
32+
/// <br/>| MinicapDirect | Fast | Low | Lossy | |
33+
/// <br/>| MinicapStream | Very Fast | Low | Lossy | |
34+
/// <br/>| EmulatorExtras | Very Fast | Low | Lossless | Emulators only: MuMu 12, LDPlayer 9 |
35+
/// </code>
36+
///
3137
/// </summary>
3238
[Flags]
3339
public enum AdbScreencapMethods : System.UInt64

‎src/MaaFramework.Binding/Enums/Controllers/GamepadButton.cs‎

Lines changed: 44 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -13,42 +13,50 @@
1313
namespace MaaFramework.Binding;
1414

1515
/// <summary>
16-
/// Virtual gamepad button codes for click_key/key_down/key_up
17-
/// <para>Use these values with MaaControllerPostClickKey, MaaControllerPostKeyDown, MaaControllerPostKeyUp.</para>
18-
/// <para>Values are based on XUSB (Xbox 360) button flags. DS4 face buttons are mapped to Xbox equivalents.</para>
19-
/// <para>Xbox 360 buttons:</para>
20-
/// <code>| Value | Button | Description |</code>
21-
/// <code>|---------|---------------------|------------------------|</code>
22-
/// <code>| 0x1000 | A | A button |</code>
23-
/// <code>| 0x2000 | B | B button |</code>
24-
/// <code>| 0x4000 | X | X button |</code>
25-
/// <code>| 0x8000 | Y | Y button |</code>
26-
/// <code>| 0x0100 | LB (Left Shoulder) | Left bumper |</code>
27-
/// <code>| 0x0200 | RB (Right Shoulder) | Right bumper |</code>
28-
/// <code>| 0x0040 | L_THUMB | Left stick click |</code>
29-
/// <code>| 0x0080 | R_THUMB | Right stick click |</code>
30-
/// <code>| 0x0010 | START | Start button |</code>
31-
/// <code>| 0x0020 | BACK | Back button |</code>
32-
/// <code>| 0x0400 | GUIDE | Guide/Home button |</code>
33-
/// <code>| 0x0001 | DPAD_UP | D-pad up |</code>
34-
/// <code>| 0x0002 | DPAD_DOWN | D-pad down |</code>
35-
/// <code>| 0x0004 | DPAD_LEFT | D-pad left |</code>
36-
/// <code>| 0x0008 | DPAD_RIGHT | D-pad right |</code>
37-
/// <para>DualShock 4 buttons (aliases to Xbox buttons):</para>
38-
/// <code>| Value | Button | Xbox Equivalent | Description |</code>
39-
/// <code>|---------|-----------|-----------------|---------------------------|</code>
40-
/// <code>| 0x1000 | CROSS | A | Cross (X) button |</code>
41-
/// <code>| 0x2000 | CIRCLE | B | Circle button |</code>
42-
/// <code>| 0x4000 | SQUARE | X | Square button |</code>
43-
/// <code>| 0x8000 | TRIANGLE | Y | Triangle button |</code>
44-
/// <code>| 0x0100 | L1 | LB | L1 button |</code>
45-
/// <code>| 0x0200 | R1 | RB | R1 button |</code>
46-
/// <code>| 0x0040 | L3 | L_THUMB | Left stick click |</code>
47-
/// <code>| 0x0080 | R3 | R_THUMB | Right stick click |</code>
48-
/// <code>| 0x0010 | OPTIONS | START | Options button |</code>
49-
/// <code>| 0x0020 | SHARE | BACK | Share button |</code>
50-
/// <code>| 0x10000 | PS | - | PS button (DS4 special) |</code>
51-
/// <code>| 0x20000 | TOUCHPAD | - | Touchpad click (DS4 only) |</code>
16+
/// Virtual gamepad button codes for <see cref="IMaaController.ClickKey(int)"/> / <see cref="IMaaController.KeyDown(int)"/> / <see cref="IMaaController.KeyUp(int)"/>
17+
///
18+
/// <para>Use these values with MaaControllerPostClickKey, MaaControllerPostKeyDown, MaaControllerPostKeyUp.
19+
/// <br/>Values are based on XUSB (Xbox 360) button flags. DS4 face buttons are mapped to Xbox equivalents.</para>
20+
///
21+
/// <para>Xbox 360 buttons:</para>
22+
///
23+
/// <code>| Value | Button | Description |
24+
/// <br/>|---------|---------------------|------------------------|
25+
/// <br/>| 0x1000 | A | A button |
26+
/// <br/>| 0x2000 | B | B button |
27+
/// <br/>| 0x4000 | X | X button |
28+
/// <br/>| 0x8000 | Y | Y button |
29+
/// <br/>| 0x0100 | LB (Left Shoulder) | Left bumper |
30+
/// <br/>| 0x0200 | RB (Right Shoulder) | Right bumper |
31+
/// <br/>| 0x0040 | L_THUMB | Left stick click |
32+
/// <br/>| 0x0080 | R_THUMB | Right stick click |
33+
/// <br/>| 0x0010 | START | Start button |
34+
/// <br/>| 0x0020 | BACK | Back button |
35+
/// <br/>| 0x0400 | GUIDE | Guide/Home button |
36+
/// <br/>| 0x0001 | DPAD_UP | D-pad up |
37+
/// <br/>| 0x0002 | DPAD_DOWN | D-pad down |
38+
/// <br/>| 0x0004 | DPAD_LEFT | D-pad left |
39+
/// <br/>| 0x0008 | DPAD_RIGHT | D-pad right |
40+
/// </code>
41+
///
42+
/// <para>DualShock 4 buttons (aliases to Xbox buttons):</para>
43+
///
44+
/// <code>| Value | Button | Xbox Equivalent | Description |
45+
/// <br/>|---------|-----------|-----------------|---------------------------|
46+
/// <br/>| 0x1000 | CROSS | A | Cross (X) button |
47+
/// <br/>| 0x2000 | CIRCLE | B | Circle button |
48+
/// <br/>| 0x4000 | SQUARE | X | Square button |
49+
/// <br/>| 0x8000 | TRIANGLE | Y | Triangle button |
50+
/// <br/>| 0x0100 | L1 | LB | L1 button |
51+
/// <br/>| 0x0200 | R1 | RB | R1 button |
52+
/// <br/>| 0x0040 | L3 | L_THUMB | Left stick click |
53+
/// <br/>| 0x0080 | R3 | R_THUMB | Right stick click |
54+
/// <br/>| 0x0010 | OPTIONS | START | Options button |
55+
/// <br/>| 0x0020 | SHARE | BACK | Share button |
56+
/// <br/>| 0x10000 | PS | - | PS button (DS4 special) |
57+
/// <br/>| 0x20000 | TOUCHPAD | - | Touchpad click (DS4 only) |
58+
/// </code>
59+
///
5260
/// </summary>
5361
[Flags]
5462
public enum GamepadButton : System.UInt64

‎src/MaaFramework.Binding/Enums/Controllers/GamepadTouch.cs‎

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,27 @@
1313
namespace MaaFramework.Binding;
1414

1515
/// <summary>
16-
/// Virtual gamepad touch contact definitions for touch_down/touch_move/touch_up
17-
/// <para>For gamepad controller, the touch functions are repurposed for analog inputs:</para>
18-
/// <para>- x, y: Analog stick position</para>
19-
/// <para>- pressure: Trigger value (0~255)</para>
20-
/// <para>Contact mapping:</para>
21-
/// <code>| Contact | Input | x range | y range | pressure | Description |</code>
22-
/// <code>|---------------|-----------------|---------------|---------------|------------|----------------------------------|</code>
23-
/// <code>| LeftStick | Left Stick | -32768~32767 | -32768~32767 | ignored | Left analog stick X/Y position |</code>
24-
/// <code>| RightStick | Right Stick | -32768~32767 | -32768~32767 | ignored | Right analog stick X/Y position |</code>
25-
/// <code>| LeftTrigger | Left Trigger | ignored | ignored | 0~255 | Left trigger (LT/L2) value |</code>
26-
/// <code>| RightTrigger | Right Trigger | ignored | ignored | 0~255 | Right trigger (RT/R2) value |</code>
27-
/// <para>Usage:</para>
28-
/// <para>- touch_down(contact, x, y, pressure): Start analog input</para>
29-
/// <para>- touch_move(contact, x, y, pressure): Update analog input position/value</para>
30-
/// <para>- touch_up(contact): Release/reset analog input to center/zero</para>
16+
/// Virtual gamepad touch contact definitions for <see cref="IMaaController.TouchDown(int, int, int, int)"/> / <see cref="IMaaController.TouchMove(int, int, int, int)"/> / <see cref="IMaaController.TouchUp(int)"/>
17+
///
18+
/// <para>For gamepad controller, the touch functions are repurposed for analog inputs:
19+
/// <br/>- x, y: Analog stick position
20+
/// <br/>- pressure: Trigger value (0~255)</para>
21+
///
22+
/// <para>Contact mapping:</para>
23+
///
24+
/// <code>| Contact | Input | x range | y range | pressure | Description |
25+
/// <br/>|---------------|-----------------|---------------|---------------|------------|----------------------------------|
26+
/// <br/>| LeftStick | Left Stick | -32768~32767 | -32768~32767 | ignored | Left analog stick X/Y position |
27+
/// <br/>| RightStick | Right Stick | -32768~32767 | -32768~32767 | ignored | Right analog stick X/Y position |
28+
/// <br/>| LeftTrigger | Left Trigger | ignored | ignored | 0~255 | Left trigger (LT/L2) value |
29+
/// <br/>| RightTrigger | Right Trigger | ignored | ignored | 0~255 | Right trigger (RT/R2) value |
30+
/// </code>
31+
///
32+
/// <para>Usage:
33+
/// <br/>- touch_down(contact, x, y, pressure): Start analog input
34+
/// <br/>- touch_move(contact, x, y, pressure): Update analog input position/value
35+
/// <br/>- touch_up(contact): Release/reset analog input to center/zero</para>
36+
///
3137
/// </summary>
3238
public enum GamepadTouch : System.UInt64
3339
{

‎src/MaaFramework.Binding/Enums/Controllers/GamepadType.cs‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,15 @@ namespace MaaFramework.Binding;
1414

1515
/// <summary>
1616
/// Virtual gamepad type.
17-
/// <para>Select ONE type only.</para>
18-
/// <code>| Type | Description |</code>
19-
/// <code>|---------------|------------------------------------------------|</code>
20-
/// <code>| Xbox360 | Microsoft Xbox 360 Controller (wired) |</code>
21-
/// <code>| DualShock4 | Sony DualShock 4 Controller (wired) |</code>
17+
///
18+
/// <para>Select ONE type only.</para>
19+
///
20+
/// <code>| Type | Description |
21+
/// <br/>|---------------|------------------------------------------------|
22+
/// <br/>| Xbox360 | Microsoft Xbox 360 Controller (wired) |
23+
/// <br/>| DualShock4 | Sony DualShock 4 Controller (wired) |
24+
/// </code>
25+
///
2226
/// </summary>
2327
public enum GamepadType : System.UInt64
2428
{

0 commit comments

Comments
 (0)