Module configuration UI

[laxu]

Now that Agent allows you to configure module settings using Smart Macros, are there plans to add easy UI pages to configure all this stuff?

If yes, are there any designs for these? I might have some time to implement some UIs.

[mondalaci]

According to the latest blog posts, there are such plans. Feel free to share your designs.

[laxu]

I think the question here is whether these should be implemented under the Modules (currently not visible in UI) as their own pages to configure the "default" functionality or if this should be somehow tied to the Keymaps instead considering macros and keymap changes can reconfigure them.

One idea how it could work is that e.g we have a side menu that looks like this like it already exists in code:

Modules
     Key cluster
     Trackball
     Touchpad
     Trackpoint

Opening these shows sliders like the Mouse Key Speed page or the smart macro docs. These configure the default functionality (I guess like the $onInit smart macro) for each module that applies unless overridden by macro/keymap change events.

I guess at least these pages should also contain things like disabling some features (e.g double tap to drag for Touchpad or tiny trackball for Key cluster).

[mondalaci]

I'd put cogwheel icons near the modules. By clicking one, Agent would jump to the modules -> $currentModule page. I'd only show the pages of the mounted modules in the sidebar.

On module pages, I'd expose every option currently featured in the smart macro sidebar, which includes general module options and module-specific options. I don't want to introduce further options for now, such as disabling double tap to drag. Disabling the mini trackball of the key cluster is possible via navigation modes.

I agree that these settings should affect the default behavior of modules. Per-keymap behavior can be achieved via smart macros.

[daneel23]

Hi! Is it possible to swap direction to "natural" (apple-like) for minitrackball in keycluster module with new UHK agent UI and firmware?

If smart macros are the way, are there some examples to start from scratch and a macros reference guide?

[kareltucek]

If smart macros are the way, are there some examples to start from scratch and a macros reference guide?

Search for "module scroll direction" in the right pane.

[mondalaci]

Current UI mockup:

The puzzle buttons lead to the relevant module pages, also accessible in the side menu:

@laxu Would you be interested in creating mockups for the module pages? I'm quite busy nowadays and interested in what you come up with.

[laxu]

I'm afraid I have been also extremely busy this year so I haven't had any time to work on this stuff. I will have to see if I have some time over Christmas or early next year.

[mondalaci]

Module configuration page mockup:

The "Key cluster settings" and "Touchpad settings" sections should only be shown on the pages of respective modules.

The layout is inaccurate. Implement the layout according to the following:

• Divide the page into a left and right half, just like on the "Mouse key speed" page. Put the "Navigation modes" section in the right half and the rest in the left half.
• Arrange left edge of the slider, checkbox, and select widgets along the same line.

[mondalaci]

"Mouse key speed" page extended with "Axis skew" and "Compensate diagonal speed" options:

[mondalaci]

Related PR: UltimateHackingKeyboard/firmware#737

[mondalaci]

Let me specify the last missing page for this issue. Add a new "Typing behavior" menu item below the "Led settings" menu item.

[kareltucek]

(All the secondary role settings are for the advanced strategy only, so it seems like a good idea to me to gray them out when "Simple" is checked.)

[mondalaci]

@kareltucek Exactly my thoughts, and I was going to ask you about it. Any further grayouts? For example, should we also gray out "double tap timeout" when "double tap to primary" is unchecked?

[kareltucek]

"double tap timeout" when "double tap to primary" is unchecked

Makes sense. Yes.

[kareltucek]

Also a slight problem is that the "Double tap to lock layer timeout" also controls smart macro "ifDoubletap" condition... which is not at all clear from the UI.

[mondalaci]

@kareltucek How about clarifying it in the smart macro documentation?

[kareltucek]

Sounds quite clear to me?

Also not sure how that is relevant to misleading UI.

(Feel free to let it stand as it is, although I would rename it simply tou "Double tap timeout".)

[mondalaci]

But then we'd have two "double tap timeout" options, which I find confusing, even if they're in different sections.

[ert78gb]

Hi @kareltucek,

Laszlo recommended asking you about the Typing behaviour screen.

What are the tooltip texts?

What are the min, max, step and default values of the slider components?

• min: Lowest possible value
• max: Highest possible value
• step: When the user uses the slider what is the minimal changes that they can apply
• default: The default values of the variable. We use it when the user first use the module or use the web site version of the agent.

When the simple resolution strategy selected of the secondary roles should I reset the values besides greying them or I can leave them as they are?

[kareltucek]

property	min	max	step	default	tooltip
resolution strategy				Simple	Simple resolution strategy activates the secondary role whenever there is another keypress while the dual-role key is pressed. If there is no such press, it briefly activates the primary role on the release of the dual-role key. Advanced strategy allows for more complex activation conditions, in order to allow using secondary roles on alphanumeric keys, as Simple strategy tends to interfere with writing.
Timeout	50	1000	5	350	If an (advanced strategy) dual-role key is held for at least this amount of time, the Timeout Action is activated even when there is no other activity.
Timeout action				Secondary	Dual-role-key role to be activated when the timeout is reached.
Trigger by release				true	When checked, dual-role key is also activated when another key is released while the dual role-key is pressed. Thus the role is determined by the release order of the two keys.
Trigger safety margin	-100	100	1	50	This virtually offsets the release time of the dual-role key. Thus positive values fine-tune the dual role resolution sensitivity towards the primary role, while negative values fine-tune the dual role resolution sensitivity towards the secondary role. Intended to be used with the Trigger by release option.
Double tap to primary				true	If the dual-role key is double-tapped, the primary role is activated. Useful for keys that need to be held, such as space.
Double tap timeout	50	1000	5	200	Double tap timeout configures doubletap time behavior for the secondary roles.
Double tap to lock layer timeout	50	1000	5	400	Double tap to lock layer timeout configures doubletap timeout for layer switchers and for the macro ifDoubletap condition.
Keystroke delay	0	50	1	0	Keystroke delay defines minimum delay between two consecutive usb reports, thus slowing down keyboard output in case of fast bursts (e.g., from the macro engine). This improves compatibility as many programs (especially RDP clients) have problems accepting too fast input.

---

When the simple resolution strategy selected of the secondary roles should I reset the values besides greying them or I can leave them as they are?

Please leave them as they are.

---

Do you need similar information for some of the other screens?

---

@mondalaci as a sidenote, I am wondering if we should somehow retain control over the default values of some of the properties (especially the Keystroke Delay) unless the user deliberately specifies them.

E.g., the dictionary method used for modules has the benefit that if the user does not adjust a value and consequently agent does not write it into the config, and we update the defaults, the user gets the benefit of the updated default.

[mondalaci]

@kareltucek Agent will always write these properties to the user configuration for the sake of simplicity, so Agent's default values should reflect firmware defaults.

I'm unsure what you mean by retaining control, but the above hopefully answers your question.

[kareltucek]

I'm unsure what you mean by retaining control, but the above hopefully answers your question.

I mean that if the user does not deliberately choose his preferred value, and we choose to change our default, it would be nice if that user's value changed to the new default too.

(But yeah, above answers the question.)

[mondalaci]

Gotcha. I think that we should seldom change defaults because the user might dislike the new default and be unaware of the change. And to reiterate, it's easier for Agent to always set properties.

[ert78gb]

@kareltucek thanks for the collection.

Do you need similar information for some of the other screens?

I tried to collect them from the smart macro doc and I asked Laci too. But I haven't found all information yet, so if you could create the same table for other screens/fields would be a big help for me. THX

[kareltucek]

