Allow laying out content beyond standard areas in iOS

[johnzhou721]

What is the problem or limitation you are having?

On iOS, e.g. the Photos app displays images fullscreen, having content behind the status bar.

There might also occasionally be use-cases where, say we'd like a slightly tinted colored background extending all the way up.

Describe the solution you'd like

A platform-specific API for extending content and layout beyond the area into the navigation bar and status bar.

An example design could include allowing the users to modify the top_offset of the container, and providing conveniences like exposing the height of the status and navigation bars, helping users decide exactly how much to extend. We could also expose values of these kinds for users to adjust layouts of certain things appropriately. [edit]

Describe alternatives you've considered

Do nothing

Additional context

No response

[freakboy3742]

This sort of layout concern is clearly becoming more important - especially on mobile.

The big question is how to represent the idea in a way that either (a) can be transparently ignored on platforms that don't support it, or (b) can be clearly flagged as something that is "mobile specific". Some sort of flag to modify/alter the handling of top_offset might do it; but we will need a much more complete design process before we can commit to anything here.

[johnzhou721]

@freakboy3742 Yes, I'd agree that this is not quite right.

Worth noting that it's not just the top edge; for example if one wants some label at the bottom, it can't go outside of the safe area. So it's not just the top offset, also bottom.

Another thing is that the flagging can get complex. There's already 3 usecases in a plain window: either top status bar padded and start layout out after, top device notch / window corner padded and start layout out after (in the case of ipados), or ignore everything and layout from the top. This could potentially get more complex with the fact that on iPadOS, the top status bar is not always in the window.

At the bottom, we'd have "keyboard", "device notch", or "nothing" after we get keyboard stuff right. And then, to make things even more fun, there's OptionContainers and ScrollContainers.

So a single flag isn't really going to do it. Maybe an enum could help more -- it might even be worth exposing properties from the impl layer for all of these values, and then a custom hook to adjust top_offset / related variabes for users to use after we do our default logic.

Thoughts?

[johnzhou721]

Note that bottom corners are rounded on Cocoa and GTK4 + libadwatia as well.

[freakboy3742]

Thoughts?

To me, rounded corners are a completely separate issue. That's a thing that is mostly avoided by having layouts that don't flow all the way to a content area's edge. IMHO, it's not a thing that we really need to concern ourselves with; UI testing of any specific layout can incorporate padding or margins to avoid those problem areas. We might be able to provide some overall design guidance, but ultimately, this should be in the hand of the designer.

The issue we need to resolve is creating an app that has a ScrollContainer as the main window content, and ensuring that a button at the top of the container screen and a button at the bottom of the container can both be pressed by scrolling sufficiently.

However, the more I think about this, the more I wonder if we actually do have a problem beyond the ability to maybe set the background tint of the titlebar and/or of the main window. This isn't a question the end user should need to concern themselves with - if I put a button in a scroll container, I shouldn't need to do mental gymnastics to work out how to pad that button in such a way that it can be pressed.

[johnzhou721]

@freakboy3742

However, the more I think about this, the more I wonder if we actually do have a problem beyond the ability to maybe set the background tint of the titlebar and/or of the main window. This isn't a question the end user should need to concern themselves with - if I put a button in a scroll container, I shouldn't need to do mental gymnastics to work out how to pad that button in such a way that it can be pressed.

iOS and macOS does this by way of the safe area/content insets thing I mentioned previously. So this is already happening in our codebase (with the exception that some scroll extent APIs might be wrong -- we might also need some tweaks for nested scroll containers in e.g. sidebars to work properly.).

