gfx/multi_document.h
MultiDocumentPanel: several documents in one area, as tabs or as windows.
#include <sonore/gfx/multi_document.h>- 2types
- 1other declaration
- Guides: The native editor
On this page
Design notes
What it is for here
A plugin with more than one thing open at once -- several sample editors in a sampler, a modulation matrix beside an envelope, the scripts of a scriptable effect -- and a standalone app built on this SDK. The panel holds documents (any Component) and shows them one of two ways: as tabs, one document filling the area under a tab strip, or as windows floating inside the panel that can be moved, resized, raised and closed. Switching between the two keeps every window's place.
Windows inside the editor, not on the desktop
The windows are components, drawn with a title bar by the look-and-feel. A plugin may not open top-level windows of its own without risking them behind the host's -- alert.h has that story -- and documents that float inside the editor cannot be lost.
An inactive window takes the FIRST click to come to the front and nothing else: its content is covered until then. A click that both raised a window and pressed the button under it would act on a document the user had not yet seen come forward.
Closing is a question
A document with unsaved changes has to be able to say no. tryToCloseDocument is asked first and answers through a callback rather than a return value, so the answer can come after an AlertOverlay has asked the user -- nothing here blocks, and nothing in a plugin may.
Destroyed later, not now
A window is closed from its own close button, and an owned document often from a button inside it. Destroying either there frees the object whose click is still on the stack. They are taken out of the tree at once -- the router forgets everything inside -- and freed at the next paint.
Types 2
class MultiDocumentPanelWindow : public Widget
One floating document: a frame with a title bar, a close button and a resize corner, around the document.
class MultiDocumentPanel : public Widget
Several documents in one area, as tabs or as windows floating inside it -- the reference's MultiDocumentPanel. The file comment covers the windows, closing as a question, and why destruction is deferred.
A document is any Component, either owned by the caller (it must outlive its time here, and is handed back out of any window when it closes or the panel goes) or handed over as a unique_ptr and destroyed when it closes -- at the next paint, not inside the close call. Message thread only; tryToCloseDocument may answer later, after asking the user.