beeware / beeware/toga

Add a DetailScaffold

Open
#4,304 0 comments 2 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
5.4k
Forks
827
Avg merge
15h 39m
Merged PRs (30d)
40

Description

### What is the problem or limitation you are having?

We should add a DetailScaffold - a scaffold that provides the structure for an app with 3 layers of "depth" in content - "selections", "content", and "detail". Selections control what is displayed in the content; selecting part of the content populates the detail.

This is the underlying pattern for apps such as mail (mailbox, contents of mailbox, contents of message), IDEs (IDE mode, list of files, detail of file) etc.

### Describe the solution you'd like

A DetailScaffold will extend the default Scaffold (see #4298), but will also accept a definition of a grouped collection of content that can be selected, and optionally provide an initial view for the detail.

The scaffold will have an `on_show_content(widget, selection, **kwargs)` and `on_show_detail(widget, selection, **kwargs)` handler; these handlers are expected to ensure that the main content widget or detail widget (as appropriate) is in a "presentable" state (updating the values, or replacing the entire view, based on the selection provided). This mirrors the API from DetailContainer (#4300).

On desktop platforms, the DetailScaffold will be implemented as 3-part SplitContainer where the left hand container provides an always-visible list of content that can be selected. Tree-based widgets should be used for the list of content.

On iOS, the DetailScaffold will be implemented using [UISplitViewController](https://developer.apple.com/documentation/uikit/uisplitviewcontroller?language=objc), with the list of content that can be selected being a UITableViewController.

On Android, the selections will be implemented using a [NavigationRail](https://m3.material.io/components/navigation-rail/overview) combined with a [SlidingPaneLayout](https://developer.android.com/develop/ui/views/layout/twopane).

### Describe alternatives you've considered

-

### Additional context

See discussions on #4271 for background.

On mobile, the "selections" list will also need to handle the display of App group commands, as the top-left location of the navigation bar that will be used to reveal the selection list will occupy the space that is used on the default scaffold to display the app menu.

Contributor guide

Open the contributing guide

Research direction

Start by reading the related Scaffold proposal in #4298, the DetailContainer API in #4300, and the background discussion in #4271. Map the requested three-layer selection, content, and detail behavior across desktop, iOS, and Android. Done means a defined DetailScaffold API with the requested handlers and platform-specific implementations, including mobile App group commands.

Written by the indexing model from the issue text.

Assessment

Tech stack
android, ios, python
Domain
desktop, frontend, mobile-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.