NAME

Clay::UI::Enum::Bubble - how far a Clay::UI event travels up the widget tree

SYNOPSIS

use v5.22;
use warnings;

use Clay::UI::Enum::Bubble;
use Clay::UI::Events::Event;

my $event = Clay::UI::Events::Event->new(
	name        => 'OnPing',
	bubble_mode => Clay::UI::Enum::Bubble->ALWAYS,
);
say $event->bubble_mode->name;    # ALWAYS
say 'travels to every ancestor'                  # compare with == and !=
	if $event->bubble_mode == Clay::UI::Enum::Bubble->ALWAYS;

DESCRIPTION

Every event has a bubble mode ("bubble_mode" in Clay::UI::Events::Event). When a widget fires an event ("fire_event" in Clay::UI::Role::Events::Emitter), all listeners of that widget for the event's name run first, in the order they were registered. Then the bubble mode decides whether the event moves on to the widget's parent, where the same happens again, up to the root widget.

A listener stops the event when it returns anything but Clay::UI::Enum::Result->CONTINUE, including undef and an empty return (see Clay::UI::Enum::Result). Stopping never skips other listeners of the same widget: the decision is made per widget, after all its listeners ran.

The values are singleton objects (built with Object::PadX::Enum); compare them with == and !=.

VALUES

ALWAYS

Clay::UI::Enum::Bubble->ALWAYS

The event visits the widget and every ancestor, whatever the listeners return. handled_by names the first widget where a listener stopped it.

IF_CONTINUE

Clay::UI::Enum::Bubble->IF_CONTINUE

The event moves on to the parent unless a listener of the current widget stopped it. A widget without listeners for the event passes it on. This is the default of Clay::UI::Events::Event and of the built-in OnPress, OnRelease, OnScroll, OnFocus and OnBlur.

NEVER

Clay::UI::Enum::Bubble->NEVER

Only the widget the event was fired at sees it; ancestors never do. The default of OnHoverStart and OnHoverStopped.

METHODS

name

my $name = $mode->name;    # 'ALWAYS', 'IF_CONTINUE' or 'NEVER'

The value's name.

values

my @modes = Clay::UI::Enum::Bubble->values;

All three values, in the order ALWAYS, IF_CONTINUE, NEVER.

from_name

my $mode = Clay::UI::Enum::Bubble->from_name('NEVER');

The value with that name. Further methods (ordinal, from_ordinal) come from Object::PadX::Enum.

SEE ALSO

Clay::UI::Enum::Result, Clay::UI::Role::Events::Emitter, Clay::UI::Events::Event.