The QWidgetAction class extends QAction by an interface for inserting custom widgets into action based containers, such as toolbars. More...

#include <qwidgetaction.h>

Inheritance diagram for QWidgetAction:

Public Functions
QWidget *	defaultWidget () const
	Returns the default widget. More...

	QWidgetAction (QObject *parent)
	Constructs an action with parent. More...

void	releaseWidget (QWidget *widget)
	Releases the specified widget. More...

QWidget *	requestWidget (QWidget *parent)
	Returns a widget that represents the action, with the given parent. More...

void	setDefaultWidget (QWidget *w)
	Sets widget to be the default widget. More...

virtual	~QWidgetAction ()
	Destroys the object and frees allocated resources. More...

Public Functions inherited from QAction
QActionGroup *	actionGroup () const
	Returns the action group for this action. More...

void	activate (ActionEvent event)
	Sends the relevant signals for ActionEvent event. More...

QList< QGraphicsWidget * >	associatedGraphicsWidgets () const
	Returns a list of widgets this action has been added to. More...

QList< QWidget * >	associatedWidgets () const
	Returns a list of widgets this action has been added to. More...

bool	autoRepeat () const

QVariant	data () const
	Returns the user data as set in QAction::setData. More...

QFont	font () const

QIcon	icon () const

QString	iconText () const

bool	isCheckable () const

bool	isChecked () const

bool	isEnabled () const

bool	isIconVisibleInMenu () const

bool	isSeparator () const
	Returns true if this action is a separator action; otherwise it returns false. More...

bool	isVisible () const

QMenu *	menu () const
	Returns the menu contained by this action. More...

MenuRole	menuRole () const

QWidget *	parentWidget () const
	Returns the parent widget. More...

Priority	priority () const

	QAction (QObject *parent)
	Constructs an action with parent. More...

	QAction (const QString &text, QObject *parent)
	Constructs an action with some text and parent. More...

	QAction (const QIcon &icon, const QString &text, QObject *parent)
	Constructs an action with an icon and some text and parent. More...

void	setActionGroup (QActionGroup *group)
	Sets this action group to group. More...

void	setAutoRepeat (bool)

void	setCheckable (bool)

void	setData (const QVariant &var)
	Sets the action's internal data to the given userData. More...

void	setFont (const QFont &font)

void	setIcon (const QIcon &icon)

void	setIconText (const QString &text)

void	setIconVisibleInMenu (bool visible)

void	setMenu (QMenu *menu)
	Sets the menu contained by this action to the specified menu. More...

void	setMenuRole (MenuRole menuRole)

void	setPriority (Priority priority)

void	setSeparator (bool b)
	If b is true then this action will be considered a separator. More...

void	setShortcut (const QKeySequence &shortcut)

void	setShortcutContext (Qt::ShortcutContext context)

void	setShortcuts (const QList< QKeySequence > &shortcuts)
	Sets shortcuts as the list of shortcuts that trigger the action. More...

void	setShortcuts (QKeySequence::StandardKey)
	Sets a platform dependent list of shortcuts based on the key. More...

void	setSoftKeyRole (SoftKeyRole softKeyRole)

void	setStatusTip (const QString &statusTip)

void	setText (const QString &text)

void	setToolTip (const QString &tip)

void	setWhatsThis (const QString &what)

QKeySequence	shortcut () const

Qt::ShortcutContext	shortcutContext () const

QList< QKeySequence >	shortcuts () const
	Returns the list of shortcuts, with the primary shortcut as the first element of the list. More...

bool	showStatusText (QWidget *widget=0)
	Updates the relevant status bar for the widget specified by sending a QStatusTipEvent to its parent widget. More...

SoftKeyRole	softKeyRole () const

QString	statusTip () const

QString	text () const

QString	toolTip () const

QString	whatsThis () const

	~QAction ()
	Destroys the object and frees allocated resources. More...

Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...

const QObjectList &	children () const
	Returns a list of child objects. More...