property	min	max	step	tooltip
Base speed	0	10	0.1	Increases module's sensitivity evenly in both high speeds and low speeds.
Speed	0	10	0.1	Increases module's sensitivity unevenly - more in high speeds than in low speeds. Exact curve shape is governed by the Acceleration exponent.
Acceleration	0	2	0.05	Increasing this exponent increases Speed's contribution in high speeds and decreases Speed's contribution at low speeds. If possible, fit in here the diagram at https://raw.githubusercontent.com/UltimateHackingKeyboard/firmware/master/doc-dev/resources/mouse_speeds.svg .
Scroll speed divisor	1	100	1	Number of pixels needed to produce one scroll event.
Caret speed divisor	1	100	1	Number of pixels needed to produce one event in discrete navigation modes (caret, media, zoom).
Scroll axis lock				If checked, scrolling direction is locked in the dominant axis, preventing any events being produced in the other axis.
Caret axis lock				If checked, discrete navigation mode (caret, media, zoom) direction is locked in the dominant axis, preventing any events being produced in the other axis.
Axis lock first tick skew	0.1	10	0.1	Multiplies contribution towards first event in axis locked modes. Values smaller than one make the module require bigger push to start moving. Values bigger than one make modules produce the first event even with a very light push.
Axis lock skew	0.1	1	0.1	Controls how big the axes movement disproportion has to be in order to switch the locked axis. Lower value means stronger axis-locking behavior.
Invert vertical scrolling				Inverts Y scroll direction.
Swap axes				Swaps axes, making the key cluster trackball scroll vertically when swiped sideways.
Invert horizontal scrolling				Inverts X scroll direction.
Pinch-to-zoom mode				Navigation mode to be triggered by the touchpad pinch zoom gesture.
Pinch-to-zoom divisor	1	50	1	Number of zoom events (as reported by the touchpad board) needed to produce one zoom event (as reported by the UHK).
Hold continuation timeout	0	1000	1	When non-zero, touchpad allows the finger to be lifted and repositioned during drag-and-drop actions, as long as the finger is lifted for less than this timeout milliseconds.
Navigation modes				Controls module behavior in different layers.
Axis skew	0.1	10	0.1	Skews mouse keys axis speed.
Compensate diagonal speed				When checked, diagonal speed is corrected to be as slow as single-axis speed. (Otherwise, axis speeds add up and so cursor moves faster on diagonals than in horizontal/vertical lines.)

As for default values:

Property	Default value
Swap axes	false
Invert horizontal scrolling	false
Pinch-to-zoom mode	zoom
Pinch-to-zoom divisor	4.0
Hold continuation timeout	0
Mouse key axis skew	1
Mouse key scroll axis skew	1
Compensate diagonal speed	false

property name	trackball default	trackpoint default	touchpad default	keycluster
Base speed	0.5	0.0	0.5	5.0
Speed	0.5	1.0	0.7	0
Adceleration	1.0	0.0	1.0	0
Scroll speed divisor	8.0	8.0	8.0	5.0
Caret speed divisor	16.0	16.0	16.0	5.0
Scroll axis lock	true	true	true	true
Caret axis lock	true	true	true	true
Axis lock first tick skew	2.0	2.0	2.0	0.5
Axis lock skew	0.5	0.5	0.5	0.5
Invert vertical scrolling	false	false	false	false

Special behaviors:

• Ideally, Axis lock first tick skew and mouse key axis skew sliders should use logarithmic scales centered around 1. (E.g.,
  the slider representing internaly the range -1 to 1, and outputting the value of pow(10,x).)
• For Keycluster:
  • Base speed has max 500.
  • Base speed, scroll speed divisor and caret speed divisor should have step 5.
  • Speed and Acceleration should be disabled. (I.e., locked at 0.)

Generally the steps are quite arbitrary, feel free to adjust them if it seems reasonable. Also, don't be alarmed that mins/maxs don't match the docs. The firmware accepts anything that fits the target types, so the only point of having them is to guide the user as to what a reasonable value is.

[ert78gb]

awesome, thx

[mondalaci]

Done by #2166