feat(indev) Add crown support to pointer input device

[kisvegabor]

Description of the feature or fix

It nicely integrates the the typical watch crown features with the pointer input device. To test it with SDL change LV_SDL_MOUSEWHEEL_MODE to 1.

cc @XuNeo @bjsylvia

Checkpoints

• Run code-format.py from the scripts folder. astyle needs to be installed.
• Update the Documentation if needed
• Add Examples if relevant.
• Add Tests if applicable.
• If you added new options to lv_conf_template.h run lv_conf_internal_gen.py and update Kconfig.

Be sure the following conventions are followed:

• Follow the Styling guide
• Prefer enums instead of macros. If inevitable to use defines export them with LV_EXPORT_CONST_INT(defined_value) right after the define.
• In function arguments prefer type name[] declaration for array parameters instead of type * name
• Use typed pointers instead of void * pointers
• Do not malloc into a static or global variables. Instead declare the variable in lv_global_t structure in lv_global.h and mark the variable with (LV_GLOBAL_DEFAULT()->variable) when it's used. See a detailed description here.
• Widget constructor must follow the lv_<widget_name>_create(lv_obj_t * parent) pattern.
• Widget members function must start with lv_<module_name> and should receive lv_obj_t * as first argument which is a pointer to widget object itself.
• structs should be used via an API and not modified directly via their elements.
• struct APIs should follow the widgets' conventions. That is to receive a pointer to the struct as the first argument, and the prefix of the struct name should be used as the prefix of the function name too (e.g. lv_disp_set_default(lv_disp_t * disp))
• Functions and structs which are not part of the public API must begin with underscore in order to mark them as "private".
• Arguments must be named in H files too.
• To register and use callbacks one of the following needs to be followed (see a detailed description here):
  • For both the registration function and the callback pass a pointer to a struct as the first argument. The struct must contain void * user_data field.
  • The last argument of the registration function must be void * user_data and the same user_data needs to be passed as the last argument of the callback.
  • Callback types not following these conventions should end with xcb_t.

[XuNeo]

The code looks really clean. I'll try it later. Thank you.

[bjsylvia]

@kisvegabor I used this patch to run on a Mac environment, but there are crashes related to scrolling animation when using the scroll wheel. I will try it on Ubuntu later.

[kisvegabor]

I'm using on Linux as well, but SDL should be the same on both places.

[bjsylvia]

@kisvegabor I try to run it on Ubuntu and it works well.
On the Mac system, there is no crash after compiling without relying on Xcode Clang.

Regarding implementation, there is a suggestion: for the operation of the digital crown, LVGL only need to report the corresponding event device type and scroll event, without the need for conversion to key events.

If the upper layer application or component needs to respond to such scroll events to change button status or adjust progress, it should be handled by the upper layer application logic.
For example, on Google WearOS it notifies the scroll event from a rotary encoder device :
https://developer.android.com/training/wearables/user-input/rotary-input
https://developer.android.com/reference/kotlin/androidx/compose/ui/input/rotary/RotaryScrollEvent

While on Apple WatchOS it reports digital crown rotation event :
https://developer.apple.com/documentation/swiftui/digitalcrownevent

[kisvegabor]

You can get the event device type by lv_indev_get_type(lv_event_get_indev(e)) but I'm not sure if we should use a scroll event here for two reasons:

1. We don't have a scroll event now 🙂 LV_EVENT_SCROLLED is sent when the widget was already scrolled just to notify anyone who is interested in it
2. It's not really a scroll but an increment or decrement.

What would be the advantage of approaching from the direction of scroll? I understand that it used in Android, however we haven't followed Android's approach so far and selectively picking a few things might cause conflicts.

[lvgl-bot]

We need some feedback on this pull request.

Now we mark this as "stale" because there was no activity here for 14 days.

Remove the "stale" label or comment else this will be closed in 7 days.

[XuNeo]

From the meeting conclusion, using a 32bit number for key event together with its repeat count can eliminate the loop to send key event one by one.

