← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/kdebase-workspace/gutsy

« back to all changes in this revision

Viewing changes to kdm/kfrontend/themer/kdmitem.h

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell
  • Date: 2007-09-05 20:45:14 UTC
  • Revision ID: james.westby@ubuntu.com-20070905204514-632hhspl0nvrc84i
Tags: upstream-3.93.0
Import upstream version 3.93.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 );
 
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
        void setIsButton( bool on ) { isButton = on; }
 
149
        void setShowType( const QString &t, bool i ) { m_showType = t; m_showTypeInvert = i; }
 
150
 
 
151
        virtual void setWidget( QWidget *widget );
 
152
        void showWidget( bool show = true );
 
153
        void plugActions( bool plug = true );
 
154
 
 
155
        void setVisible( bool show );
 
156
        bool isVisible() const { return m_visible; }
 
157
        void updateVisible();
 
158
 
 
159
        QRect rect() const { return area; }
 
160
 
 
161
        void showStructure( const QString &pfx );
 
162
 
 
163
Q_SIGNALS:
 
164
        void needUpdate( int x, int y, int w, int h );
 
165
        void needPlacement();
 
166
        void needPlugging();
 
167
        void activated( const QString &id );
 
168
 
 
169
protected Q_SLOTS:
 
170
        void widgetGone();
 
171
 
 
172
protected:
 
173
        KdmThemer *themer();
 
174
 
 
175
        /**
 
176
         * Returns the optimal/minimal size for this item.
 
177
         * This should be reimplemented in items like label and pixmap.
 
178
         * @return (-1,-1) if no size can be determined (so it should
 
179
         * default to parent's size).
 
180
         */
 
181
        virtual QSize sizeHint();
 
182
 
 
183
        /**
 
184
         * Low level graphical function to paint the item.
 
185
         * All items must reimplement this function to draw themeselves
 
186
         * (or a part of) into the @p image keeping inside the @p rect .
 
187
         * Try to do this as fast as possible.
 
188
         * @param painter the painter to draw the item with
 
189
         * @param region the part of the the image to render
 
190
         */
 
191
        virtual void drawContents( QPainter *painter, const QRect &region ) = 0;
 
192
 
 
193
        /**
 
194
         * Called when item changes its 'state' variable. This must
 
195
         * handle item's repaint.
 
196
         */
 
197
        virtual void statusChanged( bool descend );
 
198
 
 
199
        virtual void doPlugActions( bool plug );
 
200
 
 
201
        /**
 
202
         * emits needUpdate( int, int, int, int ) with the full widget area.
 
203
         */
 
204
        void needUpdate();
 
205
 
 
206
        // This enum identifies in which state the item is
 
207
        enum ItemState { Snormal, Sactive, Sprelight } state;
 
208
 
 
209
        static KdmItem *currentActive;
 
210
 
 
211
        // This is the placement of the item
 
212
        QRect area;
 
213
 
 
214
        QString buddy;
 
215
        bool isButton;
 
216
 
 
217
        // This struct is filled in by KdmItem base class
 
218
        struct DataPair {
 
219
                DataPoint x, y;
 
220
        };
 
221
        struct {
 
222
                DataPair pos, minSize, size, maxSize;
 
223
                QString anchor;
 
224
                int expand;
 
225
        } geom;
 
226
 
 
227
        const QSize &ensureHintedSize( QSize & );
 
228
        const QSize &ensureBoxHint( QSize &, QStack<QSize> &, QSize & );
 
229
        void calcSize( const DataPair &,
 
230
                       QStack<QSize> &, QSize &, QSize &,
 
231
                       QSize & );
 
232
 
 
233
        StyleType style;
 
234
 
 
235
        /* For internal use ONLY
 
236
         * Add a child item. This function is called automatically
 
237
         * when constructing an @p item with this as the parent.
 
238
         */
 
239
        void addChildItem( KdmItem *item );
 
240
 
 
241
        bool childrenContain( int x, int y );
 
242
 
 
243
        void activateBuddy();
 
244
 
 
245
        QString itemType;
 
246
        QList<KdmItem *> m_children;
 
247
#define forEachChild(v) foreach (KdmItem *v, m_children)
 
248
#define forEachVisibleChild(v) forEachChild (v) if (v->isVisible())
 
249
 
 
250
        // Layouting related variables
 
251
        enum { MNone = 0, MFixed = 1, MBox = 2 } currentManager;
 
252
        KdmLayoutBox *boxManager;
 
253
        KdmLayoutFixed *fixedManager;
 
254
 
 
255
        QWidget *myWidget;
 
256
 
 
257
        QString m_showType;
 
258
        bool m_showTypeInvert;
 
259
 
 
260
        bool m_visible;
 
261
 
 
262
        friend class KdmLabel; // isButton
 
263
        friend class KdmLayoutBox; // geom.expand
 
264
        friend class KdmThemer;
 
265
};
 
266
 
 
267
#endif