mousegrid: implement grid-based mouse navigation #24811

windo · 2025-01-12T20:35:36Z

Add 2 modes of "grid-based" mouse cursor movement schemes:

Specifying an absolute x-y coordinate using 26-character alphabet
Iteratively picking a 3x3 direction to zoom in towards

Both of these pose as an absolute positiong digitizer.

Description

Complements mouse keys by allowing for moving the cursor to the right part of the screen rapidly.

I've only just implemented the alphabet-based method so I haven't tried to use that mode very much yet. But I have used the direction-based method lightly over the past weeks and in some cases I prefer it over reaching for an actual pointing device. So I think something like this could be pretty nice.

See the documentation for an overview of how to use this.

Types of Changes

Issues Fixed or Closed by This PR

[Feature Request] Iterative quadrant-based mouse pointing #24760

Checklist

My code follows the code style of this project: C, Python
I have read the PR Checklist document and have made the appropriate changes.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have added tests to cover my changes.
I have tested the changes and verified that they work and don't break anything (as well as I can manage).

Add 2 modes of "grid-based" mouse cursor movement schemes: 1. Specifying an absolute x-y coordinate using 26-character alphabet 2. Iteratively picking a 3x3 direction to zoom in towards Both of these pose as an absolute positiong digitizer.

windo · 2025-01-13T12:25:34Z

All the keys definitiely don't need to be in the basic range (I wasn't sure how to define keys at all, so this is just what I got working first) and maybe some actions (NEAR and ANIMATE) perhaps are not as needed or can just exist as APIs to be called from custom keys users set up for themselves.

I haven't added any tests, but happy to add some if it looks like this feature might be worth merging.

tzarc

This set of changes will do for now, will do another pass once addressed.

tzarc · 2025-01-15T18:05:03Z

data/constants/keycodes/keycodes_0.0.6_basic.hjson

This will need to be 0.0.7 as this version of keycodes is already locked-in on master. You'll need another file, keycodes_0.0.7.hjson with content {} too.

tzarc · 2025-01-15T18:08:17Z

data/constants/keycodes/keycodes_0.0.6_basic.hjson

