API — ICoreEssentials/UI/Events

The public contract of 7 header(s) under src/ICoreEssentials/UI/Events — 6 class/struct definition(s), 11 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreDragEvent.h#

src/ICoreEssentials/UI/Events/ICoreDragEvent.h

ICoreDragEvent#

ICoreDragEvent.h:8 · struct · 0 declaration(s)

What a widget hook learns about a drag entering, moving over, or dropping on it.

struct ICoreDragEvent {
public:
    // Position in the receiving widget's own coordinates.
    ICorePoint pos;

    ICoreMimePayload payload;
};
};

ICoreEventConversion.h#

src/ICoreEssentials/UI/Events/ICoreEventConversion.h

Builders that turn a Qt event into the value its hook receives. FOR WRAPPER .CPPS ONLY -- this header names Qt event types, so including it anywhere outside the wrapper zone is itself a boundary violation. Every wrapper base class (ICoreWidget today, the graphics classes when they grow hooks) uses these instead of hand-rolling the field mapping.

Declares no class of its own — see the file.

ICoreFocusEvent.h#

src/ICoreEssentials/UI/Events/ICoreFocusEvent.h

ICoreFocusEvent#

ICoreFocusEvent.h:15 · struct · 3 declaration(s)

What a focus hook learns.

struct ICoreFocusEvent {
public:
    ICoreFocusReason reason = ICoreFocusReason::Other;

    // Arriving by keyboard is the distinction almost every caller actually
    // wants; spelling it once here keeps the three-way switch out of the hooks.
    [[nodiscard]] bool isKeyboardDriven() const;

    // ------------------------------------------------------------------
    // ⚠ THE SAME TWO-AXIS PAIR ICoreKeyEvent AND ICoreMouseEvent CARRY, ADDED
    // FOR THE SAME REASON (P2.10b-4) AND USED BY focusGaining ALONE. A `bool
    // focusGaining` hook can say "do not run the toolkit base"; it cannot say
    // what to tell the event. ICorePortViewDescriptionLabel needs both: a label
    // that is not user-editable clears the focus it just got AND ignores, and
    // returning true alone would accept it.
    //
    // ⚠ It is meaningless on the focus-OUT pair, and deliberately not wired
    // there: focusLosing/focusLost return void because, as their note says,
    // declining is not a thing a focus loss can do.
    //
    // ⚠ ignore() is const and the flag is mutable because every hook takes a
    // `const ICoreFocusEvent&` -- the shape ICoreKeyEvent records, for the
    // reason ICoreMouseEvent's note records rejecting the alternative on cost.
    // ------------------------------------------------------------------
    void ignore() const;

    [[nodiscard]] bool isIgnored() const;

    // ⚠ PUBLIC, and set through ignore() rather than written directly. It is a
    // member rather than an Impl because this is an aggregate built fresh on
    // the stack for EVERY event -- a heap Impl here would be a malloc per
    // keystroke and per mouse move, and there is no implementation to hide
    // behind it: every other field of this struct is public already. Mutable
    // so ignore() can be const, because every hook takes a const reference.
    mutable bool m_ignored = false;
};
};

ICoreInputEnums.h#

src/ICoreEssentials/UI/Events/ICoreInputEnums.h

ICore names for the Qt:: constants that cross the wrapper boundary.

Clients spell ICoreAlignment::Center where they used to spell Qt::AlignCenter; the wrapper .cpps translate with a static_cast, which is only sound because every enumerator's underlying value below EQUALS its Qt counterpart. That equality is not trusted to this comment -- it is pinned by static_asserts in ICoreInputEnumsVerify.cpp, which includes the real Qt headers (it lives in the wrapper zone, so it may) and refuses to compile the moment Qt and this file disagree.

This header itself names no Qt token, so any layer may include it.

ICoreEasingSpec#

ICoreInputEnums.h:274 · struct · 2 declaration(s)

A curve plus the two knobs the toolkit exposes for the springy ones.

struct ICoreEasingSpec {
public:
    ICoreEasing curve = ICoreEasing::Linear;

    // Overshoot size for the Back and Elastic families. < 0 keeps the default.
    double amplitude = -1.0;

    // Oscillation frequency for the Elastic family. < 0 keeps the default.
    double period = -1.0;

    // Implicit on purpose: setEasing(ICoreEasing::OutCubic) must keep working
    // unchanged at the ~10 sites that write it, spec overload or not.
    ICoreEasingSpec(ICoreEasing c = ICoreEasing::Linear);

    ICoreEasingSpec(ICoreEasing c, double amplitudeValue, double periodValue);
};
};

File-scope declarations#

