| -rw-r--r-- | noncore/graphics/opie-eye/lib/oimagezoomer.cpp | 90 | ||||
| -rw-r--r-- | noncore/graphics/opie-eye/lib/oimagezoomer.h | 84 |
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 @@ -6,57 +6,147 @@ #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 ); 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 @@ -10,18 +10,35 @@ 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 ); @@ -35,31 +52,82 @@ public slots: 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 ) ); } } } |