Events

gui-kit passes event payloads to element callbacks registered with Element::onClick, Element::onMouseMove, Element::onMouseEnter, Element::onMouseLeave, Element::onKeyDown, and Element::onKeyUp.

EventType

The kind of event being dispatched.

enum class EventType {
  Click,
  MouseMove,
  MouseEnter,
  MouseLeave,
  KeyDown,
  KeyUp,
};

Event

The base class of every event. It supports DOM-style control: events dispatched on a nested element bubble up through its ancestors unless stopped.

class Event {
public:
  EventType type;
  ElementBase *target;
  ElementBase *currentTarget;
  bool bubbles;
  bool cancelable;

  void preventDefault();
  bool isDefaultPrevented() const;
  void stopPropagation();
  bool isPropagationStopped() const;
};

preventDefault()

Cancels the default behavior of the event, if it is cancelable.

void preventDefault();

isDefaultPrevented()

Returns true if preventDefault() has been called.

bool isDefaultPrevented() const;

stopPropagation()

Stops the event from bubbling any further up the tree.

void stopPropagation();

isPropagationStopped()

Returns true if stopPropagation() has been called.

bool isPropagationStopped() const;

MouseEvent

Derived from Event. Passed to onClick, onMouseMove, onMouseEnter, and onMouseLeave callbacks.

class MouseEvent : public Event {
public:
  int x = 0;
  int y = 0;
  int clicks = 0;
  int button = 0;
};

x / y

The cursor position, relative to the window.

clicks

The number of clicks in the event (1 = single, 2 = double, ...).

button

The mouse button index that was pressed.

KeyboardEvent

Derived from Event. Passed to the onKeyDown / onKeyUp callbacks.

class KeyboardEvent : public Event {
public:
  Key key = Key::Unknown;
  bool shiftKey = false;
  bool ctrlKey = false;
  bool altKey = false;
  bool metaKey = false;
  bool repeat = false;
};

key

The key, as a guikit::Key enum value.

shiftKey / ctrlKey / altKey / metaKey

Whether the corresponding modifier was held during the event.

repeat

Whether this is an auto-repeat of a held key.

Key enum

guikit::Key is a large enum covering printable characters, function keys, navigation keys, modifiers, and the numeric keypad. Common values include Key::Return, Key::Escape, Key::Space, Key::A, Key::F1, Key::Up, Key::LeftControl, and Key::Unknown. GLFW key codes are translated automatically via the internal fromGLFW helper, so callbacks always receive a guikit::Key.

Event dispatch

Mouse events are hit-tested against the whole widget tree and bubble from the deepest element under the cursor up to the root. Hover follows the web model:

• onMouseEnter fires once when the pointer enters the element.
• onMouseMove fires on every pointer motion over the element (and bubbles).
• onMouseLeave fires once when the pointer leaves the element.

Example

#include <guikit/window.hpp>
#include <guikit/box.hpp>
#include <guikit/colors.hpp>
#include <guikit/events/mouse-event.hpp>

using namespace guikit;

int main() {
    Window window("Events Demo", 800, 600);

    window.rootElement->addChild<Box>()
        .setWidth(200)
        .setHeight(100)
        .setBackgroundColor(Colors::Cyan600())
        .onClick([](MouseEvent &e) {
            // e.x, e.y, e.clicks, e.button
        })
        .onMouseEnter([](MouseEvent &e) {
            // fired once when the cursor enters
        })
        .onMouseMove([](MouseEvent &e) {
            // fired continuously while the cursor is over the element
        });

    window.show();
    return 0;
}