Acknowledged
3 months ago
CIQQA-3103

BehaviorDelegate.onActionMenu() doc is confusing: "This will be triggered when action menu is pushed. Invoke WatchUi.showActionMenu to push an action menu."

https://developer.garmin.com/connect-iq/api-docs/Toybox/WatchUi/View.html#setActionMenuIndicator-instance_function

The full text for the doc is:

Represents the Action Menu behavior.

This will be triggered when action menu is pushed. Invoke WatchUi.showActionMenu to push an action menu.

(emphasis mine)

This is confusing for several reasons:

- the phrases "action menu is pushed" and "push an action menu" sound very similar but have completely different meanings.

- "action menu" and "push[ed]" are each used twice with completely different meanings.

- In "action menu is pushed", "action menu" clearly refers to the action menu UI element (the action menu indicator), and "pushed" refers to the user physically "pushing" the element. (However, in fact, the user cannot push/tap the element - at least on Vivoactive 6 - they have to swipe left on it). So the wording is not just confusing, but it's unambiguously wrong.

- In "push an action menu", "an action menu" clearly refers to an action menu view, and "push" refers to programmatically pushing the action menu view onto the view stack.

I don't have a great way to rewrite these docs, but I'll give it a shot:

Represents the Action Menu behavior. This behavior is available when the action menu indicator is enabled (visible on the screen).

This will be triggered when the user swipes left on the action menu indicator. On some devices, the user can also tap on the action menu indicator or press START while the action menu indicator is visible [*].

Invoke WatchUi.showActionMenu() to push an action menu view.

See also: View.setActionMenuIndicator()

[*] see comment below: https://forums.garmin.com/developer/connect-iq/i/bug-reports/behaviordelegate-onactionmenu-doc-is-confusing-this-will-be-triggered-when-action-menu-is-pushed-invoke-watchui-showactionmenu-to-push-an-action-menu?CommentId=289e558d-8540-4599-99ed-3caae8967af4

Of course I am assuming that CIQ will support setActionMenuIndicator() in FR955 and other 5-button touchscreen watches, and that onActionMenu() will work similarly to the native behaviour of the action menu indicator / action menu.

But perhaps this is a bad assumption since the supported devices section of the setMenuIndicator doc explicitly lists Vivoactive 6 and the announcement for SDK 8.1.1 specifically called out va6 with regards to this function.

FlowState
  • 3 months ago

    This will be triggered when the user swipes left on the action menu indicator. On some devices, the user can also tap on the action menu indicator or press START while the action menu indicator is visible [*].

    [*] It's unclear to me whether Garmin actually wants to trigger onActionMenu if the user presses START while the action menu indicator is visible, on 5-button watches. This would match native behaviour, but it could also be limiting to devs who may want to use the START button for something else.

    For further context, the action menu indicator works as follows on my FR955 [5-button watch with touchscreen]:

    - The action menu indicator is a button hint next to the START button [at the top right of the screen]. [Yes, this button hint is also used for other purposes in the native UI.]

    - When that button hint is displayed [and an action menu is available], then an action menu can be opened by:

    -- tapping the button hint

    -- swiping left [from the button hint or just below it]

    -- pressing START

    Of course I am assuming that CIQ will support setActionMenuIndicator() in FR955 and other 5-button touchscreen watches, and that onActionMenu() will work similarly to the native behaviour of the action menu indicator / action menu.