Jazz2::UI::Windows::Element class

Element of the interface.

Elements form a tree. A parent measures and places its children every frame, so whatever an element shows is always read from the application as it is — nothing has to be told to update. Sizes set on an element are in units, its bounds are in pixels of the screen.

Derived classes

class Button
Button with a text, an icon or both.
class CheckBox
Check box with a text.
class ColorPicker
Picks a color by its saturation and value in a square, its hue in a bar next to it, and optionally alpha.
class ColorSwatch
Shows a color, a translucent one over a checkerboard.
class DockFrame
Panel that is docked at an edge of the screen or floats over everything else.
class Dropdown
Shows a value and opens a menu to choose another one.
class FormRow
Row of a Form.
class Label
Text.
class MenuBarItem
Item of the menu bar, opens its menu.
class MenuRow
Row of a menu.
class PaletteGrid
The 256 entries of a palette in a grid of 16 × 16, to pick one of them, or a range of them.
class RadialMenu
Menu of items in a ring around a point, as the weapon wheel of the game.
class ScrollView
Shows a part of its content and lets the rest be scrolled to.
class Separator
Line between parts of a panel.
class Splitter
Edge of a panel that is dragged to resize it.
class Stack
Places its children in a row or a column.
class TextBox
Single line of text that can be edited.
class VirtualList
List of rows of the same height that draws only the rows that are seen.

Public static variables

static float Auto constexpr
Size that is decided by the content.

Public static functions

static void BeginLayout()
Starts a frame of layout, sizes measured until EndLayout() are kept for it.
static void EndLayout()
Ends a frame of layout.
static auto GetLayoutFrame() -> std::uint32_t
Returns a number of the current frame of layout, 0 outside of it.

Constructors, destructors, conversion operators

Element()
~Element() virtual
Element(const Element&) deleted

Public functions

auto operator=(const Element&) -> Element& deleted
auto GetParent() const -> Element*
Returns the parent, or nullptr.
auto GetChildCount() const -> std::int32_t
Returns the number of children.
auto GetChild(std::int32_t index) const -> Element*
Returns a child.
auto AddChild(std::unique_ptr<Element> child) -> Element*
Adds a child.
template<class T, class... Args>
auto Add(Args && ... args) -> T*
Creates and adds a child.
auto InsertChild(std::size_t index, std::unique_ptr<Element> child) -> Element*
Adds a child before the child at index, at the end if it's past the last one.
void ClearChildren()
Removes all children.
auto GetSurface() const -> Surface*
Returns the surface the element is shown on, or nullptr.
auto IsShown() -> bool
Returns true if the element is shown.
auto IsUsable() -> bool
Returns true if the element and all its parents can be used.
auto IsHovered() const -> bool
Returns true if the pointer is over the element.
auto IsPressed() const -> bool
Returns true if the element is being pressed.
auto IsFocused() const -> bool
Returns true if the element has the keyboard focus.
auto GetHoverAmount() const -> float
Returns how much the element is highlighted by the pointer over it, from 0 to 1, animated.
auto Measure(const Context& context, Vector2f available) -> Vector2f virtual
Returns the size the element wants, in pixels.
auto MeasureCached(const Context& context, Vector2f available) -> Vector2f
Returns the size the element wants as Measure() does, measured at most once a frame for the same space.
auto MeasureDependsOnAvailable() const -> bool virtual
Returns false if what Measure() returns doesn't depend on the available size, it's measured once a frame then.
void Arrange(const Context& context, const Rectf& bounds) virtual
Places the element and its children.
void Draw(Painter& painter) virtual
Draws the element and its children.
void Update(float timeMult) virtual
Advances animations of the element and its children.
auto HitTest(Vector2f pos) -> Element* virtual
Returns the element under a position that takes the pointer, or nullptr.
auto GetHitBounds() const -> Rectf virtual
Returns the area the element takes the pointer in, its bounds unless it's grabbed a little outside of them, as a window by its edges.
auto AcceptsPointer() const -> bool virtual
Returns true if the element takes the pointer itself.
auto OnPointerDown(const PointerEvent& event) -> bool virtual
Called when the pointer is pressed over the element, returns true to keep getting it until released.
void OnPointerDownInside(const PointerEvent& event) virtual
Called before the pointer is pressed over an element inside of this one, on each of its parents.
void OnPointerMove(const PointerEvent& event) virtual
Called when the pointer moves while pressed over the element.
void OnPointerUp(const PointerEvent& event, bool inside) virtual
Called when the pointer is released, inside tells whether it's still over the element.
void OnPointerCancel() virtual
Called instead of OnPointerUp() when the press was taken away, such as by a finger scrolling the list it's in.
auto YieldsToScroll() const -> bool virtual
Returns true if a press on the element may become scrolling of the list it's in.
auto DragsAfterHold() const -> bool virtual
Returns true if a finger has to rest on the element for a moment before it drags it.
auto YieldsToViewGestures() const -> bool virtual
Returns true if the element lies over the level view and a finger on it may still pan the view.
void OnPointerHold(const PointerEvent& event) virtual
Called when a finger rested on an element that drags after it's held, its moves come from now on, see DragsAfterHold().
auto OnWheel(const PointerEvent& event) -> bool virtual
Called when the pointer is scrolled over the element, returns true if it was used.
auto OnKeyPressed(const KeyboardEvent& event) -> bool virtual
Called when a key is pressed while the element has the focus, returns true if it was used.
auto OnTextInput(const TextInputEvent& event) -> bool virtual
Called when text is typed while the element has the focus.
auto IsFocusable() const -> bool virtual
Returns true if the element can take the keyboard focus.
auto IsTabStop() const -> bool virtual
Returns true if Tab can give the element the keyboard focus.
auto KeepsFocus() const -> bool virtual
Returns true if a click on the element, or inside of it, leaves the focus where it is, as the keys of a keyboard on the screen.
void OnFocusChanged(bool focused) virtual
Called when the element gets or loses the keyboard focus.
auto GetTooltip(Vector2f pos) const -> StringView virtual
Returns the tooltip at a position.
auto GetTitle() const -> StringView virtual
Returns the title of the element as a window, the system shows it on the taskbar while it's in a window of its own.
auto IsDetached() const -> bool
Returns true if the element of the tree is in a window of its own, see Surface::PlaceDetachable().

