add more spacing

[personal-kdebase.git] / workspace / kdm / kfrontend / themer / kdmitem.h

/*
 *  Copyright (C) 2003 by Unai Garro <ugarro@users.sourceforge.net>
 *  Copyright (C) 2004 by Enrico Ros <rosenric@dei.unipd.it>
 *  Copyright (C) 2004 by Stephan Kulow <coolo@kde.org>
 *  Copyright (C) 2004 by Oswald Buddenhagen <ossi@kde.org>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef KDMITEM_H
#define KDMITEM_H

#include "parse.h"

#include <QDomNode>
#include <QObject>
#include <QStack>

class KdmItem;
class KdmLayoutBox;
class KdmLayoutFixed;
class KdmThemer;

class QPainter;

struct SizeHint {
        QSize min, opt, max;
};

/** class KdmItem
 * @short Base class for every kdmthemes' element.
 *
 * This class provides methods for arranging it and its children to the
 * screen (see note below), painting the whole area or a sub-region using
 * an opened painter, handling mouse events or events in general dispatching
 * them to children and sending some signals to the root (for example on
 * mouse click).
 *
 * KdmItem sits in a hierarchical top to bottom tree with signals that
 * traverse the tree back from leafs (or inner nodes) to the root.
 *
 * To implement a KdmItem only a few virtual protected methods must be
 * reimplemented, other virtual functions are there for convenience only -
 * the default implementation should satisfy your needs.
 */

/**
 * A note on layouting - how does it work?
 *  - setgeometry is called by parent (passing the new geometry)
 *    - item changes its geometry
 *    - if item embeds a widget, reposition it too
 *    - call children's box manager. box->update( my geom )
 *      - sum up the whole space taken by children (via *hint calls) if
 *        needed for box width / height computation. note that the computed
 *        geometry should be equal or similar to parent's geometry.
 *      - pad the rectangle bounding box' contents
 *      - for every child
 *        - if vertical
 *          ( use a top-to-bottom insertion, spacing insertion lines by
 *            children's individual height )
 *          - set up a zero height Parent (placed at the insertion line's
 *            position) and get Geom = child->placementHint( p )
 *          - set up child's Size using Parent's width and Geom's height.
 *          - call to child->setGeometry( Parent.topLeft, Size )
 *        - if horizontal
 *          - flows like the vertical one but uses a left-to-right insertion
 *            and insertion entry points are vertical lines
 *    - call to children's fix manager. fixed->update( my geom )
 *      - for every child
 *          - S = get child's geometry hint (and we'll give item the whole
 *            space it needs, without constraints)
 *          - call to child->setGeometry( S )
 *    - TODO: send a selective redraw signal also merging children's areas
 */

class KdmItem : public QObject {
        Q_OBJECT

public:
        /**
         * Item constructor and destructor
         */
        KdmItem( QObject *parent, const QDomNode &node );
        virtual ~KdmItem();

        /**
         * Fixup the geometry of an item and its children (even if fixed
         * or boxed ones). Note that this will generate repaint signals
         * when needed. The default implementation should fit all needs.
         */
        virtual void setGeometry( QStack<QSize> &parentSizes, const QRect &newGeometry, bool force );

        /**
         * Paint the item and its children using the given painter.
         * This is the compositing core function. It buffers paint operations
         * to speed up rendering of dynamic objects.
         */
        void paint( QPainter *painter, const QRect &boundaries, bool background, bool primaryScreen );

        /**
         * Update representation of contents and repaint.
         */
        virtual void update();

        /**
         * Handle mouse motion and dispatch events to children. This
         * leads to items prelighting, activation() on click and more..
         */
        void mouseEvent( int x, int y, bool pressed = false, bool released = false );

        /**
         * Similar to sizeHint(..), this returns the area of the item
         * given the @p parentGeometry. The default implementation
         * takes into account geometric constraints and layoutings.
         * @param parentGeometry the geometry of the caller item or a
         * null rect if the geometry of the parent is not yet defined.
         */
        QRect placementHint( QStack<QSize> &sizes, const QSize &size, const QPoint &offset );
        QRect placementHint( QStack<QSize> &sizes, const QPoint &offset );
        void sizingHint( QStack<QSize> &parentSizes, SizeHint &hint );

