Magnum::Ui::PointerEvent class new in Git master
#include <Magnum/Ui/Event.h>

Pointer press or release event.

Constructors, destructors, conversion operators

PointerEvent(Nanoseconds time, PointerEventSource source, Pointer pointer, bool primary, Long id) explicit: Constructor.
PointerEvent(Nanoseconds time, PointerEventSource source, Pointer pointer, bool primary, Long id, const Vector2& position, bool nodePressed, const Vector2& nodeSize) explicit: Constructor.

Public functions

auto time() const -> Nanoseconds: Time at which the event happened.
auto isFallthrough() const -> bool: Whether it's a fallthrough event.
auto source() const -> PointerEventSource: Pointer event source.
auto pointer() const -> Pointer: Pointer type that got pressed or released.
auto isPrimary() const -> bool: Whether the pointer is primary.
auto id() const -> Long: Pointer ID.
auto position() const -> Vector2: Event position.
auto nodeSize() const -> Vector2: Size of the node the event is called on.
auto isNodePressed() const -> bool: Whether the event is called on a node that's currently pressed.
auto isNodeHovered() const -> bool: Whether the event is called on a node that's currently hovered.
auto isNodeFocused() const -> bool: Whether the event is called on a node that's currently focused.
auto isCaptured() const -> bool: Whether the event is captured on a node.
void setCaptured(bool captured): Set whether to capture the event on a node.
auto isAccepted() const -> bool: Whether the event is accepted.
void setAccepted(bool accepted = true): Set the event as accepted.

Function documentation

Magnum::Ui::PointerEvent::PointerEvent(Nanoseconds time, PointerEventSource source, Pointer pointer, bool primary, Long id) explicit

Constructor.

Parameters
time	Time at which the event happened
source	Pointer event source
pointer	Pointer type that got pressed or released
primary	Whether the pointer is primary
id	Pointer ID

The time may get used for UI animations. A default-constructed value causes an animation play time to be in the past, thus immediately transitioning to a stopped state. The pointer is expected to match source, primary is expected to be true for PointerEventSource::Mouse and PointerEventSource::Pen. The position, capture and node-related properties are set from AbstractUserInterface event handler internals.

Magnum::Ui::PointerEvent::PointerEvent(Nanoseconds time, PointerEventSource source, Pointer pointer, bool primary, Long id, const Vector2& position, bool nodePressed, const Vector2& nodeSize) explicit

Constructor.

Meant to be used for testing purposes. The position, nodePressed and nodeSize gets overwritten in AbstractUserInterface event handler internals.

bool Magnum::Ui::PointerEvent::isFallthrough() const

Whether it's a fallthrough event.

Fallthrough events are sent to nodes with NodeFlag::FallthroughPointerEvents set that are parents of the node that received the event originally. If this function returns true, isNodePressed(), isNodeHovered(), isNodeFocused() and isCaptured() refer to the child node the original event was called on.

Accepting a primary fallthrough event causes a AbstractLayer::pointerCancelEvent() to be sent to the currently pressed, hovered, captured and focused nodes, if any. If (and only if) the original node was captured or pressed, the fallthrough node is made captured or pressed instead. If (and only if) the original node was hovered, the fallthrough node is made hovered, however, currently, no AbstractLayer::pointerEnterEvent() is subsequently sent to it. The focused node, if any, is lost and not transferred anywhere unless the node that accepted the fallthrough event is itself focused, in which case it stays.

Accepting a secondary fallthrough event causes a AbstractLayer::pointerCancelEvent() to be sent only to the currently captured node, if any. If (and only if) the original node was captured, the fallthrough node is made captured instead.

PointerEventSource Magnum::Ui::PointerEvent::source() const

Pointer event source.

Pointer Magnum::Ui::PointerEvent::pointer() const

Pointer type that got pressed or released.

bool Magnum::Ui::PointerEvent::isPrimary() const

Whether the pointer is primary.

Used to distinguish among multiple pointers in a multi-touch scenario. Events coming from PointerEventSource::Mouse and PointerEventSource::Pen are always primary. See setCaptured() for details about interaction between primary and non-primary pointer events and pointer capture.

Long Magnum::Ui::PointerEvent::id() const

Pointer ID.

Used to distinguish among multiple pointers in a multi-touch scenario. Events coming from PointerEventSource::Mouse and PointerEventSource::Pen are always primary, although their ID can differ.

Vector2 Magnum::Ui::PointerEvent::position() const

Event position.

Relative to top left corner of the node the event is called on. Use nodeSize() to calculate a position relative to the node size or to other edges / corners. If the position has any coordinate less than 0.0f or greater or equal to nodeSize(), the event was called outside of the node area, for example when a pointer is released outside of a captured node.

Vector2 Magnum::Ui::PointerEvent::nodeSize() const

Size of the node the event is called on.

Returns a size of given node after all layout calculations.

bool Magnum::Ui::PointerEvent::isNodePressed() const

Whether the event is called on a node that's currently pressed.

Returns true if AbstractUserInterface::currentPressedNode() is the same as the node the event is called on or is a child of a node a fallthrough event is called on, false otherwise. In particular, is false for a first press event happening on given node and is true for a release event if it happens inside the pressed node. However, it's true also for a release that happens outside of a pressed and captured node.

bool Magnum::Ui::PointerEvent::isNodeHovered() const

Whether the event is called on a node that's currently hovered.

Returns true if AbstractUserInterface::currentHoveredNode() is the same as the node the event is called on or is a child of a node a fallthrough event is called on, false otherwise. In particular, is false for a press or release event that happened without a preceding move on given node, is also false if a release event happens outside of a captured node.

Note that even if this function returns true, the event handler still controls whether the pointer is actually treated as being in an active area of the node by either accepting the event or not accepting it and letting it potentially fall through to other nodes.

bool Magnum::Ui::PointerEvent::isNodeFocused() const

Whether the event is called on a node that's currently focused.

Returns true if AbstractUserInterface::currentFocusedNode() is the same as the node the event is called on or is a child of a node a fallthrough event is called on, false otherwise. Unlike isNodeHovered(), returns true also if the actual pointer position is outside of the area of the node the event is called on, for example in case of an event capture.

bool Magnum::Ui::PointerEvent::isCaptured() const

Whether the event is captured on a node.

Implicitly true if AbstractUserInterface::currentCapturedNode() is the same as the node the event is called on or is a child of a node a fallthrough event is called on, false otherwise, unless a previously called event handler modified the capture.

Always implicitly true for a primary press event, unless a previously called event handler reset the capture. On a release event is implicitly true if the event happens on a captured node, or if a previously called event handler set the capture.

void Magnum::Ui::PointerEvent::setCaptured(bool captured)

Set whether to capture the event on a node.

By default, after a press event of a primary pointer, a node captures all following pointer and key events until and including a release of the primary pointer, even if they happen outside of the node area. Press and release events of non-primary pointers are sent to the captured node but don't affect it in any way.

If capture is disabled, the events are always sent to the actual node under the pointer. Which means that for example a node can receive a pointer press event without a corresponding release later, or a release alone.

Calling this function only makes sense on a pointer press event or a non-primary pointer release event, it has no effect on primary pointer release event.

bool Magnum::Ui::PointerEvent::isAccepted() const

Whether the event is accepted.

Implicitly false.

void Magnum::Ui::PointerEvent::setAccepted(bool accepted = true)

Set the event as accepted.

Once an event is accepted, it doesn't propagate further. It may however still fall through to parent nodes marked with NodeFlag::FallthroughPointerEvents, see isFallthrough() for more information.