API — ICoreEssentials/UI/MenuBar

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

ICoreMenu.h#

src/ICoreEssentials/UI/MenuBar/ICoreMenu.h

I-Core menus.

The app's own drop-down / context menu, replacing QMenu. A QMenu is drawn by the platform style: it takes its colours from the desktop, not from the visual identity, so the one strip of the app that opens on every session was the one strip that never matched it.

Everything here is painted from theme tokens with QPainter -- the surface, the rows and the keyboard model are the ones ICoreGlobalSearchDialog established (rounded raised panel behind a hairline, inset pill rows, arrow keys move a highlight, Enter opens, Esc closes), so a menu reads as the same family as the search panel and the combo box list.

Like the combo box list -- and unlike the search panel, which is an overlay

ICoreMenuItem#

ICoreMenu.h:81 · class · final · bases public ICoreWidget · pImpl · 26 declaration(s)

One line of a menu.

class ICoreMenuItem final : public ICoreWidget {
public:
    enum class Kind { Action, Separator, Caption };

    ICoreMenuItem(ICoreMenu* ownerMenu, Kind kind, ICoreString text);
    ~ICoreMenuItem() override;

    [[nodiscard]] Kind getKind() const;
    [[nodiscard]] bool isAction() const;

    void setText(const ICoreString& text);
    [[nodiscard]] ICoreString getText() const;

    // Right column. Set for you when addItem() is given a key sequence.
    void setShortcutText(const ICoreString& shortcutText);

    // Own flag rather than QWidget::setEnabled: a disabled Qt widget stops
    // receiving mouse events, which would leave the previous row highlighted
    // while the pointer sits on this one.
    void setItemEnabled(bool enabled);
    [[nodiscard]] bool isItemEnabled() const;

    void setCheckable(bool checkable);
    [[nodiscard]] bool isCheckable() const;
    void setChecked(bool checked);
    [[nodiscard]] bool isChecked() const;

    // Leading icon, named from the SVG registry (":/SVGs/TrashIcon.svg"). It is
    // recoloured to the row's own text colour rather than kept as the file drew
    // it, so it follows the label through hover, disabled and a theme switch --
    // the icons in the registry are black line art, which a dark surface would
    // otherwise swallow.
    void setIconPath(const ICoreString& resourcePath);
    [[nodiscard]] bool hasIcon() const;

    [[nodiscard]] ICoreMenu* getSubMenu() const;

    // The row's counterpart in the system menu bar, on the platforms that have
    // one (see ICoreMenu::setNativeMirror). Null everywhere else, and null for
    // a menu that is not part of the menu bar.
    [[nodiscard]] QAction* getNativeAction() const;

    // Whether the row leaves room for the leading column that holds the tick or
    // the icon. The menu turns this on for every row once any one of its rows
    // needs it, so the labels of a mixed menu still line up.
    void setReservesLeadColumn(bool reserves);

    void setHighlighted(bool highlighted);
    [[nodiscard]] bool isHighlighted() const;

    // Width this row would like: label, the gap, and its right column.
    int preferredWidth() const;

    ICoreSizeF preferredSize() const override;

protected:
    void paintContent(ICorePainter& painter) override;
    void pointerEntered() override;
    bool mousePressed(const ICoreMouseEvent& event) override;
    bool mouseReleased(const ICoreMouseEvent& event) override;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreMenu#

ICoreMenu.h:159 · class · final · bases public ICoreWidget · pImpl · 24 declaration(s)

The menu itself.

class ICoreMenu final : public ICoreWidget {
public:
    explicit ICoreMenu(ICoreNativeWidget* parent = nullptr);
    ~ICoreMenu() override;

    // ---------------- building
    ICoreMenuItem* addItem(const ICoreString& text, std::function<void()> onActivated);
    ICoreMenuItem* addItem(const ICoreString& text, const ICoreKeySequence& shortcut,
                           std::function<void()> onActivated);
    ICoreMenuItem* addCheckableItem(const ICoreString& text, bool checked,
                                    std::function<void(bool)> onToggled);
    ICoreMenuItem* addCaption(const ICoreString& caption);
    void addSeparator();

