core/handle

Allows generating event handlers by chaining input functions to filter or short-circuit the handling flow. Any input function that returns a falsy value will stop the chain.

The returned handler function has a finally() member that accepts a function and returns a new handler function. The accepted function is called once the original handler completes regardless of the returned value.

Adapts an event with adapter before calling handler.

The adapter function receives the same arguments as any handler. The value returned from adapter is passed as the first argument to handler with the remaining arguments kept the same. This is often useful to generate a custom event payload before forwarding on to a callback.

Example:

import {adaptEvent, forward} from '@enact/core/handle';

// calls the onChange callback with an event payload containing a type and value member
const incrementAndChange = adaptEvent(
	(ev, props) => ({
	  type: 'onChange',
	  value: props.value + 1
	}),
	forward('onChange')
)

Invokes a method by name on the component to which core/handle.handle is bound.

If the methods exists on the object, it is called with the event, props, and context and its return value is returned.

If the method does not exist or handle isn't bound to an instance, it returns false.

Example:

import {call, handle, forProp} from '@enact/core/handle';

const incrementIfEnabled = handle(
  forProp('disabled', false),
  call('increment')
);

class Counter extends React.Component {
  constructor () {
    super();

    this.handleIncrement = incrementIfEnabled.bind(this);
  }

  render () {
    // ...
  }
}

Allows handling to continue if the value of prop on the event strictly equals value

Example:

import {forEventProp, handle} from '@enact/core/handle';

const logWhenXEqualsZero = handle(
  forEventProp('x', 0),
  (ev) => console.log('ev.x was equal to zero', ev)
);

Allows handling to continue if the event's keyCode is mapped to name within core/keymap.

Example:

import {forKey, handle} from '@enact/core/handle';

const logForEnterKey = handle(
  forKey('enter'),
  (ev) => console.log('Enter key pressed down', ev)
);

Allows event handling to continue if event.keyCode === value.

Example:

import {forKeyCode, handle} from '@enact/core/handle';

const logForEscapeKey = handle(
  forKeyCode(27),
  (ev) => console.log('Escape key pressed down', ev)
);

Allows handling to continue if the value of prop on the props strictly equals value.

Example:

import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);

Forwards the event to a function at name on props. If the specified prop is undefined or is not a function, it is ignored. The return value of the forwarded function is ignored and true is always returned instead.

Example:

import {forward, handle} from '@enact/core/handle';

const forwardAndLog = handle(
  forward('onClick'),
  (ev) => console.log('event forwarded to onClick from props', ev)
);

Creates a handler that will forward the event to a function at name on props.

If adapter is not specified, a new event payload will be generated with a type member with the name of the custom event. If adapter is specified, the type member is added to the value returned by adapter.

The adapter function receives the same arguments as any handler. The value returned from adapter is passed as the first argument to handler with the remaining arguments kept the same. This is often useful to generate a custom event payload before forwarding on to a callback.

Example:

import {forwardCustom} from '@enact/core/handle';

// calls the onChange callback with the event: {type: 'onChange'}
const forwardChange = forwardCustom('onChange');

// calls the onChange callback with the event: {type: 'onChange', index}
const forwardChangeWithIndex = forwardCustom('onChange', (ev, {index}) => ({index}));

Logs the event, props, and context optionally preceded by a custom message. Will only log in development mode.

Example:

import {forProp, handle, log} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  log('checked props is true')
);

Accepts a handler and returns the logical complement of the value returned from the handler.

Example:

import {forProp, forward, not, handle} from '@enact/core/handle';

// calls the onChange callback when disabled is not true
const handleChange = handle(
 not(forProp('disabled', true)),
 forward('onChange')
)

Calls the first handler whose condition passes. Each branch must be passed as an array with the first element being the condition function and the second being the handler function. The same arguments are passed to both the condition function and the handler function. The value returned from the handler is returned.

Example:

const handler = oneOf(
	[forKey('enter'), handleEnter],
	[forKey('left'), handleLeft],
	[forKey('right'), handleRight]
);

Calls event.preventDefault() and returns true.

Example:

import {handle, preventDefault} from '@enact/core/handle';

const preventAndLog = handle(
  preventDefault,
  (ev) => console.log('preventDefault called', ev)
);

A function that always returns true. Optionally accepts a handler function which is called before returning true.

Example:

// Used to coerce an existing function into a handler
const coercedHandler = handle(
  returnsTrue(doesSomething),
  willAlwaysBeCalled
);

// Used to emulate if/else blocks with `oneOf`
const ifElseHandler = oneOf(
	[forKey('enter'), handleEnter],
	[returnsTrue, handleOtherwise]
);

Calls event.stopPropagation() and returns true

Example:

import {handle, stop} from '@enact/core/handle';

const stopAndLog = handle(
  stop,
  (ev) => console.log('stopPropagation called', ev)
);

Calls event.stopImmediatePropagation() and returns true

Example:

import {handle, stopImmediate} from '@enact/core/handle';

const stopImmediateAndLog = handle(
  stopImmediate,
  (ev) => console.log('stopImmediatePropagation called', ev)
);