Draft – Requesting Feedback on Architectural Direction

[zinzilulo]

This PR migrates Stellarium’s UI from custom window/dialog infrastructure to standard Qt windowing (QMainWindow, QDialog).

The primary goal is to remove custom UI glue and rely on Qt’s native behavior for window management, focus, modality, and platform integration. No new UI concepts or workflows are introduced.

Description

Key changes include:

• Introduction of StelMainWindow as the owner of application-level UI concerns (menubar, window title/icon, geometry, window management).
• Ownership of the main view moved under StelMainWindow to allow correct dialog parenting.
• Unification of dialog handling into a single StelDialog inheriting from QDialog.
• Removal of legacy dialog/window helpers (StelDialogSeparate, TitleBar, ResizeableFrame, and related proxy logic).
• Mechanical updates to all plugins to use StelDialog, QWidget, or QDialog.
• Thinning of main.cpp; UI responsibilities moved into StelMainWindow.
• StelMainView no longer manages window title or icon (further refactoring planned separately).
• StelApp remains largely unchanged.

Because Qt windowing defines layout, focus, and stacking behavior, this migration results in broad UI changes. These are a direct consequence of removing custom infrastructure rather than an intentional redesign. A minimal Qt stylesheet is included to provide a functional baseline after the migration; it is not coupled to the architectural changes and can be freely modified or removed.

Screenshots (if appropriate):

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• This change requires a documentation update
• Housekeeping

How Has This Been Tested?

Manual testing focused on functional parity and regression detection:

• Application startup and shutdown
• Main window creation and geometry handling
• Dialog creation, modality, stacking, and focus
• Plugin dialogs and windows
• Basic interaction workflows
• This PR does not introduce automated tests; changes are primarily architectural and UI-related.

Test Configuration:

• Operating system: macOS 26.2
• Graphics Card: Apple M4 Max
• CMake: CC=clang CXX=clang++ cmake ../ -GNinja -DENABLE_QT6=ON -DENABLE_QTWEBENGINE=OFF -DENABLE_TESTING=ON

Test Results:

• All Stellarium-owned tests passed locally
• Some third-party dependency tests are reported as “Not Run” (skipped), which appears to be expected and unrelated to this change

Checklist:

• My code follows the code style of this project.
  • Best effort will be made to align further if this is merged
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (header file)
• I have updated the respective chapter in the Stellarium User Guide
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[alex-w]

A main question is… for what?

[zinzilulo]

A main question is… for what?

This work started from exploring how to add a menubar, which reveals that the existing UI architecture does not align well with Qt’s windowing model and makes standard Qt UI features awkward to implement. Rather than extending the custom window and dialog infrastructure further, I moved the UI closer to Qt’s intended usage (QMainWindow, QDialog).
This reduces technical friction for future work that relies on Qt’s native windowing behavior. As a side effect of removing the custom windowing layer, window moving and resizing are now handled natively by the OS, switching between dialogs and windows integrates better with the system window manager, and accessibility works more naturally. These are not the primary goals, but welcome improvements that come from relying on Qt instead of reimplementing its behavior.

[alex-w]

Why you need to see a menubar?

[10110111]

the existing UI architecture does not align well with Qt’s windowing model

I think this is intentional.

Besides, what you're doing is not just switching to Qt-based window management, it separates Stellarium windows, turning Stellarium's behavior from MDI to a very different model, with separate window getting focus while deactivating the main window. This is a problem on some GPUs in Windows, where the exclusive full screen mode gets flicker when separate windows (even as simple as tooltips) appear, see the discussion in #4678.

Also, how well do the global shortcuts like F4 work now? Do they open the corresponding dialog even when Stellarium window isn't active (e.g. minimized)? Or, if not, do they work when, say, the Help dialog is active?

And, you will now have to implement full support for the Night mode in the CSS (and this will miss the window decorations (and possibly window glow), unless you implement them on the client side, which loses the native OS window dragging-by-titlebar you aimed to get).

[gzotti]

Stellarium's UI style is one of the original features that even predate Qt's use (not sure about the sliding bars, but the lower menu bar is ancient) and is one identifying feature of this program. While I would like to see somebody implement a working alternative GUI using QML which might fit better in an optional Android build on small-screen/vertical devices, I am not sure I want to see a "standard" menu bar just for the sake of having a menu bar. Are there any user benefits? How does that change full-screen mode?

[10110111]

I think the menu bar is something we could have as an optional feature. This wouldn't require the drastic change of window management as is done in this PR, and it could just be a plugin, similarly to the TUI or Remote Control plugins.

I would like to see somebody implement a working alternative GUI using QML which might fit better in an optional Android build on small-screen/vertical devices

IMO, QML would be unmanageable with the huge number of GUI options Stellarium has. Currently we can visually place all the checkboxes/radios/buttons etc. in the right places thanks to Qt Designer. But is there such a visual tool for QML?

[gzotti]

Menu bar as plugin: OK. Or even as CMake option fore self-builders whose lives depend on menu bars, as long as it can be maintained with low effort.
QML: I don't know it well enough. Most examples show 1-2 GUI elements created on the fly, and I wonder the same about larger GUIs. Without an equivalent support like Qt Designer it's likely unmanageable. (It's already a nightmare updating 2 RemoteControl GUI pages.) What are other projects doing? We had a few PRs showing Android builds with modified GUIs. All broke the standard build and were still unusable on small-screen devices (speaking only of my 10" tablet), and IMO the UI is just not usable for pure touch devices. It might be possible QML has some advantage here, but I won't invest another year into this. Alternatively, maybe the RC GUI can be made "responsive" as sole GUI for small-screen devices, with a dedicated button to call it. My HTML/CSS skills are too rusty for that, though.

[zinzilulo]

Thanks for the detailed feedback. After considering the concerns raised here, I agree that this work should be split and the scope narrowed, while still clearly describing the intended behavior of each part.

Concretely, I suggest splitting this into two parts:

1. Menubar & application-level UI ownership (upstream)

This part is non-breaking and primarily housekeeping:

• Introduce QMainWindow (StelMainWindow) as the owner of application-level UI concerns (menubar, window title/icon, geometry).
• Thin main.cpp and StelMainView accordingly.
• Provide the menubar behind a CMake option, so it remains optional and low-risk for platforms or builds that do not want it.

With the option disabled (default), behavior is identical to current master:

• No change to dialog behavior
• No change to focus rules or shortcuts
• No change to visual layout

On macOS menubar has effectively no visual impact:

• The menubar is always separate from the application window and is part of the platform’s standard UX.
• It behaves identically in fullscreen and windowed mode.

“Why you need to see a menubar?”

Beyond convention, the macOS menubar enables standard system features (notably Help-menu search) without introducing new workflows or UI concepts. This improves discoverability while keeping Stellarium’s existing interaction model intact.

2. Dialog / window model migration (downstream for now)

I understand that Stellarium’s current MDI-like dialog model is intentional and historically motivated, particularly for fullscreen stability and visual consistency.

“The existing UI architecture does not align well with Qt’s windowing model. I think this is intentional.”

Agreed. The dialog refactor (moving fully to native QDialog and removing the proxy/MDI-like layer) is a separate and more consequential change. It intentionally moves Stellarium away from an MDI-like model toward native multi-window behavior, with the following effects:

• Window moving, resizing, stacking, and modality are handled by the OS and Qt rather than custom infrastructure.
• Switching between or closing dialogs and windows integrates naturally with the system window manager.
• Accessibility and platform integration work more naturally because native windows are no longer hidden behind a custom compositor.

At the same time, this change has clear trade-offs, including:

• Known fullscreen interactions on Windows (including GPU-specific issues)
• Reduced control over native window decorations, with implications for night mode
• A visible behavioral shift compared to the historical MDI-style model

Given those trade-offs, I’m happy to continue evaluating this dialog/windowing model downstream and report concrete findings (especially around Windows fullscreen behavior, night mode and platform-appropriate dialog presentation, such as native sheets where available) before proposing anything upstream.

Summary

• Menubar / QMainWindow refactor: optional, contained, non-breaking, and preserves Stellarium’s UI identity.
• Dialog/windowing changes: intentional behavior change with benefits and costs; better evaluated and refined independently.

If this split sounds reasonable, I’ll rework this PR to contain only the QMainWindow introduction and optional menubar, and move the dialog/windowing refactor to a separate downstream branch or follow-up.

[gzotti]

There is some QML GUI design support, not tested: https://doc.qt.io/qtcreator/creator-qtquickdesigner-plugin.html. The full Qt Design Studio requires more than a FOSS license, though. :-(

[10110111]

If this split sounds reasonable, I’ll rework this PR to contain only the QMainWindow introduction and optional menubar, and move the dialog/windowing refactor to a separate downstream branch or follow-up.

The optional menubar feature sounds OK. The windowing change needs more consideration.