Magnum::Ui::AbstractWidget class new in Git master
#include <Magnum/Ui/Widget.h>

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.