        /**
         * Create the box layout manager; next children will be
         * managed by the box layouter
         */
        void setBoxLayout( const QDomNode &node = QDomNode() );

        /**
         * Create the fixed layout manager; next children will be
         * in fixed position relative to this item
         */
        void setFixedLayout( const QDomNode &node = QDomNode() );

        QString type() const { return itemType; }
        void setType( const QString &t ) { itemType = t; }

        virtual void setWidget( QWidget *widget );
        void showWidget( bool show = true );
        void plugActions( bool plug = true );

        void setVisible( bool show );
        bool isVisible() const { return m_visible; }
        void updateVisible();

        QRect rect() const { return area; }

        void showStructure( const QString &pfx );

Q_SIGNALS:
        void needUpdate( int x, int y, int w, int h );
        void needPlacement();
        void needPlugging();
        void activated( const QString &id );

protected Q_SLOTS:
        void widgetGone();

protected:
        KdmThemer *themer();

        /**
         * Returns the optimal/minimal size for this item.
         * This should be reimplemented in items like label and pixmap.
         * @return (-1,-1) if no size can be determined (so it should
         * default to parent's size).
         */
        virtual QSize sizeHint();

        /**
         * Low level graphical function to paint the item.
         * All items must reimplement this function to draw themeselves
         * (or a part of) into the @p image keeping inside the @p rect .
         * Try to do this as fast as possible.
         * @param painter the painter to draw the item with
         * @param region the area of the device to be painted. This is already
         *   intersected with the area of the item.
         */
        virtual void drawContents( QPainter *painter, const QRect &region ) = 0;

        /**
         * Called when item changes its 'state' variable. This must
         * handle item's repaint.
         */
        virtual void statusChanged( bool descend );

        virtual void doPlugActions( bool plug );

        bool eventFilter( QObject *o, QEvent *e );
        void setWidgetAttribs( QWidget * );
        void updatePalette( QWidget *w );

        void updateThisVisible();

        /**
         * emits needUpdate( int, int, int, int ) with the full widget area.
         */
        void needUpdate();

        // This enum identifies in which state the item is
        enum ItemState { Snormal, Sactive, Sprelight } state;

        static KdmItem *currentActive;

        // This is the placement of the item
        QRect area;

        QString buddy;
        bool isButton;
        bool isBackground;
        enum { ScrGreeter, ScrOther, ScrAll } paintOnScreen;

        // This struct is filled in by KdmItem base class
        struct DataPair {
                DataPoint x, y;
        };
        struct {
                DataPair pos, minSize, size, maxSize;
                QString anchor;
                int expand;
        } geom;

        const QSize &ensureHintedSize( QSize & );
        const QSize &ensureBoxHint( QSize &, QStack<QSize> &, QSize & );
        void calcSize( const DataPair &,
                       QStack<QSize> &, QSize &, QSize &,
                       QSize & );

        StyleType style;

        /* For internal use ONLY
         * Add a child item. This function is called automatically
         * when constructing an @p item with this as the parent.
         */
        void addChildItem( KdmItem *item );

        bool childrenContain( int x, int y );

        void activateBuddy();

        QString itemType;
        QList<KdmItem *> m_children;
#define forEachChild(v) foreach (KdmItem *v, m_children)
#define forEachVisibleChild(v) forEachChild (v) if (v->isVisible())

        // Layouting related variables
        enum { MNone = 0, MFixed = 1, MBox = 2 } currentManager;
        KdmLayoutBox *boxManager;
        KdmLayoutFixed *fixedManager;

        QWidget *myWidget;

        QString m_showType;
        bool m_showTypeInvert;
        int m_minScrWidth, m_minScrHeight;

        bool m_visible, m_shown;

        friend class KdmLabel; // isButton
        friend class KdmLayoutBox; // geom.expand
        friend class KdmThemer;
};

#endif