bool	connect (const QObject sender, const char signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const

bool	disconnect (const char signal=0, const QObject receiver=0, const char *member=0)

bool	disconnect (const QObject receiver, const char member=0)

void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...

void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...

QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...

template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...

template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...

template<typename T >
QList< T >	findChildren (const QRegExp &re) const

bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...

void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...

bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...

void	killTimer (int id)
	Kills the timer with timer identifier, id. More...

virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...

void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...

QString	objectName () const

QObject *	parent () const
	Returns a pointer to the parent object. More...

QVariant	property (const char *name) const
	Returns the value of the object's name property. More...

Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...

void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...

void	setObjectName (const QString &name)

void	setParent (QObject *)
	Makes the object a child of parent. More...

bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...

void	setUserData (uint id, QObjectUserData *data)

bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...

int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...

QThread *	thread () const
	Returns the thread in which the object lives. More...

QObjectUserData *	userData (uint id) const

virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Protected Functions
QList< QWidget * >	createdWidgets () const
	Returns the list of widgets that have been using createWidget() and are currently in use by widgets the action has been added to. More...

virtual QWidget *	createWidget (QWidget *parent)
	This function is called whenever the action is added to a container widget that supports custom widgets. More...

virtual void	deleteWidget (QWidget *widget)
	This function is called whenever the action is removed from a container widget that displays the action using a custom widget previously created using createWidget(). More...

virtual bool	event (QEvent *)
	Reimplemented Function More...

virtual bool	eventFilter (QObject , QEvent )
	Reimplemented Function More...

Protected Functions inherited from QAction
	QAction (QActionPrivate &dd, QObject *parent)

Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...

virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...

virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...

virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...

	QObject (QObjectPrivate &dd, QObject *parent=0)

int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...

QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...

Friends
class	QToolBar

Additional Inherited Members
Public Types inherited from QAction
enum	ActionEvent { Trigger, Hover }
	This enum type is used when calling QAction::activate() More...

enum	MenuRole { NoRole, TextHeuristicRole, ApplicationSpecificRole, AboutQtRole, AboutRole, PreferencesRole, QuitRole }
	This enum describes how an action should be moved into the application menu on Mac OS X. More...

enum	Priority { LowPriority = 0, NormalPriority = 128, HighPriority = 256 }
	This enum defines priorities for actions in user interface. More...

enum	SoftKeyRole { NoSoftKey, PositiveSoftKey, NegativeSoftKey, SelectSoftKey }
	This enum describes how an action should be placed in the softkey bar. More...

Public Slots inherited from QAction
void	hover ()
	This is a convenience slot that calls activate(Hover). More...

void	setChecked (bool)

void	setDisabled (bool b)
	This is a convenience function for the enabled property, that is useful for signals–slots connections. More...

void	setEnabled (bool)

void	setVisible (bool)

void	toggle ()
	This is a convenience function for the checked property. More...

void	trigger ()
	This is a convenience slot that calls activate(Trigger). More...

Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...

Signals inherited from QAction
void	changed ()
	This signal is emitted when an action has changed. More...

void	hovered ()
	This signal is emitted when an action is highlighted by the user; for example, when the user pauses with the cursor over a menu option, toolbar button, or presses an action's shortcut key combination. More...

void	toggled (bool)
	This signal is emitted whenever a checkable action changes its isChecked() status. More...

void	triggered (bool checked=false)
	This signal is emitted when an action is activated by the user; for example, when the user clicks a menu option, toolbar button, or presses an action's shortcut key combination, or when trigger() was called. More...

Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...

Static Public Functions inherited from QObject
static bool	connect (const QObject sender, const char signal, const QObject receiver, const char member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...

static bool	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char member)
	Disconnects signal in object sender from method in object receiver. More...

static bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &member)

static uint	registerUserData ()

static QString	tr (const char sourceText, const char comment=0, int n=-1)

static QString	trUtf8 (const char sourceText, const char comment=0, int n=-1)

Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...

Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr

Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject

Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()

T *	qobject_cast (QObject *object)

	QObjectList

