workspace/kdm/kfrontend/themer/kdmitem.h

   1 /*
   2  *  Copyright (C) 2003 by Unai Garro <ugarro@users.sourceforge.net>
   3  *  Copyright (C) 2004 by Enrico Ros <rosenric@dei.unipd.it>
   4  *  Copyright (C) 2004 by Stephan Kulow <coolo@kde.org>
   5  *  Copyright (C) 2004 by Oswald Buddenhagen <ossi@kde.org>
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License as published by
   9  *  the Free Software Foundation; either version 2 of the License, or
  10  *  (at your option) any later version.
  11  *
  12  *  This program is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *  GNU General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU General Public License
  18  *  along with this program; if not, write to the Free Software
  19  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  20  */
  21
  22 #ifndef KDMITEM_H
  23 #define KDMITEM_H
  24
  25 #include "parse.h"
  26
  27 #include <QDomNode>
  28 #include <QObject>
  29 #include <QStack>
  30
  31 class KdmItem;
  32 class KdmLayoutBox;
  33 class KdmLayoutFixed;
  34 class KdmThemer;
  35
  36 class QPainter;
  37
  38 struct SizeHint {
  39         QSize min, opt, max;
  40 };
  41
  42 /** class KdmItem
  43  * @short Base class for every kdmthemes' element.
  44  *
  45  * This class provides methods for arranging it and its children to the
  46  * screen (see note below), painting the whole area or a sub-region using
  47  * an opened painter, handling mouse events or events in general dispatching
  48  * them to children and sending some signals to the root (for example on
  49  * mouse click).
  50  *
  51  * KdmItem sits in a hierarchical top to bottom tree with signals that
  52  * traverse the tree back from leafs (or inner nodes) to the root.
  53  *
  54  * To implement a KdmItem only a few virtual protected methods must be
  55  * reimplemented, other virtual functions are there for convenience only -
  56  * the default implementation should satisfy your needs.
  57  */
  58
  59 /**
  60  * A note on layouting - how does it work?
  61  *  - setgeometry is called by parent (passing the new geometry)
  62  *    - item changes its geometry
  63  *    - if item embeds a widget, reposition it too
  64  *    - call children's box manager. box->update( my geom )
  65  *      - sum up the whole space taken by children (via *hint calls) if
  66  *        needed for box width / height computation. note that the computed
  67  *        geometry should be equal or similar to parent's geometry.
  68  *      - pad the rectangle bounding box' contents
  69  *      - for every child
  70  *        - if vertical
  71  *          ( use a top-to-bottom insertion, spacing insertion lines by
  72  *            children's individual height )
  73  *          - set up a zero height Parent (placed at the insertion line's
  74  *            position) and get Geom = child->placementHint( p )
  75  *          - set up child's Size using Parent's width and Geom's height.
  76  *          - call to child->setGeometry( Parent.topLeft, Size )
  77  *        - if horizontal
  78  *          - flows like the vertical one but uses a left-to-right insertion
  79  *            and insertion entry points are vertical lines
  80  *    - call to children's fix manager. fixed->update( my geom )
  81  *      - for every child
  82  *          - S = get child's geometry hint (and we'll give item the whole
  83  *            space it needs, without constraints)
  84  *          - call to child->setGeometry( S )
  85  *    - TODO: send a selective redraw signal also merging children's areas
  86  */
  87
  88 class KdmItem : public QObject {
  89         Q_OBJECT
  90
  91 public:
  92         /**
  93          * Item constructor and destructor
  94          */
  95         KdmItem( QObject *parent, const QDomNode &node );
  96         virtual ~KdmItem();
  97
  98         /**
  99          * Fixup the geometry of an item and its children (even if fixed
 100          * or boxed ones). Note that this will generate repaint signals
 101          * when needed. The default implementation should fit all needs.
 102          */
 103         virtual void setGeometry( QStack<QSize> &parentSizes, const QRect &newGeometry, bool force );
 104
 105         /**
 106          * Paint the item and its children using the given painter.
 107          * This is the compositing core function. It buffers paint operations
 108          * to speed up rendering of dynamic objects.
 109          */
 110         void paint( QPainter *painter, const QRect &boundaries, bool background );
 111
 112         /**
 113          * Update representation of contents and repaint.
 114          */
 115         virtual void update();
 116
 117         /**
 118          * Handle mouse motion and dispatch events to children. This
 119          * leads to items prelighting, activation() on click and more..
 120          */
 121         void mouseEvent( int x, int y, bool pressed = false, bool released = false );
 122
 123         /**
 124          * Similar to sizeHint(..), this returns the area of the item
 125          * given the @p parentGeometry. The default implementation
 126          * takes into account geometric constraints and layoutings.
 127          * @param parentGeometry the geometry of the caller item or a
 128          * null rect if the geometry of the parent is not yet defined.
 129          */
 130         QRect placementHint( QStack<QSize> &sizes, const QSize &size, const QPoint &offset );
 131         QRect placementHint( QStack<QSize> &sizes, const QPoint &offset );
 132         void sizingHint( QStack<QSize> &parentSizes, SizeHint &hint );
 133
 134         /**
 135          * Create the box layout manager; next children will be
 136          * managed by the box layouter
 137          */
 138         void setBoxLayout( const QDomNode &node = QDomNode() );
 139
 140         /**
 141          * Create the fixed layout manager; next children will be
 142          * in fixed position relative to this item
 143          */
 144         void setFixedLayout( const QDomNode &node = QDomNode() );
 145
 146         QString type() const { return itemType; }
 147         void setType( const QString &t ) { itemType = t; }
 148
 149         virtual void setWidget( QWidget *widget );
 150         void showWidget( bool show = true );
 151         void plugActions( bool plug = true );
 152
 153         void setVisible( bool show );
 154         bool isVisible() const { return m_visible; }
 155         void updateVisible();
 156
 157         QRect rect() const { return area; }
 158
 159         void showStructure( const QString &pfx );
 160
 161 Q_SIGNALS:
 162         void needUpdate( int x, int y, int w, int h );
 163         void needPlacement();
 164         void needPlugging();
 165         void activated( const QString &id );
 166
 167 protected Q_SLOTS:
 168         void widgetGone();
 169
 170 protected:
 171         KdmThemer *themer();
 172
 173         /**
 174          * Returns the optimal/minimal size for this item.
 175          * This should be reimplemented in items like label and pixmap.
 176          * @return (-1,-1) if no size can be determined (so it should
 177          * default to parent's size).
 178          */
 179         virtual QSize sizeHint();
 180
 181         /**
 182          * Low level graphical function to paint the item.
 183          * All items must reimplement this function to draw themeselves
 184          * (or a part of) into the @p image keeping inside the @p rect .
 185          * Try to do this as fast as possible.
 186          * @param painter the painter to draw the item with
 187          * @param region the area of the device to be painted. This is already
 188          *   intersected with the area of the item.
 189          */
 190         virtual void drawContents( QPainter *painter, const QRect &region ) = 0;
 191
 192         /**
 193          * Called when item changes its 'state' variable. This must
 194          * handle item's repaint.
 195          */
 196         virtual void statusChanged( bool descend );
 197
 198         virtual void doPlugActions( bool plug );
 199
 200         bool eventFilter( QObject *o, QEvent *e );
 201         void setWidgetAttribs( QWidget * );
 202         void updatePalette( QWidget *w );
 203
 204         void updateThisVisible();
 205
 206         /**
 207          * emits needUpdate( int, int, int, int ) with the full widget area.
 208          */
 209         void needUpdate();
 210
 211         // This enum identifies in which state the item is
 212         enum ItemState { Snormal, Sactive, Sprelight } state;
 213
 214         static KdmItem *currentActive;
 215
 216         // This is the placement of the item
 217         QRect area;
 218
 219         QString buddy;
 220         bool isButton;
 221         bool isBackground;
 222
 223         // This struct is filled in by KdmItem base class
 224         struct DataPair {
 225                 DataPoint x, y;
 226         };
 227         struct {
 228                 DataPair pos, minSize, size, maxSize;
 229                 QString anchor;
 230                 int expand;
 231         } geom;
 232
 233         const QSize &ensureHintedSize( QSize & );
 234         const QSize &ensureBoxHint( QSize &, QStack<QSize> &, QSize & );
 235         void calcSize( const DataPair &,
 236                        QStack<QSize> &, QSize &, QSize &,
 237                        QSize & );
 238
 239         StyleType style;
 240
 241         /* For internal use ONLY
 242          * Add a child item. This function is called automatically
 243          * when constructing an @p item with this as the parent.
 244          */
 245         void addChildItem( KdmItem *item );
 246
 247         bool childrenContain( int x, int y );
 248
 249         void activateBuddy();
 250
 251         QString itemType;
 252         QList<KdmItem *> m_children;
 253 #define forEachChild(v) foreach (KdmItem *v, m_children)
 254 #define forEachVisibleChild(v) forEachChild (v) if (v->isVisible())
 255
 256         // Layouting related variables
 257         enum { MNone = 0, MFixed = 1, MBox = 2 } currentManager;
 258         KdmLayoutBox *boxManager;
 259         KdmLayoutFixed *fixedManager;
 260
 261         QWidget *myWidget;
 262
 263         QString m_showType;
 264         bool m_showTypeInvert;
 265         int m_minScrWidth, m_minScrHeight;
 266
 267         bool m_visible, m_shown;
 268
 269         friend class KdmLabel; // isButton
 270         friend class KdmLayoutBox; // geom.expand
 271         friend class KdmThemer;
 272 };
 273
 274 #endif