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

Base for stateful widgets.

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

Widgets, anchors and nodes

To be written.

Stateful, non-owned and stateless widgets

To be written.

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(NonOwnedT, AbstractUserInterface& ui, NodeHandle node) explicit: Construct a non-owned widget.
AbstractWidget(NoCreateT) explicit: Construct with no underlying node.
AbstractWidget(const AbstractAnchor& anchor) explicit: Construct from a positioning anchor.
AbstractWidget(NonOwnedT, const AbstractAnchor& anchor) explicit: Construct a non-owned widget from a positioning anchor.
AbstractWidget(const AbstractWidget&) deleted: Copying is not allowed.
AbstractWidget(AbstractWidget&& other) noexcept: Move constructor.
~AbstractWidget(): Destructor.
operator NodeHandle() const: Widget node.

Public functions

auto operator=(const AbstractWidget&) -> AbstractWidget& deleted: Copying is not allowed.
auto operator=(AbstractWidget&& other) -> AbstractWidget& noexcept: Move assignment.
auto isOwned() const -> bool: Whether the widget is owned.
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(NonOwnedT, AbstractUserInterface& ui, NodeHandle node) explicit

Construct a non-owned widget.

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

The node is expected to be valid in ui. Compared to AbstractWidget(AbstractUserInterface&, NodeHandle) the node doesn't get removed on destruction. Instead, it gets removed either once any parent node is removed, or when AbstractUserInterface::removeNode() is explicitly called on node().

Magnum::Ui::AbstractWidget::AbstractWidget(NoCreateT) 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(NonOwnedT, const AbstractAnchor& anchor) explicit

Construct a non-owned widget from a positioning anchor.

The ui() and node() is set to AbstractAnchor::ui() and AbstractAnchor::node(). Compared to AbstractWidget(const AbstractAnchor&) the widget node doesn't get removed on destruction. Instead, it gets removed either once any parent node is removed, or when AbstractUserInterface::removeNode() is explicitly called on 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 isOwned() is true and node() is not NodeHandle::Null, expects it to be valid and calls AbstractUserInterface::removeNode(). If isOwned() is false or node() is NodeHandle::Null, the destructor is guaranteed to not access ui() in any way.

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

Widget node.

Same as node().

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

Whether the widget is owned.

Returns false if the widget was constructed using either AbstractWidget(NonOwnedT, AbstractUserInterface&, NodeHandle) or AbstractWidget(NonOwnedT, const AbstractAnchor&), true otherwise. If the widget is owned, the underlying node() gets removed on destruction.

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.

Instead of calling this function to prevent a widget destructor from removing the node you can also construct the widget using the NonOwned tag, if the subclass exposes it, or call a stateless widget function instead of creating an instance instead (such as button() instead of making a Button instance).