Jazz2::UI::Windows::Surface class

Shows the interface and passes input to it.

The surface is drawn over the whole window at its own scale, in pixels of the screen. It holds the tree of the interface and the elements shown over it — menus, dialogs, tooltips. Whatever the pointer does over the interface goes to it, the rest is left to the view of the level.

Base classes

class Jazz2::UI::Canvas
Canvas.

Public static variables

static std::int32_t RootSlots constexpr
Number of slots the root draws in, the one it's given and those after it, for panels floating over the others.

Public static functions

static auto GetReadableFont(float textScale) -> UI::Font*
Returns the readable font for text drawn at a scale, see ReadableFont::Get().
static auto GetResizeOverlay(bool left, bool top, bool right, bool bottom) -> CursorOverlay
Returns the arrows for resizing by edges, a corner if one edge of each direction is set, CursorOverlay::None if none is.
static auto GetPanelsDepth() -> std::uint16_t
Returns the depth the panels are drawn from, what is shown over the level is drawn below it.
static auto GetOverlaysDepth() -> std::uint16_t
Returns the depth elements shown over the interface are drawn from, see HasStackedModal().
static void NotifyDestroyed(Element* element)
Forgets an element that is being destroyed.
static void Retire(std::unique_ptr<Element> element)
Takes an element out of the interface, it's destroyed at the start of the next frame.

Constructors, destructors, conversion operators

Surface()
~Surface() override
Surface(const Surface&) deleted

Public functions

auto operator=(const Surface&) -> Surface& deleted
template<class T, class... Args>
auto SetRoot(Args && ... args) -> T*
Sets the root of the interface.
auto SetRoot(std::unique_ptr<Element> root) -> Element*
Sets the root of the interface.
auto GetRoot() const -> Element*
Returns the root of the interface.
auto PushOverlay(std::unique_ptr<Element> element, OverlayOptions&& options) -> Element*
Shows an element over the interface.
void CloseOverlay(Element* element)
Closes an element shown over the interface, it's destroyed at the end of the frame.
void MoveOverlay(Element* element, Vector2f position, float fallbackRight = -1.0f)
Moves an element shown over the interface, its top left corner, it's no longer centered then.
auto RaiseOverlay(Element* element) -> bool
Brings a window shown over the interface in front of the other windows and gives it the keyboard.
void ClosePopups()
Closes all popups — menus, lists and pickers — windows stay, see OverlayOptions.
auto HasModal() const -> bool
Returns true if a modal element is shown.
auto HasOverlays() const -> bool
Returns true if any element is shown over the interface.
auto HasStackedModal() const -> bool
Returns true if a modal element is shown over another element shown over the interface, as a file picker over a dialog.
auto IsOverlayShown(const Element* element) const -> bool
Returns true if an element is shown over the interface and isn't closing.
auto IsDetached(const Element* element) const -> bool
Returns true if an element is in a window of its own, outside of the main window.
auto CanDetach() const -> bool
Returns true if elements can be shown in windows of their own, it depends on the system and AllowDetaching.
auto PlaceDetachable(Element* element, const Rectf& wanted, bool moving, bool restore = false) -> Rectf
Lets an element of the tree of the interface get a window of its own once it's moved out of the main window.
void ReleaseDetachable(Element* element)
Shows an element placed by PlaceDetachable() in the main window again, as when it was docked.
auto GetScale() const -> float
Returns the scale of the interface, pixels per unit.
void SetScale(float scale)
Sets the scale of the interface.
auto GetContext() const -> Context
Returns what the interface is measured with.
auto GetFont() const -> UI::Font*
Returns the font of the interface, filtered as the scale needs, see Context::GetFont().
auto GetScreenSize() const -> Vector2f
Returns the size of the screen in pixels.
auto GetSafeBounds() const -> Rectf
Returns the part of the screen the interface is kept in, in pixels, see SafeMargins.
auto OnPointerDown(const PointerEvent& event) -> bool
Passes a press of the pointer, returns true if the interface took it.
auto OnPointerMove(const PointerEvent& event) -> bool
Passes a move of the pointer, returns true if it's over the interface or the interface holds it.
auto OnPointerUp(const PointerEvent& event) -> bool
Passes a release of the pointer, returns true if the interface took it.
auto OnWheel(const PointerEvent& event) -> bool
Passes scrolling, returns true if the interface took it.
auto OnKeyPressed(const KeyboardEvent& event) -> bool
Passes a key, returns true if the interface took it.
auto OnTextInput(const TextInputEvent& event) -> bool
Passes typed text, returns true if the interface took it.
auto IsOverInterface(Vector2f pos) -> bool
Returns true if the interface is under a position.
auto TakesTouchAt(Vector2f pos) -> bool
Returns true if a finger at a position is the interface's at once, not one that may still pan the view, see Element::YieldsToViewGestures().
void TrackPointer(Vector2f pos)
Follows the pointer while its moves go elsewhere.
auto GetPointerPos() const -> Vector2f
Returns the last position of the pointer.
auto HasCapture() const -> bool
Returns true if the interface holds the pointer.
void CancelPointerCapture()
Lets go of the pointer the interface holds, the element that holds it is told it was cancelled, not released.
void DismissTooltip()
Hides the tooltip and forgets what is pointed at, until the pointer moves again.
void SetFocus(Element* element)
Gives the keyboard focus to an element, or takes it away.
auto GetFocus() const -> Element*
Returns the element with the keyboard focus, or nullptr.
auto MoveFocus(bool backwards) -> bool
Gives the focus to the next element Tab reaches, or the previous one.
void EnsureVisible(Element* element)
Scrolls the list an element is in so the element is seen.
auto GetHover() const -> Element*
Returns the element under the pointer, or nullptr.
void ShowToast(StringView text, IconId icon = StockIcon::Info)
Shows a short message for a while.
void SetCursorOverlay(CursorOverlay overlay)
Shows an icon by the pointer for this frame, as the cursor of a window would show it.
auto GetCursorOverlay() const -> CursorOverlay
Returns what is shown by the pointer in this frame so far.
auto GetPointerLabelOffset(float distance) const -> float
Returns how far below the pointer a label shown by it starts, in pixels.
void SetPointerTooltip(StringView text)
Shows a tooltip by the pointer for this frame, at once.
auto GetPanelsNode() -> SceneNode*
Returns the node that draws the tree of the interface into the picture of the level, the surface owns it, see DrawsPanelsInLevel.
auto IsDrawingInLevel() const -> bool
Returns true while the tree of the interface is drawn into the picture of the level.
auto LeavesKeyToShortcuts(const KeyboardEvent& event) -> bool
Returns true if a text box being typed into leaves a key to the shortcuts, see IsKeyLeftByText.
void OnUpdate(float timeMult) override
Called every frame to update the node state.
auto OnDraw(RenderQueue& renderQueue) -> bool override
Called when the node needs to be drawn, returning true if a command was added.

Public variables

bool AllowDetaching
Whether elements may get windows of their own outside of the main window.
Function<void(Painter&, Vector2f)> DrawOver
Draws over all of the interface, in a slot of its own and the slot after it, with the size of the screen.
Function<const Texture*(BackdropKind, Vector2f, Rectf&, bool)> GetBackdrop
Returns a blurred picture of what is behind a part of the interface and the part of the screen it covers, or nullptr.
Function<bool()> DrawsPanelsInLevel
Returns true if the tree of the interface is drawn into the picture of the level in this frame.
bool ShowVirtualCursor
Whether a cursor moved by a gamepad is shown.
Vector2f VirtualCursor
Position of the cursor moved by a gamepad, in pixels of the screen.
bool TouchInput
Whether the pointer is a finger.
bool WindowsHidden
Whether windows that aren't modal are hidden, as while a level is played, they're shown again after.
float KeyboardInset
Height of the bottom of the screen a keyboard of the system covers, in pixels, set every frame.
Thickness SafeMargins
Part of each edge of the screen the interface keeps clear of, as a fraction of its width or height.
Function<bool(const KeyboardEvent&)> IsPassThroughKey
Returns true for a key that runs a shortcut even while a text is typed, such as saving.
Function<bool(const KeyboardEvent&)> IsKeyLeftByText
Returns true for a key a text being typed doesn't take, it goes on to the shortcuts, such as showing the help.