However, the crown or rotary encoder has its own feature differs with keyboard. For example the sensitivity when scrolling list and roller.

For roller, press keyboard LEFT or RIGHT should focus next item. However, using rotary encoder, we may say rotate 10 steps will trigger a refocus to next item in roller.

Android and IOS have treated rotary encoder differently than keyboard, they must have reasons. It would be better we investigate the usage further.

[kisvegabor]

As the feature doesn't any API we don't need to merge it for v9. It means we have some more time think about it.

The sensitivity of the roller is a great example for why we need to treat it separately. Where shall we store this sensitivity value? As a style property? Or a normal widget property?

Probably we need a similar sensitivity for scrolling too.

[lvgl-bot]

We need some feedback on this pull request.

Now we mark this as "stale" because there was no activity here for 14 days.

Remove the "stale" label or comment else this will be closed in 7 days.

[XuNeo]

Not stale.

[kisvegabor]

In summary what we should do is

• having a new LV_EVENT_ROTARY_SCROLL and the ticks parameter.
• send this event from LV_INDEV_ENCODER too
• handle LV_EVENT_ROTARY_SCROLL in the existing widgets
• add a sensitivity style property (1 by default for roller, dropdown, etc)
• make the scroll size depend on the ticks and the sensitivity of the widget

I think it's a good idea to merge this functionality into the pointer input device type as they share the focused object and the crown is usually used in together with a touch pad.

[kisvegabor]

I added the ROTARY event. Finally added these to lv_indev_t:

/**< Rotary diff count will be divided by this value when widgets are adjusted*/
int32_t rotary_adjust_divider;

/**< Rotary diff count will be multiples by this value when scrolling to get scroll throw size*/
int32_t rotary_scroll_sensitvity;

[XuNeo]

Thank you Gabor. I just have few comments want to confirm.

[XuNeo]

lv_obj_t * obj = indev->pointer.last_pressed;
Should the user manually click the screen when a new page is loaded, in order to make the rotary works by default?

[kisvegabor]

I was thinking about it too. What about setting it automatically to the screen when a new screen is loaded?

[XuNeo]

How about searching a scrollable obj instead if last_pressed is NULL?

[kisvegabor]

I've slightly reworked it:

• Configured the base sensitivity in indev->rotary_sensitvity with 1/256 unit
• Configure the per widget sensitivity with the rotary_sensitvity style property with 1/256 unit again. For scrollable widgets you can set it to a larger value (set dpi / 4 in the default theme), but it's 256 by default, so slider, dropdown, etc are stepping one.

The final diff is calculated like:

  uint32_t indev_sensitivity = indev->rotary_sensitvity;
  uint32_t obj_sensitivity = lv_obj_get_style_rotary_sensitivity(indev_obj_act, 0);
  int32_t diff = (int32_t)((int32_t)indev->pointer.diff * indev_sensitivity * obj_sensitivity + 32768) >> 16;

[lvgl-bot]

We need some feedback on this pull request.

Now we mark this as "stale" because there was no activity here for 14 days.

Remove the "stale" label or comment else this will be closed in 7 days.

[PGNetHun]

Suggested change

	#endif /*LV_SDL_MOUSEWHEEL_MODE*/
	#endif /* __EMSCRIPTEN__ */

[PGNetHun]

I think using "constants" (in our case new SD_MOUSEWHEEL_MODE_ENCODER and SDL_MOUSEWHEEL_MODE_CROWN macros) is better and more descriptive than repeating the values 0 and 1 in files.
Now we know what 0 and 1 mean, but later we will forget, and have to remember, or investigate what they mean.

[kisvegabor]

True, I'll fix these.

[XuNeo]

Thank you Gabor! All looks good to me.

[kisvegabor]

I've updated the docs and added LV_SDL_MOUSEWHEEL_MODE_ENCODER/CROWN as @PGNetHun suggested. enums can't be used here as the enum values are not resolved at the pre-processing stage so they can't be used in #ifs.

[kisvegabor]

@PGNetHun
Fixed, thanks!