From 3127a7be81a2a74aa0471b49e31dc8c4471393ee Mon Sep 17 00:00:00 2001
From: Rob Scheepmaker <r.scheepmaker@student.utwente.nl>
Date: Mon, 25 Aug 2008 23:46:00 +0000
Subject: [PATCH] Add some much needed apidox to PopupApplet.

svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=852548
---
 popupapplet.h | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/popupapplet.h b/popupapplet.h
index 0bc1429bd..c77446c2f 100644
--- a/popupapplet.h
+++ b/popupapplet.h
@@ -33,6 +33,18 @@ class Dialog;
 class Icon;
 class PopupAppletPrivate;
 
+/**
+ * Allows applets to automatically 'collapse' into an icon when put in an panel, and is a convenient
+ * base class for any applet that wishes to use extenders.
+ * Applets that subclass this class should implement either widget() or graphicsWidget() to return a
+ * widget that will be displayed in the applet if the applet is in a Planar or MediaCenter form
+ * factor. If the applet is put in a panel, an icon will be displayed instead, which shows the
+ * widget in a popup when clicked.
+ * If you use this class as a base class for your extender using applet, you should implement
+ * graphicsWidget() to return extender(), and connect the extenders geometryChanged() signal to the
+ * widgetGeometryChanged() slot.
+ */
+
 class PLASMA_EXPORT PopupApplet : public Plasma::Applet
 {
     Q_OBJECT
@@ -40,17 +52,52 @@ public:
     PopupApplet(QObject *parent, const QVariantList &args);
     ~PopupApplet();
 
+    /**
+     * @arg icon the icon that has to be displayed when the applet is in a panel.
+     */
     void setIcon(const QIcon &icon);
+
+    /**
+     * @arg icon the icon that has to be displayed when the applet is in a panel.
+     */
     void setIcon(const QString &iconName);
+
+    /**
+     * @return the icon that is displayed when the applet is in a panel.
+     */
     QIcon icon() const;
 
+    /**
+     * Implement either this function or graphicsWidget.
+     * @return the widget that will get shown in either a layout in the applet, or in a Dialog,
+     * depending on the form factor of the applet.
+     */
     virtual QWidget *widget();
+
+    /**
+     * Implement either this function or widget.
+     * @return the widget that will get shown in either a layout in the applet, or in a Dialog,
+     * depending on the form factor of the applet.
+     */
     virtual QGraphicsWidget *graphicsWidget();
 
+    /**
+     * Shows the dialog showing the widget if the applet is in a panel.
+     * @arg displayTime the time in ms that the popup should be displayed, defaults to 0 which means
+     * always (until the user closes it again, that is).
+     */
     void showPopup(uint displayTime = 0);
 
 public Q_SLOTS:
+    /**
+     * Hides the popup.
+     */
     void hidePopup();
+
+    /**
+     * Notify PopupApplet that the geometry of the graphicsWidget has changed. When you use an
+     * extender you'll want to connect the extender's geometryChanged() signal to this slot.
+     */
     void widgetGeometryChanged();
 
 protected: