Input Event Routing

Introduction

The windows created by your app will receive various input events, such as mouse button events and keyboard events.

This guide discusses which elements in a window's element hierarchy will receive messages in response to a given event, and in which order.

In general, if an element is disabled (see PBElementSetDisabled) it will not receive input event messages.

This guide discusses various element states, such as hovered and pressed. Elements are notified when their state changes with the PBMsg_UPDATE_STATE message.

Mouse Movement Events

Mouse movement events cause PBMsg_MOUSE_MOVE to be sent to the hovered element.

The hovered element is the element directly under the mouse cursor. The bounds of an element for this purpose can be adjusted by handling the PBMsg_CONTAINS_POINT message. Elements with the PBElement_INPUT_MOUSE_NONE flag cannot be hovered, and the element behind them will be considered for hover.

Mouse Button Down Events

When a mouse button is pressed down, the system first finds the hovered elements as described above. Then, it and its ancestors are searched for the closest element with the corresponding PBElement_INPUT_MOUSE_ flag. This element will become the pressed element.

For example, consider a left mouse button down event. If the hovered element has the PBElement_INPUT_MOUSE_LEFT flag, then it will become the pressed element. If it does not have this flag, but its layout parent does, then the layout parent will become the pressed element.

The pressed element is then sent the corresponding mouse button down message, such as PBMsg_LEFT_DOWN for the left mouse button.

Mouse Dragging Events

If the mouse is moved while holding a mouse button down, mouse drag events are generated.

The pressed element is sent the corresponding mouse drag message, such as PBMsg_LEFT_DRAG while holding the left mouse button.

While dragging the mouse, the hovered element cannot be changed to another element. That said, the element is nevertheless not considered hovered if the mouse is outside its bounds.

Mouse Button Up Events

If the mouse is within the pressed element when the button is released, it is sent the corresponding click message. For example, PBMsg_LEFT_CLICK is sent for the left mouse button. PBMsg_OPEN_CONTEXT_MENU is additionally sent for releasing the right mouse button in this case.

Regardless of the mouse position, the pressed element is then sent the mouse up message, such as PBMsg_LEFT_UP for the left mouse button. It is then no longer the pressed element.

Raw Mouse Events

Raw mouse events provide an alternate model for routing mouse input.

When the mouse is moved or dragged, PBMsg_RAW_MOUSE_MOVE is sent to the hovered or pressed element respectively, and all of its ancestors.

When a mouse button is pressed or released, the corresponding raw mouse message is sent to the pressed element and all of its ancestors.

Mouse Wheel Events

If an element is pressed, it is sent the PBMsg_MOUSE_WHEEL message. Otherwise, the hovered element is sent the message.

If the message handler returns 0, then the message is sent to the layout parent as well. This process may repeat until the window (the root) is reached. If 1 is returned, then processing completes immediately.

Keyboard Events

The focused element is sent the PBMsg_KEY_DOWN and PBMsg_KEY_UP messages.

If the message handler returns 0, then the message is sent to the layout parent as well. This process may repeat until the window (the root) is reached. If 1 is returned, then processing completes immediately.

If the root is reached without any element returning 1, then the system will compare the keyboard event against the list of keyboard shortcuts registered in the window with PBWindowRegisterKeyboardShortcut.

The focused element is set with the PBElementFocus function. An element can also be focused by the user if it is a tab stop, which is determined by the PBElement_TAB_STOP flag.

Modifiers Change Events

This event is generated whenever the set of held modifiers keys (command, shift, etc.) changes.

If an element is pressed, it is sent the PBMsg_MODIFIER_KEYS_CHANGED message. Otherwise, the hovered element is sent the message. The message is also sent to all its ancestors.