Add api doc comments + delete old stuff in applet

svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=833277

applet.cpp

@@ -435,55 +435,6 @@ QRect Applet::mapToView(const QGraphicsView *view, const QRectF &rect) const
 QPoint Applet::popupPosition(const QSize &s) const
 {
     return ToolTipManager::popupPosition(this,s);
-    /*QGraphicsView *v = view();
-    Q_ASSERT(v);
-
-    QPoint pos = v->mapFromScene(scenePos());
-    pos = v->mapToGlobal(pos);
-    //kDebug() << "==> position is" << scenePos() << v->mapFromScene(scenePos()) << pos;
-    Plasma::View *pv = dynamic_cast<Plasma::View *>(v);
-
-    Plasma::Location loc = Floating;
-    if (pv) {
-        loc = pv->containment()->location();
-    }
-
-    switch (loc) {
-    case BottomEdge:
-        pos = QPoint(pos.x(), pos.y() - s.height());
-        break;
-    case TopEdge:
-        pos = QPoint(pos.x(), pos.y() + (int)size().height());
-        break;
-    case LeftEdge:
-        pos = QPoint(pos.x() + (int)size().width(), pos.y());
-        break;
-    case RightEdge:
-        pos = QPoint(pos.x() - s.width(), pos.y());
-        break;
-    default:
-        if (pos.y() - s.height() > 0) {
-             pos = QPoint(pos.x(), pos.y() - s.height());
-        } else {
-             pos = QPoint(pos.x(), pos.y() + (int)size().height());
-        }
-    }
-
-    //are we out of screen?
-
-    QRect screenRect = QApplication::desktop()->screenGeometry(pv ? pv->containment()->screen() : -1);
-    //kDebug() << "==> rect for" << (pv ? pv->containment()->screen() : -1) << "is" << screenRect;
-
-    if (pos.rx() + s.width() > screenRect.right()) {
-        pos.rx() -= ((pos.rx() + s.width()) - screenRect.right());
-    }
-
-    if (pos.ry() + s.height() > screenRect.bottom()) {
-        pos.ry() -= ((pos.ry() + s.height()) - screenRect.bottom());
-    }
-    pos.rx() = qMax(0, pos.rx());
-
-    return pos;*/
 }
 
 void Applet::updateConstraints(Plasma::Constraints constraints)

tooltip_p.h

@@ -28,17 +28,12 @@
 #include <QString> // stack allocated
 #include <QGraphicsWidget>
 
-#include <plasma/tooltipmanager.h> //ToolTipData struct
+#include <plasma/tooltipmanager.h> //ToolTipContent struct
 
 namespace Plasma {
 
     class ToolTipPrivate;
 
-/**
-    @author Dan Meltzer
-*   A Singleton tooltip.  Before calling show it is necessary to
-*   call setLocation and setData
-*/
 class ToolTip : public QWidget
 {
     Q_OBJECT

tooltipmanager.cpp

@@ -308,7 +308,6 @@ QPoint ToolTipManager::popupPosition(const QGraphicsItem * item, const QSize &s)
     return pos;
 }
 
-//PRIVATE CLASS IMPLEMENTATION
 }
 
 #include "tooltipmanager.moc"

tooltipmanager.h

@@ -43,21 +43,25 @@ namespace Plasma
   class ToolTipManagerPrivate;
 
   /**
-  * @short The class to manage a tooltip on a plasma applet
+  * @short The class to manage tooltips on QGraphicsWidget in Plasma
   *
-  *	Manage tooltip on plasma applet, before using it you have to set information
+  *	Manage tooltips on QGraphicsWidget. First you have to register your widget by calling registerWidget on the ToolTipManager singleton. After this you have to set the content of the tooltip by calling setWidgetToolTipContent using the struct ToolTipContent. The tooltip manager unregister automatically the widget when it is destroyed but if you want to do it manually call unregisterWidget. If you use plasma's applets show/hide of tooltip is automatically manage but if you use custom QGraphicsWidget, please call showToolTip on you hoverEnterEvent or hideToolTip on you hoverLeaveEvent.
   */
   class PLASMA_EXPORT ToolTipManager  : public QObject
   {
       Q_OBJECT
   public:
+
+     /**
+      * Content of a tooltip
+      */
       struct ToolTipContent
       {
 	  ToolTipContent() : windowToPreview( 0 ) {}
-	  QString mainText; //Important information
-	  QString subText; //Elaborates on the Main Text
-	  QPixmap image; // Icon to show;
-	  WId windowToPreview; // Id of window to show preview
+	  QString mainText; /**Important information, e.g. the title*/
+	  QString subText; /** Elaborates on the Main Text */
+	  QPixmap image; /** Icon to show */
+	  WId windowToPreview; /** Id of a window if you want to show a preview */
       };
 
       /**
@@ -75,27 +79,75 @@ namespace Plasma
         * Default destructor.
         */
       ~ToolTipManager();
-
+      
+      /**
+      * Function to show a tooltip of a widget registered in the tooltip manager
+      * @param widget the widget on which the tooltip will be displayed
+      */
       void showToolTip(QGraphicsWidget *widget);
 
+      /**
+      * Function to know if a tooltip of a widget is displayed
+      * @param widget the desired widget
+      * @return true if te tooltip of the widget is currently displayed, otherwhise no
+      */
       bool isWidgetToolTipDisplayed(QGraphicsWidget *widget);
 
+      /**
+      * Function to launch a delayed hide of the current displayed tooltip
+      * @param widget the desired widget
+      */
       void delayedHideToolTip();
 
+      /**
+      * Function to hide the tooltip of the desired widget
+      * @param widget the desired widget
+      */
       void hideToolTip(QGraphicsWidget *widget);
 
+      /**
+      * Function to register a widget to the tooltip manager, after this a setWidgetToolTipContent
+      * must be called
+      * @param widget the desired widget
+      */
       void registerWidget(QGraphicsWidget *widget);
 
+      /**
+      * Function to unregister a widget in the tooltip manager, i.e. means that memory will be free
+      * @param widget the desired widget to delete
+      */
       void unregisterWidget(QGraphicsWidget *widget);
 
+      /**
+      * Function to set the content of a tooltip on a desired widget
+      * @param widget the desired widget
+      * @param data the content of the tooltip
+      */
       void setWidgetToolTipContent(QGraphicsWidget *widget,const ToolTipContent &data);
       
+      /**
+      * Function to know if widget has a tooltip registered in the tooltip manager
+      * @param widget the widget
+      * @return true if this widget has a tooltip
+      */
       bool widgetHasToolTip(QGraphicsWidget *widget);
       
+      /**
+      * Reccomended position for a popup window like a menu or a tooltip
+      * given its size
+      * @param s size of the popup
+      * @returns reccomended position
+      */
       static QPoint popupPosition(const QGraphicsItem * item, const QSize &s);
 
   private Q_SLOTS:
+    /**
+      * @internal called when the theme of plasma has change
+      */
     void themeUpdated();
+    /**
+      * @internal called when a widget inside the tooltip manager is deleted
+      */
     void onWidgetDestroyed(QObject * object);
 
   private: