Skip to content

Clarify primary and secondary actions in DetailedList#4212

Merged
mhsmith merged 12 commits intobeeware:mainfrom
tabibeyal:main
Mar 3, 2026
Merged

Clarify primary and secondary actions in DetailedList#4212
mhsmith merged 12 commits intobeeware:mainfrom
tabibeyal:main

Conversation

@tabibeyal
Copy link
Contributor

@tabibeyal tabibeyal commented Mar 1, 2026

The previous documentation described platform behavior in general terms, which was misleading for Android. This update explicitly describes how each platform implements primary and secondary actions: Android uses a long press menu, iOS uses swipe gestures, GTK and macOS use right-click menus, Qt displays standalone buttons, and Windows does not currently support actions.
Fixes: #3727

@tabibeyal tabibeyal marked this pull request as draft March 1, 2026 15:10
@tabibeyal tabibeyal marked this pull request as ready for review March 1, 2026 15:42
Copy link
Contributor

@johnzhou721 johnzhou721 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks pretty good already -- a couple of nits, and a direction to extend this in if you're interested.

@tabibeyal
Copy link
Contributor Author

Below is the latest draft. Are there any additional comments before creating the pull request?

Items in a DetailedList can respond to a primary and secondary action through mechanisms specific to each platform:

* On **Android**, when an item is long-pressed, a menu with the primary and secondary actions is displayed.
* On **iOS**, the primary action is displayed and performed when swiping to the left, and the secondary action is displayed and performed when swiping to the right. 
* On **GTK**, a right click on the selected row, displays the buttons for primary and secondary action.
* On **macOS**, a right click on the selected row, displays a context menu with the primary and secondary actions.
* On **Qt**, primary and secondary actions are displayed as buttons shown in the rows of the DetailedList.
* On **Windows**, the implementation does not currently support primary or secondary actions.

The primary and secondary actions will only be enabled in the DetailedList UI if a handler has been provided.

@mhsmith
Copy link
Member

mhsmith commented Mar 2, 2026

If you do want to update the "refresh" documentation, then you might as well do it in this PR. There's no point in creating a separate one.

Some CI checks failed: you can see them at the bottom of the PR page, and you should also have received an email. Follow the links for instructions on how to resolve them.

@mhsmith
Copy link
Member

mhsmith commented Mar 2, 2026

Also, please don't click the "resolve conversation" button; let the person who started the conversation do that. Automatic resolution when accepting a suggestion is OK.

@tabibeyal
Copy link
Contributor Author

Also, please don't click the "resolve conversation" button; let the person who started the conversation do that. Automatic resolution when accepting a suggestion is OK.

Sure, no problem, I'm still learning the platform, thanks for letting me know.

@tabibeyal
Copy link
Contributor Author

If you do want to update the "refresh" documentation, then you might as well do it in this PR. There's no point in creating a separate one.

Some CI checks failed: you can see them at the bottom of the PR page, and you should also have received an email. Follow the links for instructions on how to resolve them.

I resolved the CI errors and started working on "refresh" documentation,

Clarified the actions available in DetailedList across platforms, including refresh action details.
Documented refresh behavior along with clarifications.
* On **GTK**, a right click on the selected row, displays the buttons for primary and secondary action.
* On **macOS**, a right click on the selected row, displays a context menu with the primary and secondary actions.
* On **Qt**, primary and secondary actions are displayed as buttons shown in the rows of the DetailedList.
Items in a DetailedList can respond to a primary action, a secondary action, and a refresh action. The implementation of each action varies by platform:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Items don't respond to a refresh action, hence the phrase "as a whole" further down.

@@ -0,0 +1 @@
Clarified platform-specific behavior for primary and secondary actions, and documented refresh behavior, in DetailedList.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor updates to the documentation should go in the misc category so they don't clutter the release notes.

Comment on lines +77 to +78
* On **macOS**, pulling on the trackpad triggers a refresh.
* On **iOS** and **Android**, pulling the list triggers a refresh.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are both "pull-down" interactions, there's no need to make a distinction based on the hardware.

@mhsmith
Copy link
Member

mhsmith commented Mar 3, 2026

I've fixed the remaining issues. Thanks for the contribution!

@mhsmith mhsmith merged commit a02d954 into beeware:main Mar 3, 2026
42 checks passed
@tabibeyal
Copy link
Contributor Author

It was a great experience, thanks for being patient with me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Android DetailedList doesn't respond to left/right swipes

3 participants