File indexing completed on 2024-04-28 15:29:10
0001 // -*- c++ -*- 0002 /* 0003 SPDX-FileCopyrightText: 2001-2006 Richard Moore <rich@kde.org> 0004 SPDX-FileCopyrightText: 2004-2005 Sascha Cunz <sascha.cunz@tiscali.de> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 0009 #ifndef KPASSIVEPOPUP_H 0010 #define KPASSIVEPOPUP_H 0011 0012 #include <knotifications_export.h> 0013 0014 #ifdef QT_WIDGETS_LIB 0015 #include <QFrame> 0016 #endif 0017 0018 #include <memory> 0019 0020 class QSystemTrayIcon; 0021 0022 #if KNOTIFICATIONS_ENABLE_DEPRECATED_SINCE(5, 79) 0023 /** 0024 * @class KPassivePopup kpassivepopup.h KPassivePopup 0025 * 0026 * @short A dialog-like popup that displays messages without interrupting the user. 0027 * 0028 * The simplest uses of KPassivePopup are by using the various message() static 0029 * methods. The position the popup appears at depends on the type of the parent window: 0030 * 0031 * @li Normal Windows: The popup is placed adjacent to the icon of the window. 0032 * @li System Tray Windows: The popup is placed adjacent to the system tray window itself. 0033 * @li Skip Taskbar Windows: The popup is placed adjacent to the window 0034 * itself if it is visible, and at the edge of the desktop otherwise. 0035 * 0036 * You also have the option of calling show with a QPoint as a parameter that 0037 * removes the automatic placing of KPassivePopup and shows it in the point you want. 0038 * 0039 * The most basic use of KPassivePopup displays a popup containing a piece of text: 0040 * \code 0041 * KPassivePopup::message( "This is the message", this ); 0042 * \endcode 0043 * We can create popups with titles and icons too, as this example shows: 0044 * \code 0045 * QPixmap px; 0046 * px.load( "hi32-app-logtracker.png" ); 0047 * KPassivePopup::message( "Some title", "This is the main text", px, this ); 0048 * \endcode 0049 * This screenshot shows a popup with both a caption and a main text which is 0050 * being displayed next to the toolbar icon of the window that triggered it: 0051 * \image html kpassivepopup.png "A passive popup" 0052 * 0053 * For more control over the popup, you can use the setView(QWidget *) method 0054 * to create a custom popup. 0055 * \code 0056 * KPassivePopup *pop = new KPassivePopup( parent ); 0057 * 0058 * QWidget* content = new QWidget( pop ); 0059 * QVBoxLayout* vBox = new QVBoxLayout( content ); 0060 * QLabel* label = new QLabel( "<b>Isn't this great?</b>", content ); 0061 * vBox->addWidget( label ); 0062 * 0063 * QPushButton* btnYes = new QPushButton( "Yes", content ); 0064 * QPushButton* btnNo = new QPushButton( "No", content ); 0065 * 0066 * QHBoxLayout* hBox = new QHBoxLayout( content ); 0067 * hBox->addWidget( btnYes ); 0068 * hBox->addWidget( btnNo ); 0069 * 0070 * vBox->addLayout( vBox ); 0071 * 0072 * pop->setView( content ); 0073 * pop->show(); 0074 * \endcode 0075 * 0076 * @deprecated since 5.79, use KNotification 0077 * 0078 * @author Richard Moore, rich@kde.org 0079 * @author Sascha Cunz, sascha.cunz@tiscali.de 0080 */ 0081 class KNOTIFICATIONS_EXPORT KPassivePopup : public QFrame 0082 { 0083 Q_OBJECT 0084 Q_PROPERTY(bool autoDelete READ autoDelete WRITE setAutoDelete) 0085 Q_PROPERTY(int timeout READ timeout WRITE setTimeout) 0086 0087 public: 0088 /** 0089 * Styles that a KPassivePopup can have. 0090 */ 0091 enum PopupStyle { 0092 Boxed, ///< Information will appear in a framed box (default) 0093 Balloon, ///< Information will appear in a comic-alike balloon 0094 }; 0095 0096 /** 0097 * Creates a popup for the specified widget. 0098 * @deprecated since 5.79, use KNotification 0099 */ 0100 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0101 explicit KPassivePopup(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()); 0102 0103 /** 0104 * Creates a popup for the specified window. 0105 */ 0106 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0107 explicit KPassivePopup(WId parent); 0108 0109 /** 0110 * Cleans up. 0111 */ 0112 ~KPassivePopup() override; 0113 0114 /** 0115 * Sets the main view to be the specified widget (which must be a child of the popup). 0116 */ 0117 void setView(QWidget *child); 0118 0119 /** 0120 * Creates a standard view then calls setView(QWidget*) . 0121 */ 0122 void setView(const QString &caption, const QString &text = QString()); 0123 0124 /** 0125 * Creates a standard view then calls setView(QWidget*) . 0126 */ 0127 virtual void setView(const QString &caption, const QString &text, const QPixmap &icon); 0128 0129 /** 0130 * Returns a widget that is used as standard view if one of the 0131 * setView() methods taking the QString arguments is used. 0132 * You can use the returned widget to customize the passivepopup while 0133 * keeping the look similar to the "standard" passivepopups. 0134 * 0135 * After customizing the widget, pass it to setView( QWidget* ) 0136 * 0137 * @param caption The window caption (title) on the popup 0138 * @param text The text for the popup 0139 * @param icon The icon to use for the popup 0140 * @param parent The parent widget used for the returned widget. If left 0, 0141 * then "this", i.e. the passive popup object will be used. 0142 * 0143 * @return a QWidget containing the given arguments, looking like the 0144 * standard passivepopups. The returned widget contains a QVBoxLayout, 0145 * which is accessible through layout(). 0146 * @see setView( QWidget * ) 0147 * @see setView( const QString&, const QString& ) 0148 * @see setView( const QString&, const QString&, const QPixmap& ) 0149 */ 0150 QWidget *standardView(const QString &caption, const QString &text, const QPixmap &icon, QWidget *parent = nullptr); 0151 0152 /** 0153 * Returns the main view. 0154 */ 0155 QWidget *view() const; 0156 0157 /** 0158 * Returns the delay before the popup is removed automatically. 0159 */ 0160 int timeout() const; 0161 0162 /** 0163 * Sets whether the popup will be deleted when it is hidden. 0164 * 0165 * The default is false (unless created by one of the static 0166 * message() overloads). 0167 */ 0168 virtual void setAutoDelete(bool autoDelete); 0169 0170 /** 0171 * Returns whether the popup will be deleted when it is hidden. 0172 * 0173 * @see setAutoDelete 0174 */ 0175 bool autoDelete() const; 0176 0177 /** 0178 * Returns the position to which this popup is anchored. 0179 */ 0180 QPoint anchor() const; 0181 0182 /** 0183 * Sets the anchor of this popup. 0184 * 0185 * The popup is placed near to the anchor. 0186 */ 0187 void setAnchor(const QPoint &anchor); 0188 0189 /** 0190 * Convenience method that displays popup with the specified message beside the 0191 * icon of the specified widget. 0192 * Note that the returned object is destroyed when it is hidden. 0193 * @see setAutoDelete 0194 * @deprecated since 5.79, use KNotification 0195 */ 0196 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0197 static KPassivePopup *message(const QString &text, QWidget *parent, const QPoint &p = QPoint()); 0198 0199 /** 0200 * Convenience method that displays popup with the specified message beside the 0201 * icon of the specified QSystemTrayIcon. 0202 * Note that the returned object is destroyed when it is hidden. 0203 * @see setAutoDelete 0204 * @deprecated since 5.79, use KNotification 0205 */ 0206 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0207 static KPassivePopup *message(const QString &text, QSystemTrayIcon *parent); 0208 0209 /** 0210 * Convenience method that displays popup with the specified caption and message 0211 * beside the icon of the specified widget. 0212 * Note that the returned object is destroyed when it is hidden. 0213 * @see setAutoDelete 0214 * @deprecated since 5.79, use KNotification 0215 */ 0216 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0217 static KPassivePopup *message(const QString &caption, const QString &text, QWidget *parent, const QPoint &p = QPoint()); 0218 0219 /** 0220 * Convenience method that displays popup with the specified caption and message 0221 * beside the icon of the specified QSystemTrayIcon. 0222 * Note that the returned object is destroyed when it is hidden. 0223 * @see setAutoDelete 0224 * @deprecated since 5.79, use KNotification 0225 */ 0226 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0227 static KPassivePopup *message(const QString &caption, const QString &text, QSystemTrayIcon *parent); 0228 0229 /** 0230 * Convenience method that displays popup with the specified icon, caption and 0231 * message beside the icon of the specified widget. 0232 * Note that the returned object is destroyed when it is hidden. 0233 * @see setAutoDelete 0234 * @deprecated since 5.79, use KNotification 0235 */ 0236 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0237 static KPassivePopup * 0238 message(const QString &caption, const QString &text, const QPixmap &icon, QWidget *parent, int timeout = -1, const QPoint &p = QPoint()); 0239 0240 /** 0241 * Convenience method that displays popup with the specified icon, caption and 0242 * message beside the icon of the specified QSystemTrayIcon. 0243 * Note that the returned object is destroyed when it is hidden. 0244 * @see setAutoDelete 0245 * @deprecated since 5.79, use KNotification 0246 */ 0247 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0248 static KPassivePopup *message(const QString &caption, const QString &text, const QPixmap &icon, QSystemTrayIcon *parent, int timeout = -1); 0249 0250 /** 0251 * Convenience method that displays popup with the specified icon, caption and 0252 * message beside the icon of the specified window. 0253 * Note that the returned object is destroyed when it is hidden. 0254 * @see setAutoDelete 0255 * @deprecated since 5.79, use KNotification 0256 */ 0257 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0258 static KPassivePopup *message(const QString &caption, const QString &text, const QPixmap &icon, WId parent, int timeout = -1, const QPoint &p = QPoint()); 0259 0260 /** 0261 * Convenience method that displays popup with the specified popup-style and message beside the 0262 * icon of the specified widget. 0263 * Note that the returned object is destroyed when it is hidden. 0264 * @see setAutoDelete 0265 * @deprecated since 5.79, use KNotification 0266 */ 0267 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0268 static KPassivePopup *message(int popupStyle, const QString &text, QWidget *parent, const QPoint &p = QPoint()); 0269 0270 /** 0271 * Convenience method that displays popup with the specified popup-style and message beside the 0272 * icon of the specified QSystemTrayIcon. 0273 * Note that the returned object is destroyed when it is hidden. 0274 * @see setAutoDelete 0275 * @deprecated since 5.79, use KNotification 0276 */ 0277 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0278 static KPassivePopup *message(int popupStyle, const QString &text, QSystemTrayIcon *parent); 0279 0280 /** 0281 * Convenience method that displays popup with the specified popup-style, caption and message 0282 * beside the icon of the specified QSystemTrayIcon. 0283 * Note that the returned object is destroyed when it is hidden. 0284 * @see setAutoDelete 0285 * @deprecated since 5.79, use KNotification 0286 */ 0287 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0288 static KPassivePopup *message(int popupStyle, const QString &caption, const QString &text, QSystemTrayIcon *parent); 0289 0290 /** 0291 * Convenience method that displays popup with the specified popup-style, caption and message 0292 * beside the icon of the specified widget. 0293 * Note that the returned object is destroyed when it is hidden. 0294 * @see setAutoDelete 0295 * @deprecated since 5.79, use KNotification 0296 */ 0297 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0298 static KPassivePopup *message(int popupStyle, const QString &caption, const QString &text, QWidget *parent, const QPoint &p = QPoint()); 0299 0300 /** 0301 * Convenience method that displays popup with the specified popup-style, icon, caption and 0302 * message beside the icon of the specified widget. 0303 * Note that the returned object is destroyed when it is hidden. 0304 * @see setAutoDelete 0305 * @deprecated since 5.79, use KNotification 0306 */ 0307 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0308 static KPassivePopup * 0309 message(int popupStyle, const QString &caption, const QString &text, const QPixmap &icon, QWidget *parent, int timeout = -1, const QPoint &p = QPoint()); 0310 0311 /** 0312 * Convenience method that displays popup with the specified popup-style, icon, caption and 0313 * message beside the icon of the specified QSystemTrayIcon. 0314 * Note that the returned object is destroyed when it is hidden. 0315 * @see setAutoDelete 0316 * @deprecated since 5.79, use KNotification 0317 */ 0318 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0319 static KPassivePopup *message(int popupStyle, const QString &caption, const QString &text, const QPixmap &icon, QSystemTrayIcon *parent, int timeout = -1); 0320 0321 /** 0322 * Convenience method that displays popup with the specified popup-style, icon, caption and 0323 * message beside the icon of the specified window. 0324 * Note that the returned object is destroyed when it is hidden. 0325 * @see setAutoDelete 0326 * @deprecated since 5.79, use KNotification 0327 */ 0328 KNOTIFICATIONS_DEPRECATED_VERSION(5, 79, "Use KNotification") 0329 static KPassivePopup * 0330 message(int popupStyle, const QString &caption, const QString &text, const QPixmap &icon, WId parent, int timeout = -1, const QPoint &p = QPoint()); 0331 0332 // we create an overloaded version of show() 0333 using QFrame::show; 0334 0335 public Q_SLOTS: 0336 /** 0337 * Sets the delay for the popup is removed automatically. Setting the delay to 0 0338 * disables the timeout, if you're doing this, you may want to connect the 0339 * clicked() signal to the hide() slot. 0340 * Setting the delay to -1 makes it use the default value. 0341 * 0342 * @see timeout 0343 */ 0344 void setTimeout(int delay); 0345 0346 /** 0347 * Sets the visual appearance of the popup. 0348 * @see PopupStyle 0349 */ 0350 void setPopupStyle(int popupstyle); 0351 0352 /** 0353 * Shows the popup in the given point 0354 */ 0355 void show(const QPoint &p); 0356 0357 /** @reimp */ 0358 void setVisible(bool visible) override; 0359 0360 Q_SIGNALS: 0361 /** 0362 * Emitted when the popup is clicked. 0363 */ 0364 void clicked(); // clazy:exclude=overloaded-signal 0365 0366 /** 0367 * Emitted when the popup is clicked. 0368 */ 0369 void clicked(const QPoint &pos); // clazy:exclude=overloaded-signal 0370 0371 protected: 0372 /** 0373 * Positions the popup. 0374 * 0375 * The default implementation attempts to place it by the taskbar 0376 * entry; failing that it places it by the window of the associated 0377 * widget; failing that it places it at the location given by 0378 * defaultLocation(). 0379 * 0380 * @see moveNear() 0381 */ 0382 virtual void positionSelf(); 0383 0384 /** 0385 * Returns a default location for popups when a better placement 0386 * cannot be found. 0387 * 0388 * The default implementation returns the top-left corner of the 0389 * available work area of the desktop (ie: minus panels, etc). 0390 */ 0391 virtual QPoint defaultLocation() const; 0392 0393 /** 0394 * Moves the popup to be adjacent to @p target. 0395 * 0396 * The popup will be placed adjacent to, but outside of, @p target, 0397 * without going off the current desktop. 0398 * 0399 * Reimplementations of positionSelf() can use this to actually 0400 * position the popup. 0401 */ 0402 void moveNear(const QRect &target); 0403 0404 /** @reimp */ 0405 void hideEvent(QHideEvent *) override; 0406 0407 /** @reimp */ 0408 void mouseReleaseEvent(QMouseEvent *e) override; 0409 0410 /** @reimp */ 0411 void paintEvent(QPaintEvent *pe) override; 0412 0413 private: 0414 /* @internal */ 0415 class Private; 0416 std::unique_ptr<Private> const d; 0417 }; 0418 0419 #endif 0420 0421 #endif // KPASSIVEPOPUP_H 0422 0423 // Local Variables: 0424 // End: