KHamburgerMenu

Search for usage in LXR

#include <KHamburgerMenu>

Inheritance diagram for KHamburgerMenu:

Signals

void aboutToShowMenu ()
 

Public Member Functions

 KHamburgerMenu (QObject *parent)
 
void addToMenu (QMenu *menu)
 
void hideActionsOf (QWidget *widget)
 
void insertIntoMenuBefore (QMenu *menu, QAction *before)
 
QMenuBarmenuBar () const
 
bool menuBarAdvertised () const
 
void setMenuBar (QMenuBar *menuBar)
 
void setMenuBarAdvertised (bool advertise)
 
void setShowMenuBarAction (QAction *showMenuBarAction)
 
void showActionsOf (QWidget *widget)
 
- Public Member Functions inherited from QWidgetAction
 QWidgetAction (QObject *parent)
 
QWidgetdefaultWidget () const const
 
void releaseWidget (QWidget *widget)
 
QWidgetrequestWidget (QWidget *parent)
 
void setDefaultWidget (QWidget *widget)
 
- Public Member Functions inherited from QAction
 QAction (const QIcon &icon, const QString &text, QObject *parent)
 
 QAction (const QString &text, QObject *parent)
 
 QAction (QObject *parent)
 
QActionGroupactionGroup () const const
 
void activate (QAction::ActionEvent event)
 
QList< QGraphicsWidget * > associatedGraphicsWidgets () const const
 
QList< QWidget * > associatedWidgets () const const
 
bool autoRepeat () const const
 
void changed ()
 
QVariant data () const const
 
QFont font () const const
 
void hover ()
 
void hovered ()
 
QIcon icon () const const
 
QString iconText () const const
 
bool isCheckable () const const
 
bool isChecked () const const
 
bool isEnabled () const const
 
bool isIconVisibleInMenu () const const
 
bool isSeparator () const const
 
bool isShortcutVisibleInContextMenu () const const
 
bool isVisible () const const
 
QMenumenu () const const
 
QAction::MenuRole menuRole () const const
 
QWidgetparentWidget () const const
 
QAction::Priority priority () const const
 
void setActionGroup (QActionGroup *group)
 
void setAutoRepeat (bool)
 
void setCheckable (bool)
 
void setChecked (bool)
 
void setData (const QVariant &userData)
 
void setDisabled (bool b)
 
void setEnabled (bool)
 
void setFont (const QFont &font)
 
void setIcon (const QIcon &icon)
 
void setIconText (const QString &text)
 
void setIconVisibleInMenu (bool visible)
 
void setMenu (QMenu *menu)
 
void setMenuRole (QAction::MenuRole menuRole)
 
void setPriority (QAction::Priority priority)
 
void setSeparator (bool b)
 
void setShortcut (const QKeySequence &shortcut)
 
void setShortcutContext (Qt::ShortcutContext context)
 
void setShortcuts (const QList< QKeySequence > &shortcuts)
 
void setShortcuts (QKeySequence::StandardKey key)
 
void setShortcutVisibleInContextMenu (bool show)
 
void setStatusTip (const QString &statusTip)
 
void setText (const QString &text)
 
void setToolTip (const QString &tip)
 
void setVisible (bool)
 
void setWhatsThis (const QString &what)
 
QKeySequence shortcut () const const
 
Qt::ShortcutContext shortcutContext () const const
 
QList< QKeySequenceshortcuts () const const
 
bool showStatusText (QWidget *widget)
 
QString statusTip () const const
 
QString text () const const
 
void toggle ()
 
void toggled (bool checked)
 
QString toolTip () const const
 
void trigger ()
 
void triggered (bool checked)
 
QString whatsThis () const const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (const QObject *object)
 