@@ -0,0 +1,116 @@
+{
+    "keycodes": {
+        "0x00E8": {


Let's start these at a higher keycode range -- this low is a bit too close to pure USB HID keycodes.
Perhaps starting at 0x77C0?

tzarc · 2025-01-15T18:13:30Z

docs/features/mouse_grid.md

+|0 |`MG_L` |`MG_C`|`MG_R` |
+|+1|`MG_BL`|`MG_B`|`MG_BR`|
+
+In first interation, the whole screen is divided into a 3x3 grid to pick from, while second iteration picks within the 3x3 subgrid of the "quadrant" picked in the first iteration.


Technically we'd need to be a 2x2 grid for quadrants to work as a term. Given that the grid size is configurable, perhaps we swap to segments?

Suggested change

In first interation, the whole screen is divided into a 3x3 grid to pick from, while second iteration picks within the 3x3 subgrid of the "quadrant" picked in the first iteration.

In first interation, the whole screen is divided into a 3x3 grid to pick from, while second iteration picks within the 3x3 subgrid of the segment picked in the first iteration.

tzarc · 2025-01-15T18:18:07Z

docs/features/mouse_grid.md

+
+In first interation, the whole screen is divided into a 3x3 grid to pick from, while second iteration picks within the 3x3 subgrid of the "quadrant" picked in the first iteration.
+
+Since the "quadrants" are not visualized on screen while navigating, if a movement target is kind of between two quadrants, it can be difficult to tell which one is the "correct" coordinate.


Suggested change

Since the "quadrants" are not visualized on screen while navigating, if a movement target is kind of between two quadrants, it can be difficult to tell which one is the "correct" coordinate.

Since the segments aren't displayed on screen while navigating, it can be difficult to determine which segment is 'correct' when a movement target spans two segments.

tzarc · 2025-01-15T18:21:16Z

docs/features/mouse_grid.md

+
+Since the "quadrants" are not visualized on screen while navigating, if a movement target is kind of between two quadrants, it can be difficult to tell which one is the "correct" coordinate.
+
+In order to be forgiving of some inaccuracy, the default configuration leaves a little bit of buffer by zooming in slightly less than would be required for the 1/9th of the "quadrant". This means that for slightly inaccurate path can still reach the target but may require an extra keystroke.


Suggested change

In order to be forgiving of some inaccuracy, the default configuration leaves a little bit of buffer by zooming in slightly less than would be required for the 1/9th of the "quadrant". This means that for slightly inaccurate path can still reach the target but may require an extra keystroke.

The default configuration accounts for some inaccuracy by zooming in slightly less than what would be required for exactly 1/9th-sized segments. This allows slightly inaccurate paths to still reach the target, though it may require an extra keystroke.

tzarc · 2025-01-15T18:52:08Z

quantum/mousegrid.h

+// Little bit of overlap when using directional grid to further refine cursor
+// position.
+#ifndef MG_ALPHABET_RESCALE_MULTIPLIER
+#    define MG_ALPHABET_RESCALE_MULTIPLIER 2.0


Suggested change

# define MG_ALPHABET_RESCALE_MULTIPLIER 2.0

# define MG_ALPHABET_RESCALE_MULTIPLIER 2.0f

tzarc · 2025-01-15T18:59:04Z

quantum/mousegrid.c

+}
+
+void cancel_animation(void) {
+    animation_since = 0;


Suggested change

animation_since = 0;

cancel_deferred_exec(animation_token);

tzarc · 2025-01-15T18:59:43Z

quantum/mousegrid.c

+        default:
+            dx = 0;
+            dy = 0;
+            animation_since = 0;


Suggested change

animation_since = 0;

cancel_animation();

tzarc · 2025-01-15T19:00:10Z

quantum/mousegrid.c

+    if (animation_since == 0) {
+        // Animation has been cancelled.
+        return 0;
+    }
+


Suggested change

if (animation_since == 0) {

// Animation has been cancelled.

return 0;

}

tzarc · 2025-01-15T19:03:43Z

quantum/mousegrid.h

+// Little bit of overlap when using directional grid to further refine cursor
+// position.


Please describe this value's usage a bit more:

Suggested change

// Little bit of overlap when using directional grid to further refine cursor

// position.

// Little bit of overlap when using directional grid to further refine cursor

// position. Lower values mean XXXXXXX, higher values mean YYYYYY.

tzarc · 2025-01-15T19:27:46Z

Also, bunch of build failures due to:

quantum/keyboard.c:495:5: error: implicit declaration of function 'mousegrid_init' [-Wimplicit-function-declaration]
  495 |     mousegrid_init();
      |     ^~~~~~~~~~~~~~

github-actions bot added core documentation dd Data Driven Changes labels Jan 12, 2025

zvecr changed the base branch from master to develop January 12, 2025 21:33

tzarc requested changes Jan 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

mousegrid: implement grid-based mouse navigation #24811

mousegrid: implement grid-based mouse navigation #24811

windo commented Jan 12, 2025

windo commented Jan 13, 2025

tzarc left a comment

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc Jan 15, 2025

tzarc commented Jan 15, 2025

	In first interation, the whole screen is divided into a 3x3 grid to pick from, while second iteration picks within the 3x3 subgrid of the "quadrant" picked in the first iteration.
	In first interation, the whole screen is divided into a 3x3 grid to pick from, while second iteration picks within the 3x3 subgrid of the segment picked in the first iteration.


		In first interation, the whole screen is divided into a 3x3 grid to pick from, while second iteration picks within the 3x3 subgrid of the "quadrant" picked in the first iteration.

		Since the "quadrants" are not visualized on screen while navigating, if a movement target is kind of between two quadrants, it can be difficult to tell which one is the "correct" coordinate.

	Since the "quadrants" are not visualized on screen while navigating, if a movement target is kind of between two quadrants, it can be difficult to tell which one is the "correct" coordinate.
	Since the segments aren't displayed on screen while navigating, it can be difficult to determine which segment is 'correct' when a movement target spans two segments.


		Since the "quadrants" are not visualized on screen while navigating, if a movement target is kind of between two quadrants, it can be difficult to tell which one is the "correct" coordinate.

		In order to be forgiving of some inaccuracy, the default configuration leaves a little bit of buffer by zooming in slightly less than would be required for the 1/9th of the "quadrant". This means that for slightly inaccurate path can still reach the target but may require an extra keystroke.

	In order to be forgiving of some inaccuracy, the default configuration leaves a little bit of buffer by zooming in slightly less than would be required for the 1/9th of the "quadrant". This means that for slightly inaccurate path can still reach the target but may require an extra keystroke.
	The default configuration accounts for some inaccuracy by zooming in slightly less than what would be required for exactly 1/9th-sized segments. This allows slightly inaccurate paths to still reach the target, though it may require an extra keystroke.

	# define MG_ALPHABET_RESCALE_MULTIPLIER 2.0
	# define MG_ALPHABET_RESCALE_MULTIPLIER 2.0f

		// Little bit of overlap when using directional grid to further refine cursor
		// position.

mousegrid: implement grid-based mouse navigation #24811

Are you sure you want to change the base?

mousegrid: implement grid-based mouse navigation #24811

Conversation

windo commented Jan 12, 2025

Description

Types of Changes

Issues Fixed or Closed by This PR

Checklist

windo commented Jan 13, 2025

tzarc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tzarc commented Jan 15, 2025