@lumino/messaging
- Version 2.0.2
- Published
- 141 kB
- 2 dependencies
- BSD-3-Clause license
Install
npm i @lumino/messaging
yarn add @lumino/messaging
pnpm add @lumino/messaging
Overview
Lumino Message Passing
Index
Classes
Interfaces
Type Aliases
Namespaces
Classes
class ConflatableMessage
class ConflatableMessage extends Message {}
A convenience message class which conflates automatically.
#### Notes Message conflation is an advanced topic. Most user code will not make use of this class.
This message class is useful for creating message instances which should be conflated, but which have no state other than
type
.If conflation of stateful messages is required, a custom
Message
subclass should be created.
property isConflatable
readonly isConflatable: boolean;
Test whether the message is conflatable.
#### Notes This property is always
true
.
method conflate
conflate: (other: ConflatableMessage) => boolean;
Conflate this message with another message of the same
type
.#### Notes This method always returns
true
.
class Message
class Message {}
A message which can be delivered to a message handler.
#### Notes This class may be subclassed to create complex message types.
constructor
constructor(type: string);
Construct a new message.
Parameter type
The type of the message.
property isConflatable
readonly isConflatable: boolean;
Test whether the message is conflatable.
#### Notes Message conflation is an advanced topic. Most message types will not make use of this feature.
If a conflatable message is posted to a handler while another conflatable message of the same
type
has already been posted to the handler, theconflate()
method of the existing message will be invoked. If that method returnstrue
, the new message will not be enqueued. This allows messages to be compressed, so that only a single instance of the message type is processed per cycle, no matter how many times messages of that type are posted.Custom message types may reimplement this property.
The default implementation is always
false
.
property type
readonly type: string;
The type of the message.
#### Notes The
type
of a message should be related directly to its actual runtime type. This means thattype
can and will be used to cast the message to the relevant derivedMessage
subtype.
method conflate
conflate: (other: Message) => boolean;
Conflate this message with another message of the same
type
.Parameter other
A conflatable message of the same
type
.Returns
true
if the message was successfully conflated, orfalse
otherwise.#### Notes Message conflation is an advanced topic. Most message types will not make use of this feature.
This method is called automatically by the message loop when the given message is posted to the handler paired with this message. This message will already be enqueued and conflatable, and the given message will have the same
type
and also be conflatable.This method should merge the state of the other message into this message as needed so that when this message is finally delivered to the handler, it receives the most up-to-date information.
If this method returns
true
, it signals that the other message was successfully conflated and that message will not be enqueued.If this method returns
false
, the other message will be enqueued for normal delivery.Custom message types may reimplement this method.
The default implementation always returns
false
.
Interfaces
interface IMessageHandler
interface IMessageHandler {}
An object which handles messages.
#### Notes A message handler is a simple way of defining a type which can act upon on a large variety of external input without requiring a large abstract API surface. This is particularly useful in the context of widget frameworks where the number of distinct message types can be unbounded.
method processMessage
processMessage: (msg: Message) => void;
Process a message sent to the handler.
Parameter msg
The message to be processed.
interface IMessageHook
interface IMessageHook {}
An object which intercepts messages sent to a message handler.
#### Notes A message hook is useful for intercepting or spying on messages sent to message handlers which were either not created by the consumer, or when subclassing the handler is not feasible.
If
messageHook
returnsfalse
, no other message hooks will be invoked and the message will not be delivered to the handler.If all installed message hooks return
true
, the message will be delivered to the handler for processing.**See also:** MessageLoop.installMessageHook and MessageLoop.removeMessageHook
method messageHook
messageHook: (handler: IMessageHandler, msg: Message) => boolean;
Intercept a message sent to a message handler.
Parameter handler
The target handler of the message.
Parameter msg
The message to be sent to the handler.
Returns
true
if the message should continue to be processed as normal, orfalse
if processing should cease immediately.
Type Aliases
type MessageHook
type MessageHook = | IMessageHook | ((handler: IMessageHandler, msg: Message) => boolean);
A type alias for message hook object or function.
#### Notes The signature and semantics of a message hook function are the same as the
messageHook
method of IMessageHook.
Namespaces
namespace MessageLoop
namespace MessageLoop {}
The namespace for the global singleton message loop.
function clearData
clearData: (handler: IMessageHandler) => void;
Clear all message data associated with a message handler.
Parameter handler
The message handler of interest.
#### Notes This will clear all posted messages and hooks for the handler.
function flush
flush: () => void;
Process the pending posted messages in the queue immediately.
#### Notes This function is useful when posted messages must be processed immediately.
This function should normally not be needed, but it may be required to work around certain browser idiosyncrasies.
Recursing into this function is a no-op.
function getExceptionHandler
getExceptionHandler: () => ExceptionHandler;
Get the message loop exception handler.
Returns
The current exception handler.
#### Notes The default exception handler is
console.error
.
function installMessageHook
installMessageHook: (handler: IMessageHandler, hook: MessageHook) => void;
Install a message hook for a message handler.
Parameter handler
The message handler of interest.
Parameter hook
The message hook to install.
#### Notes A message hook is invoked before a message is delivered to the handler. If the hook returns
false
, no other hooks will be invoked and the message will not be delivered to the handler.The most recently installed message hook is executed first.
If the hook is already installed, this is a no-op.
function postMessage
postMessage: (handler: IMessageHandler, msg: Message) => void;
Post a message to a message handler to process in the future.
Parameter handler
The handler which should process the message.
Parameter msg
The message to post to the handler.
#### Notes The message will be conflated with the pending posted messages for the handler, if possible. If the message is not conflated, it will be queued for normal delivery on the next cycle of the event loop.
Exceptions in hooks and handlers will be caught and logged.
function removeMessageHook
removeMessageHook: (handler: IMessageHandler, hook: MessageHook) => void;
Remove an installed message hook for a message handler.
Parameter handler
The message handler of interest.
Parameter hook
The message hook to remove.
#### Notes It is safe to call this function while the hook is executing.
If the hook is not installed, this is a no-op.
function sendMessage
sendMessage: (handler: IMessageHandler, msg: Message) => void;
Send a message to a message handler to process immediately.
Parameter handler
The handler which should process the message.
Parameter msg
The message to deliver to the handler.
#### Notes The message will first be sent through any installed message hooks for the handler. If the message passes all hooks, it will then be delivered to the
processMessage
method of the handler.The message will not be conflated with pending posted messages.
Exceptions in hooks and handlers will be caught and logged.
function setExceptionHandler
setExceptionHandler: (handler: ExceptionHandler) => ExceptionHandler;
Set the message loop exception handler.
Parameter handler
The function to use as the exception handler.
Returns
The old exception handler.
#### Notes The exception handler is invoked when a message handler or a message hook throws an exception.
type ExceptionHandler
type ExceptionHandler = (err: Error) => void;
A type alias for the exception handler function.
Package Files (1)
Dependencies (2)
Dev Dependencies (19)
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@lumino/messaging
.
- Markdown[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@lumino/messaging)
- HTML<a href="https://www.jsdocs.io/package/@lumino/messaging"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 3320 ms. - Missing or incorrect documentation? Open an issue for this package.