Event

Event is what a handler receives: where the pointer was, which key, which menu option, what a drag landed on — and a handle to the component it fired on. It arrives as the handler’s parameter.

src/marker.ts2

                 onClick={(event) => { report(event.self, readout); }}

Reference

The handler parameter

A handler is a function taking one parameter. Declare it if you read it:

src/menu.ts2

                 onOptionSelect={locked === 1 ? null : (event) => { setChosen(nameOf(event.option)); }}>

and leave it out if you do not:

src/shop.ts2

<layer x={i * 79} y={0} w={74} h={22} onClick={() => { setTab(i); }}>

Fields

• self: A Ref to the component the event fired on. A handler can change, measure or hand on the thing it fired on without a ref being declared for it. It passes to a parameter declared ComponentId.
• component, subId: The same component as an address: which component, and which child of it. subId is never a row number.
• mouseX, mouseY: Numbers. The pointer, relative to the component. For a wheel event, mouseY is the notch direction. In a drag, they are where the dragged component’s edge is inside the draggable container.
• option: A number. Which right-click option was chosen, counting from 1 in the order they appear in options. An empty entry still counts.
• optionSubject: A string. The subject the menu showed beside the verb.
• keyCode: A number. The client’s own code for the key pressed — not a character code. Escape is 13, Enter 84, Backspace 85.
• keyChar: A number. The character the key typed, as its character code — '0' is 48.
• dragTarget, dragTargetSubId: What a drag was dropped on, as a component and which child of it, or -1 when it landed on nothing. dragTargetSubId is an address, like subId.

Caveats

• The event cannot be stored, passed or returned whole. Read its fields.
• It cannot be destructured (TS2E206). Read the fields off the parameter.
• subId and dragTargetSubId are addresses, and arithmetic on them is refused (TS2E132). To learn which row of a .map() fired, name the callback’s index — it is captured into the handler like any other local.
• self is a handle, not a number. It cannot be stored in a local, and it does not reach a parameter declared Ref (TS2E129). Declare the parameter ComponentId. component cannot be stored in a local either (TS2E003).
• keyChar is a number. Putting it in a template writes the character’s code, not the character; a string cannot be built from typed keys. Build a number from digits instead — Keyboard and input.
• Which fields are filled depends on the event: onClick has no option.
• A handler’s reads are point-in-time. Reading a cell or a game value inside a handler does not make the component follow it — How updates happen.

refused/events.ts2

              onClick={(event) => { setTab(event.subId - 1); }} />

refused/event.ts2

const brighten = (target: Ref): void => { target.color = Colors.WHITE; };

const Refused = (): Component => (
  <text w="fill" h={16} text="Click me" font={Fonts.PLAIN} color={Colors.AMBER}
        onClick={(event) => { brighten(event.self); }} />
);

Usage

Changing the thing that fired

src/marker.ts2

                 onOptionSelect={(event) => {
                   // One axis, in pixels: the other axis is read back and both
                   // are pinned where they are now.
                   event.self.x = event.self.x + 8;
                   report(event.self, readout);
                 }}>

report declares target: ComponentId, which is what self passes to.

Handling which menu option was chosen

src/menu.ts2

const nameOf = (option: Int): String => {
  if (option === 1) { return 'Wield'; }
  if (option === 5) { return 'Drop'; }
  return 'Examine';
};

Wield is option 1, Drop is 5 and Examine is 10: empty strings count.

Turning a drag into a number

src/slider.ts2

                  onDrag={(event) => { setLevel(Math.clamp(0, 100, event.mouseX * 100 / TRAVEL)); }} />

event.mouseX is inside the container draggable names, so that container decides the range as well as the bounds.

Reading what a drag landed on

src/slider.ts2

                onDragComplete={(event) => { if (event.dragTarget !== -1) { setFirst(1 - first); } }} />

Reading a key

src/entry.ts2

            onKey={(event) => {
              if (event.keyCode === KEY_ENTER) {
                setWithdraw(amount);
                setAmount(0);
                return;
              }
              if (event.keyCode === KEY_BACKSPACE) {
                setAmount(amount / 10);
                return;
              }
              if (event.keyChar >= CHAR_ZERO && event.keyChar <= CHAR_NINE && amount < 100000) {
                setAmount(amount * 10 + (event.keyChar - CHAR_ZERO));
              }
            }} />

Scrolling with the wheel

src/chrome.ts2

  content.onScrollWheel = (event) => {
    content.scrollY = content.scrollY + event.mouseY * WHEEL;
    trackScroll(gutter, thumb, capTop, capBottom, content);
  };

Knowing where a watch fired

src/watch.ts2

  useWatch(Varps.POISON, (event) => { writePoison(event.component); }, poisonLabel);

A watch handler is a handler like any other: event.component is the host the watch was bound on.

Troubleshooting

event is an unresolved name

You are outside a handler, or the handler did not declare the parameter. Add it: onClick={(event) => …}.

Destructuring is refused

Write (event) => … and read event.mouseY.

My drag is offset, or runs out before the end

event.mouseX is measured inside the draggable container. If that is the whole bar rather than the trough the thumb slides in, every measurement is out by the difference. Point draggable at the exact region the thumb moves within.

event.option is not what I expected

Options are numbered from 1, in the order they appear in options. An empty string still occupies its slot.

I want the row index in a mapped handler

Name the callback’s index: (item, i) => <… onClick={() => { pick(i); }} />. It is captured into the handler; event.subId is not a row number.