Add API comments so we can now move it to OpieMM

2 files changed, 166 insertions, 8 deletions

diff --git a/noncore/graphics/opie-eye/lib/oimagezoomer.cpp b/noncore/graphics/opie-eye/lib/oimagezoomer.cpp
index ffa3c0c..4df5dcc 100644
--- a/noncore/graphics/opie-eye/lib/oimagezoomer.cpp
+++ b/noncore/graphics/opie-eye/lib/oimagezoomer.cpp
@@ -1,104 +1,194 @@
 #include "oimagezoomer.h"
 
 #include <qimage.h>
 #include <qpixmap.h>
 #include <qpainter.h>
 #include <qrect.h>
 #include <qpoint.h>
 #include <qsize.h>
 
 namespace Opie {
 namespace MM {
+
+/**
+ * \brief The most simple c'tor
+ * The main c'tor. You still need to set a QPixmap/QIMage,
+ *  setImageSize,setViewPortSize,setVisiblePoint
+ *
+ * @param parent The parent widget
+ * @param name A name for this widget
+ * @param fl The widget flags
+ *
+ */
 OImageZoomer::OImageZoomer( QWidget* parent,  const char* name,  WFlags fl )
     :  QFrame( parent, name, fl ) {
     init();
 }
 
+
+/**
+ * \brief This c'tor takes a QPixmap additional
+ *
+ * You initially set the QPixmap but you still need to provide
+ * the additional data to make this widget useful
+ *
+ * @param pix A Pixmap it'll be converted to a QImage later!
+ * @param par The parent widget
+ * @param name The name of this widget
+ * @param fl The widget flags
+ */
 OImageZoomer::OImageZoomer( const QPixmap& pix, QWidget* par, const char* name, WFlags fl )
     : QFrame( par, name, fl ) {
     init();
     setImage( pix );
 }
 
+
+/**
+ * \brief This c'tor takes a QImage instead
+ * You just provide a QImage which is saved. It behaves the same as the others.
+ *
+ * @param img A Image which will be used for the zoomer content
+ * @param par The  parent of the widget
+ * @param name The name of the widget
+ * @param fl The widgets flags
+ */
+OImageZoomer::OImageZoomer( const QImage& img, QWidget* par, const char* name,  WFlags fl)
+    : QFrame( par, name, fl ) {
+    init();
+    setImage( img );
+}
+
+
+/**
+ * \brief overloaded c'tor
+ *
+ * This differs only in the arguments it takes
+ *
+ *
+ * @param pSize The size of the Page you show
+ * @param vSize The size of the viewport. The size of the visible part of the widget
+ * @param par The parent of the widget
+ * @param name The name
+ * @param fl The window flags
+ */
 OImageZoomer::OImageZoomer( const QSize& pSize, const QSize& vSize, QWidget* par,
                             const char* name, WFlags fl )
     : QFrame( par, name, fl ), m_imgSize( pSize ),m_visSize( vSize ) {
     init();
 }
 
+/**
+ * d'tor
+ */
 OImageZoomer::~OImageZoomer() {
 
 }
 
 void OImageZoomer::init() {
     setFrameStyle( Panel | Sunken );
 }
 
+
+/**
+ * \brief set the page/image size
+ * Tell us the QSize of the Data you show to the user. We need this
+ * to do the calculations
+ *
+ * @param size The size of the stuff you want to zoom on
+ */
 void OImageZoomer::setImageSize( const QSize& size ) {
     m_imgSize = size;
     repaint();
 }
+
+/**
+ * \brief Set the size of the viewport
+ * Tell us the QSize of the viewport. The viewport is the part
+ * of the widget which is exposed on the screen
+ *
+ * @param size Te size of the viewport
+ *
+ * @see QScrollView::viewport()
+ */
 void OImageZoomer::setViewPortSize( const QSize& size ) {
     m_visSize = size;
     repaint();
 }
 
+/**
+ * \brief the point in the topleft corner which is currently visible
+ * Set the visible point. This most of the times relate to QScrollView::contentsX()
+ * and QScrollView::contentsY()
+ *
+ * @see setVisiblePoint(int,int)
+ */
 void OImageZoomer::setVisiblePoint( const QPoint& pt ) {
     m_visPt = pt;
     repaint();
 }
 
+
+/**
+ * Set the Image. The image will be resized on resizeEvent
+ * and it'll set the QPixmap background
+ *
+ * @param img The image will be stored internally and used as the background
+ */
 void OImageZoomer::setImage( const QImage& img) {
     m_img = img;
     resizeEvent( 0 );
     repaint();
 }
 
+/**
+ * overloaded function it calls the QImage version
+ */
 void OImageZoomer::setImage( const QPixmap& pix) {
     setImage( pix.convertToImage() );
 }
 
 void OImageZoomer::resizeEvent( QResizeEvent* ev ) {
     QFrame::resizeEvent( ev );
     setBackgroundOrigin(  QWidget::WidgetOrigin );
     // TODO Qt3 use PalettePixmap and use size
     QPixmap pix; pix.convertFromImage( m_img.smoothScale( size().width(), size().height() ) );
     setBackgroundPixmap( pix);
 }
 
 void OImageZoomer::drawContents( QPainter* p ) {
     /*
      * if the page size
      */
     if ( m_imgSize.isEmpty() )
         return;
 
    /*
     * paint a red rect which represents the visible size
     *
     * We need to recalculate x,y and width and height of the
     * rect. So image size relates to contentRect
     *
     */
     QRect c( contentsRect() );
     p->setPen( Qt::red );
 
     int len = m_imgSize.width();
     int x = (c.width()*m_visPt.x())/len        + c.x();
     int w = (c.width()*m_visSize.width() )/len + c.x();
     if ( w > c.width() ) w = c.width();
 
     len = m_imgSize.height();
     int y = (c.height()*m_visPt.y() )/len          + c.y();
     int h = (c.height()*m_visSize.height() )/len + c.y();
     if ( h > c.height() ) h = c.height();
 
     p->drawRect( x, y, w, h );
 }
 
 void OImageZoomer::mousePressEvent( QMouseEvent*  ) {
     m_mouseX = m_mouseY = -1;
 }
 
 void OImageZoomer::mouseMoveEvent( QMouseEvent* ev ) {
     int mx, my;
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
@@ -1,66 +1,134 @@
 #ifndef OPIE_ODP_IMAGE_ZOOMER_H
 #define OPIE_ODP_IMAGE_ZOOMER_H
 
 #include <qframe.h>
 #include <qimage.h>
 
 class QPixmap;
 class QRect;
 class QPoint;
 
 
 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
 public:
     OImageZoomer( QWidget* parent = 0, const char* name = 0, WFlags fl = 0 );
     OImageZoomer( const QPixmap&,QWidget* parent = 0, const char* name = 0,  WFlags fl = 0 );
     OImageZoomer( const QImage&, QWidget* parent = 0, const char* name= 0, WFlags fl = 0 );
     OImageZoomer( const QSize&, const QSize&, QWidget* par, const char*, WFlags fl );
     ~OImageZoomer();
 
 public slots:
     void setImageSize( const QSize& );
     void setViewPortSize( const QSize& );
     void setVisiblePoint( const QPoint& );
     void setVisiblePoint( int x, int y );
     void setImage( const QImage& );
     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;
     QPoint m_visPt;
     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 ) );
 }
 
 }
 }
 #endif