However, this brings up another interesting issue: there should be a way if you have a hero image at the top of the ScrollContainer to not apply this adjustment, i.e. letting it overlap the top without being able to scroll down. And this ties the ScrollContainer discussion back to this ticket (and regular layouts should be adjusted in this case as well; there's some decisions to be made because this really only makes sense for iOS 26+ (we need to manually remove a scroll edge effect though), in iOS18- the blur can signal we can croll up further which is confusing.)

To me, rounded corners are a completely separate issue. That's a thing that is mostly avoided by having layouts that don't flow all the way to a content area's edge. IMHO, it's not a thing that we really need to concern ourselves with; UI testing of any specific layout can incorporate padding or margins to avoid those problem areas. We might be able to provide some overall design guidance, but ultimately, this should be in the hand of the designer.

Rounded corners, however, are different on almost every platform, even different versions of iOS, so I think we should at least expose that value somewhere.

[freakboy3742]

However, this brings up another interesting issue: there should be a way if you have a hero image at the top of the ScrollContainer to not apply this adjustment, i.e. letting it overlap the top without being able to scroll down. And this ties the ScrollContainer discussion back to this ticket (and regular layouts should be adjusted in this case as well; there's some decisions to be made because this really only makes sense for iOS 26+ (we need to manually remove a scroll edge effect though), in iOS18- the blur can signal we can croll up further which is confusing.)

If you have an idea for how to express that in a clean way, then I'm open to suggestions; but ultimately, Toga is an abstraction framework. There will be things you can't do with Toga because there isn't a clean way to make the abstraction work.

Toga's API need to expose a way to make a UI that is, by default, usable. We might be missing some features of some platforms in service of making an API where the default mode of operation is "safe by default". I'm completely OK with not exposing some features (like bleeding/static hero images) if it means the API remains obvious, and safe by default, for the 90% case of users.

Rounded corners, however, are different on almost every platform, even different versions of iOS, so I think we should at least expose that value somewhere.

Should we? Apple's HIG almost explicitly says the opposite - that content should bleed into the corners. This is, IMHO, stupid - and I cannot for the life of me work out why Apple has suddenly become obsessed with transparency and roundness - both of which objectively make it difficult or impossible to reach some content - but, those are Apple's rules, and we have to live with them.

[johnzhou721]

Rounded corners, however, are different on almost every platform, even different versions of iOS, so I think we should at least expose that value somewhere.

Should we? Apple's HIG almost explicitly says the opposite - that content should bleed into the corners. [...]

Apple's HIG:

Make sure backgrounds and full-screen artwork extend to the edges of the display.

(emphasis mine)

So say we want to have a status Label at the bottom of the screen, that's not background or full-screen artwork, and making that go down to the edge will make it clipped and unusable.

[...] This is, IMHO, stupid - and I cannot for the life of me work out why Apple has suddenly become obsessed with transparency and roundness

I agree. That's why I plan on developing on Linux (perhaps looking into how to get support for Linux phones) after I get done with this ticket and get liquid glass into a satisfiable state.

Clarification on the whole discussion, by the way: This is related to but distinct from the "liquid glass adaptation" work I was doing earlier, which lays out the views in a fairly standard area with the ability to extend some widgets. This part is about extending the performed layout in general.

However, this brings up another interesting issue: there should be a way if you have a hero image at the top of the ScrollContainer to not apply this adjustment, i.e. letting it overlap the top without being able to scroll down. And this ties the ScrollContainer discussion back to this ticket (and regular layouts should be adjusted in this case as well; there's some decisions to be made because this really only makes sense for iOS 26+ (we need to manually remove a scroll edge effect though), in iOS18- the blur can signal we can croll up further which is confusing.)

If you have an idea for how to express that in a clean way, then I'm open to suggestions; but ultimately, Toga is an abstraction framework. There will be things you can't do with Toga because there isn't a clean way to make the abstraction work.

Suggestion:

On window (because this works with a plain window as well) before we refresh the main container, a handler named "on_adjust_insets" -- in which 4 values are given for top, bottom, left, and right insets respectively; those insets on mobile will by default have 0 for bottom, left, and right, and the heights of the status and navigation bars for top.

Next, expose values for the height of status and navigation bars (and window toolbars on macOS; lots of apps are starting to use transparent window toolbars) and the height of the bottom rounded corner. Let's call those parameters window.top_bars and window.bottom_corners, respectively, so if you have a label at the bottom and want it to not be clipped by window corners, you would do:

def on_adjust_insets(self, window, top, bottom, left, right):
    bottom += window.bottom_corners
    return top, bottom, left, right

If you want a hero image in the window to overlap with the top bar, you'd do:

def on_adjust_insets(self, window, top, bottom, left, right):
    top -= window.top_bars
    return top, bottom, left, right

Now, the same thing for window above applies to ScrollContainer as well, but we choose slightly different inset values as defaults: we make top, bottom, left and right insets all follow the native safe area, i.e. areas not covered by bars etc. Users will then follow a similar approach to on_adjust_insets as above to adjusts the layout insets for the ScrollContainer [1]. So, for a ScrollContainer (after we implement liquid glass adaptation, scrollcontainers should automatically extend beyond layout insets regardless of what the layout is as long as it's at the edge of the layout) with an ImageView at the top, we can do this:

def on_adjust_insets(self, scroll_container, top, bottom, left, right):
    top -= self.window.top_bars
    return top, bottom, left, right

[1] By default, ScrollContainer automatically adjusts its display of its content container to follow these insets, but that does not work and requires manual tweaking for e.g. extending things under sidebar. Apple's SwiftUI automatically does all this work for you, though.

[johnzhou721]

At least for scroll container... it seems that the only usecases are "ignore insets on top/left/right/bottom", and specific adjustment isn't that necessary, since we might create the illusion of "still more content above/below" if it's at a weird place.

So for ScrollContainer, writing "ignore_insets=[bool, bool, bool, bool]" (or ignore_insets_top, ...) will probably just make sense if we choose to expose such things.

For window, for user tweaking instead of a function we can expose an enum to see how we can tweak window things. For possible things, we can have an API like this (names subject to change):

enum TopInset:
    Default --> what our behavior is right now, ignoring bars but allowing device notches
    IgnoreBars --> Content can overlap toolbars if the platform allows making it transparent (iOS 26+, macOS 26+), and potentially status bars / window titlebar.
    SafeCorners --> Content will not overlap any device notches and will not be clipped at all.

enum OtherInset:
    Default --> Can layout all the way to notches
    SafeCorners --> Content layout stops at device notches / window corners

// Possibly a BottomInset enum with a keyboard option when we get there?

I'm also going to suggest here that this is different from the liquid glass adaptation work I have been doing. We should still regardless of the layout options users choose, be able to automatically extend ScrollContainers when it makes sense on the platform; that is, for example, when a ScrollContainer is on the edge of the container, it will be extended beyond the container on iOS26+ and on iOS18-, extended only if ScrollContainer is the content of the container. Box objects should also be extended as well, in case they're used to provide background color to a view. Users will control how scrolling objects behave separately.

---

Drawing attention to this:

However, the more I think about this, the more I wonder if we actually do have a problem beyond the ability to maybe set the background tint of the titlebar and/or of the main window. This isn't a question the end user should need to concern themselves with - if I put a button in a scroll container, I shouldn't need to do mental gymnastics to work out how to pad that button in such a way that it can be pressed.

Sure -- we'd probably need to carefully implement this manually everywhere besides iOS and macOS (for which we'd need some tweaks but nothing major; [1] from last comment is partially inaccurate, but I don't want to get down to details too much right now).

---

@freakboy3742 Thoughts on the specific proposal I've made above in this comment, after thinking about possible usecases a bit more carefully? Thank you, and sorry for perhaps being too bold about features recently.

[freakboy3742]

My impression is that there's 2 separate problems being addressed here.

1. Providing helpers to avoid putting content into a rounded corner.
2. Providing tooling to break out of "normal" visible layout so that a hero image (or similar) can fill the full background of a layout.

It strikes me that these are two problems that need different solutions.

Regardless of rounded corners, it's entirely reasonable to put a label at the bottom of a layout. It's only a problem if that label also extends into the far left or far right of the layout. The size of the window radius is something you need to know in order to adapt to that... but it really is up to the app developer, and the specifics on one particular layout, whether that's a problem. It might make sense to expose the "corner radius" as a constant so that I could put margin=radius on an element that might stray into that space, or just put that margin on the entire top-level container... but will having that constant actually help? Most layout should have an external padding anyway, and AFAICT, the size of the "rounded corner dead space", even with the absurd Liquid Glass levels of roundness, is still smaller than you'd see in most layouts as "reasonable external padding".

The "bleed hero image under the titlebar" issue is a separate one - that's a fundamental question of layout. For this, I'd suggest the answer is a boolean, probably on (Main)Window - by default, the rendered area is "entirely safe"; but you can opt into letting your layout bleed under the titlebar if that will work in your specific app circumstances.

[johnzhou721]

@freakboy3742

I believe we could probably decide on if we want to expose radius for the usecase of margin=radius later.

So I propose MainWindow.bleed_top, a boolean, as the ability to have the top layout go into the window's title bar areas, if such functionality is available on the platform. If a ScrollContainer is at the top of the layout and is being extended outside of the regular area already (as per previous liquid glass discussion adaptations), it will lose the ability to pull down to the point where the top content matches the bottom edge of the top notch (default iOS behavior.)

Thoughts before I potentially start implementing this?