    // A second key for a row that already has one (Ctrl+B beside Ctrl+D). It is
    // registered but not drawn: the row keeps showing the key it was made with,
    // so the shortcut column stays one line.
    void addAlternateShortcut(ICoreMenuItem* item, const ICoreKeySequence& shortcut) const;

    // A nested menu, owned by this one. Fill it exactly like its parent.
    ICoreMenu* addSubMenu(const ICoreString& text);

    // The row in the parent menu that opens this one -- for giving a submenu's
    // row an icon, since addSubMenu hands back the menu rather than the row.
    // Null on a menu that is not a submenu.
    [[nodiscard]] ICoreMenuItem* getOwnerItem() const;

    void clearItems();

    // ---------------- the system menu bar
    //
    // On a desktop that keeps the app's menus outside its windows -- macOS, in
    // the bar beside the Apple logo -- the menus still have to be declared once,
    // here. Given a QMenu to mirror into, every row added from now on gets a
    // QAction counterpart in it, and the two stay in step: what the row says,
    // whether it is enabled and whether it is ticked are set on both, and either
    // one being activated runs the same callback. The painted menu is simply
    // never shown there.
    //
    // Set by ICoreMenuBar on the menus it owns, before anything is added to
    // them. Submenus inherit a mirror of their own. A context menu has none.
    //
    // ⚠ Q2.3 MOVED THE ACCESSOR PAIR IMPL-SIDE (§5). The mirror is a QMenu and
    // there is no wrapper to name instead -- it is the platform's own menu, not
    // something this API builds -- so the pair went behind
    // ICoreMenuNativeMirrorAccess.h, the ICoreNativeHandleAccess.h pattern. Both
    // callers (this class's addSubMenu and ICoreMenuBar) are inside the
    // sanctioned MenuBar zone and include that header from their .cpp.

    // Where the real QShortcuts of addItem() are installed. Application-context,
    // so the keys work in every window of the app and not only the one the host
    // belongs to -- an editor torn off into its own window answers them too.
    // Submenus inherit it. Set this before adding items that carry a shortcut.
    void setShortcutHost(ICoreNativeWidget* host);

    // Asked just before an application-context shortcut runs its row; false stands
    // the key down. Application context means every window hears the key, and not
    // every window is somewhere the key means anything: a project browser or a
    // script window is only borrowing the keyboard, and a bare Delete pressed in
    // one of them must not reach the canvas sitting behind it. A menu bar that
    // never sets one fires everywhere, which is what a single-window app wants.
    // Submenus inherit it. Set this before adding items that carry a shortcut --
    // each shortcut takes the hook that was in place when it was registered.
    void setShortcutScopeHook(std::function<bool()> hook);

    // Run just before the menu shows: where a menu refreshes what its rows say
    // and which of them are enabled, so it never opens on stale state.
    void setAboutToShowHook(std::function<void()> hook);

    // Left / Right at the top level walk the menu bar. Installed by ICoreMenuBar
    // on the menus it owns; a menu opened as a plain context menu has none and
    // simply ignores those keys.
    void setSiblingNavigationHook(std::function<void(int delta)> hook);

    // ---------------- showing
    void popupUnder(ICoreNativeWidget* anchor);            // drop-down: under the widget that owns it
    // Context menu: at the pointer. Q2.3 deleted the QPoint overload that stood
    // beside this one -- all five call sites already held an ICorePoint and
    // bound here, so it was an unused second spelling.
    void popupAt(const ICorePoint& globalTopLeft);

    // Closes this menu and everything it opened. closeWholeChain() walks up to
    // the root first, which is what activating an item does.
    void closeChain();
    void closeWholeChain();

    [[nodiscard]] bool isMenuOpen() const;

    // This menu closed -- for the menu bar, which un-presses its title. The
    // ICore mirror of the Qt signal below; new subscribers use this one, since
    // the Qt signal does not survive the pImpl conversion.
    ICoreSignal<> onMenuClosed;

protected:
    bool keyPressed(const ICoreKeyEvent& event) override;