Function documentation

static UI::Font* Jazz2::UI::Windows::Surface::GetReadableFont(float textScale)

Returns the readable font for text drawn at a scale, see ReadableFont::Get().

The surface keeps it. Returns nullptr if there's no surface or the font can't be read.

static void Jazz2::UI::Windows::Surface::Retire(std::unique_ptr<Element> element)

Takes an element out of the interface, it's destroyed at the start of the next frame.

Nothing points at it or anything in it from then on — the pointer, the focus — a press held by it is taken away (see Element::OnPointerCancel()). It's destroyed at once if there's no surface.

Element* Jazz2::UI::Windows::Surface::PushOverlay(std::unique_ptr<Element> element, OverlayOptions&& options)

Shows an element over the interface.

A modal element takes the keyboard focus away from everything under it, a text being typed there is confirmed first.

void Jazz2::UI::Windows::Surface::MoveOverlay(Element* element, Vector2f position, float fallbackRight = -1.0f)

Moves an element shown over the interface, its top left corner, it's no longer centered then.

See OverlayOptions::FallbackRight for fallbackRight.

bool Jazz2::UI::Windows::Surface::RaiseOverlay(Element* element)

Brings a window shown over the interface in front of the other windows and gives it the keyboard.

It stays under modal elements shown after it. A focus outside of it is taken away, so keys go to it. Returns false if the element isn't shown over the interface.

bool Jazz2::UI::Windows::Surface::HasStackedModal() const

Returns true if a modal element is shown over another element shown over the interface, as a file picker over a dialog.

While the tree of the interface is drawn into the picture of the level, the elements under the top modal one are drawn there too, over BackdropKind::UnderModal, so the picture behind the modal one has them.

bool Jazz2::UI::Windows::Surface::IsDetached(const Element* element) const

Returns true if an element is in a window of its own, outside of the main window.

An element shown over the interface (see OverlayOptions::Detachable) or one of the tree of the interface (see PlaceDetachable()). Its position is still relative to the main window, as the positions of the pointer over it are, see PointerEvent::WindowId.

Rectf Jazz2::UI::Windows::Surface::PlaceDetachable(Element* element, const Rectf& wanted, bool moving, bool restore = false)

Lets an element of the tree of the interface get a window of its own once it's moved out of the main window.

As a floating panel. Called every frame while the element may have one, with where it wants to be relative to the main window in pixels and whether the user is moving it now. Returns where it is: in a window of its own it stays where it is on the desktop while it isn't moved, also when the main window moves, so it moves relative to the main window. Once it's moved back into the main window, or ReleaseDetachable() is called, it's shown in the main window again. While this isn't called for it, as while it's hidden, its window is hidden and comes back with it. With restore, it gets a window of its own also when it isn't moved, if it wants to be outside of the main window — as it was the last time. Its parent doesn't draw it while it's in a window of its own, see Element::IsDetached().

Rectf Jazz2::UI::Windows::Surface::GetSafeBounds() const

Returns the part of the screen the interface is kept in, in pixels, see SafeMargins.

The whole screen unless the margins are set. Windows, menus and messages are placed inside of it, and the root is expected to place its panels there too, it's given the whole screen.

void Jazz2::UI::Windows::Surface::TrackPointer(Vector2f pos)

Follows the pointer while its moves go elsewhere.

