Skip to content

Add a Windows and Views page to the programming guide - #2973

Merged
pvcraven merged 1 commit into
developmentfrom
windows-views-guide
Oct 9, 2026
Merged

pvcraven merged 1 commit into
developmentfrom
windows-views-guide

Conversation

@pvcraven

@pvcraven pvcraven commented Oct 9, 2026

Copy link
Copy Markdown
Member

Closes #2549

Adds Windows and Views to the programming guide (Manual section, before Event Loop). It covers:

  • The Window: creating it, fullscreen, resizing, update and draw rates, background color. It links to the event loop page and the fullscreen and resizable examples.
  • Why use views: one class per screen instead of if self.state == ... in every method, with a menu → game example.
  • Showing views: what show_view() does, in order. __init__ runs once, but on_show_view runs every time the view is shown, so the page says what belongs in each. There's a pause-screen example that shows the same game view again, so the game continues.
  • How events reach a view: the view's method runs first, then the window's own method with the same name, unless the view returns True. The trap is a Window subclass whose on_draw draws on top of every view. pushfoo mentioned confusion about the on_ methods in the issue.
  • Resizing: a hidden view doesn't get on_resize, so update cameras in on_show_view.
  • Background color per view, and UIView: it enables and disables its UIManager on show and hide, and overrides must call super().
  • Links to the views tutorial, the three view examples and sections.

I checked the behavior described by running views in a hidden window: the order of calls, events reaching the view and then the window, returning True stopping the window's handler, and on_show_view running again when a view is reshown. I also ran the page's examples.

Docstring fixes

  • Window.show_view() said it shows the new view "in the next frame" and is "not a blocking call". It actually calls on_hide_view() on the old view and on_show_view() on the new one before returning. The docstring now says that and links to the new page.
  • View.on_show_view() said "Called once when the view is shown". It runs each time the view is shown. The docstring now says what belongs there versus __init__.
  • View.on_hide_view() now says when it's called and what it's for.

Viewport and scissor, mentioned in the issue, fit better in the camera guide, so they're not on this page.

The docs build with -W (nitpicky) passes, and ruff passes.

🤖 Generated with Claude Code

Explains the window, when to use views, what show_view does, why
on_show_view runs every time a view is shown, how events reach a view
and then the window, resizing while hidden, per-view background colors,
and UIView.

Fixes Window.show_view's docstring, which said the new view is shown in
the next frame; it calls on_hide_view and on_show_view before returning.
on_show_view's docstring said it's called once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pvcraven
pvcraven merged commit 4a33f86 into development Oct 9, 2026
7 checks passed
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.

Docs: Window / View section

1 participant