// ICore names for the Qt:: constants that cross the wrapper boundary.
// 
// Clients spell ICoreAlignment::Center where they used to spell
// Qt::AlignCenter; the wrapper .cpps translate with a static_cast, which is
// only sound because every enumerator's underlying value below EQUALS its Qt
// counterpart. That equality is not trusted to this comment -- it is pinned by
using ICoreReal = double;

enum class ICoreMouseButton : unsigned int {
    None = 0x00000000,
    Left = 0x00000001,
    Right = 0x00000002,
    Middle = 0x00000004,
};

// Bitmask of ICoreMouseButton values ("which buttons are held right now").
using ICoreMouseButtons = unsigned int;

enum class ICoreKeyModifier : unsigned int {
    None = 0x00000000,
    Shift = 0x02000000,
    Control = 0x04000000,
    Alt = 0x08000000,
    Meta = 0x10000000,
    Keypad = 0x20000000,
};

// Bitmask of ICoreKeyModifier values.
using ICoreKeyModifiers = unsigned int;

// The keys client code actually branches on. A key event also carries the raw
// key code, so an exotic key can still be matched by value; printable keys
// use their ASCII uppercase code (ICoreKey::A == 'A'), exactly as Qt does.
enum class ICoreKey : int {
    Space = 0x20,
    Plus = 0x2b, Minus = 0x2d, Equal = 0x3d, Underscore = 0x5f,
    Digit0 = 0x30, Digit1, Digit2, Digit3, Digit4, Digit5, Digit6, Digit7, Digit8, Digit9,
    A = 0x41, B, C, D, E, F, G, H, I, J, K, L, M,
    N, O, P, Q, R, S, T, U, V, W, X, Y, Z,
    Escape = 0x01000000,
    Tab = 0x01000001,
    Backtab = 0x01000002,
    Backspace = 0x01000003,
    Return = 0x01000004,
    Enter = 0x01000005,
    Insert = 0x01000006,
    Delete = 0x01000007,
    Home = 0x01000010,
    End = 0x01000011,
    ArrowLeft = 0x01000012,
    ArrowUp = 0x01000013,
    ArrowRight = 0x01000014,
    ArrowDown = 0x01000015,
    PageUp = 0x01000016,
    PageDown = 0x01000017,
    Shift = 0x01000020,
    Control = 0x01000021,
    Meta = 0x01000022,
    Alt = 0x01000023,
    F1 = 0x01000030, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,
};

enum class ICoreAlignment : unsigned int {
    Left = 0x0001,
    Right = 0x0002,
    HCenter = 0x0004,
    Justify = 0x0008,
    Top = 0x0020,
    Bottom = 0x0040,
    VCenter = 0x0080,
    Baseline = 0x0100,
    Center = HCenter | VCenter,
};

enum class ICoreOrientation : unsigned int {
    Horizontal = 0x1,
    Vertical = 0x2,
};

// How a widget wants a layout to treat its size hint, one axis at a time.
enum class ICoreSizeBehavior : int {
    // The values are the toolkit's grow/shrink/expand bit set, not a
    // sequence -- Maximum is 4 and Preferred is 5, which is why the
    // static_asserts next door exist rather than a comment claiming so.
    Fixed = 0,        // the hint is the size, full stop
    Minimum = 1,      // the hint is a floor; may grow
    Maximum = 4,      // the hint is a ceiling; may shrink
    Preferred = 5,    // the hint is ideal; may grow or shrink
    MinimumExpanding = 3,
    Expanding = 7,    // wants as much room as it can get
    Ignored = 13,     // the hint carries no information
};

// What kind of top-level a widget is, if any. Child (the default) means it
// is laid out inside its parent and is not a window at all.
enum class ICoreWindowNature {
    Child,
    FramelessWindow,   // a real window with no OS title bar
    Popup,             // dismissed by a click elsewhere; takes focus
    FloatingCard,      // a hover card: no frame, no shadow, never takes focus
    // Q5.1: a real window WITH the OS title bar -- the plain top-level. The
    // vocabulary had frameless but not decorated, so the one site that wanted
    // it (ICoreBlockCodeEditorWindow) had to reach past the wrapper for a bare
    // setWindowFlag. Appended rather than inserted: nothing pins these values,
    // but renumbering an enum other code stores is a gratuitous risk.
    DecoratedWindow,
};

// How many rows a view lets the user pick at once.
enum class ICoreSelectionMode : int {
    None = 0,
    Single = 1,
    Multi = 2,
    Extended = 3,     // click, shift-click, ctrl-click -- the usual list behaviour
    Contiguous = 4,
};

enum class ICoreScrollBarPolicy : int {
    AsNeeded = 0,
    AlwaysOff = 1,
    AlwaysOn = 2,
};

enum class ICoreTextElide : int {
    Left = 0,
    Right = 1,
    Middle = 2,
    None = 3,
};