void *	qt_find_obj_child (QObject parent, const char type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

The QWidgetAction class extends QAction by an interface for inserting custom widgets into action based containers, such as toolbars.

Since: 4.2

Most actions in an application are represented as items in menus or buttons in toolbars. However sometimes more complex widgets are necessary. For example a zoom action in a word processor may be realized using a QComboBox in a QToolBar, presenting a range of different zoom levels. QToolBar provides QToolBar::insertWidget() as convenience function for inserting a single widget. However if you want to implement an action that uses custom widgets for visualization in multiple containers then you have to subclass QWidgetAction.

If a QWidgetAction is added for example to a QToolBar then QWidgetAction::createWidget() is called. Reimplementations of that function should create a new custom widget with the specified parent.

If the action is removed from a container widget then QWidgetAction::deleteWidget() is called with the previously created custom widget as argument. The default implementation hides the widget and deletes it using QObject::deleteLater().

If you have only one single custom widget then you can set it as default widget using setDefaultWidget(). That widget will then be used if the action is added to a QToolBar, or in general to an action container that supports QWidgetAction. If a QWidgetAction with only a default widget is added to two toolbars at the same time then the default widget is shown only in the first toolbar the action was added to. QWidgetAction takes over ownership of the default widget.

Note that it is up to the widget to activate the action, for example by reimplementing mouse event handlers and calling QAction::trigger().

Mac OS X: If you add a widget to a menu in the application's menu bar on Mac OS X, the widget will be added and it will function but with some limitations:

The widget is reparented away from the QMenu to the native menu view. If you show the menu in some other place (e.g. as a popup menu), the widget will not be there.
Focus/Keyboard handling of the widget is not possible.
Due to Apple's design, mouse tracking on the widget currently does not work.
Connecting the triggered() signal to a slot that opens a modal dialog will cause a crash in Mac OS X 10.4 (known bug acknowledged by Apple), a workaround is to use a QueuedConnection instead of a DirectConnection.

See also: QAction, QActionGroup, QWidget

Definition at line 57 of file qwidgetaction.h.

Constructors and Destructors

◆ QWidgetAction()

QWidgetAction::QWidgetAction ( QObject * parent )

explicit

Constructs an action with parent.

Definition at line 114 of file qwidgetaction.cpp.

     : QAction(*(new QWidgetActionPrivate), parent)
 {
 }

◆ ~QWidgetAction()

QWidgetAction::~QWidgetAction ( )

virtual

Destroys the object and frees allocated resources.

Definition at line 122 of file qwidgetaction.cpp.

 {
     Q_D(QWidgetAction);
     for (int i = 0; i < d->createdWidgets.count(); ++i)
         disconnect(d->createdWidgets.at(i), SIGNAL(destroyed(QObject*)),
                    this, SLOT(_q_widgetDestroyed(QObject*)));
     QList<QWidget *> widgetsToDelete = d->createdWidgets;
     d->createdWidgets.clear();
     qDeleteAll(widgetsToDelete);
     delete d->defaultWidget;
 }

Functions

◆ createdWidgets()

QList< QWidget * > QWidgetAction::createdWidgets ( ) const

protected

Returns the list of widgets that have been using createWidget() and are currently in use by widgets the action has been added to.

Definition at line 280 of file qwidgetaction.cpp.

 {
     Q_D(const QWidgetAction);
     return d->createdWidgets;
 }

◆ createWidget()

QWidget * QWidgetAction::createWidget ( QWidget * parent )

protectedvirtual

This function is called whenever the action is added to a container widget that supports custom widgets.

If you don't want a custom widget to be used as representation of the action in the specified parent widget then 0 should be returned.

See also: deleteWidget()

Definition at line 255 of file qwidgetaction.cpp.

Referenced by requestWidget().

 {
     Q_UNUSED(parent)
     return 0;
 }

◆ defaultWidget()

QWidget * QWidgetAction::defaultWidget ( ) const

Returns the default widget.

Definition at line 162 of file qwidgetaction.cpp.

Referenced by defaultWidgetAction().

 {
     Q_D(const QWidgetAction);
     return d->defaultWidget;
 }

◆ deleteWidget()

void QWidgetAction::deleteWidget ( QWidget * widget )

protectedvirtual

This function is called whenever the action is removed from a container widget that displays the action using a custom widget previously created using createWidget().

The default implementation hides the widget and schedules it for deletion using QObject::deleteLater().

See also: createWidget()

Definition at line 270 of file qwidgetaction.cpp.

Referenced by releaseWidget().

 {
     widget->hide();
     widget->deleteLater();
 }

◆ event()

bool QWidgetAction::event ( QEvent * event )

protectedvirtual

Reimplemented Function

Reimplemented from QAction.

Definition at line 227 of file qwidgetaction.cpp.

 {
     Q_D(QWidgetAction);
     if (event->type() == QEvent::ActionChanged) {
         if (d->defaultWidget)
             d->defaultWidget->setEnabled(isEnabled());
         for (int i = 0; i < d->createdWidgets.count(); ++i)
             d->createdWidgets.at(i)->setEnabled(isEnabled());
     }
     return QAction::event(event);
 }

◆ eventFilter()

bool QWidgetAction::eventFilter	(	QObject *	obj,
		QEvent *	event
	)

protectedvirtual

Reimplemented Function

Reimplemented from QObject.

Definition at line 242 of file qwidgetaction.cpp.

 {
     return QAction::eventFilter(obj,event);
 }

◆ releaseWidget()

void QWidgetAction::releaseWidget ( QWidget * widget )

Releases the specified widget.

Container widgets that support actions call this function when a widget action is removed.

See also: requestWidget(), deleteWidget(), defaultWidget()

Definition at line 204 of file qwidgetaction.cpp.

Referenced by QToolBarLayout::takeAt(), and QMenu::~QMenu().

 {
     Q_D(QWidgetAction);
 
     if (widget == d->defaultWidget) {
         d->defaultWidget->hide();
         d->defaultWidget->setParent(0);
         d->defaultWidgetInUse = false;
         return;
     }
 
     if (!d->createdWidgets.contains(widget))
         return;
 
     disconnect(widget, SIGNAL(destroyed(QObject*)),
                this, SLOT(_q_widgetDestroyed(QObject*)));
     d->createdWidgets.removeAll(widget);
     deleteWidget(widget);
 }

◆ requestWidget()

QWidget * QWidgetAction::requestWidget ( QWidget * parent )

Returns a widget that represents the action, with the given parent.

Container widgets that support actions can call this function to request a widget as visual representation of the action.

See also: releaseWidget(), createWidget(), defaultWidget()

Definition at line 177 of file qwidgetaction.cpp.

 {
     Q_D(QWidgetAction);
 
     QWidget *w = createWidget(parent);
     if (!w) {
         if (d->defaultWidgetInUse || !d->defaultWidget)
             return 0;
         d->defaultWidget->setParent(parent);
         d->defaultWidgetInUse = true;
         return d->defaultWidget;
     }
 
     connect(w, SIGNAL(destroyed(QObject*)),
             this, SLOT(_q_widgetDestroyed(QObject*)));
     d->createdWidgets.append(w);
     return w;
 }

◆ setDefaultWidget()

void QWidgetAction::setDefaultWidget ( QWidget * widget )

Sets widget to be the default widget.

The ownership is transferred to QWidgetAction. Unless createWidget() is reimplemented by a subclass to return a new widget the default widget is used when a container widget requests a widget through requestWidget().

Definition at line 141 of file qwidgetaction.cpp.

Referenced by QToolBar::addWidget(), and QToolBar::insertWidget().

 {
     Q_D(QWidgetAction);
     if (widget == d->defaultWidget || d->defaultWidgetInUse)
         return;
     delete d->defaultWidget;
     d->defaultWidget = widget;
     if (!widget)
         return;
 
     setVisible(!(widget->isHidden() && widget->testAttribute(Qt::WA_WState_ExplicitShowHide)));
     d->defaultWidget->hide();
     d->defaultWidget->setParent(0);
     d->defaultWidgetInUse = false;
     if (!isEnabled())
         d->defaultWidget->setEnabled(false);
 }

Friends and Related Functions

◆ QToolBar

friend class QToolBar

friend

Definition at line 82 of file qwidgetaction.h.

The documentation for this class was generated from the following files:

/src/gui/kernel/qwidgetaction.h
/src/gui/kernel/qwidgetaction.cpp

Public Functions

Protected Functions

Friends

Additional Inherited Members

Detailed Description

Constructors and Destructors

◆ QWidgetAction()

◆ ~QWidgetAction()

Functions

◆ createdWidgets()

◆ createWidget()

◆ defaultWidget()

◆ deleteWidget()

◆ event()

◆ eventFilter()

◆ releaseWidget()

◆ requestWidget()

◆ setDefaultWidget()

Friends and Related Functions

◆ QToolBar