Element class
#include <Jazz2/UI/Windows/Element.h>
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
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
trueif the element is shown. - auto IsUsable() -> bool
- Returns
trueif the element and all its parents can be used. - auto IsHovered() const -> bool
- Returns
trueif the pointer is over the element. - auto IsPressed() const -> bool
- Returns
trueif the element is being pressed. - auto IsFocused() const -> bool
- Returns
trueif 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
falseif 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
trueif the element takes the pointer itself. - auto OnPointerDown(const PointerEvent& event) -> bool virtual
- Called when the pointer is pressed over the element, returns
trueto 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,
insidetells 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
trueif a press on the element may become scrolling of the list it's in. - auto DragsAfterHold() const -> bool virtual
- Returns
trueif a finger has to rest on the element for a moment before it drags it. - auto YieldsToViewGestures() const -> bool virtual
- Returns
trueif 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
trueif it was used. - auto OnKeyPressed(const KeyboardEvent& event) -> bool virtual
- Called when a key is pressed while the element has the focus, returns
trueif 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
trueif the element can take the keyboard focus. - auto IsTabStop() const -> bool virtual
- Returns
trueifTabcan give the element the keyboard focus. - auto KeepsFocus() const -> bool virtual
- Returns
trueif 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
trueif 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::
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::
Its parent doesn't draw it then and pointing at it doesn't reach it there, the surface does both in its window.