// Whether, and how, a widget accepts keyboard focus. The values are a bit set
// (Strong == Tab|Click|0x8), not a sequence -- see the static_asserts.
enum class ICoreFocusPolicy : int {
    None = 0,
    Tab = 0x1,
    Click = 0x2,
    Strong = 0xb,
    Wheel = 0xf,
};

// A per-widget behaviour switch -- the toolkit's "widget attribute" set.
// 
// A shortlist of the nine this project actually sets, not a mirror of the
// toolkit's ~130, for the same reason ICoreEasing is a shortlist: a name is
// only worth having if it means something here. The values are the toolkit's
// own and are NOT a sequence -- they are positions in a bitfield the toolkit
enum class ICoreWidgetAttribute : int {
    OpaquePaintEvent = 4,            // the widget paints every pixel itself
    NoSystemBackground = 9,
    TransparentForMouseEvents = 51,  // clicks fall through to what is behind
    DeleteOnClose = 55,
    Hover = 74,                      // ask for enter/leave events (see ICoreWidget)
    // Marked "internal" in the toolkit's own header. Kept because the styling
    // module needs it for a stylesheet background to paint on a plain widget,
    // and there is no public spelling that does the same job.
    StyledBackground = 93,
    ShowWithoutActivating = 98,
    DontShowOnScreen = 103,          // lay out and render, but never map a window
    TranslucentBackground = 120,
};

// What kind of top-level a widget is, plus the frame hints that modify it.
// 
// Distinct from ICoreWindowNature, which is a NARROWED vocabulary -- four
// named shapes the editor actually builds. This is the wide form, for the
// constructor parameters that pass a caller's flags through verbatim. Prefer
// ICoreWindowNature in new code; this exists so those ctors stop naming Qt.
enum class ICoreWindowFlag : unsigned int {
    Widget = 0x00000000,
    Window = 0x00000001,
    Dialog = 0x00000002 | Window,
    Popup = 0x00000008 | Window,
    Tool = Popup | Dialog,
    FramelessWindowHint = 0x00000800,
    WindowStaysOnTopHint = 0x00040000,
    WindowDoesNotAcceptFocus = 0x00200000,
    CustomizeWindowHint = 0x02000000,
    NoDropShadowWindowHint = 0x40000000,
};

// Bitmask of ICoreWindowFlag values -- the same shape as ICoreMouseButtons.
using ICoreWindowFlags = unsigned int;

// How a view's columns take their width.
enum class ICoreColumnResize : int {
    Interactive = 0,
    Stretch = 1,
    Fixed = 2,
    ToContents = 3,
};

// How wide a keyboard shortcut listens. The values are the toolkit's context
// constants, which are not in this order -- WidgetWithChildren is 3 and
// Application is 2 -- so the static_asserts next door are what keeps them
// honest rather than the order they are written in here.
// 
// Window is the default at every call site: a key that means something in one
enum class ICoreShortcutScope : int {
    Window = 1,
    WidgetWithChildren = 3,   // the host widget and anything inside it, only
    Application = 2,
};

// The motion curves the editor actually uses. Deliberately a shortlist, not a
// mirror of the toolkit's ~40: a named vocabulary is only worth having if the
// names mean something here.
enum class ICoreEasing {
    Linear, InQuad, OutQuad, InOutQuad,
    InCubic, OutCubic, InOutCubic,
    InBack, OutBack, OutElastic, InOutSine,
};

enum class ICoreFontWeight : int {
    Normal = 400,
    Medium = 500,
    DemiBold = 600,
    Bold = 700,
};

enum class ICorePenStyle : int {
    None = 0,
    Solid = 1,
    Dash = 2,
    Dot = 3,
    DashDot = 4,
    DashDotDot = 5,
};

enum class ICorePenCap : int {
    Flat = 0x00,
    Square = 0x10,
    Round = 0x20,
};

// How two segments of a stroked line meet. Deliberately the three the toolkit
// offers as line joins; the SVG-compatible miter variant has no call site.
enum class ICorePenJoin : int {
    Miter = 0x00,
    Bevel = 0x40,
    Round = 0x80,
};

// Why a widget is being given focus. It matters: a field focused by the mouse
// does not select its contents, one focused by Tab does.
enum class ICoreFocusReason : int {
    Mouse = 0,
    Tab = 1,
    Backtab = 2,
    ActiveWindow = 3,
    Popup = 4,
    Shortcut = 5,
    MenuBar = 6,
    Other = 7,
};

enum class ICoreCursorShape : int {
    Arrow = 0,
    UpArrow = 1,
    Cross = 2,
    Wait = 3,
    IBeam = 4,
    SizeVertical = 5,
    SizeHorizontal = 6,
    SizeBackwardDiagonal = 7,
    SizeForwardDiagonal = 8,
    SizeAll = 9,
    Blank = 10,
    SplitVertical = 11,
    SplitHorizontal = 12,
    PointingHand = 13,
    Forbidden = 14,
    WhatsThis = 15,
    Busy = 16,
    OpenHand = 17,
    ClosedHand = 18,
    DragCopy = 19,
    DragMove = 20,
    DragLink = 21,
};