Public variables

Rectf Bounds
Bounds in pixels of the screen, set when the element is placed.
bool Visible
Whether the element is shown.
bool Enabled
Whether the element can be used, a disabled element is dimmed.
float Width
Width in units, or Auto.
float Height
Height in units, or Auto.
float Flex
How much of the space left in a stack the element takes, relative to the others.
String Tooltip
Text shown when the pointer rests over the element.
Function<bool()> IsVisibleFunc
Returns whether the element is shown, replaces Visible when set.
Function<bool()> IsEnabledFunc
Returns whether the element can be used, replaces Enabled when set.

Protected functions

auto GetFixedSize(const Context& context) const -> Vector2f
Returns the fixed size in pixels, or a negative value for Auto.

Protected variables

SmallVector<std::unique_ptr<Element>, 0> _children
Element* _parent
Surface* _surface
bool _hovered
bool _pressed
bool _focused
float _hoverAmount

Function documentation

void Jazz2::UI::Windows::Element::ClearChildren()

Removes all children.

They're taken out of the interface at once, but destroyed only at the start of the next frame (see Surface::Retire()), so a callback of a child may rebuild what the child is in and the child still finishes what it was doing.

Vector2f Jazz2::UI::Windows::Element::Measure(const Context& context, Vector2f available) virtual

Returns the size the element wants, in pixels.

The available size is what the parent can give, a size without limit is a very large number.

Vector2f Jazz2::UI::Windows::Element::MeasureCached(const Context& context, Vector2f available)

Returns the size the element wants as Measure() does, measured at most once a frame for the same space.

The layout of a frame asks for the size of an element again and again, once by each of its parents. While the surface lays out the interface, the size is kept for the rest of the frame, nothing changes then. Parents should measure their children by this.

bool Jazz2::UI::Windows::Element::YieldsToScroll() const virtual

Returns true if a press on the element may become scrolling of the list it's in.

A finger dragged over a button scrolls the list then, the button isn't clicked. Elements that are dragged themselves keep the press.

bool Jazz2::UI::Windows::Element::DragsAfterHold() const virtual

Returns true if a finger has to rest on the element for a moment before it drags it.

A finger dragged at once scrolls the list the element is in instead, and the element gets no moves until it was held, see OnPointerHold(). A quick tap still clicks it. The mouse drags it at once.

bool Jazz2::UI::Windows::Element::YieldsToViewGestures() const virtual

Returns true if the element lies over the level view and a finger on it may still pan the view.

A second finger then moves the view, the element gets the press only once the first one moved alone.

bool Jazz2::UI::Windows::Element::IsTabStop() const virtual

Returns true if Tab can give the element the keyboard focus.

Buttons and other controls are reached by Tab too, though a click doesn't focus them. Every element that can take the focus can, by default.

bool Jazz2::UI::Windows::Element::IsDetached() const

Returns true if the element of the tree is in a window of its own, see Surface::PlaceDetachable().

Its parent doesn't draw it then and pointing at it doesn't reach it there, the surface does both in its window.