1/* This file is part of the KDE libraries
2 Copyright (C) 2000 Carsten Pfeiffer <pfeiffer@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KPUSHBUTTON_H
21#define KPUSHBUTTON_H
22
23#include <QtGui/QPushButton>
24
25#include <kstandardguiitem.h>
26
27class QDrag;
28class QMenu;
29class KIcon;
30
31namespace KAuth {
32 class Action;
33}
34
35/**
36 * @brief A QPushButton with drag-support and KGuiItem support
37 *
38 * This is nothing but a QPushButton with drag-support and KGuiItem support.
39 * You must call #setDragEnabled (true) and override the virtual method
40 * dragObject() to specify the QDragObject to be used.
41 *
42 * \image html kpushbutton.png "KDE Push Button"
43 *
44 * @author Carsten Pfeiffer <pfeiffer@kde.org>
45 */
46class KDEUI_EXPORT KPushButton : public QPushButton
47{
48 Q_OBJECT
49 Q_PROPERTY(bool isDragEnabled READ isDragEnabled WRITE setDragEnabled)
50
51public:
52
53 /**
54 * Default constructor.
55 */
56 explicit KPushButton( QWidget *parent = 0 );
57
58 /**
59 * Constructor, that sets the button-text to @p text
60 */
61 explicit KPushButton( const QString &text, QWidget *parent = 0 );
62
63 /**
64 * Constructor, that sets an icon and the button-text to @p text
65 */
66 KPushButton( const KIcon &icon, const QString &text, QWidget *parent = 0 );
67
68 /**
69 * Constructor that takes a KGuiItem for the text, the icon, the tooltip
70 * and the what's this help
71 */
72 explicit KPushButton( const KGuiItem &item, QWidget *parent = 0 );
73
74 /**
75 * Destructs the button.
76 */
77 ~KPushButton();
78
79 /**
80 * Enables/disables drag-support. Default is disabled.
81 */
82 void setDragEnabled( bool enable );
83
84 /**
85 * @returns if drag support is enabled or not.
86 */
87 bool isDragEnabled() const;
88
89 /**
90 * Sets the KGuiItem for this button.
91 */
92 void setGuiItem( const KGuiItem& item );
93
94 /**
95 * Sets the standard KGuiItem for this button.
96 */
97 void setGuiItem( KStandardGuiItem::StandardItem item );
98
99 /**
100 * Reads the standard KGuiItem for this button.
101 */
102 KStandardGuiItem::StandardItem guiItem() const;
103
104 /**
105 * Sets the Icon Set for this button. It also takes into account the
106 * KGlobalSettings::showIconsOnPushButtons() setting.
107 */
108 void setIcon( const KIcon &icon );
109
110 /**
111 * Sets the pixmap for this button. This one exists mostly for usage in Qt designer.
112 */
113 void setIcon( const QIcon &pix );
114
115 /**
116 * Sets the text of the button
117 */
118 void setText( const QString &text );
119
120 /**
121 * Sets a delayed popup menu
122 * for consistency, since menu() isn't virtual
123 */
124 void setDelayedMenu(QMenu *delayed_menu);
125
126 /**
127 * returns a delayed popup menu
128 * since menu() isn't virtual
129 */
130 QMenu *delayedMenu();
131
132 /**
133 * Reimplemented to add arrow for delayed menu
134 * @since 4.4
135 */
136 virtual QSize sizeHint() const;
137
138 /**
139 * Returns the action object associated with this button, or 0 if it does not have one
140 *
141 * @returns the KAuth::Action associated with this button.
142 */
143 KAuth::Action *authAction() const;
144
145 /**
146 * Sets the action object associated with this button
147 *
148 * By setting a KAuth::Action, this button will become associated with it, and
149 * whenever it gets clicked, it will trigger the authorization and execution process
150 * for the action. The signal activated will also be emitted whenever the button gets
151 * clicked and the action gets authorized. Pass 0 to this function to disassociate the button
152 *
153 * @param action the KAuth::Action to associate with this button.
154 */
155 void setAuthAction(KAuth::Action *action);
156
157 /**
158 * Sets the action object associated with this button
159 *
160 * Overloaded member to allow creating the action by name
161 *
162 * @param actionName the name of the action to associate
163 */
164 void setAuthAction(const QString &actionName);
165
166protected:
167 /**
168 * Reimplement this and return the QDrag object that should be used
169 * for the drag. Remember to give it "this" as parent.
170 *
171 * Default implementation returns 0, so that no drag is initiated.
172 */
173 virtual QDrag * dragObject();
174
175 /**
176 * Reimplemented to add drag-support
177 */
178 virtual void mousePressEvent( QMouseEvent * );
179 /**
180 * Reimplemented to add drag-support
181 */
182 virtual void mouseMoveEvent( QMouseEvent * );
183
184 /**
185 * Reimplemented to add arrow for delayed menu
186 * @since 4.4
187 */
188 virtual void paintEvent( QPaintEvent * );
189
190 /**
191 * Starts a drag (dragCopy() by default) using dragObject()
192 */
193 virtual void startDrag();
194
195Q_SIGNALS:
196 /**
197 * Signal emitted when the button is triggered and authorized
198 *
199 * If the button needs authorization, whenever the user triggers it,
200 * the authorization process automatically begins.
201 * If it succeeds, this signal is emitted. The KAuth::Action object is provided for convenience
202 * if you have multiple Action objects, but of course it's always the same set with
203 * setAuthAction().
204 *
205 * WARNING: If your button needs authorization you should connect eventual slots processing
206 * stuff to this signal, and NOT clicked. Clicked will be emitted even if the user has not
207 * been authorized
208 *
209 * @param action The object set with setAuthAction()
210 */
211 void authorized(KAuth::Action *action);
212
213private:
214 /**
215 * Internal.
216 * Initialize the KPushButton instance
217 */
218 void init( const KGuiItem &item );
219
220private:
221 class KPushButtonPrivate;
222 KPushButtonPrivate * const d;
223
224 Q_PRIVATE_SLOT(d, void slotSettingsChanged( int ))
225 Q_PRIVATE_SLOT(d, void slotPressedInternal())
226 Q_PRIVATE_SLOT(d, void slotClickedInternal())
227 Q_PRIVATE_SLOT(d, void slotDelayedMenuTimeout())
228 Q_PRIVATE_SLOT(d, void authStatusChanged(int))
229};
230
231#endif // KPUSHBUTTON_H
232