Instruction set reference
HIPE_OP_EVENT_REQUEST
Send this instruction to the server to request notifications of a particular event on a particular element.
- location: The element for which you require event notifications.
- arg[0]: The type of event (see notes below).
- arg[1]: Optional. Which of these events should have their default action cancelled, e.g. to stop the Tab key moving the keyboard focus, or the mouse wheel scrolling. See "Cancelling default actions" below.
- requestor: user value to be passed back to the client each time the requested event arises.
Notes
For specifying the type of event, names of events are the same as their HTML/Javascript equivalents, except without the "on" prefix.
For example, to get reports of click events, you would pass "click" in arg[0] (not "onclick"), or for a key pressed down event you would pass "keydown" (not "onkeydown" as in HTML/Javascript).
Each event is reported with HIPE_OP_EVENT, which lists the detail reported for each event type, including which modifier keys (Shift, Alt, Ctrl, Meta) were held.
keyup and keydown events can be requested on a child iframe: they report keys pressed while the keyboard focus is inside the client occupying that frame (or inside any frame nested within it). The events carry the requestor value of your most recent request for that event on that iframe, and each key is reported once: requesting keydown or keyup again on the same iframe replaces the requestor rather than adding another report. The detail includes the modifier mask as for any other keydown or keyup event. The same keys also reach your body element, so if you have requested keydown or keyup on the body as well, you receive both reports. keypress events remain within the iframe and don't propagate out to the parent client.
mousedown and mouseup events can also be requested on a child iframe: they report every press and release of a mouse button anywhere in that frame, including inside frames nested within it. They tell you where the pointer was, not what it was over. The detail is in your own coordinates, as if the event had happened on the iframe element itself:
| Detail | Value |
|---|---|
| button | As for any mouse event (1 = left). |
| pageX, pageY | The pointer's position on your page. |
| offsetX, offsetY | The same, relative to the iframe element. |
| modifiers | The modifier mask, as for any mouse event. |
As with keys, the events carry the requestor of your most recent request for that event on that iframe, and the child client still receives its own mouse events as usual. A frame that has no content yet reports nothing.
Several requests can be active for the same event on the same element. Each request adds a new listener, and all of them stay active, so each event is reported once per request. This happens even if the requests use the same requestor value. For example, if you request the click event on the same button twice, each click on that button is reported twice.
To replace a request, cancel it with HIPE_OP_EVENT_CANCEL before requesting the event again.
Cancelling default actions
arg[1] can cancel an event's default action: what would happen without your app (a key typing text or moving the focus, the wheel scrolling, a right-click opening the edit menu, and so on). The event is cancelled as it happens, before the default action, so the decision is made from rules given in advance. You still receive the event as usual, and can then do something else instead (e.g. indent a line when Tab is pressed).
arg[1] is a list of rules separated by ;. An event is cancelled if it matches any of them. Each rule is code,modifiers, written like the event's detail in HIPE_OP_EVENT:
- code: the keyCode for keydown and keyup, the character code for keypress, or the mouse button (1 = left, 2 = middle, 3 = right) for mouse events.
- modifiers: the modifier mask (1 = Shift, 2 = Alt, 4 = Ctrl, 8 = Meta, added together), which must match exactly. 0 means no modifier keys held.
* matches anything, and ,modifiers can be left out to match any modifiers. So * alone cancels every event. A rule with a specific code or modifier mask never matches an event that doesn't have one: e.g. wheel events have no code (only * matches), and events such as input or scroll have neither. Rules that can't be read are ignored.
| Event | arg[1] | Cancels |
|---|---|---|
| keydown | 9,0;9,1 | Tab and Shift+Tab (the focus doesn't move) |
| keydown | 83,4 | Ctrl+S |
| keydown | 9 | Tab with any modifier keys |
| wheel | *,4 | Ctrl+wheel (plain wheel still scrolls) |
| mousedown | 1 | left-button presses (no focus change or text selection) |
| contextmenu | - | nothing: the edit menu still opens |
Notes:
- The rules apply to events on the element and on everything inside it, so put them on the smallest element that needs them. For example, cancelling Tab on the body would also stop Tab working in any text box in your app.
- Cancelling a keydown also stops the key typing any text (its keypress doesn't happen) and stops any editing command for it (e.g. Ctrl+A selecting everything). Text entered through an input method (e.g. with dead keys) isn't affected.
- Cancelling doesn't depend on the client: it happens even while your app is busy. But your response to the event arrives later than the key itself, so a key the user types straight afterwards may take effect first.
- A new request for the same event on the same element replaces its rules (an empty arg[1] or - removes them), although events are still reported once per request. HIPE_OP_EVENT_CANCEL removes them.
- contextmenu: an empty arg[1] cancels every right-click, as requesting this event always has, so your app replaces the framing manager's edit menu. Use - to be told about right-clicks and still show the edit menu.
- Rules on a child iframe don't affect the child client's own events, and a client can't cancel keys that its framing manager relies on (such as Esc and the function keys): these still reach it.
Events and locations
An event request belongs to the element, not its location number: each event is reported with the location the element has when it happens. After HIPE_OP_FREE_LOCATION the element's events are no longer reported. See "Locations".