Called for every move, also while the view or a tool holds the pointer and the interface doesn't get the moves, so what is shown by the pointer, such as the cursor overlay, stays with it.

bool Jazz2::UI::Windows::Surface::MoveFocus(bool backwards)

Gives the focus to the next element Tab reaches, or the previous one.

Only inside of a modal element if one is shown, otherwise inside of where the focus is, of the top element shown over the interface, or of the panels. Returns false if there's nothing to go to.

void Jazz2::UI::Windows::Surface::SetCursorOverlay(CursorOverlay overlay)

Shows an icon by the pointer for this frame, as the cursor of a window would show it.

Called every frame by whatever is pointed at or dragged — in Element::Update() or in Element::Draw() — it's forgotten after the frame is drawn, so it goes away by itself once nothing asks for it. The last call in a frame wins. It's drawn over everything at a distance from the pointer that grows with the scale of the interface, and not at all for a finger.

float Jazz2::UI::Windows::Surface::GetPointerLabelOffset(float distance) const

Returns how far below the pointer a label shown by it starts, in pixels.

Below the cursor overlay set so far in this frame, so it doesn't cover the label, or distance if none is.

void Jazz2::UI::Windows::Surface::SetPointerTooltip(StringView text)

Shows a tooltip by the pointer for this frame, at once.

Called every frame by whatever is dragged and tells something of it, such as the size it gives — as SetCursorOverlay(), it's forgotten after the frame is drawn and the last call in a frame wins. It looks and is placed as the tooltip of an element, which it's shown instead of, and also while the pointer is held.

bool Jazz2::UI::Windows::Surface::IsDrawingInLevel() const

Returns true while the tree of the interface is drawn into the picture of the level.

The panels show what is under them blurred then, so what is shown over the level is seen under them too.

Variable documentation

Function<const Texture*(BackdropKind, Vector2f, Rectf&, bool)> Jazz2::UI::Windows::Surface::GetBackdrop

Returns a blurred picture of what is behind a part of the interface and the part of the screen it covers, or nullptr.

Asked for every frame with the size of the screen, before the part is drawn, which is drawn over the picture then, see Painter::Backdrop(). The last argument tells whether the tree of the interface is drawn into the picture of the level in this frame, see DrawsPanelsInLevel.

Function<bool()> Jazz2::UI::Windows::Surface::DrawsPanelsInLevel

Returns true if the tree of the interface is drawn into the picture of the level in this frame.

Asked for every frame while the picture is drawn, if the node of GetPanelsNode() is drawn into it. The tree is drawn with the rest otherwise.

bool Jazz2::UI::Windows::Surface::TouchInput

Whether the pointer is a finger.

Nothing is pointed at without touching then. A tooltip is shown by holding a finger still, and a finger dragged over a list scrolls it.

float Jazz2::UI::Windows::Surface::KeyboardInset

Height of the bottom of the screen a keyboard of the system covers, in pixels, set every frame.

A text box typed into stays above it — a window it's in is moved up, the panels are laid out above the keyboard if it's in them and would be covered.

Thickness Jazz2::UI::Windows::Surface::SafeMargins

Part of each edge of the screen the interface keeps clear of, as a fraction of its width or height.

For a display that cuts off the edges of the picture, as a television can. What is behind the interface, the level, still takes the whole screen. See GetSafeBounds().

Function<bool(const KeyboardEvent&)> Jazz2::UI::Windows::Surface::IsPassThroughKey

Returns true for a key that runs a shortcut even while a text is typed, such as saving.

The text is confirmed first, then the key goes on to the shortcuts as if nothing was typed into.

Function<bool(const KeyboardEvent&)> Jazz2::UI::Windows::Surface::IsKeyLeftByText

Returns true for a key a text being typed doesn't take, it goes on to the shortcuts, such as showing the help.

Unlike IsPassThroughKey, the text stays as it is being typed. Only keys that type nothing should be left, such as function keys. If it's not set, F1 and F5 are. Tab is always left, it moves the focus.