Magnum::Ui::AbstractWidget class new in Git master

Abstract base for stateful widgets.

A move-only owning wrapper over a NodeHandle. The BasicWidget template and the Widget typedef then restrict the type to a concrete user interface instance.

Stateful widgets (such as a Button) are meant to be used when their visual state will need be modified during their lifetime (for example, a button changing its color or text), or when the widget implementation maintains a state that is regularly queried by the application (for example, an input text label, or a list selection).

In comparison, stateless widgets (such as a button()) are only set up once and then live until removed, either explicitly through their NodeHandle, or implicitly when the parent nodes are removed. Stateless widgets are more lightweight as no individual destructors need to be called for them and should be preferred where possible.

Derived classes

template<class UserInterface>
class BasicWidget new in Git master
Templated abstract base for stateful widgets.

Constructors, destructors, conversion operators

AbstractWidget(AbstractUserInterface& ui, NodeHandle node) explicit
Constructor.
AbstractWidget(NoCreateT, AbstractUserInterface& ui) explicit
Construct with no underlying node.
AbstractWidget(const AbstractAnchor& anchor) explicit
Construct from a positioning anchor.
AbstractWidget(const AbstractWidget&) deleted
Copying is not allowed.
AbstractWidget(AbstractWidget&& other) noexcept
Move constructor.
~AbstractWidget()
Destructor.
operator NodeHandle() const

Public functions

auto operator=(const AbstractWidget&) -> AbstractWidget& deleted
Copying is not allowed.
auto operator=(AbstractWidget&& other) -> AbstractWidget& noexcept
Move assignment.
auto ui() const -> AbstractUserInterface&
User interface instance this widget is part of.
auto node() const -> NodeHandle
Widget node.
auto isHidden() const -> bool
Whether the widget is hidden.
auto setHidden(bool hidden) -> AbstractWidget&
Set the widget hidden.
auto isDisabled() const -> bool
Whether the widget is disabled.
auto setDisabled(bool disabled) -> AbstractWidget&
Set the widget disabled.
auto release() -> NodeHandle
Release the widget node.

Function documentation

Magnum::Ui::AbstractWidget::AbstractWidget(AbstractUserInterface& ui, NodeHandle node) explicit

Constructor.

Parameters
ui User interface instance
node Node to create the widget on

The node is expected to be valid in ui.

Magnum::Ui::AbstractWidget::AbstractWidget(NoCreateT, AbstractUserInterface& ui) explicit

Construct with no underlying node.

The instance is equivalent to a moved-out state, i.e. not usable for anything. Move another instance over it to make it useful.

Magnum::Ui::AbstractWidget::AbstractWidget(const AbstractAnchor& anchor) explicit

Construct from a positioning anchor.

The ui() and node() is set to AbstractAnchor::ui() and AbstractAnchor::node().

Magnum::Ui::AbstractWidget::AbstractWidget(AbstractWidget&& other) noexcept

Move constructor.

Performs a destructive move, i.e. the other node() becomes NodeHandle::Null.

Magnum::Ui::AbstractWidget::~AbstractWidget()

Destructor.

If node() is not NodeHandle::Null, expects it to be valid and calls AbstractUserInterface::removeNode(). If node() is NodeHandle::Null, the destructor is guaranteed to not access ui() in any way.

Magnum::Ui::AbstractWidget::operator NodeHandle() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

NodeHandle Magnum::Ui::AbstractWidget::node() const

Widget node.

Returns NodeHandle::Null for a moved-out or released widget. The returned handle may be also invalid if AbstractUserInterface::removeNode() was explicitly called on it or if any parent node was removed.

bool Magnum::Ui::AbstractWidget::isHidden() const

Whether the widget is hidden.

Equivalent to querying NodeFlag::Hidden on node() with AbstractUserInterface::nodeFlags(). Note that the query doesn't include the parents, which means it can still return false if the widget is hidden transitively.

AbstractWidget& Magnum::Ui::AbstractWidget::setHidden(bool hidden)

Set the widget hidden.

Returns Reference to self (for method chaining)

Equivalent to adding or clearing NodeFlag::Hidden on node() with AbstractUserInterface::addNodeFlags() or clearNodeFlags().

bool Magnum::Ui::AbstractWidget::isDisabled() const

Whether the widget is disabled.

Equivalent to querying NodeFlag::Disabled on node() with AbstractUserInterface::nodeFlags(). Note that the query doesn't include the parents, which means it can still return false if the widget is disabled transitively.

AbstractWidget& Magnum::Ui::AbstractWidget::setDisabled(bool disabled)

Set the widget disabled.

Returns Reference to self (for method chaining)

Equivalent to adding or clearing NodeFlag::Disabled on node() with AbstractUserInterface::addNodeFlags() or clearNodeFlags().

NodeHandle Magnum::Ui::AbstractWidget::release()

Release the widget node.

Returns the node handle and resets it to NodeHandle::Null, making the widget equivalent to a moved-out instance. Assuming the handle was valid in the first place, the widget then becomes a stateless one, and gets removed either when AbstractUserInterface::removeNode() is explicitly called on the returned handle or if any parent node is removed.