qobject_cast (QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Protected Member Functions

virtual QWidgetcreateWidget (QWidget *parent) override
 
- Protected Member Functions inherited from QWidgetAction
QList< QWidget * > createdWidgets () const const
 
virtual void deleteWidget (QWidget *widget)
 
virtual bool event (QEvent *event) override
 
virtual bool eventFilter (QObject *obj, QEvent *event) override
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Additional Inherited Members

- Public Types inherited from QAction
enum  ActionEvent
 
enum  MenuRole
 
enum  Priority
 
- Properties inherited from QAction
 autoRepeat
 
 checkable
 
 checked
 
 enabled
 
 font
 
 icon
 
 iconText
 
 iconVisibleInMenu
 
 menuRole
 
 priority
 
 shortcut
 
 shortcutContext
 
 shortcutVisibleInContextMenu
 
 statusTip
 
 text
 
 toolTip
 
 visible
 
 whatsThis
 
- Properties inherited from QObject
 objectName
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QAction
 AboutQtRole
 
 AboutRole
 
 ApplicationSpecificRole
 
 HighPriority
 
 Hover
 
 LowPriority
 
 NormalPriority
 
 NoRole
 
 PreferencesRole
 
 QuitRole
 
 TextHeuristicRole
 
 Trigger
 
- Public Attributes inherited from QObject
typedef QObjectList
 

Detailed Description

A menu that substitutes a menu bar when necessary.

Allowing users to toggle the visibility of the menu bar and/or toolbars, while pretty/"simple by default", can lead to various grave usability issues. This class makes it easy to prevent all of them.

Simply add a KHamburgerMenu to your UI (typically to a QToolBar) and make it aware of a QMenuBar like this:

auto hamburgerMenu = KStandardAction::hamburgerMenu(nullptr, nullptr, actionCollection());
toolBar()->addAction(hamburgerMenu);
// after the QMenuBar has been initialised
hamburgerMenu->setMenuBar(menuBar()); // line not needed if there is no QMenuBar

The added menu button will only be visible when the QMenuBar is hidden. With this minimal initialisation it will contain the contents of the menu bar. If a user (also) hides the container the KHamburgerMenu was added to they might find themselves without a way to get a menu back. To prevent this, it is recommended to add the hamburgerMenu to prominent context menus like the one of your central widget preferably at the first position. Simply write:

hamburgerMenu->addActionToMenu(contextMenu);

The added menu will only be visible if the QMenuBar is hidden and the hamburgerMenu->createdWidgets() are all invisible to the user.

Populating the KHamburgerMenu

This is easy:

auto menu = new QMenu(this);
menu->addAction(action);
// Add actions, separators, etc. like usual.

You probably do not want this to happen on startup. Therefore KHamburgerMenu provides the signal aboutToShowMenu that you can connect to a function containing the previous statements.

this, &MainWindow::updateHamburgerMenu);
// You might want to disconnect the signal after initial creation if the contents never change.

Deciding what to put on the hamburger menu

  1. Be sure to add all of the most important actions. Actions which are already visible on QToolBars, etc. will not show up in the hamburgerMenu. To manage which containers KHamburgerMenu should watch for redundancy use hideActionsOf(QWidget *) and showActionsOf(QWidget *). When a KHamburgerMenu is added to a widget, hideActionsOf(that widget) will automatically be called.
  2. Do not worry about adding all actions the application has to offer. The KHamburgerMenu will automatically have a section advertising excluded actions which can be found in the QMenuBar. There will also be the showMenuBarAction if you set it with setShowMenuBarAction().
  3. Do not worry about the help menu. KHamburgerMenu will automatically contain a help menu as the second to last item (if you set a QMenuBar which is expected to have the help menu as the last action).
Since
5.81

Definition at line 94 of file khamburgermenu.h.

Member Function Documentation

◆ aboutToShowMenu

void KHamburgerMenu::aboutToShowMenu ( )
signal

This signal is emitted when a hamburger menu button is about to be pressed down.

It is also emitted when a QMenu that contains a visible KHamburgerMenu emits QMenu::aboutToShow.

◆ addToMenu()

void KHamburgerMenu::addToMenu ( QMenu menu)

Adds this KHamburgerMenu to menu.

It will only be visible in the menu if both the menu bar and all of this QWidgetAction's createdWidgets() are invisible. If it is visible in the menu, then opening the menu emits the aboutToShowMenu signal.

Parameters
menuThe menu this KHamburgerMenu is supposed to appear in.

Definition at line 107 of file khamburgermenu.cpp.

◆ createWidget()

QWidget * KHamburgerMenu::createWidget ( QWidget parent)
overrideprotectedvirtual
See also
QWidgetAction::createWidget

Reimplemented from QWidgetAction.

Definition at line 185 of file khamburgermenu.cpp.

◆ hideActionsOf()

void KHamburgerMenu::hideActionsOf ( QWidget widget)

Adds widget to a list of widgets that should be monitored for their actions().

If the widget is a QMenu, its actions will be treated as known to the user. If the widget isn't a QMenu, its actions will only be treated as known to the user when the widget is actually visible.

Parameters
widgetA widget that contains actions which should not show up in the KHamburgerMenu redundantly.

Definition at line 141 of file khamburgermenu.cpp.

◆ insertIntoMenuBefore()

void KHamburgerMenu::insertIntoMenuBefore ( QMenu menu,
QAction before 
)

Inserts this KHamburgerMenu to menu's list of actions, before the action before.

It will only be visible in the menu if both the menu bar and all of this QWidgetAction's createdWidgets() are invisible. If it is visible in the menu, then opening the menu emits the aboutToShowMenu signal.

Parameters
beforeThe action before which KHamburgerMenu should be inserted.
menuThe menu this KHamburgerMenu is supposed to appear in.
See also
QWidget::insertAction(), QMenu::insertMenu()
Since
5.99

Definition at line 113 of file khamburgermenu.cpp.

◆ menuBar()

QMenuBar * KHamburgerMenu::menuBar ( ) const
See also
setMenuBar()

Definition at line 63 of file khamburgermenu.cpp.

◆ menuBarAdvertised()

bool KHamburgerMenu::menuBarAdvertised ( ) const
See also
setMenuBarAdvertised()

Definition at line 85 of file khamburgermenu.cpp.

◆ setMenuBar()

void KHamburgerMenu::setMenuBar ( QMenuBar menuBar)

Associates this KHamburgerMenu with menuBar.

The KHamburgerMenu will from now on only be visible when menuBar is hidden. (Menu bars with QMenuBar::isNativeMenuBar() == true are considered hidden.)

Furthermore the KHamburgerMenu will have the help menu from the menuBar added at the end. There will also be a special sub-menu advertising actions which are only available in the menu bar unless advertiseMenuBar(false) was called.

Parameters
menuBarThe QMenuBar the KHamburgerMenu should be associated with. This can be set to nullptr.

Definition at line 43 of file khamburgermenu.cpp.

◆ setMenuBarAdvertised()

void KHamburgerMenu::setMenuBarAdvertised ( bool  advertise)

By default the KHamburgerMenu contains a special sub-menu that advertises actions of the menu bar which would otherwise not be visible or discoverable for the user.

This method removes or re-adds that sub-menu.

Parameters
advertisesets whether the special sub-menu that advertises menu bar only actions should exist.

Definition at line 74 of file khamburgermenu.cpp.

◆ setShowMenuBarAction()

void KHamburgerMenu::setShowMenuBarAction ( QAction showMenuBarAction)

Adds the showMenuBarAction as the first item of the sub-menu which advertises actions from the menu bar.

See also
setMenuBarAdvertised()

Definition at line 96 of file khamburgermenu.cpp.

◆ showActionsOf()

void KHamburgerMenu::showActionsOf ( QWidget widget)

Reverses a hideActionsOf(widget) method call.

See also
hideActionsOf()

Definition at line 168 of file khamburgermenu.cpp.


The documentation for this class was generated from the following files:
void aboutToShowMenu()
This signal is emitted when a hamburger menu button is about to be pressed down.
void setMenu(QMenu *menu)
void hideActionsOf(QWidget *widget)
Adds widget to a list of widgets that should be monitored for their actions().
QMetaObject::Connection connect(const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
KHamburgerMenu * hamburgerMenu(const QObject *recvr, const char *slot, QObject *parent)
Opens a menu that substitutes the menubar.
QAction * addAction(const QString &text)
QMenu * menu() const const
void setMenuBar(QMenuBar *menuBar)
Associates this KHamburgerMenu with menuBar.
QMenuBar * menuBar() const
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 9 2023 04:12:56 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.