ui/Cancelable

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

Import Usage

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

Members

Cancelable   Higher-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.stopPropagation();
  }},
  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 Usage

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

Configuration

Required Property •  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

Boolean

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.

addCancelHandler   Function

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

removeCancelHandler   Function

removeCancelHandler( handler ) → undefined

Removes an event handler to filter cancel events

1 Param

handler Function

A previously added filter function

Returns

 undefined