ICoreKeyEvent.h#

src/ICoreEssentials/UI/Events/ICoreKeyEvent.h

ICoreKeyEvent#

ICoreKeyEvent.h:9 · struct · 4 declaration(s)

What a widget hook learns about a key event.

struct ICoreKeyEvent {
public:
    int key = 0;

    ICoreKeyModifiers modifiers = 0;

    // The text this key would insert ("" for pure modifiers and navigation).
    ICoreString text;

    bool autoRepeat = false;

    [[nodiscard]] bool is(ICoreKey which) const;

    [[nodiscard]] bool hasModifier(ICoreKeyModifier which) const;

    // ------------------------------------------------------------------
    // ⚠ THE SAME TWO-AXIS PAIR ICoreMouseEvent CARRIES, AND ADDED FOR THE SAME
    // REASON (P2.10b-4). A `bool keyPressed` hook can say "do not run the
    // toolkit base"; it cannot say what to tell the parent item. Those are two
    // facts, and ICoreGraphicsBoxedText needs both: it swallows Return/Enter to
    // prevent a newline, and it does so with `event->ignore()` -- so the key
    // keeps propagating to the item above, which is how a dialog still sees
    // Enter. Returning true alone would ACCEPT it and silently swallow that.
    //
    // ⚠ ignore() is const and the flag is mutable because every hook takes a
    // `const ICoreKeyEvent&`. Widening the hooks instead is the edit
    // ICoreMouseEvent's note records being rejected on cost.
    // ------------------------------------------------------------------
    void ignore() const;

    [[nodiscard]] bool isIgnored() const;

    // ⚠ PUBLIC -- see ICoreFocusEvent.h for why an event aggregate carries this
    // as a member instead of behind an Impl. Set through ignore(); mutable so
    // ignore() can be const, because every hook takes a const reference.
    mutable bool m_ignored = false;
};
};

ICoreMouseEvent.h#

src/ICoreEssentials/UI/Events/ICoreMouseEvent.h

ICoreMouseEvent#

ICoreMouseEvent.h:33 · struct · 2 declaration(s)

What a widget hook learns about a pointer event.

struct ICoreMouseEvent {
public:
    // Position in the receiving widget's own coordinates.
    ICorePoint pos;

    // Position on the screen -- what QMouseEvent::globalPosition() carried.
    ICorePoint globalPos;

    // Position in the SCENE, for the graphics tier. Zero for widget events,
    // which have no scene.
    //
    // Carried rather than left to the receiver to map: an item handling a drag
    // needs the scene position on every move, mapping it back costs a call into
    // the item's transform chain, and the toolkit already computed it. (This was
    // omitted at first on the theory that item-local was always enough -- it is
    // used 55 times across the scene tier, so it was not.)
    ICorePoint scenePos;

    // The button that caused the event (None for pure moves).
    ICoreMouseButton button = ICoreMouseButton::None;

    // Every button held at the time of the event, or-ed together.
    ICoreMouseButtons buttons = 0;

    ICoreKeyModifiers modifiers = 0;

    // "Not mine -- let the scene carry it to whatever is under me." Pair it
    // with `return true` from the hook: true stops the toolkit base from
    // running, and this decides what the forwarder tells the toolkit event.
    //
    // A hook that returns true WITHOUT calling this accepts, exactly as
    // before. A hook that returns false runs the base and this flag is not
    // consulted at all -- the base decides accept/ignore itself, which is the
    // behaviour every unmigrated subclass still has.
    void ignore() const;

    [[nodiscard]] bool isIgnored() const;

    // Mutable so ignore() can be const -- see the note above the struct. The
    // forwarder reads this after the hook returns; it is never serialized,
    // compared or copied across events.
    //
    // ⚠ PUBLIC, not behind an Impl, and set through ignore() rather than
    // written directly. This aggregate is built fresh on the stack for every
    // pointer event, so a heap Impl would be a malloc per mouse MOVE -- and it
    // would hide nothing, since every other field here is public already.
    mutable bool m_ignored = false;
};
};

ICoreWheelEvent.h#

src/ICoreEssentials/UI/Events/ICoreWheelEvent.h

ICoreWheelEvent#

ICoreWheelEvent.h:9 · struct · 0 declaration(s)

What a widget hook learns about a scroll event.

struct ICoreWheelEvent {
public:
    // Position in the receiving widget's own coordinates.
    ICorePoint pos;

    double deltaX = 0.0;
    double deltaY = 0.0;

    ICoreKeyModifiers modifiers = 0;
};
};