From c8481d7f647ffdc08005f630263dfc05cfd7b230 Mon Sep 17 00:00:00 2001
From: zecke <zecke>
Date: Thu, 08 Apr 2004 16:54:02 +0000
Subject: Add API comments so we can now move it to OpieMM

---
(limited to 'noncore/graphics/opie-eye/lib/oimagezoomer.h')

diff --git a/noncore/graphics/opie-eye/lib/oimagezoomer.h b/noncore/graphics/opie-eye/lib/oimagezoomer.h
index 605416c..2516c61 100644
--- a/noncore/graphics/opie-eye/lib/oimagezoomer.h
+++ b/noncore/graphics/opie-eye/lib/oimagezoomer.h
@@ -13,12 +13,29 @@ namespace Opie {
 namespace MM   {
 
 /**
- * \brief small class to zoom over a widget
- *  This class takes a QImage or QPixmap
- *  and gets the size of the original image
- *  and provides depending of this widgets size
- *  a zoomer and emits the region which should
- *  be shown / zoomed to
+ * \brief small class to zoom over a Page
+ *
+ *  This class represents your page but smaller.
+ *  It can draw a Rect on top of an Image/Pixmap you supply
+ *  and you can allow the user easily zooming/moving
+ *  over your widget.
+ *  All you need to do is to supply a image/pixmap, the visible size
+ *  and the original image/pixmap size and the current visible top/left
+ *  position.
+ *
+ *  This Image works perfectly with QScrollView as you can connect
+ *  QScrollView::contentsMoving to setVisiblePoint slot and the zoomAreRel
+ *  to the QScrollView::scrollBy slot. Now you would only need to watch
+ *  the resize event anf give us the new information about QScrollView::viewport
+ *
+ *  You need to position and set the size of this widget! using setFixedSize() is quite
+ *  a good idea for this widget
+ *
+ * @see QScrollView
+ * @see QScrollView::viewport()
+ *
+ * @since 1.2
+ *
  */
 class OImageZoomer : public QFrame {
     Q_OBJECT
@@ -38,18 +55,60 @@ public slots:
     void setImage( const QPixmap& );
 
 signals:
-    void zoomAreaRel( int,int );
-    void zoomArea( int,int );
+    /**
+     * Relative movement in the coordinates of the viewport
+     * This signal can easily be connected to QScrollView::scrollBy.
+     * This signal is emitted from within the mouseMoveEvent of this widget
+     *
+     *
+     * @param x The way to move relative on the X-Axis
+     * @param y The way to move relative on the Y-Axis
+     *
+     * @see setVisiblePoint
+     * @see QScrollView::scrollBy
+     */
+    void zoomAreaRel( int x,int y);
+
+    /**
+     * Here you get absolute coordinates.
+     * This slot will be emitted from within the mouseMoveEvent of this widget.
+     * So you may not delete this widget
+     *
+     * @param x The absolute X Coordinate to scroll to.
+     * @param y The absolute Y Coordinate to scroll to.
+     *
+     */
+    void zoomArea( int x,int y);
 
 public:
+    /**
+     * make sure to call these if you reimplement
+     * @internal
+     */
     void resizeEvent( QResizeEvent* );
 
 protected:
+    /**
+     * make sure to call these if you reimplement
+     * @internal
+     */
     void drawContents( QPainter* p );
+
+    /**
+     * make sure to call these if you reimplememt
+     * @internal
+     */
     void mousePressEvent( QMouseEvent* ev );
+    /**
+     * make sure to call these if you reimplement
+     * @internal
+     */
     void mouseMoveEvent( QMouseEvent* ev );
 
 private:
+    /**
+     * @internal
+     */
     void init();
     QImage m_img;
     QSize m_imgSize, m_visSize;
@@ -57,6 +116,15 @@ private:
     int m_mouseX, m_mouseY;
 };
 
+/**
+ * This slot is present for convience. You can connect the
+ * QScrollView::contentsMoved to this slot and it calls the QPoint
+ * version for you
+ * This realtes to QScrollView::contentsX() and QScrollView::contentsY()
+ *
+ * @param x The top left x coordinate
+ * @param y The top left y coorisnate
+ */
 inline void OImageZoomer::setVisiblePoint( int x, int y ) {
     setVisiblePoint( QPoint( x, y ) );
 }
--
cgit v0.9.0.2