gfx/document_window.h
Desktop windows for an application: TopLevelWindow, ResizableWindow and DocumentWindow -- a component tree in a window of its own, with a title, close and minimise boxes, limits on its size, full screen and a menu bar.
#include <sonore/gfx/document_window.h>- 3types
- 1other declaration
- Guides: The native editor
On this page
Design notes
Built the way a host builds a plugin's window
The SDK already had the hard half: the window_*.h peers turn a component tree into pixels and the platform's input into component events, inside a parent window somebody else made. Here this SDK is that somebody else. A TopLevelWindow makes a FRAME -- an HWND, an NSWindow, an X window -- owns everything a frame owns (the title, the close box, the size limits, the zoomed and minimised states, always-on-top), and opens the very same peer inside it as a plugin editor would be opened inside a DAW. Nothing that the peers already do is done twice, and every fix to a peer reaches both.
The TopLevelWindow IS the root component, as in the reference: the peer paints it, and its children are the content, the drawn title bar, the menu bar and the resizers.
Native or drawn title bar
Native by default: the platform's own frame, buttons and edge dragging, with the limits enforced where the platform asks for them (WM_GETMINMAXINFO, WM_SIZING and WM_WINDOWPOSCHANGING; contentMin/MaxSize; WM_NORMAL_HINTS). setUsingNativeTitleBar(false) gives a frameless window with a title bar DRAWN by the tree -- its buttons, its double-click to zoom and its drag to move are components -- and resizing by a border or a corner grip that work in DESKTOP coordinates: a left-edge drag moves the window under the pointer, so measuring the drag in the window's own coordinates would feed every move back into the next.
Units
Everything here is LOGICAL: the units the tree is laid out in. A window's bounds are its CLIENT area -- the component -- on the desktop, divided by the window's scale on Windows and X11 (whose desktops are in device pixels) and in points on macOS (which is logical already).
Lifetime
The frame is made when it is first needed -- shown, measured, asked for its handle -- not in the constructor, because the style it is made with comes from getDesktopWindowStyleFlags(), a virtual a base constructor cannot reach. A change of style afterwards remakes it. closeButtonPressed() may delete the window: the drawn buttons report through the message queue, so nothing of the window is on the stack when it goes.
What runs where
Windows is RUN: sizes, limits, aspect ratio, the corner and border drags, the drawn title bar's buttons and drag, maximise/minimise/kiosk, always-on-top, alpha, the close box, keys reaching the tree, and the list of windows. The NSWindow and X11 frames are written against their documented APIs and only COMPILED here (no Mac, no X server).
Types 3
class TopLevelWindow : public Widget
A window on the desktop holding a component tree -- the tree being this object.
The base of ResizableWindow and DocumentWindow, and on its own a plain window: SplashScreen and the progress window are TopLevelWindows. Message thread only.
class ResizableWindow : public TopLevelWindow
A TopLevelWindow with a content component, size limits, a resizer, and the zoomed, minimised and full-screen states.
The reference's name "full screen" for setFullScreen is kept, and means what it means there: ZOOMED (maximised) -- the window fills the work area with its frame. Covering the whole monitor with no frame is setKioskMode.
class DocumentWindow : public ResizableWindow
A ResizableWindow with a title bar, its buttons, and a menu bar.
With the native title bar (the default) the buttons are the platform's; with setUsingNativeTitleBar(false) they are drawn (minimise, maximise, close, on the right or the left) and the bar drags the window. Either way a close request -- the box, Alt+F4, the drawn button -- arrives at closeButtonPressed(), and nothing closes unless that does something. The drawn buttons report through the message queue, so closeButtonPressed may delete the window.
The menu bar: setMenuBar(model) asks createMenuBarComponent(model) for the component that shows it -- gfx/menu_bar.h's MenuBarComponent unless it is overridden (or setMenuBarComponent hands one over directly).