Surface class
#include <Jazz2/UI/Windows/Surface.h>
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
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
trueif a modal element is shown. - auto HasOverlays() const -> bool
- Returns
trueif any element is shown over the interface. - auto HasStackedModal() const -> bool
- Returns
trueif 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
trueif an element is shown over the interface and isn't closing. - auto IsDetached(const Element* element) const -> bool
- Returns
trueif an element is in a window of its own, outside of the main window. - auto CanDetach() const -> bool
- Returns
trueif 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
trueif the interface took it. - auto OnPointerMove(const PointerEvent& event) -> bool
- Passes a move of the pointer, returns
trueif it's over the interface or the interface holds it. - auto OnPointerUp(const PointerEvent& event) -> bool
- Passes a release of the pointer, returns
trueif the interface took it. - auto OnWheel(const PointerEvent& event) -> bool
- Passes scrolling, returns
trueif the interface took it. - auto OnKeyPressed(const KeyboardEvent& event) -> bool
- Passes a key, returns
trueif the interface took it. - auto OnTextInput(const TextInputEvent& event) -> bool
- Passes typed text, returns
trueif the interface took it. - auto IsOverInterface(Vector2f pos) -> bool
- Returns
trueif the interface is under a position. - auto TakesTouchAt(Vector2f pos) -> bool
- Returns
trueif 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
trueif 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
Tabreaches, 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
truewhile the tree of the interface is drawn into the picture of the level. - auto LeavesKeyToShortcuts(const KeyboardEvent& event) -> bool
- Returns
trueif 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
trueif 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
trueif 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
truefor a key that runs a shortcut even while a text is typed, such as saving. - Function<bool(const KeyboardEvent&)> IsKeyLeftByText
- Returns
truefor 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::
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::
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.
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::
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::
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::
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::
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::
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.