pub struct UiMessage {
pub handled: Cell<bool>,
pub data: Box<dyn MessageData>,
pub destination: Handle<UiNode>,
pub direction: MessageDirection,
pub routing_strategy: RoutingStrategy,
pub perform_layout: Cell<bool>,
pub flags: u64,
}
Expand description
Message is basic communication element that is used to deliver information to widget or to user code.
§Motivation
This UI library uses message passing mechanism to communicate with widgets. This is very simple and reliable mechanism that effectively decouples widgets from each other. There is no direct way of modify something during runtime, you have to use messages to change state of ui elements.
§Direction
Each message marked with “Direction” field, which means supported routes for message. For example crate::button::ButtonMessage::Click
has “Direction: To/From UI” which means that it can be sent either from internals of library or from user code. However
crate::widget::WidgetMessage::Focus
has “Direction: From UI” which means that only internal library code can send such messages without
a risk of breaking anything.
§Threading
UiMessage is nor Send or Sync. User interface is a single-thread thing, as well as its messages.
§Examples
use fyrox_ui::{
core::pool::Handle, define_constructor, message::MessageDirection, message::UiMessage, UiNode,
UserInterface,
};
// Message must be debuggable and comparable.
#[derive(Debug, PartialEq, Clone)]
enum MyWidgetMessage {
DoSomething,
Foo(u32),
Bar { foo: u32, baz: u8 },
}
impl MyWidgetMessage {
define_constructor!(MyWidgetMessage:DoSomething => fn do_something(), layout: false);
define_constructor!(MyWidgetMessage:Foo => fn foo(u32), layout: false);
define_constructor!(MyWidgetMessage:Bar => fn bar(foo: u32, baz: u8), layout: false);
}
fn using_messages(my_widget: Handle<UiNode>, ui: &UserInterface) {
// Send MyWidgetMessage::DoSomething
ui.send_message(MyWidgetMessage::do_something(
my_widget,
MessageDirection::ToWidget,
));
// Send MyWidgetMessage::Foo
ui.send_message(MyWidgetMessage::foo(
my_widget,
MessageDirection::ToWidget,
5,
));
// Send MyWidgetMessage::Bar
ui.send_message(MyWidgetMessage::bar(
my_widget,
MessageDirection::ToWidget,
1,
2,
));
}
Fields§
§handled: Cell<bool>
Useful flag to check if a message was already handled. It could be used to mark messages as “handled” to prevent
any further responses to them. It is especially useful in bubble message routing, when a message is passed through
the entire chain of parent nodes starting from current. In this, you can mark a message as “handled” and also check
if it is handled or not. For example, this is used in crate::tree::Tree
implementation, to prevent double-click
to close all the parent trees from current.
data: Box<dyn MessageData>
Actual message data. Use UiMessage::data
method to try to downcast the internal data to a specific type.
destination: Handle<UiNode>
Handle of node that will receive message. Please note that all nodes in hierarchy will also receive this message, order is “up-on-tree” (so called “bubble” message routing). T
direction: MessageDirection
Indicates the direction of the message. See MessageDirection
docs for more info.
routing_strategy: RoutingStrategy
Defines a way of how the message will behave in the widget tree after it was delivered to
the destination node. Default is bubble routing. See RoutingStrategy
for more info.
perform_layout: Cell<bool>
Whether or not message requires layout to be calculated first.
§Motivation
Some of message handling routines uses layout info, but message loop performed right after layout pass, but some of messages may change layout and this flag tells UI to perform layout before passing message further. In ideal case we’d perform layout after each message, but since layout pass is super heavy we should do it only when it is actually needed.
flags: u64
A custom user flags. Use it if handled
flag is not enough.
Implementations§
Source§impl UiMessage
impl UiMessage
Sourcepub fn with_data<T>(data: T) -> UiMessagewhere
T: MessageData,
pub fn with_data<T>(data: T) -> UiMessagewhere
T: MessageData,
Creates new UI message with desired data.
Sourcepub fn with_destination(self, destination: Handle<UiNode>) -> UiMessage
pub fn with_destination(self, destination: Handle<UiNode>) -> UiMessage
Sets the desired destination of the message.
Sourcepub fn with_direction(self, direction: MessageDirection) -> UiMessage
pub fn with_direction(self, direction: MessageDirection) -> UiMessage
Sets the desired direction of the message.
Sourcepub fn with_handled(self, handled: bool) -> UiMessage
pub fn with_handled(self, handled: bool) -> UiMessage
Sets the desired handled flag of the message.
Sourcepub fn with_perform_layout(self, perform_layout: bool) -> UiMessage
pub fn with_perform_layout(self, perform_layout: bool) -> UiMessage
Sets the desired perform layout flag of the message.
Sourcepub fn with_routing_strategy(
self,
routing_strategy: RoutingStrategy,
) -> UiMessage
pub fn with_routing_strategy( self, routing_strategy: RoutingStrategy, ) -> UiMessage
Sets the desired routing strategy.
Sourcepub fn with_flags(self, flags: u64) -> UiMessage
pub fn with_flags(self, flags: u64) -> UiMessage
Sets the desired flags of the message.
Sourcepub fn reverse(&self) -> UiMessage
pub fn reverse(&self) -> UiMessage
Creates a new copy of the message with reversed direction. Typical use case is to re-send messages to create “response”
in a widget. For example you have a float input field and it has Value message. When the input field receives Value message
with MessageDirection::ToWidget
it checks if value needs to be changed and if it does, it re-sends same message, but with
reversed direction back to message queue so every “listener” can reach properly. The input field won’t react at
MessageDirection::FromWidget
message so there will be no infinite message loop.
Sourcepub fn destination(&self) -> Handle<UiNode>
pub fn destination(&self) -> Handle<UiNode>
Returns destination widget handle of the message.
Sourcepub fn data<T>(&self) -> Option<&T>where
T: MessageData,
pub fn data<T>(&self) -> Option<&T>where
T: MessageData,
Tries to downcast current data of the message to a particular type.
Sourcepub fn set_handled(&self, handled: bool)
pub fn set_handled(&self, handled: bool)
Sets handled flag.
Sourcepub fn direction(&self) -> MessageDirection
pub fn direction(&self) -> MessageDirection
Returns direction of the message.
Sourcepub fn set_perform_layout(&self, value: bool)
pub fn set_perform_layout(&self, value: bool)
Sets perform layout flag.
Sourcepub fn need_perform_layout(&self) -> bool
pub fn need_perform_layout(&self) -> bool
Returns perform layout flag.
Trait Implementations§
Auto Trait Implementations§
impl !Freeze for UiMessage
impl !RefUnwindSafe for UiMessage
impl Send for UiMessage
impl !Sync for UiMessage
impl Unpin for UiMessage
impl !UnwindSafe for UiMessage
Blanket Implementations§
Source§impl<T> AsyncTaskResult for T
impl<T> AsyncTaskResult for T
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.Source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.Source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.Source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
Any
. Could be used to downcast a trait object
to a particular type.Source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
Any
. Could be used to downcast a trait object
to a particular type.fn into_any(self: Box<T>) -> Box<dyn Any>
Source§impl<T> FieldValue for Twhere
T: 'static,
impl<T> FieldValue for Twhere
T: 'static,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§impl<T> MessageData for T
impl<T> MessageData for T
Source§impl<T> Pointable for T
impl<T> Pointable for T
Source§impl<T> ScriptMessagePayload for T
impl<T> ScriptMessagePayload for T
Source§fn as_any_ref(&self) -> &(dyn Any + 'static)
fn as_any_ref(&self) -> &(dyn Any + 'static)
self
as &dyn Any
Source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
self
as &dyn Any
Source§impl<SS, SP> SupersetOf<SS> for SPwhere
SS: SubsetOf<SP>,
impl<SS, SP> SupersetOf<SS> for SPwhere
SS: SubsetOf<SP>,
Source§fn to_subset(&self) -> Option<SS>
fn to_subset(&self) -> Option<SS>
self
from the equivalent element of its
superset. Read moreSource§fn is_in_subset(&self) -> bool
fn is_in_subset(&self) -> bool
self
is actually part of its subset T
(and can be converted to it).Source§fn to_subset_unchecked(&self) -> SS
fn to_subset_unchecked(&self) -> SS
self.to_subset
but without any property checks. Always succeeds.Source§fn from_subset(element: &SS) -> SP
fn from_subset(element: &SS) -> SP
self
to the equivalent element of its superset.