    // Chain ROUTING rather than a plain press: it re-routes a press that landed
    // on another menu in the chain, by global position. P5.8's decision was
    // that this needs no bespoke hook after all — ICoreMouseEvent carries BOTH
    // the widget-local `pos` and `globalPos`, which is the whole reason the
    // routing was thought to need the Qt event.
    bool mousePressed(const ICoreMouseEvent& event) override;

    void pointerEntered() override;
    void hidden() override;

    // The chain's hover router. Only a ROOT menu arms this, and only while the
    // chain is open — one watcher hit-testing every menu in it. Replaces an
    // app-wide eventFilter; see prepareToShow()/hidden() for the arming.
    void applicationPointerMoved(const ICorePoint& globalPos) override;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreMenuBar.h#

src/ICoreEssentials/UI/MenuBar/ICoreMenuBar.h

ICoreMenuBar#

ICoreMenuBar.h:34 · class · final · bases public ICoreWidget · pImpl · 12 declaration(s)

The app's menu strip.

class ICoreMenuBar final : public ICoreWidget {
public:
    explicit ICoreMenuBar(ICoreNativeWidget* parent = nullptr);
    ~ICoreMenuBar() override;

    // Whether this desktop keeps an application's menus outside its windows.
    // macOS does -- the bar at the top of the screen beside the Apple logo is
    // where a Mac user looks for File and Edit, and putting a second strip
    // inside the window would be the app disagreeing with the system about where
    // its own menus live. Windows and Linux keep the strip in the window, which
    // is where those desktops put it.
    //
    // Where it is true, the menus declared here are mirrored into a real
    // QMenuBar (see ICoreMenu::setNativeMirror), this widget is never shown, and
    // there is nothing for the editor's Show Menu Bar switch to switch.
    static bool usesSystemMenuBar();

    // "&File" gives a title reading "File" whose mnemonic is Alt+F. The menu is
    // owned by the bar; fill it with ICoreMenu's own API.
    ICoreMenu* addMenu(const ICoreString& titleWithMnemonic);

    // Where the menus' action shortcuts are registered. Set this to the window
    // before adding any menu, and Ctrl+S keeps working while the strip itself is
    // hidden -- Qt will not fire a shortcut whose host widget is invisible, and
    // saving a project is not something that should depend on a strip being on
    // screen. The Alt mnemonics stay on the strip on purpose: with nothing to
    // drop a menu from, they have nothing to do.
    void setShortcutHost(ICoreNativeWidget* host);

    // Narrows where those shortcuts are allowed to act. They are registered
    // application-wide so that a window holding a torn-off editor answers them
    // too, which means windows with nothing to do with editing hear them as well;
    // this hook is asked first and false stands the key down. Set it beside the
    // host, before adding any menu. See ICoreMenu::setShortcutScopeHook.
    void setShortcutScopeHook(std::function<bool()> hook);

    // Anything that should ride on the right end of the strip.
    // ⚠ ZERO callers tree-wide as of P6.9 (the usage line above is the only
    // mention). Narrowed rather than deleted: removing published API is the
    // owner's call, the way P1.1/P1.2's deletions were. Recommend deleting it.
    void addTrailingWidget(ICoreNativeWidget* widget);

    void closeOpenMenu();

    // Show / hide the whole strip. Any open menu goes with it. Does nothing
    // where the system carries the menus: that bar is not the app's to hide.
    void setBarVisible(bool visible);
    [[nodiscard]] bool isBarVisible() const;

    // ICore signal, not a Qt one: this class is a converted ICoreWidget.
    ICoreSignal<bool> onBarVisibilityChanged;

protected:
    void paintContent(ICorePainter& painter) override;

    // Watches the pointer while a menu is open, so sliding along the strip
    // switches menus. The open popup holds the mouse, so the titles cannot see
    // those moves themselves. Armed only while a menu is open — an
    // application-wide watch left installed sees every move in the app.
    void applicationPointerMoved(const ICorePoint& globalPos) override;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreMenuNativeMirrorAccess.h#

src/ICoreEssentials/UI/MenuBar/ICoreMenuNativeMirrorAccess.h

Declares no class of its own — see the file.