enact logoEnact
Edit on GitHub

ui/Cancelable

Provides components and methods to add support for handling cancel actions.

import Cancelable from '@enact/ui/Cancelable';

Members

CancelableHigher-Order Component

A higher-order component that adds support to a component to handle cancel actions.

The cancel event may be handled either by a design-time config function or a run-time prop function. If the component handles the event and wants to prevent upstream components from also handling the event, the callback should invoke stopPropagation() on the event object.

Note: This HoC passes a number of props to the wrapped component that should be passed to the main DOM node.

Usage of config function:

import Cancelable from '@enact/ui/Cancelable';

const MyComponent = ({myProp, ...rest}) => (
   <div {...rest}>{myProp}</div>
 );
...
const CancelableComponent = Cancelable(
  {cancel: function (ev, props) {
    // Can inspect either the `onCancel` event, `ev`, and/or the `props` to determine how
    // to handle the event (e.g. invoking an event handler from `props`).

    // Stop upstream instances of Cancelable from handling the event
    ev.stopPropagaion();
  }},
  MyComponent
);

Usage of prop function:

import Cancelable from '@enact/ui/Cancelable';

const CancelableComponent = Cancelable(
  // When a cancel action is received and a handler function exists for the prop
  // `onCancel`, it will be invoked and passed the `onCancel` event object.
  {cancel: 'onCancel'},
  MyComponent
);
import Cancelable from '@enact/ui/Cancelable';
Configuration
onCancel •
StringFunction

Called when a cancel action is invoked by the user.

If it is a string, the cancel handler will attempt to invoke a function passed as a prop of that name. If it is a function, that function will be called with the current props as the only argument.

If the function handles the cancel action, it should call stopPropagation() on the provided event object prevent container or modal Cancelable instances from also handling the action.

modal
String

Subscribes to cancel events globally for this instance.

When true, the Cancelable instance will handle cancel events globally that successfully bubble up to window regardless of which component is focused.

modal cancel handlers are processed in reverse of the order they are created such that the innermost instance (in terms of the component hierarchy) have the first opportunity to handle the event before its container components.

Default: false
component
Component

The component that will contain the wrapped component.

When set, the wrapped component will be contained within an instance of component. This may be necessary if the props passed to the wrapped component are not placed on the root element.

Default: null
Properties added to wrapped component
onCancel
Function

Called when a cancel action is received.

This callback is invoked for every cancel action before the config or prop handler is invoked.

addCancelHandlerFunction

addCancelHandler( handler )undefined

Adds an event handler to filter cancel events.

1 Param
handler Function

Function that will receive the event and should return true if the event is a cancel event.

Returns
undefined

removeCancelHandlerFunction

removeCancelHandler( handler )undefined

Removes an event handler to filter cancel events

1 Param
handler Function

A previously added filter function

Returns
undefined
ArrayBooleanFunctionModuleNumberObjectString